api-server/docs/architecture/adr-001-unified-ai-architecture.md

# ADR-001：统一 AI 架构迁移决策

## 状态

已接受（2026-06-19）

## 背景

当前知习项目存在两套独立的 AI 分析系统，以及一套规则出题系统：

- **系统 A（BullMQ + TypeScript，运行中）**：处理 active-recall 和 feynman-evaluation 分析，通过 `AiAnalysisWorker` 在 NestJS 进程内执行，写入 `AiAnalysisJob`/`AiAnalysisResult` 表，创建 `FocusItem`，发布 `ai.analysis.completed` 事件驱动 `ReviewCardSubscriber` 生成复习卡片。
- **系统 B（Rust + HTTP 轮询，闲置）**：`zhixi-heavy-runtime` 独立进程，支持 5 种分析类型（learning_state_analysis、weak_point_analysis、next_action_planning、quiz_generation、flashcard_generation），通过轮询 `AiRuntimeJob` 表获取任务，调用 DeepSeek API，结果写入多个相互独立的领域表。
- **系统 C（规则出题，运行中）**：`QuizService.create()` 通过纯文本拼接生成测验题目，不调用任何 AI 模型。

系统 B 存在以下关键问题：
1. **无任务生产者** — 唯一创建 `AiRuntimeJob` 的入口 `POST /ai/jobs` 无人调用
2. **Snapshot 结构不兼容** — Rust 端 `LearningAnalysisSnapshot` 结构体与 API 端 `SnapshotBuilderService` 产出的 JSON 结构完全不匹配
3. **Rust 无重计算** — 所有 Pipeline 的独有业务逻辑总和不足 50 行，实际是一个 HTTP 代理层
4. **数据断层** — Rust 结果写入的表（`AiLearningAnalysis`、`WeakPointCandidate`、`NextActionRecommendation`）无 iOS/Admin 消费端

同时，当前 API 进程内注册 BullMQ Processor 的部署拓扑存在以下问题：
- API 进程与 Worker 进程边界模糊，Docker 与生产环境配置不一致
- `AppModule` 中同时注册 `AiAnalysisWorker`、`DocumentImportWorker`、`NotificationWorker`
- `WorkerModule` 和 `worker.main.ts` 已存在但未独立使用

## 决策

采用 **8 批次渐进式迁移**，将 AI 分析能力从 BullMQ + Rust 双系统统一到单一 BullMQ + TypeScript 架构。

### 目标架构拓扑

```
                ┌─────────────┐
                │   iOS App   │
                └──────┬──────┘
                       │ HTTP
                ┌──────▼──────┐
                │  zhixi-api  │  NestJS (仅 Controller + Queue Producer)
                │  :3000      │  不注册任何 @Processor()
                └──────┬──────┘
                       │ Redis (BullMQ)
                ┌──────▼──────┐
                │ zhixi-worker│  NestJS (仅 @Processor())
                │  (无端口)    │  AiAnalysisWorker + DocumentImportWorker
                └──────┬──────┘  + NotificationWorker + AuditLogProcessor
                       │ HTTP    + FileCleanupProcessor
                ┌──────▼──────┐
                │  DeepSeek    │
                │  API         │
                └──────────────┘
```

### API Process 职责

- 暴露所有 HTTP Controller
- 注入 Queue Producer（`QueueService.add()`）
- 不注册任何 `@Processor()` 或 `WorkerHost`
- 不启动 BullMQ Worker 实例

### Worker Process 职责

- 注册所有 `@Processor()` 和 `WorkerHost`
- 消费 BullMQ 队列
- 调用 AI Workflow → DeepSeek API
- 写入分析结果表
- 发布领域事件
- 不暴露 HTTP 端口

### Heavy Runtime 当前处置

- 第一阶段保持部署但不修改
- 不停止 Rust 进程
- 不删除 `AiRuntimeJob` 及相关表
- M-AI-08 正式退场

## 迁移批次

