# 后端重构方案草案

## 一、需要重构的模块

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