# 2026-04-11 企业级目标架构重构计划

## 1. 计划目标

本计划用于把当前仓库从“围绕现有功能堆叠的全栈实现”重构到 [architecture.md](C:/Users/yoyuz/Documents/code/my_site/docs/architecture.md) 定义的目标态企业架构。

目标不是做一次大爆炸式重写，而是按阶段把当前代码收敛到以下稳定形态：

1. 统一身份与授权模型
2. 工作空间与内容资产彻底分离
3. 分享与快传成为两个独立业务域
4. 上传成为内容接入机制，不再直接等同于文件业务
5. 后台任务成为统一异步处理底座
6. 存储策略成为系统级治理能力
7. 管理端成为治理入口，不再夹杂业务规则事实源

## 2. 当前基线

### 2.1 后端当前包结构

- `auth`
- `files.core`
- `files.upload`
- `files.share`
- `files.search`
- `files.events`
- `files.tasks`
- `files.storage`
- `files.policy`
- `transfer`
- `admin`
- `common`
- `config`
- `api.v2`

### 2.2 前端当前结构

- `pages`
- `admin`
- `lib`
- `components`
- `hooks`
- `mobile-pages`
- `mobile-components`

### 2.3 已完成的重构基础

根据 `memory.md`，以下基础性工作已经完成，可以作为本计划起点：

1. `BackgroundTaskRetryPolicy`、`BackgroundTaskStateManager`、`BackgroundTaskStateKeys` 已从 `BackgroundTaskService` 中抽离
2. `UploadPolicyResolver` 与 `UploadSessionStateMachine` 已从上传会话主服务中抽离
3. `AuthSessionPolicy` 已从 `AuthService` 中抽离
4. 文件事件链路已拆出：
   - `FileEventService`
   - `FileEventDispatcher`
   - `FileEventPayloadCodec`
5. 自动媒体元数据任务的 `correlationId` 幂等已经具备数据库级唯一约束

这说明当前代码已经有了第一批“规则抽离”的基础，但还没有进入真正的领域边界重组阶段。

## 3. 重构范围

本计划覆盖：

- 后端领域重组
- 后端 API 收口
- 权限模型统一
- 内容资产模型统一
- 管理端权限和设置边界统一
- 前端按业务域重组

本计划不覆盖：

- UI 视觉重设计
- Android 原生壳单独重写
- 全量 API 一次性废弃
- 数据库从零重建

## 4. 目标态模块映射

### 4.1 后端目标模块

目标态后端按业务域划分为：

- `identity-access`
- `workspace`
- `content-asset`
- `sharing`
- `transfer`
- `async-job`
- `storage-governance`
- `operations-admin`
- `common-kernel`

### 4.2 当前到目标的主要映射

| 当前模块 | 目标模块 | 说明 |
| --- | --- | --- |
| `auth` | `identity-access` | 保留认证能力，但要升级成统一账号、会话、角色、授权模型 |
| `files.core` | `workspace` + `content-asset` | 当前最需要拆分的模块 |
| `files.upload` | `content-asset` + `storage-governance` | 上传接入和存储策略不应继续混在文件业务里 |
| `files.share` | `sharing` | 需要收口旧分享与 v2 分享语义 |
| `transfer` | `transfer` | 保留域名，但拆分在线/离线子域和导入边界 |
| `files.tasks` | `async-job` | 升级为统一异步底座 |
| `files.events` | `workspace` + `async-job` 支撑层 | 事件不是独立业务域，应下沉为基础能力 |
| `files.policy` + `files.storage` | `storage-governance` | 统一存储策略、能力、迁移和对象落点 |
| `admin` | `operations-admin` | 从“全能 service”重构成治理入口 |
| `api.v2` | 各域 `api` 层 | 最终应按领域归属，而不是平行于领域存在 |

### 4.3 前端目标模块

目标态前端按业务域收口为：

- `account`
- `workspace`
- `sharing`
- `transfer`
- `admin`
- `common`

当前的 `pages`、`mobile-pages`、`lib` 需要逐步按领域拆解，而不是继续按“页面+工具库”累计。

## 5. 重构总策略

### 5.1 先抽规则，再拆边界

先把高价值业务规则从胖 Service 中抽成稳定规则对象，再移动目录和模块边界。  
这样可以避免“边拆边改语义”。

### 5.2 先统一模型，再收口接口

先统一后端领域模型，再决定哪些旧接口保留、哪些 v2 接口成为唯一主线。  
不要先删接口，再倒逼领域重构。

### 5.3 先后端领域，后前端跟随

