rui-docs/superpowers/plans/2026-06-07-file-storage-service-plan.md

# 文件存储服务（rui-service-storage）实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-subagent-driven-development (recommended) or superpowers-executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 落地 `rui-service-storage` 独立微服务，提供统一上传接口（阿里云 OSS / 腾讯云 COS / 本地），并通过 Redis pub/sub 广播 `ON_UPLOAD` / `ON_FILE_DELETED` 事件。

**Architecture:** Strategy 模式 + 事件驱动。`POST /storage/upload` → 鉴权 → 校验 → Strategy 上传 → 落 `sys_file` → 推 `ON_UPLOAD` 事件 → 返回 `Result<T>`。订阅方（如 `rui-service-system`）实现 `MqConsumer` 按 `type` 字段过滤处理。

**Tech Stack:** Java 21, Spring Boot 4.x, MyBatis Plus, Fastjson2, Spring Security OAuth2, Spring Data Redis (Redisson), 阿里云 OSS SDK, 腾讯 COS SDK

**前置依赖:**
- 设计文档 [docs/superpowers/specs/2026-06-07-file-storage-service-design.md](docs/superpowers/specs/2026-06-07-file-storage-service-design.md) (commit 66f0712)
- 主仓指针 commit c467eaf
- `rui-common-mq-redis` 已就绪，`@MqTopic` 注解可用
- `rui-common-web/.../annotation/AutoPermission` 已就绪
- `rui-common-core/.../result/Result<T>` 已就绪
- Gitea #4 实施中

---

## 文件映射

### 新增
| 路径 | 操作 | 说明 |
|------|------|------|
| `rui-common/rui-common-core/.../constants/MqTopicConstants.java` | Create | MQ topic 常量 |
| `rui-common/rui-common-core/.../enums/FileBizType.java` | Modify | 工具类（非枚举），含 normalize / uploadType / deletedType |
| `rui-service/rui-service-storage/pom.xml` | Create | 新模块 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/StorageApplication.java` | Create | 启动类 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/controller/SysFileController.java` | Create | 上传/查询/删除 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/IFileStorage.java` | Create | Strategy 接口 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/impl/AliyunOssFileStorage.java` | Create | 阿里云 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/impl/TencentCosFileStorage.java` | Create | 腾讯 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/impl/LocalFileStorage.java` | Create | 本地 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/impl/FileStorageRouter.java` | Create | 选实现 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/event/UploadEventPublisher.java` | Create | ON_UPLOAD 推送 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/event/FileDeletedEventPublisher.java` | Create | ON_FILE_DELETED 推送 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/properties/FileProperties.java` | Create | @ConfigurationProperties |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/entity/SysFile.java` | Create | 实体 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/mapper/SysFileMapper.java` | Create | Mapper |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/ISysFileService.java` | Create | Service 接口 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/impl/SysFileServiceImpl.java` | Create | Service 实现 |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/dto/SysFileUploadVO.java` | Create | 上传返回 VO |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/dto/SysFileQueryVO.java` | Create | 查询返回 VO |
| `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/dto/UploadEventPayload.java` | Create | 事件 payload POJO |
| `rui-service/rui-service-storage/src/main/resources/application.yml` | Create | port=9400 |
| `sql/init-database.sql` | Modify | 新增 sys_file DDL |

### 修改
| 路径 | 操作 | 说明 |
|------|------|------|
| `rui-service/pom.xml` | Modify | `<modules>` 加 storage |
| `rui-service/rui-service-starter/pom.xml` | Modify | 加 storage 依赖 |
| `rui-service/rui-service-starter/.../StarterApplication.java` | Modify | ComponentScan + storage |
| `rui-service/rui-service-starter/src/main/resources/application.yml` | Modify | rui.modules.available 加 storage 入口 |
| `docs/backend/config-templates/application-template.yml` | Modify | rui.file.* 公共配置示例 |
| `Gitea #4` | Reply + Close | 实施完成通知 |

---

## 任务列表

