暂存提交

file/AGENTS.md

@@ -19,6 +19,7 @@
 | 未被当前 Controller 使用的旧实现 | `service/QualificationFileStorage.java` |
 | IAM 权限协作 | `client/IamQualificationClient.java` |
 | 目标表结构（尚未接入） | `src/main/resources/db/file.sql` |
+| 历史资质文件迁移 | `../scripts/migrate-local-qualification-file.ps1`、`../docs/企业资质文件迁移说明.md`；只适用于当前本地/共享目录存储实现 |
 | 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/file-service.yml` |
 
 ## 修改与验证
@@ -27,3 +28,6 @@
 - 生产存储应使用对象存储或共享文件存储；容器本地目录仅适合当前本地实现，不得硬编码环境路径。
 - 接入元数据持久化时需同时实现 Entity、Mapper、Repository、事务和迁移验证，并同步检查 IAM 资质流程及平台/商户 Controller。
 - 当前没有专属自动化测试；从父目录运行 `mvn -pl file -am test`，并按接口影响验证上传、预览、无权限和非法文件场景。
+- 非本地环境必须显式配置 `FILE_STORAGE_ROOT` 并挂载持久化可写目录；服务启动时会校验目录，存储不可用时直接启动失败，避免健康检查正常而上传返回 500。
+- 文件写入失败属于基础设施故障，统一返回 `S0503`，服务日志保留实际目录和底层异常；禁止将磁盘故障包装成 `B0001`。
+- 迁移历史 `/phase1-seed/...` 路径时必须先写入并校验真实脱敏图片，再按 `id + tenant_id + 旧 URL` 更新 IAM 元数据；禁止只改 URL。对象存储环境必须改走 File 上传接口。