baiyue-firstleg/file/AGENTS.md

File Service 模块指引

数据库访问与中文注释约束

• 强制继承 ../AGENTS.md 的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。

职责与边界

• Mapper 只由 FileServiceApplication.java 对 com.baiyue.file 根包按 @Mapper 过滤扫描；新增或移动 Mapper 后从后端根运行 node scripts/mapper-scan-contract.mjs，不得增加子域扫描配置。
• 负责企业资质文件、公共导出、入库测量图片的上传、存储、读取和鉴权。
• 资质审核元数据归 iam/，入库状态归 firstleg/，OCR 适配归 integration-service/；不跨库读取业务表。

模块入口

目标	入口
商户/平台资质	controller/QualificationFileController.java、PlatformQualificationFileController.java、controller/QualificationTypes.java；契约 src/main/resources/openapi/qualification-required-package-v1.yaml。营业执照必须与 18 位统一社会信用代码走 required-package；法人身份证选填，客户可在已有营业执照后通过 /api/merchant/v1/files/qualifications 单独新增或替换
导出中心与退避重试	controller/PlatformExportTaskController.java、service/ExportTaskService.java、service/ExportStateService.java、service/GenericXlsxExportRunner.java、config/ExportDefinitionRegistry.java、client/ExportProviderClient.java、mq/；响应公开 attemptCount/maxAttempts/nextRetryAt
测量图片/证据	controller/PlatformMeasurementImageController.java、InternalMeasurementImageController.java、service/MeasurementImageService.java
平台订单商品图片读取	controller/PlatformProductImageController.java 的 /api/platform/v1/files/product-images/{tenantId}/{fileId}、service/ProductImageService.java；仅平台 platform:order:list 可按明确客户与文件 ID 内联读取，响应 no-store
装柜与业务文件证据	controller/PlatformLoadingEvidenceController.java、InternalLoadingEvidenceController.java、service/LoadingEvidenceService.java、src/main/resources/openapi/loading-evidence-v1.yaml；五类装柜证据固定为平台所有、tenantId=0、businessId=containerBookingId，不得绑定客户或入仓单。其他业务文件进入 InternalBusinessFileController.java、service/InternalBusinessFileService.java
财务付款凭证、海外卸柜照片	通用业务文件入口 InternalBusinessFileController.java、InternalBusinessFileService.java；FINANCE_VOUCHER 按客户与业务 ID 精确校验；OVERSEAS_UNLOAD_PHOTO 是允许同柜多客户的柜级物理证据，固定平台范围 tenantId=0 并按接柜会话 ID 精确校验
公司车辆付款凭证	src/main/resources/openapi/finance-vehicle-voucher-v1.yaml；类型FINANCE_VEHICLE_VOUCHER，固定平台0和Finance费用ID，仅非空JPG/PNG、10MiB及签名校验；不复用客户凭证或维修照片
海外异常订单证据	通用内部业务文件入口；固定 businessType=OVERSEAS_EXCEPTION_EVIDENCE、tenantId=异常订单所属客户ID、businessId=异常订单ID，File 只校验文件复合归属，异常状态、完成门禁和证据引用归 Lastleg
平台司机驾驶证	通用内部业务文件入口，契约 src/main/resources/openapi/fleet-driver-license-v1.yaml；FLEET_DRIVER_LICENSE 固定平台 tenantId=0、businessId=driverId，仅非空 PDF/JPG/PNG、最大 10MiB并校验签名；Lastleg维护审核、当前/历史附件关联及读取权限
车辆保养加油照片	通用内部业务文件入口，契约 src/main/resources/openapi/fleet-vehicle-record-photo-v1.yaml；FLEET_VEHICLE_RECORD_PHOTO 固定平台0及运维记录ID，仅非空JPG/PNG、最大10MiB并校验签名；Lastleg校验车辆/记录/附件关联与权限，不使用车牌作为文件归属键
出车实测凭证	通用内部业务文件入口，契约 src/main/resources/openapi/fleet-trip-operation-evidence-v1.yaml；FLEET_TRIP_OPERATION_EVIDENCE固定平台0及车次ID，PDF/JPG/PNG、10MiB与签名校验；Lastleg管理实测版本引用及读写权限，附件选填
海外换标 PDF 资料	通用内部业务文件入口，契约 src/main/resources/openapi/overseas-relabel-document-v1.yaml；OVERSEAS_RELABEL_TOTAL_DOCUMENT 按 application.id、OVERSEAS_RELABEL_ITEM_DOCUMENT 按 item.id 归属，必须指定明确客户与正数业务 ID；仅非空 PDF、最大 10MiB，校验 MIME 和文件签名。File 按客户、类型、业务 ID、文件 ID 复合校验，Lastleg 校验申请/明细关系、客户归属、权限和业务状态
入库扣货凭证	通用内部业务文件入口；固定 businessType=INBOUND_HOLD_EVIDENCE、tenantId=客户ID、businessId=入库单ID，客户作用域单文件最多 10MiB；可见性与历史引用由 Firstleg 校验
报关源文件、报关行回执、完成文件与买单明细导出	src/main/resources/openapi/customs-file-and-export-v1.yaml；文件类别 LOADING_LIST_CUSTOMS_SOURCE、LOADING_LIST_CUSTOMS_RECEIPT、LOADING_LIST_CUSTOMS_RESULT 均为客户作用域且最多 50MB，异步导出类型 LOADING_LIST_BUY_DECLARATION_ITEMS 由 Firstleg Provider 按固定十三列供数
订舱文件	通用内部业务文件入口，契约 src/main/resources/openapi/ocean-booking-file-v1.yaml；类型固定 OCEAN_BOOKING_DOCUMENT、tenantId=0（平台专属，客户可选快照不改变文件归属，拒绝客户作用域）、businessId=oceanBookingId，任意格式且最多 50MiB，不得绑定拖车；BOOKING_CONFIRMATION/BILL_OF_LADING 文档类型及有效状态由 Firstleg 保存
拖车预约附件	通用内部业务文件入口；固定 tenantId=0、businessType=TRUCK_APPOINTMENT_ATTACHMENT、businessId=appointmentId，只允许派车单、司机/车辆资料和其他平台附件；提单文件归订舱 OCEAN_BOOKING_DOCUMENT，不得复制为拖车附件
存储与实体	service/LocalQualificationStorage.java、MeasurementImageStorage.java、entity/FileObjectEntity.java
派送单三类资料	src/main/resources/openapi/delivery-files-v1.yaml；依次为装车照片 DELIVERY_LOADING_PHOTO、BOL文件（含签名）DELIVERY_BOL、签收文件（POD签收/快递签收）DELIVERY_RECEIPT，按客户、派送内部ID、类别隔离，任意格式单文件50MiB；Lastleg持有分类绑定、保存、替换删除和历史可见性，按非空类别计数x/3，不强制必传或识别签名；File保留不可变对象与真实createdAt
下游 OCR	client/WeightOcrClient.java
SQL/配置	src/main/resources/db/file.sql、application.yml
国内/海外 PDA 版本	controller/PdaReleaseController.java、service/PdaReleaseService.java、service/PdaPackageStorage.java、src/main/resources/openapi/pda-releases-v1.yaml；平台上传草稿、发布和停发，匿名清单与包下载只暴露当前已发布/历史未停发文件；国内和海外 AppID、指针独立
测试/验证	src/test/java/com/baiyue/file/；mvn -pl file -am test

