tupingr
e3f4af9c0c
- 总体架构：新增打印/图像预处理/双飞轮/三环境部署 - 技术选型：调整决策理由（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>
247 lines
12 KiB
Markdown
247 lines
12 KiB
Markdown
# 总体架构
|
||
|
||
> 版本: 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*
|