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 上传接口。