# File Service 模块指引

## 职责边界

- File 服务是企业资质文件的唯一公开上传入口。必须先持久化并验证真实文件，再调用 IAM 内部接口登记元数据；禁止只生成或改写一个不存在文件的 URL。

- 负责企业资质文件的上传、存储、读取和访问鉴权；当前实现只使用本地磁盘，文件内容不进入 Git。
- `src/main/resources/db/file.sql` 是文件元数据、下载令牌和下载日志的目标表结构，当前代码尚未接入 Entity、Mapper 或 Repository，不能据此判断元数据持久化已实现。
- 企业资质审核状态和元数据归 `iam/`；本模块通过 IAM 客户端校验访问权限，不跨库读取 IAM 数据。

## 快速索引

| 功能 | 入口 |
|---|---|
| 商户资质上传与读取 | `src/main/java/com/baiyue/file/controller/QualificationFileController.java` |
| 平台资质查看 | `controller/PlatformQualificationFileController.java` |
| 服务状态 | `controller/FileHealthController.java` |
| 当前本地磁盘实现 | `service/LocalQualificationStorage.java` |
| 未被当前 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` |

## 修改与验证

- 严格校验租户、文件名/路径、大小、类型和读取权限，防止目录穿越、越权访问和任意文件上传。
- 生产存储应使用对象存储或共享文件存储；容器本地目录仅适合当前本地实现，不得硬编码环境路径。
- 接入元数据持久化时需同时实现 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 上传接口。