startup-plan/技术设计/api-server/已完成/[已完成]-AI架构决策清单.md

知习 AI 架构 V1：决策与执行清单

2026-05-16 已确认并完成：三层架构（Provider → Gateway → Workflow），阶段 0 全部完成。 设计方向文档：AI架构设计.md

状态：✅ 阶段 0 完成 | 阶段 1 基本完成 | 阶段 2 待推进

---

一、架构原则

核心分层

业务模块层（ActiveRecall / ai-analysis）
       ↓ 调用
AI Workflow 层（ActiveRecallAnalysisWorkflow）
       ↓ 调用
AI Gateway 层（AiGatewayService：选模型、记日志、解析 JSON、超时重试）
       ↓ 调用
AI Provider 层（DeepSeekProvider / MiniMaxProvider / MockAiProvider）

每一层的职责边界：

层	知道什么	不知道什么
Provider	messages, model, temperature, signal	知识点、主动回忆、FocusItem
Gateway	feature, promptVersion, cost, retry	业务 Workflow 细节
Workflow	知识点、回答、分析逻辑	模型 API 细节
业务模块	自己的 CRUD	AI 调用细节

---

二、已确认决策（全部实现）

编号	决策	结论	状态
A	架构分层	Provider → Gateway → Workflow 三层	✅
B	Mock 保留	Mock 跑通闭环，永久保留	✅
C	第一个 Provider	DeepSeek（V4-Flash 便宜，V4-Pro 强推理）	✅
D	第二个 Provider	MiniMax M2.7（Coding Plan 已付费，主力分析）	✅
E	Model Router	三层：cheap / primary / strong，显式 fallback	✅
F	Gateway 超时	AbortController 30s + 自动重试 + fallback	✅
G	Prompt 管理	代码文件 + promptKey / promptVersion 追踪	✅
H	JSON 校验	Zod Schema + 三层容错（parse → fence → extract）	✅
I	成本控制	AiUsageLog + AiCostCalculatorService	✅
J	旧代码清理	删除 infrastructure/ai，ai-analysis 迁到新 gateway	✅

---

三、当前文件结构

src/modules/ai/
├── ai.module.ts                            # NestJS DI：Map<string, AiProvider>
├── ai.controller.ts                        # POST /ai/analyze-recall · GET /ai/models
├── model-router.ts                         # cheap / primary / strong 三档路由
├── gateway/
│   ├── ai-gateway.types.ts                 # GatewayRequest / GatewayResponse / ModelTier
│   └── ai-gateway.service.ts               # 统一入口：选模型、30s超时、重试、JSON三层容错、记日志
├── providers/
│   ├── ai-provider.interface.ts            # AiGenerateInput(signal) / AiGenerateOutput
│   ├── mock-ai.provider.ts                 # 永久保留，返回 simulated 分析结果
│   ├── deepseek.provider.ts                # DeepSeek API（OpenAI 兼容）
│   └── minimax.provider.ts                 # MiniMax M2.7（OpenAI 兼容）
├── prompts/
│   ├── prompt-template.service.ts          # key + version 注册表
│   ├── active-recall-analysis.prompt.ts    # System Prompt
│   └── schemas/
│       └── active-recall-analysis.schema.ts # Zod Schema + JSON 输出示例
├── usage/
│   ├── ai-cost-calculator.service.ts       # 按模型计算费用
│   └── ai-usage-log.service.ts             # 写 AiUsageLog
└── workflows/
    └── active-recall-analysis.workflow.ts   # 第一个 Workflow：主动回忆分析

关联模块

src/modules/ai-analysis/                    # 导入 AiModule，用 ActiveRecallAnalysisWorkflow
├── ai-analysis.module.ts
├── ai-analysis.controller.ts               # POST /ai-analysis · GET /ai-analysis/:id
├── ai-analysis.service.ts
└── ai-analysis.repository.ts

src/modules/active-recall/                  # 导入 AiModule，提交答案异步触发分析
├── active-recall.module.ts
├── active-recall.controller.ts             # POST /active-recalls/:id/submit
├── active-recall.service.ts
└── active-recall.repository.ts