### Task 1: 公共常量与枚举（rui-common-core）

**Files:**
- Create: `rui-common/rui-common-core/src/main/java/com/rui/common/core/constants/MqTopicConstants.java`
- Modify: `rui-common/rui-common-core/src/main/java/com/rui/common/core/enums/FileBizType.java`（已从 enum 改为 final class，bizType 不维护中央清单）
- Reference style: `CacheConstants.java`（沿用 private ctor + Javadoc 写明写入方/使用方）

- [ ] **Step 1.1:** 创建 `MqTopicConstants`
  ```java
  public final class MqTopicConstants {
      public static final String ON_UPLOAD       = "ON_UPLOAD";
      public static final String ON_FILE_DELETED = "ON_FILE_DELETED";
      private MqTopicConstants() {}
  }
  ```

- [x] **Step 1.2:** ~~创建 `FileBizType` 枚举~~ 改为 final class 工具类（`normalize()` / `uploadType()` / `deletedType()`），**不维护业务类型清单**

- [ ] **Step 1.3:** 编译 `mvn -pl rui-common/rui-common-core compile` 通过

- [x] **Step 1.4:** 提交 `feat(core): 新增 MqTopicConstants 和 FileBizType`（后于本计划重构成工具类）

---

### Task 2: 数据库 DDL

**Files:**
- Modify: `sql/init-database.sql` (新增 sys_file 表 DDL)

- [ ] **Step 2.1:** 在 `sql/init-database.sql` 末尾追加 `sys_file` 表 DDL（参见设计文档 §4.1）

- [ ] **Step 2.2:** 提交 `feat(db): 新增 sys_file 表`

---

### Task 3: rui-service-storage 模块骨架

**Files:**
- Create: `rui-service/rui-service-storage/pom.xml`
- Create: `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/StorageApplication.java`
- Create: `rui-service/rui-service-storage/src/main/resources/application.yml`
- Modify: `rui-service/pom.xml`（`<modules>` 加 `<module>rui-service-storage</module>`）

- [ ] **Step 3.1:** 创建 `pom.xml`，parent 指向 `rui-service`，依赖：
  - `rui-common-web` / `rui-common-mybatis` / `rui-common-redis` / `rui-common-mq` / `rui-common-mq-redis` / `rui-common-security` / `rui-common-oauth2`（可选）
  - `spring-boot-starter-web`
  - `com.aliyun.oss:aliyun-sdk-oss`（版本从 `rui-dependencies` BOM 取）
  - `com.qcloud:cos_api`（版本从 BOM 取）
  - `spring-cloud-starter-alibaba-nacos-discovery` / `nacos-config`
  - `spring-boot-starter-actuator`
  - `lombok` / `fastjson2`

- [ ] **Step 3.2:** 创建 `StorageApplication.java`：
  ```java
  @SpringBootApplication
  @EnableDiscoveryClient
  @EnableResourceServer
  @ComponentScan(basePackages = {"com.rui.service.storage"})
  public class StorageApplication {
      public static void main(String[] args) {
          SpringApplication.run(StorageApplication.class, args);
      }
  }
  ```

- [ ] **Step 3.3:** 创建 `application.yml`（port=9400，servlet.multipart 兜底）

- [ ] **Step 3.4:** `rui-service/pom.xml` 的 `<modules>` 末尾加 `<module>rui-service-storage</module>`

- [ ] **Step 3.5:** 编译 `mvn -pl rui-service/rui-service-storage -am compile` 通过

- [ ] **Step 3.6:** 提交 `feat(storage): 新建 rui-service-storage 模块骨架`

---

### Task 4: 配置类 FileProperties

**Files:**
- Create: `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/properties/FileProperties.java`

