Files

T

tupingr e3f4af9c0c 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>

2026-05-26 12:00:52 +08:00

12 KiB

Raw Permalink Blame History

总体架构

版本: v0.4.0 | 作者: Arch AI | 基于 PRD v0.4.0 + 旧架构合并

1. 系统全景

                        ┌──────────────────────┐
                        │     用户层            │
                        │  学生 │ 家长 │ 老师    │
                        └──────────┬───────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              │                    │                    │
              ▼                    ▼                    ▼
   ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
   │  P01 小程序      │  │  P03 Web 后台    │  │  未来: 家长端     │
   │  (Taro+React)   │  │  (Next.js)       │  │  公众号/小程序   │
   └────────┬────────┘  └────────┬────────┘  └────────┬────────┘
            │                    │                    │
            └────────────────────┼────────────────────┘
                                 │ HTTPS
                                 ▼
              ┌─────────────────────────────────────┐
              │           API 网关层                 │
              │        NestJS (P01/server)          │
              │   Auth │ Rate Limit │ Validation    │
              └─────────────────┬───────────────────┘
                                │
          ┌─────────────────────┼──────────────────────┐
          │                     │                      │
          ▼                     ▼                      ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐
│   核心服务层     │  │   AI 分析服务    │  │   文件存储           │
│  用户/错题/题库  │  │  错误诊断/推荐   │  │   图片/CDN           │
└────────┬────────┘  └────────┬────────┘  └──────────┬──────────┘
         │                    │                      │
         │           ┌────────┴────────┐             │
         │           │   P02 训练引擎   │             │
         │           │  (Python/PyTorch)│             │
         │           │  Phase 2 启动    │             │
         │           └─────────────────┘             │
         │                                           │
         ▼                                           ▼
┌─────────────────┐                       ┌─────────────────┐
│   PostgreSQL    │                       │   S3 兼容存储    │
│   (主数据库)     │                       │   (图片/文件)    │
└─────────────────┘                       └─────────────────┘

2. 架构层级

层	技术	职责
展示层	Taro 4 + React 18 / Next.js	UI 渲染、用户交互
网关层	NestJS 中间件	鉴权、限流、参数校验
服务层	NestJS Service	业务逻辑编排
AI 层	Coze SDK → P02 PyTorch	OCR、错误诊断、推荐
数据层	PostgreSQL + Drizzle ORM	持久化存储
存储层	S3 兼容存储	图片/文件存储

3. 数据流

3.1 拍照录入（P0 热路径 — 含修正闭环）

[小程序] 拍照/选图
    │
    ▼
[Gateway] 鉴权 + 限流
    │
    ▼
[File Storage] 上传原图 → 返回 URL
    │
    ▼
[Image Pipeline] 图像预处理（提升 OCR 识别率）
    ├─ 透视校正（用户手动框 4 角）
    ├─ 增强处理（CLAHE + Gamma + 对比度增强）
    └─ 笔迹去除（红/蓝笔 HSV 自动去除，黑笔可选手动圈选）
    │
    ▼
[AI Service] 增强后图片 URL → Coze SDK
    ├─ OCR 提取题目文本  (confidence: 0.5-0.95)
    ├─ 学科分类          (confidence: 0.7-0.95)
    ├─ 知识点标注        (confidence: 0.5-0.9)
    └─ 错误类型诊断      (confidence: 0.5-0.9)
    │
    ▼
[Core Service] 
    ├─ 创建 ErrorItem (verification_status = "raw")
    ├─ 保存 ai_confidence JSONB
    └─ 返回识别结果 + 置信度 → 低置信度字段标记
    │
    ▼
[小程序] 展示识别结果（绿/黄/红分级）
    ├─ 用户逐字段修正低置信度字段
    ├─ 每修正一个字段 → 记录 CorrectionLog
    └─ 用户点击"确认"
    │
    ▼
[Core Service]
    ├─ PATCH ErrorItem (verification_status = "reviewed")
    ├─ 修正的字段更新为用户修正值
    └─ AI 原始值保留在 CorrectionLog
    │
    ▼
[Analysis Pipeline] reviewed 状态的错题进入分析管道

3.2 练习推荐（P1）

[小程序] 请求推荐
    │
    ▼
[Recommendation Service] 
    ├─ 查询用户薄弱点 (AnalysisReport)
    │   └─ 仅统计 verification_status != "raw" 的错题
    ├─ 粗筛：关键词 + Jaccard 相似度 → 候选集
    ├─ 精排：AI 语义匹配（候选集不足时）
    └─ 排序 + 去重 → 返回推荐列表

3.3 错题打印/PDF 输出（P0）

[小程序] 在错题列表中选择
    │
    ▼