src/infrastructure/ai/                      # ❌ 已删除（旧 AiService + 旧 MockAiProvider）

---

四、数据流（主动回忆分析）

1. POST /active-recalls/:id/submit
       ↓
2. ActiveRecallService.submit() 保存回答 + 异步 analysisWorkflow.execute()
       ↓
3. ActiveRecallAnalysisWorkflow.execute({ userId, questionText, knowledgeItemContent, userAnswer })
       ↓
4. PromptTemplateService.get('active-recall-analysis', '1.0.0')
       ↓
5. AiGatewayService.generate({ feature, userId, tier:'primary', promptKey, messages, outputSchema })
       ↓
6. ModelRouter.resolve('primary') → minimax-m2.7（fallback: deepseek-v4-pro）
       ↓
7. Provider.generate() + AbortController(30s) → fetch()
       ↓
8. JSON 三层容错：直接 parse → 提取 markdown fence → 提取 { } 对象
       ↓
9. Zod Schema 校验 → ActiveRecallAnalysisResult
       ↓
10. AiUsageLogService.log() 记 tokens / cost / latency
       ↓
11. GatewayResponse { parsed, usage }
       ↓
12. Workflow 返回 ActiveRecallAnalysisResult

---

五、数据库

AiUsageLog（已加入 schema，待 db push）

model AiUsageLog {
  id            String   @id @default(cuid())
  userId        String
  feature       String   @db.VarChar(64)
  provider      String   @db.VarChar(32)
  model         String   @db.VarChar(100)
  tier          String   @db.VarChar(32)
  promptKey     String   @db.VarChar(128)
  promptVersion String   @db.VarChar(32)
  inputTokens   Int      @default(0)
  outputTokens  Int      @default(0)
  estimatedCost Float    @default(0)
  latencyMs     Int      @default(0)
  success       Boolean  @default(true)
  errorMessage  String?  @db.VarChar(500)
  createdAt     DateTime @default(now())

  user          User     @relation(fields: [userId], references: [id])

  @@index([userId])
  @@index([feature])
  @@index([createdAt])
}

⚠️ prisma db push 待 SSH 隧道连通后执行

---

六、可执行任务状态

阶段 0：AI 地基 ✅ 14/14

#	任务	状态
1	AiUsageLog 表（prisma schema）	✅
2	统一 AiProvider 接口（generate + signal）	✅
3	ModelRouter（cheap / primary / strong）	✅
4	AiGatewayService（统一入口 + JSON 容错 + 超时重试）	✅
5	PromptTemplateService（key + version）	✅
6	DeepSeekProvider	✅
7	MiniMaxProvider	✅
8	Zod Schema（ActiveRecallAnalysisResult）	✅
9	AiUsageLogService + AiCostCalculatorService	✅
10	ActiveRecallAnalysisWorkflow	✅
11	AiModule（DI 注入）	✅
12	AiController（analyze-recall / models）	✅
13	MockAiProvider（保留不动）	✅
14	删除旧 infrastructure/ai	✅

阶段 1：集成打通 ✅ 4/6

#	任务	状态
15	ai-analysis 改用 ActiveRecallAnalysisWorkflow	✅
16	ai-analysis.module 导入 AiModule	✅
17	active-recall 提交答案触发分析	✅
18	Gateway AbortController 30s 超时	✅
19	prisma db push 建 AiUsageLog 表	⚠️ 等隧道
20	真实 AI 切换 + Prompt 调优	⏳ 后续

阶段 2：待推进

#	任务
21	11 个业务 Repository：in-memory Map → Prisma
22	所有 Controller 加 JwtAuthGuard
23	真实 AI 联调 + 样本测试 + Prompt 调优
24	更多 Workflow（知识导入、费曼分析、复习卡片、长期趋势）

---

七、一句话总结

DeepSeek 只是第一个模型，不是 AI 架构本身。
知习现在有了「可替换模型、可追踪成本、可校验输出、可沉淀学习结果」的三层 AI 工作流架构：
Provider → Gateway → Workflow。
阶段 0 全部完成，阶段 1 基本完成。