a17aba972b
Audit complete: 2 quiz systems (procedural + AI Runtime), 4 data models, 3 question types (choice/fill/judge), external Runtime polling architecture. Identified 7 anomalies including answer leak (P0) and missing prompt/schema. Co-Authored-By: Claude <noreply@anthropic.com>
586 lines
25 KiB
Markdown
586 lines
25 KiB
Markdown
# M-AI-07 Quiz 生成与题目产物迁移契约
|
||
|
||
> 审计日期：2026-06-22
|
||
> 契约状态：冻结（待 M-AI-07-01 验收）
|
||
> 对应里程碑：M-AI-07 Quiz 生成与题目产物统一引擎迁移
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [当前链路审计](#1-当前链路审计)
|
||
2. [目标链路](#2-目标链路)
|
||
3. [数据模型](#3-数据模型)
|
||
4. [题型规则](#4-题型规则)
|
||
5. [Snapshot Schema](#5-snapshot-schema)
|
||
6. [Output Schema](#6-output-schema)
|
||
7. [副作用矩阵](#7-副作用矩阵)
|
||
8. [Artifact 矩阵](#8-artifact-矩阵)
|
||
9. [幂等契约](#9-幂等契约)
|
||
10. [权限模型](#10-权限模型)
|
||
11. [答案隐藏契约](#11-答案隐藏契约)
|
||
12. [Feature Flag](#12-feature-flag)
|
||
13. [回滚流程](#13-回滚流程)
|
||
14. [架构异常与不确定项](#14-架构异常与不确定项)
|
||
|
||
---
|
||
|
||
## 1. 当前链路审计
|
||
|
||
### 1.1 当前时序（Legacy Runtime 轮询路径）
|
||
|
||
```text
|
||
Client API Server External Runtime
|
||
| | |
|
||
| POST /api/ai/jobs | |
|
||
| { jobType:"quiz_generation", | |
|
||
| targetType:"knowledge_base", | |
|
||
| targetId:"kb-1", | |
|
||
| questionCount:10, | |
|
||
| questionTypes:["choice"], | |
|
||
| difficultyLevel:"medium", | |
|
||
| idempotencyKey? } | |
|
||
|-------------------------------->| |
|
||
| | UserAiService.createAnalysisJob() |
|
||
| | `src/modules/ai-runtime/user-ai.service.ts:199` |
|
||
| | 1. Settings check (:201) |
|
||
| | 2. Validate jobType (:210-214) |
|
||
| | 3. Validate targetType=knowledge_base (:216-222) |
|
||
| | 4. Idempotency check (:225-233) |
|
||
| | 5. Resolve credential (:237-249) |
|
||
| | 6. Quota check (:252) |
|
||
| | 7. Platform budget check (:255-267) |
|
||
| | 8. Build snapshot (:270) |
|
||
| | 9. Resolve prompt/schema versions |
|
||
| | → quiz_gen_v1 / quiz_output_v1 |
|
||
| | `user-ai.service.ts:15-17` |
|
||
| | 10. Compute priority (:279) |
|
||
| | 11. Create aiRuntimeJob (pending) |
|
||
| | modelProvider=deepseek |
|
||
| | modelName=deepseek-chat (:294) |
|
||
| | `user-ai.service.ts:282-299` |
|
||
| | 12. Create QuestionGenerationPlan |
|
||
| | `user-ai.service.ts:303-318` |
|
||
| | 13. Increment quota (:338) |
|
||
| | |
|
||
| { jobId, status:"pending", | |
|
||
| planId } | |
|
||
|<--------------------------------| |
|
||
| | |
|
||
| | POST /internal/runtime/jobs/poll |
|
||
| | (InternalAuthGuard) |
|
||
| | `runtime-internal.controller.ts:22`|
|
||
| |<-------------------------------------|
|
||
| | RuntimeInternalService.pollJobs() |
|
||
| | `runtime-internal.service.ts:22` |
|
||
| | → CAS lockJob (:85) |
|
||
| | → getSnapshot (:153) |
|
||
| | → resolveCredential (:201) |
|
||
| | |
|
||
| | ★ Runtime makes AI call directly |
|
||
| | ★ prompt/schema managed externally |
|
||
| | ★ API server has NO quiz prompt |
|
||
| | ★ API server has NO quiz schema |
|
||
| | |
|
||
| | POST /internal/runtime/jobs/:id/result
|
||
| | { validatedOutput: { |
|
||
| | quizTitle, quizDescription, |
|
||
| | questions: [{ |
|
||
| | type, stem/question, |
|
||
| | options, answer/correctAnswer,|
|
||
| | explanation, sourceBlockIds |
|
||
| | }] } } |
|
||
| |<-------------------------------------|
|
||
| | |
|
||
| | submitResult() → persistResult() |
|
||
| | `runtime-internal.service.ts:220` |
|
||
| | → quiz_generation (:367-381) |
|
||
| | update Plan→completed |
|
||
| | → convertQuizCandidates() |
|
||
| | `runtime-internal.service.ts:435`|
|
||
| | Quiz.create (status=ready) |
|
||
| | QuizQuestion.create × N |
|
||
| | dedup by stem (:463-472) |
|
||
| | |
|
||
| POST /api/ai/quizzes/:id/publish | |
|
||
| → status: ready→active | |
|
||
```
|
||
|
||
### 1.2 双系统并存
|
||
|
||
| 特性 | Procedural Quiz | AI Quiz Generation |
|
||
|------|----------------|-------------------|
|
||
| 入口 | `POST /quizzes` | `POST /ai/jobs` (jobType=quiz_generation) |
|
||
| Controller | `quiz.controller.ts` | `user-ai.controller.ts` |
|
||
| Service | `quiz.service.ts` | `user-ai.service.ts` / `runtime-internal.service.ts` |
|
||
| AI 调用 | **无**（程序化生成） | **外部 Runtime**（API 不管理 prompt/schema） |
|
||
| 题目类型 | choice, fill, judge | Runtime 决定，默认 choice |
|
||
| Job 系统 | 无 | `aiRuntimeJob`（非统一 AiJob） |
|
||
| 队列 | 无 | Runtime 轮询（非 BullMQ） |
|
||
| 幂等 | 无 | `idempotencyKey` on aiRuntimeJob |
|
||
| 数据模型 | Quiz + QuizQuestion | 相同 |
|
||
| 状态 | 直接 active | ready → publish → active |
|
||
| 计费 | 无 | quota.incrementJobCount |
|
||
|
||
**本里程碑只迁移 AI Quiz Generation 路径。Procedural Quiz 保持不变。**
|
||
|
||
### 1.3 Quiz 数据模型
|
||
|
||
**文件**: `prisma/schema.prisma:1833-1904`
|
||
|
||
```text
|
||
Quiz
|
||
├─ id String @id @default(cuid())
|
||
├─ userId String
|
||
├─ knowledgeBaseId String
|
||
├─ title String @db.VarChar(255)
|
||
├─ description String? @db.Text
|
||
├─ questionCount Int @default(0)
|
||
├─ sourceType String @default("kb") @db.VarChar(16) // "kb" | "ai"
|
||
├─ sourceId String? @db.VarChar(100) // aiRuntimeJob.id
|
||
├─ status String @default("ready") @db.VarChar(16) // ready|active|archived
|
||
├─ createdAt DateTime @default(now())
|
||
└─ updatedAt DateTime @updatedAt
|
||
@@index([userId]), @@index([knowledgeBaseId])
|
||
|
||
QuizQuestion
|
||
├─ id String @id @default(cuid())
|
||
├─ quizId String
|
||
├─ type String @db.VarChar(16) // "choice"|"fill"|"judge"
|
||
├─ stem String @db.Text // 题干
|
||
├─ options Json? // 选项数组 (choice 题型)
|
||
├─ answer String @db.VarChar(500) // 正确答案
|
||
├─ explanation String? @db.Text // 解析
|
||
├─ sourceBlockIds Json? // 来源文本块引用
|
||
├─ orderIndex Int @default(0)
|
||
└─ createdAt DateTime @default(now())
|
||
@@index([quizId])
|
||
|
||
QuizAttempt
|
||
├─ id String @id @default(cuid())
|
||
├─ quizId String
|
||
├─ userId String
|
||
├─ totalQuestions Int @default(0)
|
||
├─ correctCount Int @default(0)
|
||
├─ score Int @default(0) // 0-100
|
||
├─ startedAt DateTime @default(now())
|
||
└─ finishedAt DateTime?
|
||
@@index([quizId]), @@index([userId])
|
||
|
||
QuizAnswer
|
||
├─ id String @id @default(cuid())
|
||
├─ attemptId String
|
||
├─ questionId String
|
||
├─ userAnswer String @db.VarChar(500)
|
||
├─ isCorrect Boolean @default(false)
|
||
└─ answeredAt DateTime @default(now())
|
||
@@index([attemptId]), @@index([questionId])
|
||
|
||
QuestionGenerationPlan (Legacy — 由 Unified 的 AiJob + Snapshot 替代)
|
||
├─ id String @id @default(cuid())
|
||
├─ userId String
|
||
├─ jobId String // → aiRuntimeJob.id
|
||
├─ snapshotId String?
|
||
├─ targetType String? @db.VarChar(32)
|
||
├─ targetId String? @db.VarChar(255)
|
||
├─ knowledgePointIds Json?
|
||
├─ questionTypes Json?
|
||
├─ difficultyLevel String? @db.VarChar(32) // easy|medium|hard
|
||
├─ count Int @default(5)
|
||
├─ reason String? @db.Text
|
||
├─ status String @default("pending")
|
||
├─ createdAt DateTime
|
||
└─ updatedAt DateTime
|
||
@@index([userId])
|
||
```
|
||
|
||
### 1.4 当前题型
|
||
|
||
| 题型 | 代码值 | 选项结构 | 答案结构 | 来源 |
|
||
|------|--------|---------|---------|------|
|
||
| 选择题 | `choice` | `Json` 数组（选项字符串） | 正确选项的索引（字符串） | `quiz.service.ts:43-51` |
|
||
| 填空题 | `fill` | 无 | 缺失的关键词 | `quiz.service.ts:52-56` |
|
||
| 判断题 | `judge` | 无 | `"true"` 或 `"false"`（字符串） | `quiz.service.ts:57-60` |
|
||
|
||
**AI 生成的题目默认 type=`'choice'`**（`runtime-internal.service.ts:486`），但可包含其他类型（由 Runtime 决定）。
|
||
|
||
### 1.5 输入字段分类
|
||
|
||
| 字段 | 来源 | 分类 |
|
||
|------|------|------|
|
||
| `userId` | JWT | **进入 Snapshot** |
|
||
| `targetType` | DTO | **进入 Snapshot** |
|
||
| `targetId` (knowledgeBaseId) | DTO | **进入 Snapshot** |
|
||
| `questionCount` | DTO (1-50) | **进入 Snapshot** |
|
||
| `questionTypes` | DTO (string[]) | **进入 Snapshot** |
|
||
| `difficultyLevel` | DTO | **进入 Snapshot** |
|
||
| `knowledgePointIds` | DTO | **进入 Snapshot** |
|
||
| `idempotencyKey` | DTO | **进入 Snapshot** |
|
||
| `promptKey` | 配置 `quiz_gen_v1` | **进入 Snapshot** |
|
||
| `promptVersion` | 配置 | **进入 Snapshot** |
|
||
| `modelTier` | 配置 | **进入 Snapshot** |
|
||
| 知识库内容 | DB 查询 | **进入 Snapshot（限制长度）** |
|
||
| 知识点列表 | DB 查询 | **进入 Snapshot（限制数量+内容长度）** |
|
||
| JWT / Authorization | Request Header | **禁止进入 Snapshot** |
|
||
| API Key | DB | **禁止进入 Snapshot** |
|
||
| 用户学习画像（完整） | DB | **禁止进入 Snapshot**（仅取必要配置） |
|
||
| 完整知识库内容（未筛选） | DB | **禁止进入 Snapshot** |
|
||
|
||
### 1.6 副作用矩阵
|
||
|
||
| 副作用 | 当前行为 | Unified 行为 |
|
||
|--------|---------|-------------|
|
||
| 配额消耗 | `quota.incrementJobCount` (:338) | 保持（通过 CreationService 或 Router） |
|
||
| 平台预算检查 | `budget.checkPlatformBudget` (:257) | 保持 |
|
||
| QuestionGenerationPlan | 创建 plan 记录 (:303-318) | **废弃** — 由 AiJob + Snapshot 替代 |
|
||
| 使用日志 | Runtime 记录 | API 侧通过 Engine 的 usage log |
|
||
| 学习记录 | 不创建 | 不创建 |
|
||
| 通知 | 不创建 | 不创建 |
|
||
|
||
### 1.7 答案泄漏风险（审计发现）
|
||
|
||
**P0 风险**：`user-ai.service.ts:546-556` `getQuizQuestions()` 在 SELECT 中包含 `answer` 和 `explanation` 字段。任何已认证用户可在未开始答题前通过此接口获取正确答案。
|
||
|
||
**Procedural quiz**：`quiz.service.ts:83-88` `findOne()` include `questions` 包含完整 `answer` 字段。同样泄漏。
|
||
|
||
**建议**：M-AI-07-06 必须在 Unified 路径修复此问题。Legacy 路径暂不修改（避免影响现有客户端）。
|
||
|
||
---
|
||
|
||
## 2. 目标链路
|
||
|
||
### 2.1 目标时序（Unified 路径）
|
||
|
||
```text
|
||
POST /api/ai/jobs
|
||
{ jobType: "quiz_generation", targetType: "knowledge_base", targetId, ... }
|
||
→ QuizExecutionRouter
|
||
├─ [legacy] → UserAiService.createAnalysisJob() ← 原路径
|
||
└─ [unified] →
|
||
QuizGenerationSnapshotBuilder.build()
|
||
→ AiJobCreationService.createJob()
|
||
→ AiJob + Snapshot + Outbox
|
||
→ BullMQ (ai-interactive)
|
||
→ Worker → AiJobExecutionEngine
|
||
EXECUTE: QuizGenerationExecutor (AiGateway)
|
||
VALIDATE: QuizGenerationValidator
|
||
PROJECT: QuizGenerationProjector
|
||
→ Quiz + QuizQuestion × N + Artifact
|
||
→ markSucceeded
|
||
```
|
||
|
||
### 2.2 关键差异
|
||
|
||
| 维度 | Legacy (Runtime) | Unified |
|
||
|------|-----------------|---------|
|
||
| AI 调用方 | 外部 Runtime 直接调用 Provider | API 内 Executor → AiGateway |
|
||
| Prompt 管理 | Runtime 外部管理 | API 内 PromptTemplateService |
|
||
| Schema 管理 | Runtime 外部管理 | API 内 Zod Schema |
|
||
| Job 系统 | aiRuntimeJob | 统一 AiJob |
|
||
| 队列 | Runtime 轮询 | BullMQ (ai-interactive) |
|
||
| 结果持久化 | runtime-internal.service | QuizGenerationProjector |
|
||
| 事务 | 非原子（Quiz + Questions 分步） | 原子（同一 Prisma 事务） |
|
||
|
||
---
|
||
|
||
## 3. 数据模型（迁移相关约束）
|
||
|
||
### 3.1 保持不变的字段
|
||
|
||
Quiz 和 QuizQuestion 的所有字段保持不变。Unified Projector 写入相同的表和列。
|
||
|
||
### 3.2 ID 策略
|
||
|
||
| 实体 | 当前 | Unified |
|
||
|------|------|---------|
|
||
| Quiz.id | `@default(cuid())` | 如允许显式赋值 → `deterministic(jobId)`；否则 CUID + Artifact 幂等 |
|
||
| QuizQuestion.id | `@default(cuid())` | 如允许显式赋值 → `deterministic(jobId + ordinal)`；否则 CUID + Artifact 幂等 |
|
||
| QuizQuestion.options | `Json?` | 选择题：`string[]`；填空/判断：`null` |
|
||
| QuizQuestion.answer | `String` | **按当前格式保存**（choice=索引字符串，fill=关键词，judge="true"/"false"） |
|
||
|
||
### 3.3 QuestionGenerationPlan
|
||
|
||
Unified 路径不再创建 `QuestionGenerationPlan`。由 AiJob + AiJobSnapshot 替代其功能。
|
||
|
||
---
|
||
|
||
## 4. 题型规则
|
||
|
||
### 4.1 支持题型（冻结）
|
||
|
||
```text
|
||
choice — 单选题（1 个正确答案）
|
||
fill — 填空题（缺失关键词）
|
||
judge — 判断题（true/false）
|
||
```
|
||
|
||
不新增题型。如果 AI 输出其他类型，Validator 拒绝。
|
||
|
||
### 4.2 题型约束
|
||
|
||
| 题型 | options | answer | 验证规则 |
|
||
|------|---------|--------|---------|
|
||
| `choice` | `string[]`（≥2 项） | 正确选项索引（字符串） | answer 必须是 options 的有效索引 |
|
||
| `fill` | 不需要 | 缺失关键词 | answer 非空 |
|
||
| `judge` | 不需要 | `"true"` 或 `"false"` | 必须是这两者之一 |
|
||
|
||
---
|
||
|
||
## 5. Snapshot Schema
|
||
|
||
### 5.1 必须包含
|
||
|
||
```typescript
|
||
interface QuizGenerationSnapshot {
|
||
schemaVersion: string; // "quiz-generation-v1"
|
||
snapshot: {
|
||
userId: string;
|
||
targetType: string; // "knowledge_base"
|
||
targetId: string; // knowledgeBaseId
|
||
submissionId: string; // 稳定幂等标识
|
||
|
||
// 知识内容（限制长度）
|
||
knowledgeBaseTitle: string;
|
||
knowledgeBaseDescription: string;
|
||
knowledgeItems: Array<{ // 限制数量 ≤ 50
|
||
id: string;
|
||
title: string;
|
||
content: string; // 截断 ≤ 2000 字符
|
||
summary: string;
|
||
}>;
|
||
|
||
// 生成参数
|
||
questionCount: number; // 1-50
|
||
questionTypes: string[]; // ["choice","fill","judge"]
|
||
difficultyLevel: string; // "easy"|"medium"|"hard"
|
||
knowledgePointIds: string[]; // 空数组表示全部知识点
|
||
|
||
// Prompt/模型策略（从 Definition 读取）
|
||
promptKey: string;
|
||
promptVersion: string;
|
||
modelTier: string;
|
||
inputSchemaVersion: string;
|
||
outputSchemaVersion: string;
|
||
|
||
createdAt: string; // ISO8601 归一化到秒
|
||
};
|
||
}
|
||
```
|
||
|
||
### 5.2 禁止进入 Snapshot
|
||
|
||
- JWT / Authorization Header
|
||
- API Key / Provider Credential
|
||
- 完整知识库（未筛选+未截断）
|
||
- 完整用户学习画像
|
||
- 其他用户内容
|
||
- 数据库连接信息
|
||
|
||
---
|
||
|
||
## 6. Output Schema
|
||
|
||
### 6.1 AI 输出结构（冻结）
|
||
|
||
```typescript
|
||
interface QuizGenerationOutput {
|
||
quizTitle: string; // 测验标题（非空，≤255）
|
||
quizDescription?: string; // 测验描述
|
||
questions: Array<{
|
||
type: 'choice' | 'fill' | 'judge';
|
||
stem: string; // 题干（非空）
|
||
options?: string[]; // 选项（choice 题型必填，≥2）
|
||
answer: string; // 正确答案
|
||
explanation: string; // 解析（非空）
|
||
sourceBlockIds?: string[]; // 来源引用
|
||
}>;
|
||
}
|
||
```
|
||
|
||
### 6.2 验证规则
|
||
|
||
| 规则 | 严重程度 |
|
||
|------|---------|
|
||
| questions 数组非空，≤ 50 | P0 |
|
||
| quizTitle 非空，≤ 255 | P0 |
|
||
| stem 非空 | P0 |
|
||
| type ∈ {choice, fill, judge} | P0 |
|
||
| choice → options 数组 ≥ 2 项 | P0 |
|
||
| choice → answer 是 options 的有效索引 | P0 |
|
||
| fill → answer 非空 | P0 |
|
||
| judge → answer ∈ {"true", "false"} | P0 |
|
||
| explanation 非空 | P1 |
|
||
| 题目不重复（相同 stem） | P1 |
|
||
| 选项不重复 | P1 |
|
||
| 无 Markdown 代码围栏 | P0 |
|
||
| 无模型指令文本 | P0 |
|
||
|
||
---
|
||
|
||
## 7. 副作用矩阵
|
||
|
||
| 副作用 | Legacy | Unified |
|
||
|--------|--------|---------|
|
||
| AiJob 创建 | aiRuntimeJob | 统一 AiJob |
|
||
| Snapshot 创建 | snapshot_builder | AiJobSnapshot |
|
||
| 队列入队 | Runtime 轮询 | OutboxEvent → BullMQ |
|
||
| 配额消耗 | quota.incrementJobCount | 保持（Router 层） |
|
||
| 平台预算检查 | budget.checkPlatformBudget | 保持（Router 层） |
|
||
| QuestionGenerationPlan | 创建 | **不创建**（由 AiJob+Snapshot 替代） |
|
||
| 使用日志 | Runtime 记录 | Engine 记录 |
|
||
| 学习记录 | 无 | 无 |
|
||
| 通知 | 无 | 无 |
|
||
|
||
---
|
||
|
||
## 8. Artifact 矩阵
|
||
|
||
| 实体 | artifactType | artifactId | ordinal |
|
||
|------|-------------|-----------|---------|
|
||
| Quiz | `"quiz"` | Quiz.id | 0 |
|
||
| (可选) QuizQuestion | metadata 记录 | — | — |
|
||
|
||
不为每个 QuizQuestion 创建独立 Artifact（避免 Artifact 膨胀）。
|
||
|
||
---
|
||
|
||
## 9. 幂等契约
|
||
|
||
### 9.1 请求级幂等
|
||
|
||
```text
|
||
idempotencyKey = "quiz-generation:<submissionId>"
|
||
```
|
||
|
||
- `submissionId` 优先使用客户端传入的 `idempotencyKey`
|
||
- 回退：`<targetType>:<targetId>:<contentHash>`
|
||
- Db 级唯一约束：`AiJob.@@unique([userId, jobType, idempotencyKey])`
|
||
|
||
### 9.2 投影级幂等
|
||
|
||
```text
|
||
Quiz: deterministic ID = "qz_<jobId>"
|
||
Question: deterministic ID = "qq_<jobId>_<ordinal>"
|
||
```
|
||
|
||
如 Prisma `@default(cuid())` 不允许显式 ID 赋值，使用入口 Artifact 检查 + P2002 catch 作为替代（与 M-AI-06 ReviewCard 一致）。
|
||
|
||
### 9.3 禁止的幂等方式
|
||
|
||
- ❌ `findFirst({ stem }) → create` — 不同 Quiz 可能有相同题干
|
||
- ❌ 全局 stem 去重 — 当前 `convertQuizCandidates` 使用此方式 (`runtime-internal.service.ts:463-472`)，迁移后应改为确定性 ID
|
||
|
||
---
|
||
|
||
## 10. 权限模型
|
||
|
||
| 操作 | 权限 |
|
||
|------|------|
|
||
| 生成 Quiz | 用户只能为自己的 knowledgeBase 生成 |
|
||
| 查询 Quiz | 只能查询自己的 Quiz (`userId` 过滤) |
|
||
| 查询 Question | 只能查询自己 Quiz 的 Question |
|
||
| 发布 Quiz | 只能发布自己的 Quiz |
|
||
| Admin 查询 | Admin 可查看所有（按现有 Admin 权限） |
|
||
|
||
---
|
||
|
||
## 11. 答案隐藏契约
|
||
|
||
**当前缺陷**：`getQuizQuestions()` 直接返回 `answer` + `explanation` 字段（`user-ai.service.ts:553`）。`findOne()` include questions 同样泄漏（`quiz.service.ts:85`）。
|
||
|
||
**Unified 要求**：
|
||
- Quiz 列表 DTO：不返回 questions 数组（或不含 answer/explanation）
|
||
- Quiz 详情 DTO（未作答前）：不返回 answer/explanation
|
||
- 开始答题后：不通过查询接口返回答案（答案仅在 submit 时服务端比对）
|
||
- 提交后：QuizAttempt.getResults 可以返回 question.answer（当前行为保留）
|
||
- Admin：可以查看答案
|
||
|
||
**M-AI-07-06 必须修复此问题。Legacy 路径暂不修改。**
|
||
|
||
---
|
||
|
||
## 12. Feature Flag
|
||
|
||
```text
|
||
Flag Name: QUIZ_GENERATION_ENGINE_MODE
|
||
Values: legacy | unified
|
||
Default: legacy
|
||
```
|
||
|
||
| 模式 | 行为 |
|
||
|------|------|
|
||
| `legacy` | UserAiService.createAnalysisJob() → aiRuntimeJob → Runtime 轮询 |
|
||
| `unified` | QuizGenerationSnapshotBuilder → AiJobCreationService → BullMQ → Engine |
|
||
|
||
---
|
||
|
||
## 13. 回滚流程
|
||
|
||
```text
|
||
unified → legacy:
|
||
1. 修改 FeatureFlag: QUIZ_GENERATION_ENGINE_MODE = legacy
|
||
2. 新请求立即走 Legacy 路径
|
||
3. 已创建的 Unified Job 继续完成
|
||
4. 相同 submission 不重新进入 Legacy
|
||
5. 已生成 Quiz 保留
|
||
6. 无需数据库回滚
|
||
```
|
||
|
||
---
|
||
|
||
## 14. 架构异常与不确定项
|
||
|
||
### 14.1 架构异常
|
||
|
||
| # | 异常 | 严重程度 | 处理方式 |
|
||
|---|------|---------|---------|
|
||
| A1 | API 服务器无 Quiz Prompt 模板 | **阻塞** | M-AI-07-03 需新增 `quiz-generation.prompt.ts` 和 `quiz-generation.schema.ts`（从 Runtime 获取或重新设计） |
|
||
| A2 | API 服务器无 Quiz Output Schema | **阻塞** | 同上 |
|
||
| A3 | `getQuizQuestions()` 泄漏答案 | P0 | M-AI-07-06 修复 |
|
||
| A4 | `findOne()` include questions 泄漏答案 | P0 | M-AI-07-06 修复 |
|
||
| A5 | `deepseek-chat` 硬编码（非 ModelRouter） | P2 | Unified 使用 Definition + ModelRouter |
|
||
| A6 | 当前题目去重依赖 `stem` 全局匹配 | P2 | Unified 使用确定性 ID |
|
||
| A7 | Quiz 状态 `ready` → `publish` → `active` 两阶段 | P2 | Unified 可简化为直接 `active`，或保留两阶段 |
|
||
|
||
### 14.2 不确定项
|
||
|
||
| 项 | 问题 | 建议 |
|
||
|----|------|------|
|
||
| Prompt 来源 | 当前 prompt 由外部 Runtime 管理 | 从 Runtime 团队获取 `quiz_gen_v1` 的 system prompt 和 output schema，或基于业务需求重新设计 |
|
||
| 模型 Tier | 当前硬编码 `deepseek-chat`，不经过 ModelRouter | Unified Definition 使用 `modelTier`（建议 `primary`），通过 ModelRouter 解析 |
|
||
| questionTypes 扩展 | 当前仅 choice/fill/judge，是否需支持 multi_choice/short_answer | 本批不扩展，严格按现有题型 |
|
||
| QuestionGenerationPlan | 是否保留此表供旧数据查询 | Unified 不创建新记录，旧记录保留 |
|
||
|
||
---
|
||
|
||
## 附录 A：关键文件索引
|
||
|
||
| 用途 | 绝对路径 | 关键行号 |
|
||
|------|---------|---------|
|
||
| AI Quiz 入口 Controller | `src/modules/ai-runtime/user-ai.controller.ts` | `:63` createAnalysisJob, `:85` publishQuiz, `:134` getQuiz, `:139` getQuizQuestions |
|
||
| AI Quiz 入口 Service | `src/modules/ai-runtime/user-ai.service.ts` | `:199` createAnalysisJob, `:374` publishQuiz, `:533` getQuiz, `:546` getQuizQuestions |
|
||
| AI Job DTO | `src/modules/ai-runtime/user-ai.dto.ts` | `:67` VALID_JOB_TYPES, `:74` CreateAnalysisJobDto |
|
||
| Runtime Internal Controller | `src/modules/ai-runtime/internal/runtime-internal.controller.ts` | `:22` pollJobs, `:58` submitResult |
|
||
| Runtime Internal Service | `src/modules/ai-runtime/internal/runtime-internal.service.ts` | `:22` pollJobs, `:220` submitResult, `:367` quiz persisting, `:435` convertQuizCandidates |
|
||
| Job Config | `src/modules/ai-runtime/user-ai.service.ts` | `:15-17` JOB_TYPE_CONFIG (quiz_gen_v1/quiz_output_v1) |
|
||
| Procedural Quiz Controller | `src/modules/quiz/quiz.controller.ts` | `:12` create, `:24` findOne |
|
||
| Procedural Quiz Service | `src/modules/quiz/quiz.service.ts` | `:8` create, `:38` 题型 logic |
|
||
| Quiz Prisma Model | `prisma/schema.prisma` | `:1833-1853` Quiz, `:1855-1871` QuizQuestion |
|
||
| QuizAttempt Model | `prisma/schema.prisma` | `:1873-1889` |
|
||
| QuizAnswer Model | `prisma/schema.prisma` | `:1891-1904` |
|
||
| QuestionGenerationPlan | `prisma/schema.prisma` | `:2243-2260` |
|
||
| Snapshot Builder | `src/modules/ai-runtime/snapshot-builder.service.ts` | `:379` quizAttempt data |
|
||
| Model Router | `src/modules/ai/model-router.ts` | `:18-22` cheap tier, `:24-28` primary tier |
|
||
| Prompt Template Service | `src/modules/ai/prompts/prompt-template.service.ts` | 无 quiz prompt（需新增） |
|
||
|
||
## 附录 B：题型对比
|
||
|
||
| 维度 | Procedural Quiz | AI Quiz (Legacy) | AI Quiz (Unified) |
|
||
|------|----------------|-----------------|-------------------|
|
||
| 生成方式 | 随机抽取+交替类型 | Runtime AI 调用 | AiGateway AI 调用 |
|
||
| 题型 | choice/fill/judge | Runtime 决定 | choice/fill/judge（Validator 限制） |
|
||
| 选项 | 其他 item 内容截断 | AI 生成 | AI 生成 |
|
||
| 答案 | 正确选项索引/关键词 | AI 生成 | AI 生成 |
|
||
| 解析 | item.content 截断 | AI 生成 | AI 生成 |
|
||
| 状态 | 直接可用 | ready→publish→active | 同 Legacy 或直接 active |
|