Refactor backend and frontend modules for architecture alignment
This commit is contained in:
yoyuzh
@@ -271,7 +271,7 @@
|
||||
- 媒体处理开关
|
||||
- Redis / runtime 只读状态
|
||||
|
||||
- [ ] **Step 1: 设计参数设置 DTO 与权限边界**
|
||||
- [x] **Step 1: 设计参数设置 DTO 与权限边界**
|
||||
- [ ] **Step 2: 先拆站点信息子分组**
|
||||
- 站点名称
|
||||
- 站点描述
|
||||
@@ -299,9 +299,9 @@
|
||||
- 前端品牌化字段
|
||||
- CDN / 静态资源缓存参数
|
||||
- 服务器运行信息、Redis 状态、存储后端状态
|
||||
- [ ] **Step 2: 暴露管理员参数读取与更新接口**
|
||||
- [ ] **Step 3: 只允许修改当前可安全热更新的参数**
|
||||
- [ ] **Step 4: 文档化哪些配置仍需环境变量或重启**
|
||||
- [x] **Step 2: 暴露管理员参数读取与更新接口**
|
||||
- [x] **Step 3: 只允许修改当前可安全热更新的参数**
|
||||
- [x] **Step 4: 文档化哪些配置仍需环境变量或重启**
|
||||
|
||||
### Admin-B2: File System
|
||||
|
||||
@@ -710,3 +710,32 @@
|
||||
- `cd backend && mvn -Dtest=AdminControllerIntegrationTest,AdminServiceTest,AdminServiceStoragePolicyCacheTest test`
|
||||
- `cd backend && mvn test`
|
||||
- Full backend result after this landing note: 304 tests passed.
|
||||
|
||||
## 2026-04-11 Admin Next-Phase Backend Landing Note 2
|
||||
|
||||
- Admin-B1 and Admin-B2 have now both started with read-only backend surfaces.
|
||||
- Implemented:
|
||||
- `GET /api/admin/settings`
|
||||
- `GET /api/admin/filesystem`
|
||||
- `GET /api/admin/settings` currently stops at backend-owned observation: invite-code state, configured admin usernames, JWT/user-session timing, Redis/token-blacklist availability, queue cadence, and storage/Redis runtime mode.
|
||||
- `GET /api/admin/filesystem` currently stops at operational observation: default policy snapshot, resolved upload-mode matrix, effective max file size, metadata/thumbnail capability flags, cache backend/TTL status, aggregate file/blob/entity counts, and reserved-off `WebDAV` state.
|
||||
- This batch intentionally does not introduce writable parameter settings yet. Hot-update safety boundaries and persistent admin writes remain part of the next Admin-B1 follow-up.
|
||||
- Verification passed in WSL with:
|
||||
- `cd backend && mvn -Dtest=AdminControllerIntegrationTest,AdminServiceTest,AdminServiceStoragePolicyCacheTest test`
|
||||
- `cd backend && mvn test`
|
||||
|
||||
## 2026-04-11 Admin Next-Phase Backend Landing Note 3
|
||||
|
||||
- Admin-B1 has now moved beyond read-only snapshots into the first bounded write path.
|
||||
- Implemented:
|
||||
- `PATCH /api/admin/settings/registration/invite-code`
|
||||
- `POST /api/admin/settings/registration/invite-code/rotate`
|
||||
- `GET /api/admin/settings` now also returns per-section `writeSupported` flags and a `transfer` section exposing the persisted offline-transfer storage limit.
|
||||
- Current hot-update boundary is explicit:
|
||||
- writable now: current registration invite code, offline transfer storage limit;
|
||||
- still read-only/runtime-derived: admin usernames, JWT lifetimes, Redis enablement and TTL policy, queue backend/cadence, storage provider, and other environment-bound server settings.
|
||||
- The invite-code write path is deliberately backed by the existing `RegistrationInviteState` row instead of introducing a generic mutable config store.
|
||||
- Verification passed in WSL with:
|
||||
- `cd backend && mvn -Dtest=AdminControllerIntegrationTest,AdminServiceTest,AdminServiceStoragePolicyCacheTest test`
|
||||
- `cd backend && mvn test`
|
||||
- Full backend result after this batch: 310 tests passed.
|
||||
|
||||
@@ -0,0 +1,620 @@
|
||||
# Frontend Upgrade Modules Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED: Use `superpowers:executing-plans` or `superpowers:subagent-driven-development` when implementing this plan. Keep checkbox state updated when modules land.
|
||||
|
||||
**Goal:** 为当前项目整理一份独立的前端升级计划书，明确为了配合现有 v2 能力闭环、运行时能力升级、媒体预览和后续 WebDAV/平台化演进，前端还需要新增或重构哪些模块。
|
||||
|
||||
**Repository:** `C:\Users\yoyuz\Documents\code\my_site`
|
||||
|
||||
## 1. Current Frontend Baseline
|
||||
|
||||
当前前端已经具备：
|
||||
|
||||
- 桌面端主路由：`/overview`、`/files`、`/tasks`、`/shares`、`/recycle-bin`、`/transfer`、`/admin/*`
|
||||
- 移动端壳与底部导航
|
||||
- 文件页基础搜索、上传、分享、删除、回收站入口
|
||||
- 任务页和概览页的后台任务消费
|
||||
- 分享页与分享列表页
|
||||
- 管理台用户、文件、存储策略页面
|
||||
- `front/src/lib/*` 下的 API helper 已基本分层
|
||||
|
||||
当前明显缺的前端模块不是“页面太少”，而是：
|
||||
|
||||
- 缺统一的客户端运行时状态层
|
||||
- 缺缓存感知与失效感知
|
||||
- 缺跨页面的上传状态中心
|
||||
- 缺更完整的任务入口和任务消费组件
|
||||
- 缺媒体预览组件体系
|
||||
- 缺移动端对应能力补齐
|
||||
- 缺面向多实例和运行时状态变化的前端协作层
|
||||
|
||||
## 2. Upgrade Stage Alignment
|
||||
|
||||
这份前端计划对应的是本轮总升级里的全部前端侧工作。与主升级计划的关系如下：
|
||||
|
||||
### Stage 1: Runtime Foundation
|
||||
|
||||
前端对应模块：
|
||||
|
||||
- Session And Auth Runtime
|
||||
- Files Data And Directory Cache
|
||||
- Upload Runtime
|
||||
- Tasks Runtime
|
||||
- Realtime Event Bridge
|
||||
- Admin Operations Surface
|
||||
|
||||
前端目标：
|
||||
|
||||
- 正确消费 token 黑名单和登录态失效
|
||||
- 感知热门目录缓存与失效
|
||||
- 消费上传状态缓存
|
||||
- 为异步任务和多实例事件刷新预留前端运行时
|
||||
|
||||
### Stage 2: Close Existing v2 Gaps
|
||||
|
||||
前端对应模块：
|
||||
|
||||
- Files Data And Directory Cache
|
||||
- Upload Runtime
|
||||
- Tasks Runtime
|
||||
- Mobile Capability Parity
|
||||
|
||||
前端目标：
|
||||
|
||||
- 移动端搜索补齐
|
||||
- archive/extract 前端入口补齐
|
||||
- 移动端任务入口补齐
|
||||
- 旧读取链路切换后的 UI 消费收口
|
||||
|
||||
### Stage 3: Thumbnail And Rich Media Pipeline
|
||||
|
||||
前端对应模块：
|
||||
|
||||
- Media Preview System
|
||||
- Tasks Runtime
|
||||
- Mobile Capability Parity
|
||||
|
||||
前端目标：
|
||||
|
||||
- 文件列表缩略图
|
||||
- 详情侧栏 / 弹层预览
|
||||
- 视频时长、poster、媒体属性展示
|
||||
- 缩略图与媒体任务状态反馈
|
||||
|
||||
### Stage 4: Metadata, Labels, And Search Expansion
|
||||
|
||||
前端对应模块：
|
||||
|
||||
- Files Data And Directory Cache
|
||||
- Media Preview System
|
||||
- Mobile Capability Parity
|
||||
|
||||
前端目标：
|
||||
|
||||
- 高级搜索
|
||||
- 标签与 metadata 筛选
|
||||
- 搜索条件与目录视图解耦
|
||||
|
||||
### Stage 5: WebDAV Minimum Viable Support
|
||||
|
||||
前端对应模块：
|
||||
|
||||
- Session And Auth Runtime
|
||||
- Admin Operations Surface
|
||||
|
||||
前端目标：
|
||||
|
||||
- 如后端采用应用密码 / 专用凭据，则前端需要提供管理入口
|
||||
- 管理台提供 WebDAV / 外部客户端配置展示位
|
||||
|
||||
## 3. Frontend Module Map
|
||||
|
||||
建议把后续前端升级拆成 8 个模块域：
|
||||
|
||||
1. Session & Auth Runtime
|
||||
2. Files Data & Directory Cache
|
||||
3. Upload Runtime
|
||||
4. Tasks Runtime
|
||||
5. Realtime Event Bridge
|
||||
6. Media Preview System
|
||||
7. Admin Operations Surface
|
||||
8. Mobile Capability Parity
|
||||
|
||||
## 4. Admin IA Alignment
|
||||
|
||||
参考成熟项目后台目录，当前前端管理台后续不应只保留：
|
||||
|
||||
- Dashboard
|
||||
- Users
|
||||
- Files
|
||||
- Storage Policies
|
||||
|
||||
而应逐步演进为如下信息架构：
|
||||
|
||||
1. 面板首页
|
||||
2. 参数设置
|
||||
3. 文件系统
|
||||
4. 存储策略
|
||||
5. 节点
|
||||
6. 用户组
|
||||
7. 用户
|
||||
8. 文件
|
||||
9. 文件 Blob
|
||||
10. 分享
|
||||
11. 后台任务
|
||||
12. 订单
|
||||
13. 事件
|
||||
14. 滥用举报
|
||||
15. OAuth 应用
|
||||
|
||||
当前项目前端建议分三层推进：
|
||||
|
||||
### Layer A: 当前阶段必须补齐
|
||||
|
||||
- 面板首页
|
||||
- 参数设置
|
||||
- 文件系统
|
||||
- 存储策略
|
||||
- 用户
|
||||
- 文件
|
||||
- 文件 Blob
|
||||
- 分享
|
||||
- 后台任务
|
||||
|
||||
### Layer B: 预留导航位但可先只读或隐藏
|
||||
|
||||
- OAuth 应用
|
||||
- 节点
|
||||
- 用户组
|
||||
|
||||
### Layer C: 暂不实现
|
||||
|
||||
- 订单
|
||||
- 事件独立中心
|
||||
- 滥用举报
|
||||
|
||||
前端管理台路由最终建议朝这个结构靠拢：
|
||||
|
||||
- `/admin/dashboard`
|
||||
- `/admin/settings`
|
||||
- `/admin/filesystem`
|
||||
- `/admin/storage-policies`
|
||||
- `/admin/users`
|
||||
- `/admin/files`
|
||||
- `/admin/file-blobs`
|
||||
- `/admin/shares`
|
||||
- `/admin/tasks`
|
||||
- `/admin/oauth-apps`
|
||||
|
||||
其中两个最重要的二级结构要先定下来：
|
||||
|
||||
### 参数设置页内部结构
|
||||
|
||||
建议采用顶部 tabs：
|
||||
|
||||
1. 站点信息
|
||||
2. 用户会话
|
||||
3. 验证码
|
||||
4. 媒体处理
|
||||
5. 增值服务
|
||||
6. 邮件
|
||||
7. 队列
|
||||
8. 外观
|
||||
9. 事件
|
||||
10. 服务器
|
||||
|
||||
当前项目建议：
|
||||
|
||||
- 先做可编辑：
|
||||
- 站点信息
|
||||
- 用户会话
|
||||
- 媒体处理
|
||||
- 队列
|
||||
- 外观
|
||||
- 先做只读：
|
||||
- 服务器
|
||||
- 先预留标签但不做深实现：
|
||||
- 验证码
|
||||
- 邮件
|
||||
- 事件
|
||||
- 当前不做：
|
||||
- 增值服务
|
||||
|
||||
### 文件系统页内部结构
|
||||
|
||||
建议采用顶部 tabs：
|
||||
|
||||
1. 参数设置
|
||||
2. 全文搜索
|
||||
3. 文件图标
|
||||
4. 文件浏览应用
|
||||
5. 自定义属性
|
||||
|
||||
当前项目建议：
|
||||
|
||||
- 先做：
|
||||
- 参数设置
|
||||
- 文件图标
|
||||
- 自定义属性
|
||||
- 先做只读壳：
|
||||
- 文件浏览应用
|
||||
- 当前延后：
|
||||
- 全文搜索
|
||||
|
||||
---
|
||||
|
||||
## 5. Module A: Session And Auth Runtime
|
||||
|
||||
**Goal:** 让前端能正确消费后端登录态策略升级后的失效语义，而不是继续把登录态仅看成本地 `portal-session`。
|
||||
|
||||
**Files likely involved:**
|
||||
|
||||
- `front/src/lib/api.ts`
|
||||
- `front/src/lib/auth.ts` 或新增对应模块
|
||||
- `front/src/App.tsx`
|
||||
- `front/src/pages/Login.tsx`
|
||||
- `front/src/components/layout/Layout.tsx`
|
||||
- `front/src/mobile-components/MobileLayout.tsx`
|
||||
- `front/src/hooks/*`
|
||||
|
||||
- [ ] **Step 1: 新增统一 session runtime 模块**
|
||||
- 负责 access token、refresh token、client id、client type、当前用户信息
|
||||
- 不让多个页面各自处理 401 / refresh / logout
|
||||
|
||||
- [ ] **Step 2: 补 token 撤销与强制失效感知**
|
||||
- 后端返回“token 已失效 / 已撤销 / 会话被顶掉”时统一退出
|
||||
- 区分普通 401 与“需要强制重新登录”的 401
|
||||
|
||||
- [ ] **Step 3: 新增全局 auth error handler**
|
||||
- 处理改密、管理员重置密码、封禁、同端挤下线
|
||||
- 避免文件页、任务页、分享页分别弹自己的错误
|
||||
|
||||
- [ ] **Step 4: 增加用户可见的会话状态提示组件**
|
||||
- 例如顶部 banner、toast 或 modal
|
||||
- 明确告诉用户“当前登录已失效，需要重新登录”
|
||||
|
||||
**Deliverables:**
|
||||
|
||||
- `session-runtime.ts`
|
||||
- `use-session-runtime.ts`
|
||||
- `AuthBoundary` 或同类组件
|
||||
- 全局 auth failure UI
|
||||
|
||||
---
|
||||
|
||||
## 6. Module B: Files Data And Directory Cache
|
||||
|
||||
**Goal:** 让前端能真正利用后端“热门目录缓存”，同时保持目录缓存、搜索结果、回收站和任务列表的边界清晰。
|
||||
|
||||
**Files likely involved:**
|
||||
|
||||
- `front/src/pages/files/FilesPage.tsx`
|
||||
- `front/src/mobile-pages/MobileFiles.tsx`
|
||||
- `front/src/lib/files.ts`
|
||||
- `front/src/lib/file-search.ts`
|
||||
- `front/src/lib/file-events.ts`
|
||||
- `front/src/lib/types.ts`
|
||||
- 可新增 `front/src/lib/files-cache.ts`
|
||||
|
||||
- [ ] **Step 1: 抽出统一的 files query key / cache key 生成模块**
|
||||
- 覆盖 `path + page + size + view mode + sort`
|
||||
- 不和搜索结果共用
|
||||
|
||||
- [ ] **Step 2: 新增目录数据缓存协调层**
|
||||
- 负责首屏读取、命中缓存、后台刷新、失效
|
||||
- 与 SSE 事件和上传完成后的本地刷新统一
|
||||
|
||||
- [ ] **Step 3: 把搜索视图和目录视图彻底解耦**
|
||||
- 搜索结果永不写回目录缓存
|
||||
- 清空搜索后才能回到目录态
|
||||
|
||||
- [ ] **Step 4: 增加“缓存命中但后台刷新中”的 UI 状态**
|
||||
- 避免用户误以为界面卡死
|
||||
- 尤其适合热门目录
|
||||
|
||||
**Deliverables:**
|
||||
|
||||
- `files-cache.ts`
|
||||
- `use-directory-data.ts`
|
||||
- 目录刷新状态 UI
|
||||
|
||||
---
|
||||
|
||||
## 7. Module C: Upload Runtime
|
||||
|
||||
**Goal:** 为后端上传状态能力做前端消费层，把上传队列从“局部页面状态”升级成“全局上传运行时”。
|
||||
|
||||
**Files likely involved:**
|
||||
|
||||
- `front/src/lib/upload-session.ts`
|
||||
- `front/src/pages/files/FilesPage.tsx`
|
||||
- `front/src/mobile-pages/MobileFiles.tsx`
|
||||
- `front/src/components/**/*`
|
||||
- 可新增 `front/src/lib/upload-runtime.ts`
|
||||
- 可新增 `front/src/components/upload/*`
|
||||
|
||||
- [ ] **Step 1: 新增全局 upload runtime store**
|
||||
- 管理上传项、会话 ID、进度、速度、错误、重试、取消
|
||||
- 桌面和移动共用
|
||||
|
||||
- [ ] **Step 2: 新增上传状态 polling / subscribe 模块**
|
||||
- 消费后端暴露的短生命周期上传状态
|
||||
- 保持与数据库最终状态分离
|
||||
|
||||
- [ ] **Step 3: 新增上传中心 UI**
|
||||
- 顶部悬浮面板或独立抽屉
|
||||
- 显示进行中、失败、完成
|
||||
|
||||
- [ ] **Step 4: 统一上传入口**
|
||||
- 文件页上传
|
||||
- “保存到网盘”
|
||||
- 后续 WebDAV 或外部导入触发后的状态展示
|
||||
|
||||
- [ ] **Step 5: 错误与恢复语义统一**
|
||||
- 会话过期
|
||||
- 分片失败
|
||||
- 容量不足
|
||||
- 锁冲突 / 重复提交
|
||||
|
||||
**Deliverables:**
|
||||
|
||||
- `upload-runtime.ts`
|
||||
- `use-upload-runtime.ts`
|
||||
- `UploadCenter`
|
||||
- `UploadItemCard`
|
||||
|
||||
---
|
||||
|
||||
## 8. Module D: Tasks Runtime
|
||||
|
||||
**Goal:** 把当前任务页和概览页里分散的后台任务消费统一成一个任务运行时模块，并补齐 archive/extract 的前端入口。
|
||||
|
||||
**Files likely involved:**
|
||||
|
||||
- `front/src/lib/background-tasks.ts`
|
||||
- `front/src/pages/Tasks.tsx`
|
||||
- `front/src/pages/Overview.tsx`
|
||||
- `front/src/pages/files/FilesPage.tsx`
|
||||
- `front/src/mobile-pages/MobileFiles.tsx`
|
||||
- 可新增 `front/src/lib/task-runtime.ts`
|
||||
- 可新增 `front/src/components/tasks/*`
|
||||
|
||||
- [ ] **Step 1: 抽出统一 task state parser**
|
||||
- 现在 `publicStateJson` 的解析不应只留在 `Tasks.tsx`
|
||||
|
||||
- [ ] **Step 2: 新增任务类型组件化展示**
|
||||
- `MEDIA_META`
|
||||
- `ARCHIVE`
|
||||
- `EXTRACT`
|
||||
- 后续 `THUMBNAIL`
|
||||
|
||||
- [ ] **Step 3: 为文件页增加任务快捷操作区**
|
||||
- 创建压缩
|
||||
- 创建解压
|
||||
- 提取媒体信息
|
||||
|
||||
- [ ] **Step 4: 为移动端增加最小任务能力**
|
||||
- 最近任务
|
||||
- 取消运行中任务
|
||||
- 查看失败原因
|
||||
|
||||
- [ ] **Step 5: 为异步任务 / 多实例任务更新预留刷新机制**
|
||||
- 支持轮询或事件驱动刷新
|
||||
|
||||
**Deliverables:**
|
||||
|
||||
- `task-runtime.ts`
|
||||
- `TaskSummaryPanel`
|
||||
- `TaskActionMenu`
|
||||
- `TaskStatusBadge`
|
||||
|
||||
---
|
||||
|
||||
## 9. Module E: Realtime Event Bridge
|
||||
|
||||
**Goal:** 把当前 SSE 文件事件消费升级为真正的“前端实时桥接层”，适配跨实例事件分发后的实时语义。
|
||||
|
||||
**Files likely involved:**
|
||||
|
||||
- `front/src/lib/file-events.ts`
|
||||
- `front/src/pages/files/FilesPage.tsx`
|
||||
- `front/src/mobile-pages/MobileFiles.tsx`
|
||||
- `front/src/pages/RecycleBin.tsx`
|
||||
- 可新增 `front/src/lib/realtime-runtime.ts`
|
||||
|
||||
- [ ] **Step 1: 把文件事件订阅从页面内逻辑抽到 runtime**
|
||||
- 管理连接、重连、暂停、恢复
|
||||
|
||||
- [ ] **Step 2: 增加事件去重与防抖层**
|
||||
- 防止事件总线广播 + 本地更新重复触发刷新
|
||||
|
||||
- [ ] **Step 3: 让目录页、回收站、任务页可订阅不同事件域**
|
||||
- 文件目录变更
|
||||
- 回收站恢复/删除
|
||||
- 任务状态刷新
|
||||
|
||||
- [ ] **Step 4: 增加连接质量 UI**
|
||||
- 如“实时同步中 / 已断开，正在重连”
|
||||
|
||||
**Deliverables:**
|
||||
|
||||
- `realtime-runtime.ts`
|
||||
- `use-realtime-status.ts`
|
||||
- `RealtimeStatusChip`
|
||||
|
||||
---
|
||||
|
||||
## 10. Module F: Media Preview System
|
||||
|
||||
**Goal:** 为缩略图、poster、视频时长和 richer preview 提供统一前端消费层。
|
||||
|
||||
**Files likely involved:**
|
||||
|
||||
- `front/src/pages/files/FilesPage.tsx`
|
||||
- `front/src/mobile-pages/MobileFiles.tsx`
|
||||
- `front/src/pages/FileShare.tsx`
|
||||
- `front/src/lib/files.ts`
|
||||
- `front/src/lib/types.ts`
|
||||
- 可新增 `front/src/components/media/*`
|
||||
|
||||
- [ ] **Step 1: 新增文件缩略图组件**
|
||||
- 图片缩略图
|
||||
- 视频封面
|
||||
- 加载中和失败 fallback
|
||||
|
||||
- [ ] **Step 2: 新增媒体元数据展示组件**
|
||||
- 时长
|
||||
- 尺寸
|
||||
- 基本编码信息
|
||||
|
||||
- [ ] **Step 3: 新增详情侧栏或预览弹层**
|
||||
- 桌面优先
|
||||
- 移动端先做简化版
|
||||
|
||||
- [ ] **Step 4: 为分享页补预览消费能力**
|
||||
- 不破坏密码保护和权限模型
|
||||
|
||||
**Deliverables:**
|
||||
|
||||
- `FileThumbnail`
|
||||
- `MediaMetadataPanel`
|
||||
- `FilePreviewDialog` 或同类组件
|
||||
|
||||
---
|
||||
|
||||
## 11. Module G: Admin Operations Surface
|
||||
|
||||
**Goal:** 让管理台能够消费运行时与平台化能力，而不只是停留在用户/文件/存储策略。
|
||||
|
||||
**Files likely involved:**
|
||||
|
||||
- `front/src/admin/*`
|
||||
- `front/src/lib/admin*.ts`
|
||||
- 可新增 `front/src/admin/runtime-dashboard.tsx`
|
||||
|
||||
- [ ] **Step 1: 重构管理台导航信息架构**
|
||||
- 从当前 4 个核心资源扩展为 dashboard / settings / filesystem / storage-policies / users / files / file-blobs / shares / tasks / oauth-apps
|
||||
- 移动端继续对 admin 路由做受限处理，不强行开放完整后台
|
||||
|
||||
- [ ] **Step 2: 新增参数设置页**
|
||||
- 展示和编辑当前允许后台维护的系统参数
|
||||
- 明确哪些配置只读、哪些可热更新
|
||||
- 使用 tabs 承载：站点信息 / 用户会话 / 验证码 / 媒体处理 / 增值服务 / 邮件 / 队列 / 外观 / 事件 / 服务器
|
||||
|
||||
- [ ] **Step 3: 新增文件系统页**
|
||||
- 展示上传模式、媒体处理、缓存、WebDAV、运行态能力
|
||||
- 使用 tabs 承载：参数设置 / 全文搜索 / 文件图标 / 文件浏览应用 / 自定义属性
|
||||
|
||||
- [ ] **Step 4: 新增文件 Blob 页**
|
||||
- 展示 Blob / Entity 列表、引用数、对象 key、策略、实体类型
|
||||
|
||||
- [ ] **Step 5: 新增分享管理页**
|
||||
- 展示分享状态、过期、下载数、查看数、密码保护状态
|
||||
|
||||
- [ ] **Step 6: 新增后台任务管理页**
|
||||
- 与用户侧任务页不同，这里展示全局任务池、失败分类、worker/lease 状态
|
||||
|
||||
- [ ] **Step 7: 新增 runtime 观测页或卡片**
|
||||
- 热门目录缓存命中
|
||||
- 队列积压
|
||||
- 强制失效 token 规模
|
||||
- 事件总线状态
|
||||
|
||||
- [ ] **Step 8: 新增任务运行态概览**
|
||||
- 缩略图、媒体处理、迁移任务分布
|
||||
|
||||
- [ ] **Step 9: 为后续 WebDAV / 外部客户端 / OAuth 应用预留管理入口**
|
||||
- 当前不必完整实现
|
||||
- 但前端信息架构要留位置和路由壳
|
||||
|
||||
**Deliverables:**
|
||||
|
||||
- `RuntimeDashboard`
|
||||
- `QueueHealthCard`
|
||||
- `CacheStatsCard`
|
||||
- `AdminSettingsPage`
|
||||
- `AdminSettingsSiteInfoTab`
|
||||
- `AdminSettingsSessionsTab`
|
||||
- `AdminSettingsMediaTab`
|
||||
- `AdminSettingsQueueTab`
|
||||
- `AdminSettingsAppearanceTab`
|
||||
- `AdminSettingsServerTab`
|
||||
- `AdminFilesystemPage`
|
||||
- `AdminFilesystemSettingsTab`
|
||||
- `AdminFilesystemIconsTab`
|
||||
- `AdminFilesystemViewerAppsTab`
|
||||
- `AdminFilesystemMetadataTab`
|
||||
- `AdminFileBlobsPage`
|
||||
- `AdminSharesPage`
|
||||
- `AdminTasksPage`
|
||||
- `AdminOAuthAppsPage`（可先空壳）
|
||||
|
||||
---
|
||||
|
||||
## 12. Module H: Mobile Capability Parity
|
||||
|
||||
**Goal:** 不让桌面端继续越走越远，所有新能力都要同步评估移动端最小实现。
|
||||
|
||||
**Files likely involved:**
|
||||
|
||||
- `front/src/mobile-pages/*`
|
||||
- `front/src/mobile-components/*`
|
||||
- `front/src/MobileApp.tsx`
|
||||
|
||||
- [ ] **Step 1: 移动端搜索能力补齐**
|
||||
- [ ] **Step 2: 移动端任务面板补齐**
|
||||
- [ ] **Step 3: 移动端上传中心补齐**
|
||||
- [ ] **Step 4: 移动端文件预览最小化接入**
|
||||
- [ ] **Step 5: 移动端实时状态提示补齐**
|
||||
|
||||
**Deliverables:**
|
||||
|
||||
- `MobileSearchBar`
|
||||
- `MobileTaskDrawer`
|
||||
- `MobileUploadCenter`
|
||||
- `MobilePreviewSheet`
|
||||
|
||||
---
|
||||
|
||||
## 13. Recommended Execution Order
|
||||
|
||||
1. Module A: Session And Auth Runtime
|
||||
2. Module B: Files Data And Directory Cache
|
||||
3. Module C: Upload Runtime
|
||||
4. Module D: Tasks Runtime
|
||||
5. Module E: Realtime Event Bridge
|
||||
6. Module H: Mobile Capability Parity
|
||||
7. Module F: Media Preview System
|
||||
8. Module G: Admin Operations Surface
|
||||
|
||||
## 14. Verification Rules
|
||||
|
||||
前端阶段验证只使用仓库已有命令：
|
||||
|
||||
- `cd front && npm run test`
|
||||
- `cd front && npm run lint`
|
||||
- `cd front && npm run build`
|
||||
|
||||
必要时补充手动验证：
|
||||
|
||||
- 登录失效与重新登录流程
|
||||
- 热门目录首屏和失效刷新
|
||||
- 上传中心状态变化
|
||||
- 任务创建、取消、失败重试
|
||||
- SSE/实时状态重连
|
||||
- 移动端同能力检查
|
||||
|
||||
## 15. Documentation Follow-Up
|
||||
|
||||
当前端新增关键模块后，需要同步更新：
|
||||
|
||||
- `memory.md`
|
||||
- `docs/architecture.md`
|
||||
- `docs/api-reference.md`
|
||||
|
||||
至少记录：
|
||||
|
||||
- 新前端运行时模块名称和职责
|
||||
- 与后端运行时能力的对应关系
|
||||
- 是否桌面/移动双端都已接入
|
||||
- 当前仍缺的 UI 闭环
|
||||
328
docs/superpowers/plans/2026-04-11-backend-refactor-plan.md
Normal file
328
docs/superpowers/plans/2026-04-11-backend-refactor-plan.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# 后端重构方案草案
|
||||
|
||||
## 一、需要重构的模块
|
||||
|
||||
1. 在线快传模块
|
||||
- 相关代码：`transfer/TransferService`、`transfer/TransferSessionStore`、`transfer/TransferSession`
|
||||
|
||||
2. 离线快传模块
|
||||
- 相关代码：`transfer/TransferService`、`OfflineTransferSessionRepository`、存储额度相关 admin 指标逻辑
|
||||
|
||||
3. 异步任务模块
|
||||
- 相关代码：`files/tasks/BackgroundTaskService`、`BackgroundTaskWorker`、`BackgroundTaskRepository`、`BackgroundTask`
|
||||
|
||||
4. Broker 消息模块
|
||||
- 相关代码：`common/broker/*`、`MediaMetadataTaskBrokerPublisher`、`MediaMetadataTaskBrokerConsumer`
|
||||
|
||||
5. 文件事件模块
|
||||
- 相关代码：`files/events/FileEventService`、`RedisFileEventPubSubPublisher`、`RedisFileEventPubSubListener`
|
||||
|
||||
6. 上传会话模块
|
||||
- 相关代码：`files/upload/UploadSessionService`、`UploadSessionRuntimeStateService`、`RedisUploadSessionRuntimeStateService`
|
||||
|
||||
7. 认证会话模块
|
||||
- 相关代码：`auth/AuthService`、`RefreshTokenService`、`AuthTokenInvalidationService`、`config/JwtAuthenticationFilter`
|
||||
|
||||
8. Admin 设置模块
|
||||
- 相关代码：`admin/AdminService`、settings/filesystem 相关 DTO 和 controller
|
||||
|
||||
## 二、每个模块现在的问题
|
||||
|
||||
### 1. 在线快传模块
|
||||
- 业务目标看起来是“支持 Redis + 多实例 + 分布式锁”。
|
||||
- 但当前锁只包读取，不包“读取后修改再保存”整个事务。
|
||||
- Redis 模式下是整对象覆盖写，存在并发覆盖和信令丢失问题。
|
||||
- “仅允许一个接收方加入”是业务规则，但现在不能稳定保证。
|
||||
|
||||
### 2. 离线快传模块
|
||||
- 会话、文件上传、ready 状态、存储额度检查都耦合在 `TransferService`。
|
||||
- 存储额度检查不是原子行为，并发上传可能突破上限。
|
||||
- 上传状态推进和额度校验缺少统一状态机。
|
||||
|
||||
### 3. 异步任务模块
|
||||
- 任务创建、claim、lease、heartbeat、retry、manual retry、状态 JSON 解析都混在一个 service。
|
||||
- `correlationId` 被当作幂等键使用，但没有数据库级保证。
|
||||
- attempt/retry 语义虽然有实现，但规则没有被明确定义和隔离。
|
||||
- `public_state_json/private_state_json` 既是业务状态，又承担运行态和展示态，职责混杂。
|
||||
|
||||
### 4. Broker 消息模块
|
||||
- 当前消费语义是“先 pop 再处理”，天然是 at-most-once。
|
||||
- 但业务又想靠 `correlationId` 做去重，更像 at-least-once。
|
||||
- 消息可靠性、重试、死信、幂等边界都没有单独建模。
|
||||
- broker 只是技术实现，但现在承担了业务可靠性语义。
|
||||
|
||||
### 5. 文件事件模块
|
||||
- 本地 SSE 推送、事件持久化、跨实例广播在一个 service 中耦合。
|
||||
- listener 对坏消息直接抛异常，容错策略不清晰。
|
||||
- 本地订阅过滤规则、跨实例复制规则、事件 payload 规则没有独立边界。
|
||||
|
||||
### 6. 上传会话模块
|
||||
- DB 状态和 Redis runtime 状态并存，但权威关系没有被结构化表达。
|
||||
- Redis runtime 读写失败基本是静默处理，观测和告警语义不明确。
|
||||
- 上传模式判断、会话状态推进、远端对象清理、运行态刷新都在一个 service 里。
|
||||
|
||||
### 7. 认证会话模块
|
||||
- access token 吊销、refresh token 轮换、active session 切换、封禁/改密后的清理都存在，但没有统一策略层。
|
||||
- “立即失效”的定义不够严格，尤其是时间边界处理。
|
||||
- 桌面端/移动端的单端活跃规则散落在多个方法中。
|
||||
|
||||
### 8. Admin 设置模块
|
||||
- 可写设置、运行态快照、环境配置读取混在一个聚合响应里。
|
||||
- `writeSupported` 只能提示能力，不能从结构上表达“配置源”和“运行态”区别。
|
||||
- 业务上已经有“可持久化设置”和“只读快照”两类概念，但代码层还没完全分开。
|
||||
|
||||
## 三、应该如何拆分职责
|
||||
|
||||
### 1. 在线快传模块
|
||||
建议拆成：
|
||||
- `OnlineTransferSessionService`
|
||||
- 负责业务规则：join、postSignal、poll、过期判断
|
||||
- `OnlineTransferSessionRepository`
|
||||
- 负责会话持久化/加载
|
||||
- `OnlineTransferSessionLockManager`
|
||||
- 负责会话级原子执行
|
||||
- `OnlineTransferSessionAggregate`
|
||||
- 负责接收方唯一、信令队列、cursor 等领域行为
|
||||
|
||||
目标：
|
||||
- 所有读改写保存通过一个原子入口完成
|
||||
- service 不直接操作 Redis 细节
|
||||
|
||||
### 2. 离线快传模块
|
||||
建议拆成：
|
||||
- `OfflineTransferSessionService`
|
||||
- `OfflineTransferStorageQuotaService`
|
||||
- `OfflineTransferFileStorageService`
|
||||
|
||||
目标：
|
||||
- 会话状态推进和额度规则分离
|
||||
- 上传文件、ready 判定、容量扣减有清晰边界
|
||||
|
||||
### 3. 异步任务模块
|
||||
建议拆成：
|
||||
- `BackgroundTaskCommandService`
|
||||
- 创建、取消、人工重试
|
||||
- `BackgroundTaskExecutionService`
|
||||
- claim、heartbeat、complete、fail
|
||||
- `BackgroundTaskRetryPolicy`
|
||||
- retryable、attempt、delay 计算
|
||||
- `BackgroundTaskStateCodec`
|
||||
- JSON <-> typed state
|
||||
- `BackgroundTaskIdempotencyService`
|
||||
- correlationId 规则
|
||||
|
||||
目标：
|
||||
- “任务业务规则”和“任务运行机制”分离
|
||||
- state JSON 不再到处手写 merge/remove
|
||||
|
||||
### 4. Broker 消息模块
|
||||
建议拆成：
|
||||
- `BrokerMessagePublisher`
|
||||
- `BrokerMessageConsumer`
|
||||
- `BrokerDeliveryPolicy`
|
||||
- `BrokerMessageHandler`
|
||||
|
||||
目标：
|
||||
- 明确消息语义是 at-least-once
|
||||
- 可靠性和业务处理解耦
|
||||
- 去重不靠消费者临时判断，而靠任务幂等层
|
||||
|
||||
### 5. 文件事件模块
|
||||
建议拆成：
|
||||
- `FileEventRecorder`
|
||||
- 落库
|
||||
- `FileEventDispatcher`
|
||||
- 本地 SSE 分发
|
||||
- `FileEventReplicationPublisher`
|
||||
- 跨实例发布
|
||||
- `FileEventReplicationConsumer`
|
||||
- 跨实例消费
|
||||
- `FileEventPayloadCodec`
|
||||
- payload 结构规则
|
||||
|
||||
目标：
|
||||
- 本地分发和跨实例同步分离
|
||||
- 坏消息只影响当前消息，不影响整体监听
|
||||
|
||||
### 6. 上传会话模块
|
||||
建议拆成：
|
||||
- `UploadSessionLifecycleService`
|
||||
- create/cancel/complete/prune
|
||||
- `UploadSessionContentService`
|
||||
- prepare/upload/part-record
|
||||
- `UploadSessionRuntimeViewService`
|
||||
- 运行态读取
|
||||
- `UploadSessionRuntimeStateStore`
|
||||
- Redis/no-op 存储实现
|
||||
- `UploadPolicyResolver`
|
||||
- 上传模式、大小限制、策略能力决策
|
||||
|
||||
目标：
|
||||
- DB 生命周期和 Redis 观测态分离
|
||||
- runtime state 明确为辅助层
|
||||
|
||||
### 7. 认证会话模块
|
||||
建议拆成：
|
||||
- `AuthSessionPolicy`
|
||||
- 单端活跃、吊销、生效边界
|
||||
- `AccessTokenRevocationService`
|
||||
- `RefreshTokenRotationService`
|
||||
- `UserSessionRotationService`
|
||||
|
||||
目标：
|
||||
- 改密/封禁/登录/刷新都走同一套会话规则
|
||||
- 避免规则散落在 `AuthService` 和 admin 逻辑里
|
||||
|
||||
### 8. Admin 设置模块
|
||||
建议拆成：
|
||||
- `AdminConfigSnapshotService`
|
||||
- 只读运行态
|
||||
- `AdminMutableSettingsService`
|
||||
- 可写设置
|
||||
- `AdminSettingsFacade`
|
||||
- 对外聚合
|
||||
|
||||
目标：
|
||||
- 区分“系统当前状态”和“可持久化业务设置”
|
||||
- 减少 admin service 持续膨胀
|
||||
|
||||
## 四、哪些逻辑应抽到公共规则层
|
||||
|
||||
这些不该继续散在各 service 里：
|
||||
|
||||
### 1. 幂等规则层
|
||||
- `correlationId` 生成规则
|
||||
- 同一业务动作是否允许重复创建任务
|
||||
- 幂等冲突时返回什么结果
|
||||
|
||||
### 2. 状态机规则层
|
||||
- 在线快传会话状态推进
|
||||
- 离线快传 ready 条件
|
||||
- 上传会话状态推进
|
||||
- 后台任务状态推进
|
||||
|
||||
### 3. 并发规则层
|
||||
- 会话级锁
|
||||
- 额度检查的原子更新
|
||||
- 任务 claim/lease 规则
|
||||
|
||||
### 4. 重试规则层
|
||||
- 哪些错误可重试
|
||||
- attemptCount 如何累积
|
||||
- 自动重试和人工重试的区别
|
||||
- backoff 计算规则
|
||||
|
||||
### 5. 认证会话规则层
|
||||
- 单端活跃规则
|
||||
- 改密/封禁/重置密码后的清理规则
|
||||
- access token / refresh token 失效边界
|
||||
|
||||
### 6. 事件与消息规则层
|
||||
- file event payload 结构
|
||||
- listener 遇到坏消息如何处理
|
||||
- broker 消息投递语义
|
||||
|
||||
### 7. 配置语义规则层
|
||||
- “运行态快照”
|
||||
- “持久化设置”
|
||||
- “环境配置只读项”
|
||||
|
||||
## 五、推荐重构顺序
|
||||
|
||||
### 第一阶段：先统一规则，再动结构
|
||||
1. 先定四个核心语义
|
||||
- 在线快传并发语义
|
||||
- 异步任务幂等语义
|
||||
- broker 投递语义
|
||||
- 认证会话失效语义
|
||||
|
||||
2. 把这些规则抽成独立策略/规则类
|
||||
- 先不大改 controller 和 repository
|
||||
|
||||
### 第二阶段：先改最危险的一致性问题
|
||||
1. 在线快传
|
||||
- 把读改写保存收敛到单个原子入口
|
||||
2. 异步任务幂等
|
||||
- 让 `correlationId` 成为真正约束
|
||||
3. broker 消费可靠性
|
||||
- 不再“先丢消息再处理”
|
||||
|
||||
### 第三阶段：收敛状态机和运行机制
|
||||
1. 后台任务状态机拆分
|
||||
2. 上传会话 lifecycle/runtime 拆分
|
||||
3. 文件事件 recorder/dispatcher/replication 拆分
|
||||
|
||||
### 第四阶段：清理配置和管理侧语义
|
||||
1. admin settings 拆成 snapshot + mutable settings
|
||||
2. auth session 规则统一落到策略层
|
||||
3. 去掉 service 中分散的规则分支
|
||||
|
||||
## 六、建议优先落地的重构任务列表
|
||||
|
||||
1. 先定义并固定“统一业务规则”接口
|
||||
- 不改功能，只固化规则边界
|
||||
|
||||
2. 重构在线快传
|
||||
- 先解决原子性问题
|
||||
|
||||
3. 重构后台任务幂等和 broker
|
||||
- 先解决重复任务和消息丢失问题
|
||||
|
||||
4. 重构后台任务状态机
|
||||
- 把 retry/lease/attempt 语义统一
|
||||
|
||||
5. 重构文件事件模块
|
||||
- 提高跨实例容错
|
||||
|
||||
6. 重构上传会话模块
|
||||
- 明确 DB 状态与 Redis runtime 的关系
|
||||
|
||||
7. 最后整理 auth/admin
|
||||
- 收口规则，减少横向重复逻辑
|
||||
|
||||
## 必须先达成一致的核心规则
|
||||
|
||||
1. 在线快传必须是“原子读改写”，不能接受覆盖写丢信令
|
||||
2. 自动媒体任务必须以“任务幂等”保证最终唯一，不能靠先查再插
|
||||
3. broker 语义统一为“至少投递一次 + 消费端幂等”
|
||||
4. 后台任务 `attemptCount`、自动重试、人工重试必须统一定义
|
||||
5. 上传会话中 DB 状态是权威状态，Redis 只做辅助观测
|
||||
6. 文件事件坏消息必须隔离处理，不能拖垮整个 listener
|
||||
7. 认证相关的“立即失效”必须有明确且统一的规则
|
||||
8. admin 设置必须区分“运行态快照”和“可写业务设置”
|
||||
|
||||
## 2026-04-11 Execution Status
|
||||
|
||||
Completed in the first implementation batch:
|
||||
|
||||
1. Extracted task rule components from `BackgroundTaskService`
|
||||
- `BackgroundTaskRetryPolicy`
|
||||
- `BackgroundTaskStateManager`
|
||||
- `BackgroundTaskStateKeys`
|
||||
|
||||
2. Split file-event orchestration from local dispatch
|
||||
- `FileEventService` now coordinates persistence and after-commit publishing
|
||||
- `FileEventDispatcher` owns local SSE subscription and delivery
|
||||
- `FileEventPayloadCodec` owns payload shaping
|
||||
- malformed Redis pub/sub payloads are isolated and dropped by the listener
|
||||
|
||||
3. Split upload rules from upload-session orchestration
|
||||
- `UploadPolicyResolver` owns upload-mode and size/chunk rules
|
||||
- `UploadSessionStateMachine` owns lifecycle transitions
|
||||
- `UploadSessionService` now coordinates repository + runtime-state updates around those rules
|
||||
|
||||
4. Extracted auth session rotation rules
|
||||
- `AuthSessionPolicy` now owns per-client session rotation semantics used by `AuthService`
|
||||
|
||||
Verification:
|
||||
|
||||
- `cd backend && mvn "-Dtest=BackgroundTaskRetryPolicyTest,UploadSessionStateMachineTest,AuthSessionPolicyTest,FileEventServiceTest,RedisFileEventPubSubListenerTest,BackgroundTaskServiceTest,UploadSessionServiceTest,AuthServiceTest" test`
|
||||
- `cd backend && mvn test`
|
||||
|
||||
Current remaining high-value work from this plan:
|
||||
|
||||
- deeper background-task command/execution separation
|
||||
- offline-transfer quota atomicity split
|
||||
- broader file-event replication boundary cleanup
|
||||
- admin snapshot vs mutable-settings facade split
|
||||
- further auth/admin rule consolidation
|
||||
@@ -0,0 +1,583 @@
|
||||
# 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：上传与分享收口
|
||||
|
||||
- 让上传只产生内容接入结果
|
||||
- 让分享只依赖逻辑节点授权
|
||||
- 旧上传和旧分享接口退化为兼容层
|
||||
|
||||
这三个批次完成后，整套系统才真正具备继续深度重构的稳定底盘。
|
||||
Reference in New Issue
Block a user