[Print Service]
    ├─ 获取错题数据（结构化内容优先，无匹配时降级为增强图片）
    ├─ PDFKit 排版生成（A4/300DPI）
    └─ 上传到 S3 → 返回临时下载链接（24h 过期）
    │
    ▼
[小程序] 预览 → 下载 PDF → 自行打印

4. 关键设计决策

4.1 单体后端 → 未来拆分

MVP 阶段使用单一 NestJS 后端服务。Phase 3 按业务域拆分为微服务（用户服务、错题服务、推荐服务）。

原因: MVP 阶段团队 1 人，单体架构开发效率最高，NestJS 模块化设计天然支持后续拆分。

4.2 AI 能力分层

Phase 2: Coze SDK（快速上线，无需自训模型）
    ↓
Phase 3: P02 自训模型（针对错题领域微调，降低 API 成本）

原因: MVP 验证产品价值，用现成 AI 服务。自研模型在产品方向确认后投入。

4.3 题库策略

MVP 阶段接入第三方题库 API（如作业帮开放平台），Phase 3 评估是否自建题库。

4.4 数据质量：人机协同修正闭环

核心问题: AI 识别（尤其手写体 OCR）不可能 100% 准确，错误数据进入分析管道会污染飞轮。

架构对策:

层面	机制	说明
识别时	分字段置信度	AI 对每个字段独立评分，低置信度高亮提示
入库时	verification_status	`raw`(未确认) → `reviewed`(已确认) → `corrected`(已修正)
分析时	数据质量门控	AnalysisReport 仅统计 `reviewed` 及以上状态的错题
修正时	CorrectionLog	记录 AI 值 vs 用户修正值，P02 阶段用于微调模型
交互时	低摩擦确认	批量确认、置信度分级 UI 降低修正成本

关键原则: AI 是草稿，用户是编辑。用户每一次修正都是免费的标注数据。

4.5 数据飞轮——双通道采集

ErrLens 有两条互补的数据飞轮，共同为 P02 自研模型提供训练数据：

通道	数据来源	收集内容	P02 用途
文本侧	CorrectionLog	AI 识别值 vs 用户修正值（知识点、学科、错误类型）	微调 OCR/分类/诊断模型
图像侧	用户修正操作	透视校正关键点、笔迹分割标记、题目匹配反馈	训练图像预处理模型（透视校正、笔迹去除）

两条飞轮共享同一个核心假设：产品设计得越好用，用户修正越自然，训练数据越丰富，模型越强——正向循环。

5. 部署架构（目标态）

┌──────────────────────────────────────────┐
│              微信小程序平台               │
│  (代码包 < 2MB，分包加载)                 │
└──────────────────┬───────────────────────┘
                   │ HTTPS
                   ▼
┌──────────────────────────────────────────┐
│              Nginx (HTTPS)               │
│             负载均衡 + 静态资源             │
└──────────────────┬───────────────────────┘
                   │
      ┌────────────┼────────────┐
      ▼            ▼            ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ NestJS   │ │ NestJS   │ │ NestJS   │
│ 实例 1   │ │ 实例 2   │ │ 实例 3   │
└────┬─────┘ └────┬─────┘ └────┬─────┘
     │            │            │
     └────────────┼────────────┘
                  │
     ┌────────────┼────────────┐
     ▼            ▼            ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│PostgreSQL│ │  Redis   │ │ S3/MinIO │
│  主库    │ │  缓存     │ │ 图片存储  │
└──────────┘ └──────────┘ └──────────┘

MVP 阶段用单实例部署，Nginx + 1x NestJS + 1x PostgreSQL + 1x MinIO 即可。

三环境规划（适配 Coze 沙盒自动化测试）:

环境	用途	Coze 沙盒
dev	本地开发 + AI 快速迭代	Coze 沙盒自动运行单元/集成测试
test	灰度验证 + 真机测试	Coze 沙盒运行完整回归测试
prod	生产环境	仅监控，不跑自动测试

灰度发布策略: test 环境验证通过 → prod 先切换 10% 流量 → 监控无异常 → 全量切换。

6. MVP 范围与边界

模块	MVP (Phase 2)	Phase 3+
小程序端	错题录入、列表、详情、分析、PDF 输出	练习推荐、报告、家长端
后端 API	REST API、鉴权、文件上传、图像预处理、打印	GraphQL、微服务拆分
AI 能力	Coze SDK（OCR + 分类）+ 关键词粗筛	P02 自研模型 + AI 精排
图像处理	透视校正 + CLAHE + 笔迹去除（红/蓝）	黑笔自动去除、模型训练
数据库	PostgreSQL 单库	读写分离、缓存层
部署	三环境（dev/test/prod）+ Coze 沙盒	容器化、CI/CD

关联: PRD.md → 模块设计.md → 数据模型.md

12 KiB Raw Permalink Blame History Unescape Escape