- [ ] **Step 4.1:** 创建 `FileProperties`：
  - `@ConfigurationProperties(prefix = "rui.file")` + `@Data` + `@Component`（或 `@EnableConfigurationProperties`）
  - 字段：`String active`、`DataSize defaultMaxSize`（或 long）、`Map<String, BizTypeConfig> bizTypes`、`Aliyun aliyun`、`Tencent tencent`、`Local local`
  - 嵌套类 `BizTypeConfig { DataSize maxSize; List<String> allowedExtensions; }`
  - 嵌套类 `Aliyun { boolean enabled; String endpoint, accessKey, secretKey, bucket, urlPrefix, basePath; }`
  - 嵌套类 `Tencent { boolean enabled; String secretId, secretKey, region, bucket, urlPrefix, basePath; }`
  - 嵌套类 `Local { String basePath, urlPrefix; }`

- [ ] **Step 4.2:** 编译通过

- [ ] **Step 4.3:** 与本任务其他提交合并到 Task 3 的 commit（避免空 commit）

---

### Task 5: FileStorage Strategy 接口

**Files:**
- Create: `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/IFileStorage.java`
- Create: `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/dto/FileStorageResult.java`

- [ ] **Step 5.1:** 创建 `IFileStorage` 接口：
  ```java
  public interface IFileStorage {
      String type();                                           // "ALIYUN" / "TENCENT" / "LOCAL"
      boolean enabled(FileProperties props);
      FileStorageResult upload(MultipartFile file, String storageKey, FileProperties props) throws IOException;
      void delete(String storageKey, FileProperties props);
  }
  ```

- [ ] **Step 5.2:** 创建 `FileStorageResult { String url; String storageKey; }`

---

### Task 6: AliyunOssFileStorage 实现

**Files:**
- Create: `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/impl/AliyunOssFileStorage.java`

- [ ] **Step 6.1:** 实现：
  - `@Component("ALIYUN")` + `@ConditionalOnProperty(prefix = "rui.file.aliyun", name = "enabled", havingValue = "true")`（用 `@ConditionalOnBean` 触发；或简单写死 bean，启用由 `enabled` 控制）
  - 用 `OSSClientBuilder().build(endpoint, ak, sk)`
  - `upload` 调 `ossClient.putObject(bucket, storageKey, inputStream)`
  - `delete` 调 `ossClient.deleteObject(bucket, storageKey)`
  - 构造 `url` = `urlPrefix + "/" + storageKey`
  - `enabled` 返回 `aliyun.enabled`

- [ ] **Step 6.2:** 编译通过

---

### Task 7: TencentCosFileStorage 实现

**Files:**
- Create: `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/impl/TencentCosFileStorage.java`

- [ ] **Step 7.1:** 实现：
  - `@Component("TENCENT")` + 同条件注解
  - 用 `COSClient( new BasicCOSCredentials(sid, sk), new ClientConfig(new Region(region)) )`
  - `upload` 调 `cosClient.putObject(bucket, storageKey, inputStream)`
  - `delete` 调 `cosClient.deleteObject(bucket, storageKey)`
  - 构造 `url` = `urlPrefix + "/" + storageKey`

- [ ] **Step 7.2:** 编译通过

---

### Task 8: LocalFileStorage 实现

**Files:**
- Create: `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/impl/LocalFileStorage.java`

- [ ] **Step 8.1:** 实现：
  - `@Component("LOCAL")` （默认总是启用）
  - `basePath` 启动时 `Files.createDirectories`
  - `upload` 写文件到 `basePath + storageKey`，返回 `url = urlPrefix + storageKey`
  - `delete` 调 `Files.deleteIfExists`
  - `type()` 返回 `"LOCAL"`

- [ ] **Step 8.2:** 编译通过

---

### Task 9: FileStorageRouter

**Files:**
- Create: `rui-service/rui-service-storage/src/main/java/com/rui/service/storage/service/impl/FileStorageRouter.java`

- [ ] **Step 9.1:** 实现：
  - `@Component`
  - 构造注入 `Map<String, IFileStorage>`（Spring 按 bean name 注入所有实现）
  - `route(String storageHint)` 方法：先按 `storageHint` 找；找不到走 `props.getActive()`；都没有用 `LOCAL`
  - 失败抛 `BizException("STORAGE_NOT_AVAILABLE")`