| 批次 | 名称 | 范围 |
|------|------|------|
| M-AI-01 | Worker 进程边界与部署收口 | 拆分 API/Worker 进程，不改变业务 |
| M-AI-02 | 统一 AiJob 数据库 Expand | 扩展 `AiAnalysisJob`，新增 Artifact/Snapshot/Outbox |
| M-AI-03 | 统一 Job Engine、Registry 与 Outbox | AiJobService + Registry + 双队列 |
| M-AI-04 | Active Recall 端到端迁移 | 切换生产者，iOS 展示真实结果 |
| M-AI-05 | Feynman 与 ReviewCard 可靠链路 | Outbox 替代进程内 EventEmitter |
| M-AI-06 | AI Quiz 端到端迁移 | 迁移 Rust Prompt/Schema，异步生成 |
| M-AI-07 | 后台学习分析与推荐闭环 | learning_state/weak_point/next_action |
| M-AI-08 | Heavy Runtime 退场与 Legacy Contract | 停止 Rust，归档表 |

## 第一阶段非目标（M-AI-01）

1. 不修改 `AiAnalysisJob` / `AiRuntimeJob` 表结构
2. 不新建统一 AiJob 模型
3. 不迁移 Active Recall、Feynman 或 Quiz 业务链路
4. 不停止 `zhixi-heavy-runtime` 服务
5. 不修改 iOS 代码
6. 不删除任何数据库表
7. 不修改 AI Prompt、模型或业务结果结构
8. 不新增 Prisma Migration

## 架构约束

以下约束在所有批次中持续生效：

1. `AppModule` 不允许注册 `@Processor()` 或 `WorkerHost`
2. `WorkerModule` 不允许暴露公开 HTTP Controller
3. 不允许新建第三套 AI Job 模型（除 M-AI-02 统一扩展外）
4. 不允许顺带修改 Prompt、模型选择或业务结果 Schema（各自独立 Issue）
5. 没有 iOS/Admin 消费者的任务类型不得启用自动生成
6. 自动触发必须有频率限制、幂等保护、成本上限

## 回滚原则

每个 Issue 必须提供独立回滚方案：

1. 代码层面：回滚提交或 revert PR
2. 数据库：本批次不涉及 Schema 变更，无需数据回滚
3. 部署：恢复旧 AppModule Processor 注册，停止独立 Worker service
4. 队列：验证无双重消费

## 现有 Processor 清单

| Processor | 队列 | 文件 |
|-----------|------|------|
| `AiAnalysisWorker` | `ai-analysis` | `workers/ai-analysis.worker.ts` |
| `DocumentImportWorker` | `document-import` | `workers/document-import.worker.ts` |
| `NotificationWorker` | `notification` | `workers/notification.worker.ts` |
| `AuditLogProcessor` | `audit-logs` | `modules/admin-audit-log/audit-log.processor.ts` |
| `FileCleanupProcessor` | `file-cleanup` | `modules/files/file-cleanup.processor.ts` |

## 模块依赖图（当前）

```
AppModule
├── WorkerModule (已存在但未独立使用)
│   ├── AiAnalysisWorker
│   ├── DocumentImportWorker
│   └── NotificationWorker
├── QueueModule
│   ├── BullModule.forRootAsync (Redis 连接)
│   └── BullModule.registerQueue (6 个队列)
├── AiAnalysisModule
│   ├── AiAnalysisController (HTTP 端点)
│   └── AiAnalysisService (BullMQ Producer)
├── ActiveRecallModule
│   └── ActiveRecallService (BullMQ Producer 调用者)
├── ReviewModule
│   ├── ReviewController (HTTP 端点)
│   ├── ReviewCardSubscriber (监听 ai.analysis.completed)
│   └── ReviewService
├── AiRuntimeModule
│   ├── UserAiController (HTTP 端点)
│   └── RuntimeInternalController (Rust 内部端点)
├── AdminAuditLogModule
│   └── AuditLogProcessor (@Processor)
└── FilesModule
    └── FileCleanupProcessor (@Processor)
```

## 后续 Issue 引用

后续 M-AI-01 Issue 必须引用本文档（ADR-001）作为架构约束依据。

## 证据

- 当前部署：`docker-compose.yml:1-70` — API 和 Worker 共享同一 NestJS 实例
- Worker 模块：`worker.module.ts:1-20` — 已定义但未独立使用
- Worker 入口：`worker.main.ts:1-10` — 已存在但未被 Docker/生产独立调用
- 现有架构文档：`docs/ai-runtime-architecture.md` — 描述 Rust Heavy Runtime 架构
- BullMQ 版本：`bullmq@5.77.1`、`@nestjs/bullmq@11.0.4`