这轮重构必须以后端领域边界为主。  
前端模块化重组应跟随后端稳定领域，而不是反过来。

### 5.4 每阶段都要可回归验证

每个阶段必须能在当前仓库命令范围内验证：

- `cd backend && mvn test`
- `cd front && npm run lint`
- `cd front && npm run build`

前端当前没有稳定的测试执行链路，因此阶段验收主要依赖类型检查、构建和关键后端回归。

## 6. 阶段计划

## 阶段 0：冻结目标语义和兼容边界

### 目标

在开始大规模结构调整前，先冻结必须保持一致的业务语义和兼容边界。

### 产出

1. 唯一的角色模型：`VISITOR / MEMBER / OPERATOR / ADMIN`
2. 唯一的资源模型：`WorkspaceNode` 与 `ContentAsset` 分离
3. 唯一的管理权限事实源
4. 分享与快传的边界定义
5. 旧接口与新接口的兼容期说明

### 当前代码关注点

- `auth/*`
- `admin/AdminAccessEvaluator.java`
- `config/SecurityConfig.java`
- `files/core/FileService.java`
- `files/share/ShareV2Service.java`
- `transfer/TransferService.java`

### 必须先确认的决策

1. 是否废弃“管理员用户名白名单决定权限”这条规则
2. 是否保留旧 `/api/files/share-links/**`
3. 是否保留旧 `/api/files/upload/**`
4. `maxDownloads` 是否继续同时约束导入和下载
5. `MODERATOR` 是否升级为 `OPERATOR`，还是直接移除

### 验收标准

- 目标语义形成一份可执行的决策基线
- 所有后续代码改动都不再重新定义这些问题

## 阶段 1：统一身份与授权域

### 目标

把当前 `auth + admin 权限入口 + session 规则` 重构为独立的 `identity-access` 域。

### 需要解决的问题

1. `User.role` 与 admin 白名单的双事实源
2. access token 吊销、refresh token 旋转、活跃会话切换分散在不同位置
3. 管理权限和资源权限没有统一授权模型

### 主要动作

1. 引入统一授权上下文
2. 抽出角色判断和资源授权入口
3. 让 `AuthSessionPolicy` 成为唯一会话规则入口
4. 让 admin 鉴权走角色/权限模型，而不是用户名白名单
5. 把 `DevAuthController` 对正式授权模型的影响限制在开发环境边界内

### 涉及文件

- `backend/src/main/java/com/yoyuzh/auth/*`
- `backend/src/main/java/com/yoyuzh/admin/AdminAccessEvaluator.java`
- `backend/src/main/java/com/yoyuzh/config/SecurityConfig.java`

### 阶段结果

- 管理台权限不再依赖用户名硬编码
- 登录态失效和客户端会话规则由统一策略控制

### 验收标准

- 所有受保护接口都能通过统一授权入口判断
- 改密、封禁、重登、刷新不再各写一套会话切换逻辑
- `cd backend && mvn test` 通过

## 阶段 2：拆分工作空间域与内容资产域

### 目标

把当前 `files.core` 这个胖模块拆成两个稳定业务域：

- `workspace`
- `content-asset`

### 需要解决的问题

1. `StoredFile` 同时承担路径、逻辑生命周期、物理内容引用
2. `FileBlob` / `FileEntity` / `StoredFile` 三层模型没有清晰主从边界
3. 删除、复制、导入、恢复同时跨逻辑层和物理层

### 目标模型

- `WorkspaceNode` 负责：
  - 层级
  - 名称
  - 所有权
  - 回收站生命周期
- `ContentAsset / ContentVersion` 负责：
  - 物理对象
  - 版本
  - 派生资产
  - 内容不可变性

### 主要动作

1. 给 `files.core` 划清“逻辑节点操作”和“内容对象操作”
2. 让复制、导入、恢复优先操作逻辑节点绑定，而不是直接操作底层对象
3. 把目录树逻辑从内容对象读写中剥离
4. 让最终清理只依赖内容引用与保留策略

### 涉及文件

- `backend/src/main/java/com/yoyuzh/files/core/*`
- `backend/src/main/java/com/yoyuzh/files/storage/*`
- `backend/src/main/java/com/yoyuzh/files/policy/*`

### 阶段结果

- 路径、目录、回收站归工作空间域
- 内容对象、版本、派生产物归内容资产域

### 验收标准

- 普通文件操作不再直接驱动物理对象行为
- 内容版本成为稳定对象，逻辑节点只是引用它
- `cd backend && mvn test` 通过

## 阶段 3：收口上传与存储治理

