添加快速索引文件

2026-07-31 11:06:36 +08:00
parent 71c5f2f3b5
commit 4cee256f22
20 changed files with 512 additions and 1 deletions
@@ -0,0 +1,27 @@
+# File Service 模块指引
+
+## 职责边界
+
+- 负责企业资质文件的上传、存储、读取和访问鉴权；当前实现只使用本地磁盘，文件内容不进入 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` |
+| IAM 权限协作 | `client/IamQualificationClient.java` |
+| 目标表结构（尚未接入） | `src/main/resources/db/file.sql` |
+| 存储边界测试 | `src/test/java/com/baiyue/file/service/LocalQualificationStorageTest.java` |
+| 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/file-service.yml` |
+
+## 修改与验证
+
+- 严格校验租户、文件名/路径、大小、类型和读取权限，防止目录穿越、越权访问和任意文件上传。
+- 生产存储应使用对象存储或共享文件存储；容器本地目录仅适合当前本地实现，不得硬编码环境路径。
+- 接入元数据持久化时需同时实现 Entity、Mapper、Repository、事务和迁移验证，并同步检查 IAM 资质流程及平台/商户 Controller。
+- 从父目录运行 `mvn -pl file -am test`，并按接口影响验证上传、预览、无权限和非法文件场景。