baiyue-firstleg/file/AGENTS.md

File Service 模块指引

职责与边界

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

模块入口

目标	入口
商户/平台资质	controller/QualificationFileController.java、PlatformQualificationFileController.java
导出中心	controller/PlatformExportTaskController.java、service/ExportStateService.java、mq/
测量图片/证据	controller/PlatformMeasurementImageController.java、InternalMeasurementImageController.java、service/MeasurementImageService.java
存储与实体	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。
• 生产环境显式配置 FILE_STORAGE_ROOT；磁盘故障返回 S0503，不得包装成业务错误。

分期导航

• 一期：资质上传与读取；先读 ../../docs/一期/README.md。
• 二期：测量图片和 OCR 重试；先读 ../../docs/二期/README.md 与第三方联调说明。
• 三期：按稳定契约实现装柜五类证据和报关回执的存储、归属、鉴权与审计；先读 ../../docs/三期/三期开工门禁.md。照片允许追加、错误记录仅作废不硬删除，客户不得读取照片或锁码。