- [ ] **Step 9.2:** Task 5-9 一起提交 `feat(storage): FileStorage Strategy 模式 + 三家实现`

---

### Task 10: SysFile 实体/Mapper/Service

**Files:**
- Create: `SysFile.java` (extends `BaseEntity`)
- Create: `SysFileMapper.java` (extends `BaseMapper<SysFile>`)
- Create: `ISysFileService.java` (extends `IService<SysFile>`)
- Create: `SysFileServiceImpl.java` (extends `ServiceImpl<SysFileMapper, SysFile>`)

- [ ] **Step 10.1:** `SysFile` 字段：`id, name, originalName, url, storageType, bizType, bizId, size, contentType, sha256, uploaderId`，其他由 `BaseEntity` 提供

- [ ] **Step 10.2:** Service 增加 `appendBizId(Long fileId, String bizId)` 方便订阅方回填

- [ ] **Step 10.3:** 编译通过

- [ ] **Step 10.4:** 提交 `feat(storage): sys_file 实体/Mapper/Service`

---

### Task 11: 上传/查询/删除 Controller

**Files:**
- Create: `SysFileUploadVO.java`
- Create: `SysFileQueryVO.java`
- Create: `SysFileController.java`

- [ ] **Step 11.1:** `SysFileUploadVO` 字段：`id, name, originalName, url, size, contentType, storageType, bizType`

- [ ] **Step 11.2:** `SysFileQueryVO` 字段：`id, name, originalName, url, size, bizType, createdAt`

- [ ] **Step 11.3:** `SysFileController`：
  - 类级 `@AutoPermission("sys:file:upload")`
  - `@PostMapping("/upload")` → `upload(file, bizType, storage?)` 
    - 校验 `bizType` 格式（`FileBizType.normalize()`）；不再校验「是否已注册」
    - 加载 `FileProperties.bizTypes[bizType]`，校验大小/扩展名
    - 调 `FileStorageRouter` 选实现 → `upload`
    - 算 sha256（`DigestUtils.sha256Hex`）
    - 落 `sys_file`
    - 调 `UploadEventPublisher.publish(...)`
    - 返回 `Result.ok(vo)`
  - `@GetMapping("/file/{id}")` → `@AutoPermission("sys:file:query")` 查询单条
  - `@GetMapping("/file/page")` → 分页查询
  - `@DeleteMapping("/file/{id}")` → `@AutoPermission("sys:file:delete")` 删除
  - 使用 `BaseController<...>` 或独立 `@RestController`（推荐独立，路径 `/storage`）

- [ ] **Step 11.4:** 编译通过

- [ ] **Step 11.5:** 提交 `feat(storage): 文件上传/查询/删除接口`

---

### Task 12: Event Publishers

**Files:**
- Create: `UploadEventPayload.java`
- Create: `UploadEventPublisher.java`
- Create: `FileDeletedEventPublisher.java`

- [ ] **Step 12.1:** `UploadEventPayload` POJO 字段与设计文档 §8.2 一致，标注 `@JSONField` 序列化

- [ ] **Step 12.2:** `UploadEventPublisher`：
  - `@Component @RequiredArgsConstructor`
  - 注入 `MqClient`
  - `publish(String bizType, SysFile entity, String url, Long uploaderId, Long tenantId, JSONObject extra)` （bizType 是已规范化的字符串，type = FileBizType.uploadType(bizType)）
  - 内部 `mqClient.publish(MqProvider.REDIS, MqTopicConstants.ON_UPLOAD, payload)`
  - 失败只 `log.error`，不抛（避免上传回滚）

- [ ] **Step 12.3:** `FileDeletedEventPublisher` 同上结构，topic 用 `ON_FILE_DELETED`

- [ ] **Step 12.4:** 编译通过

- [ ] **Step 12.5:** 提交 `feat(storage): ON_UPLOAD/ON_FILE_DELETED 事件推送`

---

### Task 13: 集成到 rui-service-starter

