# 总体架构

> 版本: 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*