baiyue-firstleg/file/AGENTS.md

File Service 模块指引

职责与边界

• 负责企业资质文件、公共导出、二期入库测量图片的上传、存储、读取和鉴权。
• 资质审核元数据归 iam/，入库状态归 firstleg/，OCR 适配归 integration-service/；不跨库读取业务表。

模块入口

目标	入口
商户/平台资质	controller/QualificationFileController.java、PlatformQualificationFileController.java
导出中心	controller/PlatformExportTaskController.java、service/ExportTaskService.java、service/ExportStateService.java、service/GenericXlsxExportRunner.java、config/ExportDefinitionRegistry.java、client/ExportProviderClient.java、mq/
测量图片/证据	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、InternalBusinessFileController.java、service/InternalBusinessFileService.java
财务付款凭证、海外卸柜照片	通用业务文件入口 InternalBusinessFileController.java、InternalBusinessFileService.java；业务类型分别为 FINANCE_VOUCHER、OVERSEAS_UNLOAD_PHOTO，必须按客户与业务 ID 精确校验
报关源文件、完成文件与买单明细导出	src/main/resources/openapi/customs-file-and-export-v1.yaml；文件类别 LOADING_LIST_CUSTOMS_SOURCE、LOADING_LIST_CUSTOMS_RESULT 均为客户作用域且最多 50MB，异步导出类型 LOADING_LIST_BUY_DECLARATION_ITEMS 由 Firstleg Provider 按固定十三列供数
存储与实体	service/LocalQualificationStorage.java、MeasurementImageStorage.java、entity/FileObjectEntity.java
下游 OCR	client/WeightOcrClient.java
SQL/配置	src/main/resources/db/file.sql、application.yml
测试/验证	src/test/java/com/baiyue/file/；mvn -pl file -am test

修改约束

• 上传先写真实文件再登记 IAM 元数据；异常结果未知时保留文件供重试，禁止伪造 URL。
• 所有文件按客户、入库单、文件类型校验归属；重量图片可 OCR，第三方尺寸证据不得触发重量 OCR。
• 商品图片平台读取必须同时校验平台身份、platform:order:list、客户范围、文件业务类型与正整数 ID；不得提供匿名 URL、跨客户读取或把内部存储路径返回页面。
• 公共导出只接受 ExportDefinitionRegistry 明确登记的 exportType，由 File 调用所属业务服务的内部 Provider 分批取数并生成文件；业务页面不得直连 Provider。新增或修改导出类型时同步检查业务服务 Provider、File Feign 客户端/响应上限、权限、Admin 下载中心标签与重试映射及契约测试。
• 生产环境显式配置 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 不复制这些状态。

全量验收导航

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