修改约束

• 贴标箱唛总文件和 SKU 总文件分别使用 OVERSEAS_RELABEL_CARTON_TOTAL_DOCUMENT、OVERSEAS_RELABEL_SKU_TOTAL_DOCUMENT，与明细 PDF 采用同一客户复合归属和 10MiB PDF 校验。file_object.business_type 为 VARCHAR(64)，存量扩容见海外统一增量和 scripts/db/relabel-file-scope-incremental.sql。Print 只负责生成 PDF，不保存上传文件。

• 上传先写真实文件再登记 IAM 元数据；异常结果未知时保留文件供重试，禁止伪造 URL。

• 客户单文件资质入口只接受 LEGAL_PERSON_ID/FREIGHT_FORWARDER_CERTIFICATE/BANK_ACCOUNT_LICENSE，客户范围只取登录 Token；营业执照不得绕过 required-package。同类当前资质已存在时必须显式 replace=true，成功后旧元数据标记为已替代；上传不会自动提交审核。

• 客户业务文件按客户、业务 ID 和文件类型校验归属；重量图片可 OCR，第三方尺寸证据不得触发重量 OCR。装柜四步照片与铅封是跨客户物理柜证据，所有者固定为平台（tenantId=0），业务 ID 固定为 containerBookingId，File 按柜与五类 LOADING_* 精确校验且不得跨柜复用；PDA taskId 只由 Firstleg 保存为来源/审计，不进入 File 所有权。国内 PDA 禁止直连 File 平台接口，必须经 Firstleg 校验任务、仓库和操作者后，由 Firstleg 使用内部服务令牌访问 File。

• 商品图片平台读取必须同时校验平台身份、platform:order:list、客户范围、文件业务类型与正整数 ID；不得提供匿名 URL、跨客户读取或把内部存储路径返回页面。

• 公共导出只接受 ExportDefinitionRegistry 明确登记的 exportType，由 File 调用所属业务服务的内部 Provider 分批取数并生成文件；业务页面不得直连 Provider。新增或修改导出类型时同步检查业务服务 Provider、File Feign 客户端/响应上限、权限、Admin 下载中心标签与重试映射及契约测试。

• 人工重试只允许 FAILED，或 PENDING 且已有失败尝试、正在等待自动退避的任务；后者只把当前任务与现有 Outbox 投递立即到期，不增加新任务或并发消息。RUNNING、初次等待消费、已成功或已过期任务均拒绝重试。

• 生产环境显式配置 FILE_STORAGE_ROOT；磁盘故障返回 S0503，不得包装成业务错误。

• 报关源文件和完成文件的 businessId 固定为 loadingPlanId，File DTO 仍为 Metadata(fileId, tenantId, businessType, businessId, fileName, sha256, contentType, sizeBytes)，其中 businessType 即 fileCategory；Firstleg 保存业务文件版本并决定用户入口。权限固定为 Platform 上传结果 platform:firstleg:customs:manage、下载 platform:firstleg:loading-list:list，Client 上传源文件 merchant:order:edit、下载自身源文件或获准结果 merchant:order:view。结果还必须满足整柜完成和可见性，买单客户是否存在结果入口同样由 Firstleg 判定，File 不复制这些状态。

全量验收导航

订单与客户、入库测量与计费、国内货柜履约及财务全量验收均复用本模块文件能力；按本次链路读取对应阶段/专题文档，统一核对资质、测量图片、装柜证据、报关回执的归属、鉴权、审计和生命周期。照片允许追加、错误记录仅作废不硬删除，客户不得读取内部照片或锁码。