### 目标

把上传从“文件业务的一部分”收敛为“内容接入机制”，并把存储策略升级为系统级治理域。

### 需要解决的问题

1. 旧上传和 v2 上传双轨并存
2. 上传规则在 `FileService` 和 `UploadSessionService` 中重复
3. 上传模式由实现细节驱动，而不是标准化能力模型驱动

### 主要动作

1. 让 `UploadPolicyResolver` 成为唯一上传规则入口
2. 让上传完成只产生 `ContentVersion`
3. 工作空间节点创建放到上传完成后的业务编排层
4. 收口旧 `/api/files/upload/**` 到兼容层，新的正式能力只保留 v2 上传会话
5. 统一 `StoragePolicy`、能力矩阵、对象大小限制和迁移约束

### 涉及文件

- `backend/src/main/java/com/yoyuzh/files/upload/*`
- `backend/src/main/java/com/yoyuzh/files/policy/*`
- `backend/src/main/java/com/yoyuzh/files/storage/*`
- `backend/src/main/java/com/yoyuzh/files/core/FileService.java`
- `backend/src/main/java/com/yoyuzh/api/v2/files/UploadSessionV2Controller.java`

### 阶段结果

- 上传成为统一接入层
- 存储治理成为独立域

### 验收标准

- 上传规则只有一套事实源
- v2 上传成为正式主线
- `cd backend && mvn test` 通过

## 阶段 4：收口分享域

### 目标

把分享从当前“旧接口 + v2 接口并存”收敛为统一的 `sharing` 域。

### 需要解决的问题

1. 分享存在旧接口和 v2 接口双轨
2. 分享额度、密码、导入和下载权限没有形成统一策略模型
3. 分享导入逻辑过于依赖底层文件实现

### 主要动作

1. 定义统一的 `ShareGrant` 模型
2. 把分享的访问、下载、导入权限归到同一个策略对象
3. 明确“分享对外公开的是逻辑节点，不是底层内容对象”
4. 旧分享接口保留兼容包装层，内部转发到统一分享域

### 涉及文件

- `backend/src/main/java/com/yoyuzh/files/share/*`
- `backend/src/main/java/com/yoyuzh/api/v2/shares/*`
- `backend/src/main/java/com/yoyuzh/files/core/FileController.java`
- `backend/src/main/java/com/yoyuzh/files/core/FileService.java`

### 阶段结果

- 分享只有一套规则和一套内部模型

### 验收标准

- 分享创建、访问、下载、导入都通过统一服务入口
- 旧接口只剩兼容职责
- `cd backend && mvn test` 通过

## 阶段 5：拆分快传域

### 目标

把当前 `transfer` 模块拆成真正的传输域，而不是继续由 `TransferService` 统管在线、离线、上传、导入、容量判断。

### 需要解决的问题

1. 在线快传和离线快传当前共用一个胖 Service
2. 离线快传 ready、上传、容量、导入耦合严重
3. 快传与分享的边界仍然容易混淆

### 主要动作

1. 拆出：
   - `OnlineTransferService`
   - `OfflineTransferService`
   - `OfflineTransferQuotaService`
   - `TransferImportService`
2. 在线快传只保留临时连接语义
3. 离线快传只保留临时托管语义
4. 导入动作通过工作空间/内容资产编排层完成

### 涉及文件

- `backend/src/main/java/com/yoyuzh/transfer/*`
- `front/src/lib/transfer.ts`
- `front/src/pages/Transfer.tsx`

### 阶段结果

- 在线和离线快传成为两个清晰子域
- 快传导入不再直接绑死旧文件实现

### 验收标准

- 在线和离线业务规则拆分完成
- 离线容量和 ready 条件成为独立规则入口
- `cd backend && mvn test` 通过

## 阶段 6：统一异步任务域

### 目标

把当前 `files.tasks` 从“文件附属模块”升级为平台级 `async-job` 域。

### 需要解决的问题

1. 任务模型仍然偏文件中心
2. 任务状态 JSON 和运行机制还没有完全 typed 化
3. 任务类型与业务域之间的边界仍不清晰

### 主要动作

1. 把任务分成：
   - 命令入口
   - 执行入口
   - 重试策略
   - 状态表示
   - 幂等入口
2. 用 typed state 逐步替代广泛的 JSON merge
3. 把任务从文件附属实现提升为可服务多个业务域的统一底座

### 涉及文件

- `backend/src/main/java/com/yoyuzh/files/tasks/*`
- `backend/src/main/java/com/yoyuzh/common/broker/*`
- `backend/src/main/java/com/yoyuzh/api/v2/tasks/*`

