[M-AI-04-01] 审计并冻结 Active Recall 新旧链路迁移契约 #296
Closed
opened 2026-06-21 12:48:13 +08:00 by wangdl
·
4 comments
Labels
Clear labels
adr
Area: adr
architecture
Area: architecture
area:activity
活动/统计
area:admin
管理后台
area:admin-api
area:ai
AI/RAG
area:ai-runtime
AI Runtime / AI 分析体系相关
area:analytics
area:api
API 接口
area:auth
认证与授权
area:cos
对象存储
area:database
数据库/Migration
area:import
文件导入/解析
area:knowledge
知识库/知识点
area:learning-info
area:learning-session
area:quiz
测验/自测
area:reading-event
area:reading-progress
area:review
复习系统
area:security
安全相关
audit
Area: audit
audit:api-admin-info
audit:api-info
audit:planned
已完成宏观规划,尚未代码审查
audit:reviewed
backend
Area: backend
billing
Area: billing
blocked-by:api-info-aggregation
blocked-by:api-info-core
blocked-by:api-info-ops
blocked-by:api-info-schema
blocked-by:processor
blocked-by:schema
compatibility
Area: compatibility
gate
Area: gate
infrastructure
Area: infrastructure
priority:p0
最高优先级,阻塞发布
priority:p1
高优先级,里程碑必需
priority:p2
中优先级,后续版本
prisma
Area: prisma
release
Area: release
repo:api
API 仓库 Issue
status:blocked
被阻塞
status:done
已完成
status:partial
status:todo
type:aggregation
type:bug
缺陷修复
type:design
设计
type:docs
文档
type:feature
新功能
type:migration
type:refactor
重构
type:test
work:admin-api
work:aggregation
work:api
work:artifact
题目/卡片产物
work:audit
work:circuit-breaker
熔断
work:contract
work:design
架构/协议设计工作
work:docs
work:export
work:extend-existing
work:internal-api
Runtime 内部接口
work:job
Job 调度相关
work:new-module
work:new-table
work:ops
work:query
work:quota
额度/限流
work:schema
Prisma Schema 设计
work:security
work:service
Service 层实现
work:snapshot
Snapshot 构建
work:test
No Label
Milestone
No items
No Milestone
M-AI-04 Active Recall 端到端迁移
Projects
Clear projects
No project
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: wangdl/api-server#296
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
No description provided.
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
类型 / 标签
风险等级
P0
依赖
背景
在修改 Active Recall 生产链路前,完整确认现有提交、AI 分析、状态更新和结果写入行为,并冻结迁移契约。避免因审计缺失导致迁移后行为不一致。
目标
非目标
影响范围
必须审计
HTTP 入口
POST /api/active-recalls/:id/submitService 链路
输入数据
输出与副作用
状态契约
幂等契约
回滚契约
验收标准
docs/architecture/m-ai-04-active-recall-migration-contract.md已创建建议执行顺序
第 1 个执行(M-AI-04 所有 Issue 的前置依赖)
开发完成评论
完成内容
POST /api/active-recalls/:id/submit从 Controller → Service → Queue → Worker → AI Provider → Result Repository 的真实调用链active-recall:<answerId>ACTIVE_RECALL_ENGINE_MODE=legacy|unified修改文件
docs/architecture/m-ai-04-active-recall-migration-contract.md:从???占位状态填充为完整审计文档代码证据(审计溯源)
active-recall.controller.ts:21:POST :id/submit 入口,@Body() body: any无 DTOactive-recall.service.ts:19-39:submit() → findById + createAnswer + analyzeactive-recall.service.ts:29:knowledgeItemContent 硬编码''ai-analysis.service.ts:12-31:analyze() → createJob + queue.addai-analysis.repository.ts:17-33:createJob 写入 lifecycleStatus='queued', queueName='ai-interactive'ai-analysis.repository.ts:28vsai-analysis.service.ts:21:queueName 不一致(DB 写 ai-interactive,BullMQ 入队 ai-analysis)queue.constants.ts:1:QUEUE_AI_ANALYSIS = 'ai-analysis'workers/ai-analysis.worker.ts:18-106:AiAnalysisWorker 完整执行管线modules/ai/workflows/active-recall-analysis.workflow.ts:17-41:AI 调用封装modules/ai/gateway/ai-gateway.service.ts:40-170:AiGateway 完整链路modules/ai/prompts/active-recall-analysis.schema.ts:17-28:输出 Zod Schemamodules/ai/prompts/active-recall-analysis.prompt.ts:1-27:System Promptmodules/ai/model-router.ts:23-28:primary tier 路由配置modules/review/review-card.subscriber.ts:11-51:AIAnalysisCompleted → ReviewCardai-analysis.worker.ts:85-96:FocusItem 创建副作用ai-analysis.repository.ts:55-69:AiAnalysisResult 写入schema.prisma:532-566:ActiveRecallQuestion + ActiveRecallAnswer 模型schema.prisma:568-638:AiJob (AiAnalysisJob) 模型schema.prisma:679-701:AiAnalysisResult 模型schema.prisma:703-729:FocusItem 模型schema.prisma:731-757:ReviewCard 模型测试情况
npm run buildnpx jest --testPathPatterns="ai-job|ai-runtime" --passWithNoTests未完成 / 风险
是否建议进入 Review
Blocking 问题修复
审核发现 3 个 Blocking 问题,均已修复:
1. Job Options 事实错误 ✅ 已修复
removeOnComplete: true, removeOnFail: 500queue-definitions.ts:64-65—removeOnComplete: { count: 1000, age: 24h },removeOnFail: { count: 5000, age: 7d }2. 认证/权限审计缺失 ✅ 已修复
APP_GUARD(app.module.ts:184),认证层面安全submit()不校验question.userId === userId→ P0 安全缺陷,用户 A 可提交用户 B 的问题3. FocusItem knowledgeBaseId 恒为 'unknown' ✅ 已修复
ActiveRecallAnalysisResultSchema(active-recall-analysis.schema.ts:17-28)不含knowledgeBaseId字段result.knowledgeBaseId恒为undefined,所有 FocusItem 的knowledgeBaseId恒为'unknown'knowledgeBaseId字段更新后的关键发现分级
Non-blocking 问题修复
3 个 Non-blocking 问题,均已修复:
4. 行号漂移 ✅ 已修复
queue.constants.ts:1定义QUEUE_AI_ANALYSIS— 正确queue-definitions.ts:61-66默认 JobOptions — 正确(已在 Blocking #1 中修正)5108a9a⚠️ 行号引用以 commit 5108a9a 为准5. knowledgeItemContent 虚假注释 ✅ 已修复
active-recall.service.ts:29注释// worker picks up content from the analysis workflow是虚假注释knowledgeItemContent(空字符串)【知识点原文】后为空,分析质量严重受损active-recall.service.ts:29→ai-analysis.service.ts:26→active-recall-analysis.workflow.ts:18-21)6. ModelRouter 严重度过低 ✅ 已修复
primary和strongtier 的 preferred/fallback 完全相同(deepseek-v4-pro),maxRetries: 3更新后的关键发现(最终版)
ai-interactivevs BullMQai-analysis)追加 Non-blocking 问题修复
7. audioFileId 非文本答案路径 ✅ 已修复
ActiveRecallAnswer模型包含audioFileId和answerType(schema.prisma:554-556),但当前submit()仅接受{ answerText }8. Worker stall 恢复的重复 AiAnalysisResult 风险 ✅ 已修复
maxStalledCount: 1(queue-definitions.ts:58)意味着 stalled job 被重新投递 1 次AiAnalysisResult无@@unique([jobId])约束(schema.prisma:679-700:只有@@index([jobId]))createResult()写入 → Worker 崩溃 → BullMQ 重新投递 → 再次createResult()→ 同一 jobId 产生两条 ResultActiveRecallProjector必须在 Projector 层提供幂等保证最终关键发现汇总(11 条)