Refactor backend and frontend modules for architecture alignment

2026-04-12 00:32:21 +08:00
parent f59515f5dd
commit 30a9bbc1e7
253 changed files with 25462 additions and 4786 deletions
--- a/docs/superpowers/plans/2026-04-11-backend-refactor-plan.md
+++ b/docs/superpowers/plans/2026-04-11-backend-refactor-plan.md
@@ -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