docs(arch): 旧架构合并 — 30项决策落地,5份文档升级至v0.4.0

- 总体架构:新增打印/图像预处理/双飞轮/三环境部署
- 技术选型:调整决策理由(Coze沙盒自动化测试),新增Sharp+PDFKit
- 数据模型:新增code/role/question_type+print_tasks+audit_logs,ID+code并存
- 模块设计:新增Image/Print模块,推荐两阶段匹配(关键词粗筛→AI精排)
- PRD:目标用户扩展为学生+家长,新增PDF打印,年级聚焦小初,图像预处理流程
- ADR-010:题库抽象层Adapter Pattern

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
tupingr
2026-05-26 12:00:52 +08:00
parent 6c9acbc501
commit e3f4af9c0c
8 changed files with 1687 additions and 6 deletions
+42
View File
@@ -70,3 +70,45 @@
- 新增 `sync-template.sh` 实现自动同步
- 新增 `TEMPLATE.yaml` + `init.sh` 实现一键初始化
- AI 项目框架从此可复用,token 节省 95%+
## ADR-009: 人机协同数据质量闭环
- 日期: 2026-05-26
- 状态: 已采纳
- 决策: 不依赖 AI 一次识别准确。AI 识别结果作为"草稿"入库,经用户确认/修正后才进入分析和推荐管道。所有修正记录保留为 P02 训练数据。
- 理由:
- 手写体 OCR 准确率无法保证 100%(尤其中小学生潦草字迹),错误数据直接进入分析会污染薄弱点诊断和练习推荐
- 传统方案(调高 AI 准确率)成本极高且天花板低。人机协同方案将"用户修正"从成本转化为资产
- 每一次用户修正 = 一条免费的标注数据,是训练自有模型的核心资源
- 关键设计:
- verification_status 状态机: raw → reviewed → corrected+ stale 兜底)
- 分字段置信度: 每个 AI 字段独立评分,低置信度高亮
- 数据质量门控: AnalysisReport 和 Recommendation 仅使用 reviewed+ 数据
- CorrectionLog: AI 值 vs 用户修正值的完整记录
- 交互设计: 置信度绿/黄/红三级 UI,批量确认降低摩擦
- 影响:
- error_items 表新增 verification_status + ai_confidence 列
- 新增 correction_logs 表
- 分析/推荐查询需加 verification_status 过滤
- P02 阶段训练数据来源从"外部标注"变为"内部修正记录"
## ADR-010: 题库抽象层设计 —— Adapter Pattern 多源统一接入
- 日期: 2026-05-26
- 状态: 已采纳
- 决策: 采用 Adapter Pattern(适配器模式)实现多题库源的统一接入。自有题库(PDF 录入)和第三方题库(作业帮 API)通过 `QuestionBankAdapter` 接口统一路由,调用方无感知。
- 理由:
- 旧架构仅自有题库,新架构决定了双题库源(自有 PDF + 作业帮 API),且未来可能有更多来源
- 如果直接在主业务逻辑中写 `if (source === 'zuoyebang')` 分支判断,每加一个题库源就要改业务代码
- Adapter Pattern 将"题库源差异"封装在适配器内部,业务逻辑只依赖 `QuestionBankAdapter` 接口
- 架构已明确: 决策 #1(双题库源)要求"架构层抽象适配"
- 关键设计:
- 接口定义: `QuestionBankAdapter { source, search(params), getById(id), healthCheck() }`
- 适配器工厂: `AdapterFactory``source` 字段路由到对应适配器实例
- 搜索策略: 并行查询所有适配器 → 合并去重 → 自有题库优先排序
- 新增题库源: 只需实现 `QuestionBankAdapter` 接口 + 注册到工厂,零业务代码改动
- 影响:
- `modules/question-bank/adapters/` 目录结构: `base-adapter.ts`, `self-built.adapter.ts`, `zuoyebang.adapter.ts`, `adapter.factory.ts`
- `questions``source` 字段 = 适配器路由 key`self_built` | `zuoyebang` | 未来扩展)
- `external_id` 字段存储第三方题库的原始 ID,自有题库此字段为空
- 健康检查: 每个适配器实现 `healthCheck()`,用于监控外部 API 可用性