添加AGENTS.md 快速索引

file/AGENTS.md

@@ -4,9 +4,10 @@
 
 - File 服务是企业资质文件的唯一公开上传入口。必须先持久化并验证真实文件，再调用 IAM 内部接口登记元数据；禁止只生成或改写一个不存在文件的 URL。
 
-- 负责企业资质文件的上传、存储、读取和访问鉴权；当前实现只使用本地磁盘，文件内容不进入 Git。
-- `src/main/resources/db/file.sql` 是文件元数据、下载令牌和下载日志的目标表结构，当前代码尚未接入 Entity、Mapper 或 Repository，不能据此判断元数据持久化已实现。
+- 负责企业资质文件、公共导出文件和二期入库测量图片的上传、存储、读取及访问鉴权；当前文件内容使用本地磁盘，不能进入 Git。
+- `src/main/resources/db/file.sql` 中的 `file_object` 已由测量图片链路通过 `FileObjectEntity`、`FileObjectMapper` 接入，导出任务表也已接入；企业资质文件元数据仍归 IAM，不能把不同文件链路的持久化状态混为一谈。
 - 企业资质审核状态和元数据归 `iam/`；本模块通过 IAM 客户端校验访问权限，不跨库读取 IAM 数据。
+- 入库单和测量状态归 `firstleg/`，重量识别适配归 `integration-service/`；File 只保存图片对象、返回逻辑文件 ID 并代理受控 OCR 调用。
 
 ## 快速索引
 
@@ -23,7 +24,11 @@
 | 毒消息隔离 | `mq/ExportDlqHandler.java`；定位必须使用四个 User Properties，不解析损坏 body |
 | 未被当前 Controller 使用的旧实现 | `service/QualificationFileStorage.java` |
 | IAM 权限协作 | `client/IamQualificationClient.java`；商户登记 `/qualifications`，平台登记/替换 `/platform-qualifications` |
-| 目标表结构（尚未接入） | `src/main/resources/db/file.sql` |
+| 平台称重图片上传、OCR 重试与查看 | `controller/PlatformMeasurementImageController.java`（`/api/platform/v1/files/measurements`）→ `service/MeasurementImageService.java` |
+| Firstleg 第三方测量证据图片 | `controller/InternalMeasurementImageController.java`（`/internal/file/v1/measurement-images`）→ `MeasurementImageService.uploadMeasurementEvidence/deleteMeasurementEvidence`；必须校验内部令牌 |
+| 测量图片磁盘与元数据 | `service/MeasurementImageStorage.java`、`entity/FileObjectEntity.java`、`mapper/FileObjectMapper.java`；表结构 `src/main/resources/db/file.sql` |
+| 重量 OCR 下游 | `client/WeightOcrClient.java` → `integration-service` 的 `/internal/integrations/weight-ocr/single`；尺寸测量证据不触发重量 OCR |
+| 测量图片测试 | `controller/PlatformMeasurementImageControllerContractTest.java`、`InternalMeasurementImageControllerTest.java`、`service/MeasurementImageServiceEvidenceTest.java` |
 | 历史资质文件迁移 | `../scripts/migrate-local-qualification-file.ps1`、`../docs/企业资质文件迁移说明.md`；只适用于当前本地/共享目录存储实现 |
 | 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/file-service.yml` |
 | 上传契约与存储测试 | `src/test/java/com/baiyue/file/controller/QualificationFileContractTest.java`、`service/LocalQualificationStorageTest.java` |
@@ -33,7 +38,10 @@
 - 严格校验租户、文件名/路径、大小、类型和读取权限，防止目录穿越、越权访问和任意文件上传。
 - 企业资质文件只接受 PDF、JPG 和 PNG，单个文件上限 5MB；Client、Admin 与 `LocalQualificationStorage` 的限制和提示必须保持一致。
 - 生产存储应使用对象存储或共享文件存储；容器本地目录仅适合当前本地实现，不得硬编码环境路径。
-- 接入元数据持久化时需同时实现 Entity、Mapper、Repository、事务和迁移验证，并同步检查 IAM 资质流程及平台/商户 Controller。
+- 企业资质元数据后续若迁入 File，需同时实现 Entity、Mapper、Repository、事务和迁移验证，并同步检查 IAM 资质流程及平台/商户 Controller；不得复用测量图片 `file_object` 的已接入状态宣称资质元数据已迁移。
+- 测量图片必须同时按 `tenantId + inboundId + fileId + businessType` 校验归属。平台称重图片使用 `INBOUND_WEIGHT_IMAGE` 并可调用 OCR；第三方尺寸证据使用 `INBOUND_MEASUREMENT_IMAGE`，只允许内部上传/删除且不得触发重量 OCR。
+- 平台测量图片权限与 Firstleg 权限码保持一致：上传和重试要求 `platform:firstleg:inbound:weight:edit`，查看要求 `platform:firstleg:inbound:measure:view`；内部证据接口只信任共享内部令牌和明确操作人。
+- OCR 失败时保留已落盘文件和 `file_object` 元数据供重试或人工录入；删除第三方证据采用逻辑删除并校验业务类型，不能删除称重图片或其他租户文件。
 - 从父目录运行 `mvn -pl file -am test`，并按接口影响验证商户/平台上传、替换、预览、无权限、签名伪造和磁盘故障场景。
 - 非本地环境必须显式配置 `FILE_STORAGE_ROOT` 并挂载持久化可写目录；服务启动时会校验目录，存储不可用时直接启动失败，避免健康检查正常而首次上传才返回 HTTP 200 + `S0503`。
 - 文件写入失败属于基础设施故障，统一返回 `S0503`，服务日志保留实际目录和底层异常；禁止将磁盘故障包装成 `B0001`。