**Files:**
- Modify: `rui-service/rui-service-starter/pom.xml`
- Modify: `rui-service/rui-service-starter/.../StarterApplication.java`
- Modify: `rui-service/rui-service-starter/src/main/resources/application.yml`

- [ ] **Step 13.1:** `pom.xml` 加 `<dependency> rui-service-storage </dependency>`

- [ ] **Step 13.2:** `StarterApplication` 的 `@ComponentScan` 加 `"com.rui.service.storage"`

- [ ] **Step 13.3:** `application.yml` 的 `rui.modules.available` 数组加 `code: storage, name: 文件存储, icon: tabler:cloud-upload`

- [ ] **Step 13.4:** 编译 `mvn -pl rui-service/rui-service-starter -am compile` 通过

- [ ] **Step 13.5:** 提交 `feat(starter): 集成 rui-service-storage`

---

### Task 14: 公共配置示例

**Files:**
- Modify: `docs/backend/config-templates/application-template.yml` 或 `rui-common.yaml` Nacos 配置

- [ ] **Step 14.1:** 在公共 yaml 模板加 `rui.file` 配置（active / defaultMaxSize / bizTypes 字典）参照设计文档 §9.1

- [ ] **Step 14.2:** 提交 `docs(config): rui.file 公共配置示例`

---

### Task 15: 编译验证

- [ ] **Step 15.1:** `mvn clean compile -DskipTests` 全部模块通过

- [ ] **Step 15.2:** 若有编译错误，按模块修复

---

### Task 16: 推送 + 关闭 Gitea #4

- [ ] **Step 16.1:** 累计 commit 数 ≥10 时 `git push origin main`

- [ ] **Step 16.2:** 通过 `bin/gitea-helper.sh issue-comment --id 4 --body "..."` 回复实现说明

- [ ] **Step 16.3:** `bin/gitea-helper.sh issue-close --id 4` 关闭工单

---

## 实施计划检查清单

### 规范覆盖检查

| 规范要求 | 对应任务 | 状态 |
|---------|---------|------|
| 公共常量集中 (MqTopicConstants) | Task 1 | ☐ |
| 业务类型工具类 (FileBizType，非枚举) | Task 1 | ☑ |
| 数据库继承 BaseEntity | Task 10 | ☐ |
| Strategy 模式可插拔 | Tasks 5-9 | ☐ |
| 内置 @AutoPermission 鉴权 | Task 11 | ☐ |
| 统一 Result<T> 返回 | Task 11 | ☐ |
| MQ pub/sub 事件推送 | Task 12 | ☐ |
| 集成聚合启动器 | Task 13 | ☐ |
| 配置分层 (Nacos 规则) | Task 14 | ☐ |
| 最终编译通过 | Task 15 | ☐ |
| Gitea #4 关闭 | Task 16 | ☐ |

### 验收点
- [ ] 上传 .pem 文件返回标准 Result，data.url 可访问
- [ ] 超大文件/不允许扩展名/未知 bizType 均返回 400
- [ ] Redis 收到 ON_UPLOAD 消息
- [ ] 删除后 Redis 收到 ON_FILE_DELETED 消息
- [ ] 无 JWT 返回 401，无权限返回 403
- [ ] `rui-service-starter` 启动时 storage 子模块同时激活
- [ ] Gitea #4 已关闭
- [ ] 全部 commit 推送至 origin/main

### 无占位符检查
- [ ] 无 "TBD"、"TODO"、"implement later"
- [ ] 文件路径全部相对项目根目录
- [ ] 字段命名符合 MyBatis Plus 驼峰转下划线
- [ ] 每个步骤可独立 commit + 编译

---

**计划完成！**

保存路径：`docs/superpowers/plans/2026-06-07-file-storage-service-plan.md`
设计参考：`docs/superpowers/specs/2026-06-07-file-storage-service-design.md`

**执行选项：**
1. **Subagent-Driven（推荐）** — 每个任务分派独立子代理
2. **Inline Execution** — 当前会话连续执行，编译错误时停下确认