### 阶段结果

- 异步任务成为独立业务底座

### 验收标准

- 新任务类型不再需要复制粘贴状态处理逻辑
- 任务状态推进和重试规则有唯一实现
- `cd backend && mvn test` 通过

## 阶段 7：重构管理域

### 目标

把当前 `admin` 从“聚合各种系统能力的大 Service”重构成真正的 `operations-admin` 治理入口。

### 需要解决的问题

1. 可写设置与运行时快照混在一起
2. 管理能力和业务领域对象之间缺少稳定的边界
3. 权限、审计和治理动作没有形成一致模型

### 主要动作

1. 拆出：
   - `AdminConfigSnapshotService`
   - `AdminMutableSettingsService`
   - `AdminUserGovernanceService`
   - `AdminStorageGovernanceService`
   - `AdminAuditService`
2. 让管理端只调用各领域的治理接口，而不是直接承载业务规则
3. 把审计作为显式能力引入

### 涉及文件

- `backend/src/main/java/com/yoyuzh/admin/*`

### 阶段结果

- 管理域从“胖 service”变成治理编排层

### 验收标准

- 设置、治理、审计分离
- 管理端不再承担业务事实源
- `cd backend && mvn test` 通过

## 阶段 8：前端按业务域重组

### 目标

让前端结构跟随后端领域，而不是继续沿 `pages + lib + mobile-pages` 演进。

### 主要动作

1. 把 `pages` 和 `mobile-pages` 按域拆成：
   - `account`
   - `workspace`
   - `sharing`
   - `transfer`
   - `admin`
   - `common`
2. 把 `lib` 中的接口调用和状态逻辑迁移到领域内部
3. 统一桌面端和移动端页面的业务入口，只保留展示层差异

### 涉及文件

- `front/src/pages/*`
- `front/src/mobile-pages/*`
- `front/src/lib/*`
- `front/src/admin/*`
- `front/src/App.tsx`

### 阶段结果

- 前端与后端都围绕同一领域模型组织

### 验收标准

- `cd front && npm run lint` 通过
- `cd front && npm run build` 通过

## 7. 先后顺序与依赖

严格顺序建议如下：

1. 阶段 0：冻结语义
2. 阶段 1：身份与授权
3. 阶段 2：工作空间 / 内容资产拆分
4. 阶段 3：上传 / 存储治理收口
5. 阶段 4：分享域收口
6. 阶段 5：快传域拆分
7. 阶段 6：异步任务域统一
8. 阶段 7：管理域重构
9. 阶段 8：前端域化重组

依赖关系：

- 身份与授权必须先于管理域重构
- 工作空间 / 内容资产拆分必须先于分享和快传彻底收口
- 上传 / 存储治理必须先于内容资产域稳定
- 前端域化必须放在后端领域边界稳定之后

## 8. 每阶段的兼容要求

### 后端兼容要求

- 每个阶段优先保持现有 API 对外行为稳定
- 旧接口可以保留兼容层，但内部必须逐步转发到目标域模型
- 不在同一阶段同时做“领域重组 + 外部 API 大改”

### 数据兼容要求

- 不允许把现有数据迁移风险和领域重构耦合在同一批次
- 引入新模型时，优先通过双写、映射或兼容读过渡

### 前端兼容要求

- 路由和核心页面入口在后端领域稳定前尽量保持
- 先迁移数据访问层，再迁移页面结构

## 9. 验收与验证命令

每个后端阶段完成后至少执行：

```powershell
cd backend
mvn test
```

每个前端阶段完成后至少执行：

```powershell
cd front
npm run lint
npm run build
```

如果阶段只改后端，不额外要求前端构建。  
如果阶段只改前端，也应确认依赖的 API 契约没有被破坏。

## 10. 本轮建议先开做的具体批次

如果从当前代码直接开工，建议先做下面三个批次：

### 批次 A：身份与授权统一

- 去掉 admin 白名单作为最终权限事实源
- 统一 `AuthSessionPolicy` 的会话失效入口
- 让 `/api/admin/**` 接入统一授权判断

### 批次 B：工作空间与内容资产拆分第一刀

- 先在 `files.core` 内部分出“工作空间节点规则”和“内容资产规则”
- 不急着改数据库表名，先改代码归属

### 批次 C：上传与分享收口

- 让上传只产生内容接入结果
- 让分享只依赖逻辑节点授权
- 旧上传和旧分享接口退化为兼容层

这三个批次完成后，整套系统才真正具备继续深度重构的稳定底盘。