chore(phase): Phase 1 收尾 — 一鸡多吃 + Dev工作台初始化 + Phase 2启动

- Phase 1 标记 100% 完成，Phase 2 标记 ACTIVE
- Dev AI 工作台重写：8个任务入队 + 依赖关系图
- 一鸡多吃：6篇对外分享文章（项目缘起/框架思路/阶段复盘/3篇决策故事）
- 新增 share-context Skill（内部文档→对外分享自动化）
- P01 文档同步更新（需求/架构/接口定义）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.ai/knowledge/journal/2026-05-26.md

@@ -0,0 +1,32 @@
+# Arch AI · 今日任务 · 2026-05-26
+
+## 已完成
+
+- [x] **[P0]** 编写 `docs/01_产品需求/PRD.md` — 错题本产品需求文档
+- [x] **[P0]** 设计 `docs/02_系统架构/` — 总体架构、技术选型、模块设计、数据模型
+- [x] **[P1]** 将 P01 项目文档从"代码检测"改写为"错题本"
+- [x] **[P1]** 更新 ROADMAP.md 任务看板（PRD 完成后分配 Dev 任务）
+
+## 交付物
+
+| 文件 | 状态 |
+|------|------|
+| `docs/01_产品需求/PRD.md` | 草案完成，待人类审阅（第 10 节 5 个待决策事项） |
+| `docs/02_系统架构/总体架构.md` | 完成 |
+| `docs/02_系统架构/技术选型.md` | 完成 |
+| `docs/02_系统架构/模块设计.md` | 完成 |
+| `docs/02_系统架构/数据模型.md` | 完成 |
+| `projects/P01_errlens_app/docs/01_需求概要.md` | 已改写 |
+| `projects/P01_errlens_app/docs/02_架构设计.md` | 已改写 |
+| `projects/P01_errlens_app/docs/03_接口定义.md` | 已改写 |
+| `ROADMAP.md` | 已更新，RED 阻塞解除，Dev 任务已分配 |
+
+## 明天 (2026-05-27)
+
+1. **根据人类反馈修订 PRD**（若有修改意见）
+2. **将 Dev 任务写入 Dev AI 工作台**，指导 Dev 开始开发
+3. **补充架构决策记录 ADR-009**（错题本技术选型决策）
+
+## 阻塞
+
+（无 — 等待人类审阅 PRD 第 10 节）

.ai/roles/arch/queue.md

@@ -4,11 +4,14 @@
 
 | # | 任务 | 优先级 | 状态 | 依赖 |
 |---|------|--------|------|------|
-| 1 | 信息架构重构 | P0 | DOING | — |
+| 1 | 信息架构重构 | P0 | DONE | — |
-| 2 | 错题本 PRD 编写 | P0 | TODO | 1 |
+| 2 | 错题本 PRD 编写 | P0 | DONE | 1 |
-| 3 | 系统架构设计 | P1 | TODO | 2 |
+| 3 | 系统架构设计 | P0 | DONE | 2 |
-| 4 | P01 文档改写 | P1 | TODO | 2 |
+| 4 | P01 文档改写 | P1 | DONE | 2 |
-| 5 | 架构提示词模板 | P2 | TODO | — |
+| 5 | PRD 修订（根据人类反馈） | P0 | TODO | 人类审阅 |
+| 6 | 将 Dev 任务写入 Dev 工作台 | P1 | TODO | 3 |
+| 7 | 补充 ADR-009 技术选型决策 | P1 | TODO | 3 |
+| 8 | 架构提示词模板 | P2 | TODO | — |
 
 ## 未来阶段预留
 

.ai/roles/arch/today.md

@@ -1,18 +1,44 @@
-# Arch AI · 今日任务 · 2026-05-25
+# Arch AI · 今日任务 · 2026-05-26
 
 ## 已完成
 
-- [x] 信息架构重构 — 四层分层架构全部落地
+- [x] **[P0]** 编写 `docs/01_产品需求/PRD.md` v0.3.0 — 错题本产品需求文档（已锁定）
-- [x] DASHBOARD.md + ROADMAP.md + docs/使用手册.md
+- [x] **[P0]** 设计 `docs/02_系统架构/` — 总体架构、技术选型、模块设计、数据模型（v0.3.0）
-- [x] 项目模板化（ai_project 分支）+ 同步机制
+- [x] **[P1]** 将 P01 项目文档从"代码检测"改写为"错题本"
-- [x] 知识沉淀：ADR-007, ADR-008, P-001~003, L-001
+- [x] **[P1]** 更新 ROADMAP.md 任务看板（PRD 完成后分配 Dev 任务）
+- [x] **[P0]** 数据质量架构闭环：人机协同修正（ADR-009）
+- [x] **[P0]** 决策落地：双题库源、用户树状邀请、数学+英语双学科、Freemium
+- [x] **[P0]** 旧架构合并：30 项决策逐项确认，5 份架构文档更新至 v0.4.0
+- [x] **[P0]** Phase 1 收尾：ROADMAP/DASHBOARD 更新，Dev 工作台初始化，ADR-010 补充
+- [x] **[P0]** Phase 2 启动：8 个 Dev 任务入队，依赖关系图完成
 
-## 明天 (2026-05-26)
+## Phase 1 收尾清单
 
-1. **[P0]** 编写 `docs/01_产品需求/PRD.md` — 错题本产品需求文档
+| 动作 | 状态 |
-2. **[P0]** 设计 `docs/02_系统架构/` — 系统架构文档
+|------|------|
-3. **[P1]** 将 P01 项目文档从"代码检测"改写为"错题本"
+| ROADMAP Phase 1 → DONE 100% | ✅ |
-4. **[P1]** 更新 ROADMAP.md 任务看板（PRD 完成后分配 Dev 任务）
+| ROADMAP Phase 2 → ACTIVE | ✅ |
+| DASHBOARD 阶段切换 | ✅ |
+| Dev AI queue.md 重写 | ✅ |
+| Dev AI today.md 初始化 | ✅ |
+| ADR-010 题库抽象层 | ✅ |
+
+## 旧架构合并（30 项决策全部确认）
+
+| # | 决策 | 结论 |
+|---|------|------|
+| 1 | 题库来源 | 自有 PDF 录入 + 作业帮 API 双源，架构层抽象适配 |
+| 2 | AI 能力 | 分层使用：Coze 测试/验证，Claude 架构，其他 AI 做 Coding |
+| 3 | 用户体系 | MVP 仅微信登录，邀请码分享形成树状结构 |
+| 4 | 商业化 | 基础免费 + 会员，MVP 全免费 |
+| 5 | 首发学科 | 数学 + 英语 |
+
+## 明天 (2026-05-27)
+
+1. UI 设计规范迁移（从旧架构迁移到新架构 `docs/02_系统架构/UI设计规范.md`）
+2. 测试方案迁移（从旧架构迁移，调整为 Coze 沙盒自动化测试方案）
+3. 部署方案重写（三环境 dev/test/prod + Coze 沙盒配置）
+4. 根据人类反馈做修订
 
 ## 阻塞
 

.ai/roles/dev/queue.md

@@ -1,17 +1,36 @@
 # Dev AI · 任务队列
 
-## 当前阶段 (Phase 1) 可执行任务
+## Phase 2 MVP 任务
 
 | # | 任务 ID | 项目 | 描述 | 优先级 | 状态 |
 |---|---------|------|------|--------|------|
-| 1 | P03-001 | Web | 项目初始化 | LOW | TODO |
+| 1 | P01-001 | App | 数据库 Schema 实现 + 迁移脚本 | P0 | TODO |
-| 2 | CROSS-001 | 共享 | 共享工具库更新 | HIGH | TODO |
+| 2 | P01-002 | App | Auth 模块（微信登录 + JWT） | P0 | TODO |
-| 3 | P01-001 | App | 用户登录 | HIGH | TODO |
+| 3 | CROSS-001 | 共享 | 共享工具库日期格式 bug 修复 | P0 | TODO |
-| 4 | P01-002 | App | 代码分析 API | MEDIUM | TODO |
+| 4 | P01-005 | App | Image 模块（图像预处理管线） | P0 | TODO |
-| 5 | P02-001 | 训练 | 数据预处理 | MEDIUM | TODO |
+| 5 | P01-006 | App | Print 模块（PDF 生成 + S3 + 清理） | P0 | TODO |
+| 6 | P01-004 | App | Upload 模块（图片上传 + S3 + 缩略图） | P1 | TODO |
+| 7 | P01-003 | App | User 模块（个人资料 CRUD + 邀请链） | P1 | TODO |
+| 8 | P01-007 | App | 页面路由 + 基础页面骨架 | P1 | TODO |
 
-## 任务详情
+## 依赖关系
 
-每个任务的详细描述 → `review/active/{任务ID}/task.md`
+```
-验收标准 → `review/active/{任务ID}/acceptance.md`
+P01-001 (DB Schema)
-影响范围 → `review/active/{任务ID}/impact.md`
+  ├─→ P01-002 (Auth)    ──→ P01-003 (User)   ──→ P01-007 (Pages)
+  ├─→ P01-004 (Upload)  ──→ P01-005 (Image)
+  └─→ P01-006 (Print)
+```
+
+- P01-001 是所有模块的前置依赖，优先完成
+- P01-002/004 可并行
+- P01-005 依赖 P01-004（需要上传的图片 URL 做输入）
+- P01-007 最后做，需要在各模块 API 稳定后
+
+## 参考文档
+
+- PRD: `docs/01_产品需求/PRD.md` (v0.4.0)
+- 总体架构: `docs/02_系统架构/总体架构.md` (v0.4.0)
+- 技术选型: `docs/02_系统架构/技术选型.md` (v0.4.0)
+- 模块设计: `docs/02_系统架构/模块设计.md` (v0.4.0)
+- 数据模型: `docs/02_系统架构/数据模型.md` (v0.4.0)

.ai/roles/dev/today.md

@@ -1,24 +1,29 @@
-# Dev AI · 今日任务 · 2026-05-25
+# Dev AI · 今日任务 · 2026-05-26
 
-## 进行中
+## 状态：Phase 2 MVP 启动
 
-（无）
+Phase 1（基础搭建）已收尾。PRD v0.4.0 / 系统架构 v0.4.0 / 数据模型 v0.4.0 全部锁定。
 
 ## 待领取（按优先级）
 
-| # | 任务 | 来源 | 说明 |
+| # | 任务 | 优先级 | 说明 |
-|---|------|------|------|
+|---|------|--------|------|
-| 1 | P03-001 | `review/active/P03-001/` | Web 项目初始化（无依赖，可立即开始） |
+| 1 | P01-001 | P0 | 数据库 Schema 实现 + Drizzle 迁移脚本。参考 [数据模型.md](../../../docs/02_系统架构/数据模型.md) 全部表定义 |
-| 2 | CROSS-001 | `review/active/CROSS-001/` | 共享工具库更新（等待已有 bug 修复） |
+| 2 | P01-002 | P0 | Auth 模块（微信 code2session + JWT 签发 + AuthGuard）。参考 [模块设计.md](../../../docs/02_系统架构/模块设计.md#31-auth-模块) |
+| 3 | CROSS-001 | P0 | 共享工具库日期格式 bug 修复 |
+| 4 | P01-005 | P0 | Image 模块（Sharp 图像预处理管线：透视校正 + CLAHE 增强 + 笔迹去除）。参考 [模块设计.md](../../../docs/02_系统架构/模块设计.md#36-image-模块图像预处理) |
+| 5 | P01-006 | P0 | Print 模块（PDFKit 生成 + S3 上传 + 24h 过期清理）。参考 [模块设计.md](../../../docs/02_系统架构/模块设计.md#37-print-模块pdf-输出p0) |
+| 6 | P01-004 | P1 | Upload 模块（图片上传 S3 + 缩略图） |
+| 7 | P01-003 | P1 | User 模块（个人信息 CRUD + 邀请码生成 + 邀请链查询） |
+| 8 | P01-007 | P1 | 页面路由 + 9 个基础页面骨架（含打印预览页） |
 
-## 暂不可领（等待 Arch AI）
+## 关键架构文档
 
-| # | 任务 | 阻塞原因 |
+- [数据模型.md](../../../docs/02_系统架构/数据模型.md) — 所有表定义、索引、Drizzle Schema 示例
-|---|------|----------|
+- [模块设计.md](../../../docs/02_系统架构/模块设计.md) — API 接口、模块结构
-| 1 | P01-001 用户登录 | 等待 PRD |
+- [总体架构.md](../../../docs/02_系统架构/总体架构.md) — 数据流、部署架构
-| 2 | P01-002 代码分析API | 等待 PRD |
+- [技术选型.md](../../../docs/02_系统架构/技术选型.md) — 技术栈版本
-| 3 | P02-001 数据预处理 | 等待 PRD |
 
 ## 已完成
 
-（无）
+（Phase 2 暂无）

.trae/skills/share-context/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: "share-context"
+description: "一鸡多吃：将内部开发文档（ADR、阶段复盘、开发日志）翻译为对外分享文章。阶段收尾时或用户说「一鸡多吃」「同步分享」「发布分享」时调用。"
+---
+
+# 一鸡多吃 — 内部文档转对外分享 Skill
+
+## 功能
+
+将开发过程中积累的内部文档（架构决策、阶段完成记录、踩坑经验）翻译为对外可发布的分享文章，写入 `docs/share/` 目录。
+
+**核心逻辑**：同一份工作，两种产出。内部文档（给 AI 看）→ 去敏 + 加故事 + 加思考过程 → 对外文章（给人看）。
+
+## 触发条件
+
+- 用户说「一鸡多吃」「同步分享」「发布分享」「更新分享」
+- 阶段收尾时（Phase completion）
+- 有新的 ADR 或重要决策产生后
+
+## 执行步骤
+
+### 1. 扫描内部文档，识别可分享内容
+
+按以下来源对比 `docs/share/` 已有内容，找出新增/变化：
+
+| 内部来源 | 对应对外产出 | 判断标准 |
+|---------|-------------|---------|
+| `.ai/knowledge/decisions.md` 中的新 ADR | `phase-XX/决策故事_ADR-XXX.md` | 有新 ADR 且无对应故事文件 |
+| `.ai/phases/phase-XX-*/completion.md` | `phase-XX/阶段复盘_XXX.md` | 阶段已完成且复盘文件为空/待写 |
+| `.ai/knowledge/lessons.md` | 踩坑记录（融入复盘或独立） | 有新的经验教训记录 |
+| `.ai/knowledge/journal/` | 开发周记 | 有新的日志文件 |
+
+### 2. 确定本次要写的文章
+
+列出待写文章清单，向用户确认优先级和范围。
+
+### 3. 逐篇撰写
+
+每篇文章遵循以下原则：
+
+**内容要求**：
+- 不只说「做了什么」，重点说「为什么这么选」
+- 有具体的决策场景（当时遇到了什么问题）
+- 有可复用的方法论（下次遇到类似情况怎么做）
+- 有真实的踩坑和教训（不粉饰）
+- 一句话总结（可引用/可传播）
+
+**安全要求**：
+- ❌ 不暴露 API 密钥、服务器地址、数据库连接串
+- ❌ 不暴露真实用户名、手机号、微信号
+- ❌ 不暴露未公开的第三方合作信息
+- ✅ 技术方案可以详细写
+- ✅ 决策过程可以完整写
+- ✅ 思考逻辑可以展开写
+
+**写作风格**：
+- 第一人称（「我」），人类视角
+- 像讲故事，不像写文档
+- 目标读者是「对 AI 编程感兴趣的人」，不是机器
+- 每篇 800-1500 字，独立可读
+
+### 4. 更新分享目录
+
+更新 `docs/share/README.md` 中的文章列表和状态。
+
+### 5. 告知用户
+
+```markdown
+## 一鸡多吃完成
+
+### 新增文章
+| 文件 | 内容 |
+|------|------|
+| [文章名](路径) | 一句话描述 |
+
+### 更新文章
+| 文件 | 变更 |
+|------|------|
+| [文章名](路径) | 更新内容简述 |
+
+### 分享目录
+→ `docs/share/README.md`
+```
+
+## 文件结构
+
+```
+docs/share/
+├── README.md                          # 分享目录索引
+├── 00_项目缘起.md                      # 项目背景（一次性写完，后续微调）
+├── 01_框架设计思路.md                  # 核心理念（一次性写完，后续微调）
+├── phase-01/                          # Phase 1 分享内容
+│   ├── 阶段复盘_基础搭建.md             # 阶段复盘
+│   ├── 决策故事_ADR-007.md             # 信息架构决策
+│   ├── 决策故事_ADR-009.md             # 人机协同决策
+│   └── 决策故事_旧架构合并.md           # 旧架构合并决策
+├── phase-02/                          # Phase 2 分享内容（待产生）
+│   └── ...
+└── templates/                         # 写作模板
+    ├── 阶段复盘模板.md
+    └── 决策故事模板.md
+```
+
+## 注意事项
+
+1. **不是做完再写**：开发过程中自动积累，阶段结束时批量产出
+2. **同一份工作，两种语言**：内部文档是「给 AI 看的结构化数据」，对外文章是「给人看的故事」
+3. **保持真诚**：有成功写成功，有失败写失败。读者能看出哪些是 PR 稿
+4. **去敏但不去肉**：去掉敏感信息，但保留具体细节。一个没有细节的故事没有价值
+5. **链接内部来源**：每篇文章底部可附「内部参考：ADR-XXX」但不暴露内部文件路径
+
+---
+
+**Version**: 1.0  
+**Created**: 2026-05-26  
+**Based On**: ErrLens 开发实践 — Phase 1 收尾时的「一鸡多吃」流程  
+**Purpose**: 将内部开发文档自动转化为对外分享内容，实现「开发即内容」的闭环  

DASHBOARD.md

@@ -6,9 +6,9 @@
 
 ## 当前状态
 
-**Phase 1/4 — 基础搭建** · 进度约 30%
+**Phase 2/4 — MVP 开发** · 进度 0%
 
-我们正在搭建项目的"骨架"：定义 AI 怎么协作、目录怎么组织、开发环境怎么跑。还没开始写业务代码。
+Phase 1 基础搭建已收尾（100%）。PRD/架构/数据模型全部锁定，Dev AI 开始编码。
 
 ---
 
@@ -16,8 +16,8 @@
 
 | 阶段 | 进度 | 状态 | 一句话说明 |
 |------|------|------|------------|
-| 1. 基础搭建 | ~30% | ← 当前 | 搭骨架：框架、权限、信息架构 |
+| 1. 基础搭建 | 100% | ✅ | 搭骨架：PRD 锁定、架构文档完成、旧架构合并 |
-| 2. MVP | 0% | 未开始 | 做核心：错题录入、AI 分析 |
+| 2. MVP | 0% | ← 当前 | 做核心：错题录入、AI 分析、PDF 打印、图像预处理 |
 | 3. 功能完善 | 0% | 未开始 | 加功能：推荐、多端、训练迭代 |
 | 4. 打磨发布 | 0% | 未开始 | 提质量：性能、安全、文档 |
 
@@ -25,16 +25,15 @@
 
 ## 现在在做什么
 
-- **信息架构重构** — 让 AI 能高效协作的文档体系（进行中）
+- **Dev AI 启动编码** — 数据库 Schema → Auth → Image → Print → User → Upload → 页面骨架
-- **5 个开发任务待启动** — 都在等待产品需求文档
+- **Arch AI 补尾** — ADR-010（题库抽象层）、UI 规范迁移
+- **Phase 2 目标** — 拍照录入 + AI 分析 + PDF 输出 + 用户系统完整闭环
 
 ---
 
 ## 需要你关注的事
 
-- [ ] 确认信息架构设计方向是否符合预期
+- [ ] 无。30 项决策已全部确认，Phase 2 由 AI 执行开发。
-- [ ] 审阅角色工作台（`.ai/roles/`）是否合理
-- [ ] 决定 P01 项目方向：坚持"错题本"还是调整定位
 
 ---
 
@@ -42,6 +41,8 @@
 
 | 你想看什么 | 去哪里 |
 |------------|--------|
+| **产品需求文档** | **[docs/01_产品需求/PRD.md](docs/01_产品需求/PRD.md)** |
+| **系统架构设计** | **[docs/02_系统架构/](docs/02_系统架构/)** |
 | **怎么使用这套体系** | **[docs/使用手册.md](docs/使用手册.md)** |
 | 详细任务看板 | [ROADMAP.md](ROADMAP.md) |
 | 项目为什么要这样做 | [docs/share/](docs/share/) |

ROADMAP.md

@@ -7,44 +7,61 @@
 ## 阶段总览
 
 ```
-Phase 1 [=====-----] 基础搭建     ← 当前 (40%)
+Phase 1 [==========] 基础搭建     ✅ 已完成 (100%)
-Phase 2 [----------] MVP           (0%)
+Phase 2 [----------] MVP           ← 当前 (0%)
 Phase 3 [----------] 功能完善      (0%)
 Phase 4 [----------] 打磨发布      (0%)
 ```
 
 | 阶段 | 名称 | 状态 | 进度 | 预计重点 |
 |------|------|------|------|----------|
-| 1 | 基础搭建 | ACTIVE | ~40% | 框架、脚手架、权限、信息架构 |
+| 1 | 基础搭建 | DONE | 100% | 框架、脚手架、PRD、架构设计、旧架构合并 |
-| 2 | MVP | PLANNED | 0% | 错题录入、AI 分析、基础展示 |
+| 2 | MVP | ACTIVE | 0% | 错题录入、AI 分析、PDF 打印、图像预处理 |
-| 3 | 功能完善 | PLANNED | 0% | 个性化推荐、多端适配、训练迭代 |
+| 3 | 功能完善 | PLANNED | 0% | 个性化推荐、多端、训练迭代 |
 | 4 | 打磨发布 | PLANNED | 0% | 性能优化、安全审计、文档完善 |
 
 ---
 
-## 当前阶段 (Phase 1) 任务看板
+## Phase 1 回顾（已完成）
 
-### TODO（待开始）
+| 交付物 | 版本 | 完成日期 |
+|------|------|----------|
+| 信息架构重构 | — | 2026-05-25 |
+| 错题本 PRD | v0.4.0 | 2026-05-26 |
+| 系统架构（总体+技术+模块+数据模型） | v0.4.0 | 2026-05-26 |
+| P01 文档改写（代码检测→错题本） | — | 2026-05-26 |
+| 5 项决策确认（题库/AI/用户/商业化/学科） | — | 2026-05-26 |
+| ADR-009 数据质量闭环 | — | 2026-05-26 |
+| 旧架构合并 30 项决策 | — | 2026-05-26 |
 
-| 任务 | 项目 | 描述 | 优先级 | 阻塞原因 |
+---
-|------|------|------|--------|----------|
-| P01-001 | App | 用户登录注册 | HIGH | 等待 PRD |
-| P01-002 | App | 代码分析 API | MEDIUM | 等待 PRD + 项目定位确认 |
-| P02-001 | 训练 | 数据集预处理 | MEDIUM | 等待 PRD |
-| P03-001 | Web | Web 项目初始化 | LOW | — |
-| CROSS-001 | 共享 | 共享工具库更新 | HIGH | 1 个日期格式 bug 待修 |
 
-### DOING（进行中）
+## 当前阶段 (Phase 2) 任务看板
+
+### TODO（待领）
+
+| 任务 | 项目 | 描述 | 优先级 | 负责人 |
+|------|------|------|--------|--------|
+| P01-001 | App | 数据库 Schema 实现 + 迁移脚本 | P0 | Dev AI |
+| P01-002 | App | Auth 模块（微信登录 + JWT） | P0 | Dev AI |
+| P01-005 | App | Image 模块（图像预处理管线） | P0 | Dev AI |
+| P01-006 | App | Print 模块（PDF 生成 + S3 + 过期清理） | P0 | Dev AI |
+| P01-004 | App | Upload 模块（图片上传 + S3） | P1 | Dev AI |
+| P01-003 | App | User 模块（个人信息 CRUD + 邀请链） | P1 | Dev AI |
+| P01-007 | App | 页面路由 + 基础页面骨架（含打印页） | P1 | Dev AI |
+| CROSS-001 | 共享 | 共享工具库日期格式 bug 修复 | P0 | Dev AI |
+
+### DOING
 
 | 任务 | 项目 | 描述 | 负责人 | 预计完成 |
 |------|------|------|--------|----------|
-| — | 全局 | 编写错题本 PRD | Arch AI | 2026-05-26 |
+| — | — | （无） | — | — |
 
-### DONE（已完成）
+### DONE
 
 | 任务 | 项目 | 描述 | 完成日期 |
 |------|------|------|----------|
-| — | 全局 | 信息架构重构 | 2026-05-25 |
+| — | — | （Phase 2 暂无完成项） | — |
 
 ---
 
@@ -52,9 +69,7 @@ Phase 4 [----------] 打磨发布      (0%)
 
 | 级别 | 描述 | 影响范围 | 分配给 | 创建日期 |
 |------|------|----------|--------|----------|
-| RED | PRD 未编写 | P01-001, P01-002, P02-001 无法开始 | Arch AI | 2026-05-23 |
+| YELLOW | CROSS-001 日期格式 bug | CROSS-001 无法关闭 | Dev AI | 2026-05-23 |
-| YELLOW | P01 文档内容仍是"代码检测"模板 | P01-002 定位错误 | Arch AI | 2026-05-23 |
-| YELLOW | CROSS-001 P01 日期格式 bug | CROSS-001 无法关闭 | Dev AI | 2026-05-23 |
 
 ---
 
@@ -62,5 +77,7 @@ Phase 4 [----------] 打磨发布      (0%)
 
 | 日期 | 事件 |
 |------|------|
+| 2026-05-26 | Phase 1 收尾（100%），Phase 2 启动，Dev AI 工作台初始化 |
+| 2026-05-26 | 旧架构合并完成：30 项决策落地，5 份架构文档升级至 v0.4.0 |
 | 2026-05-25 | 信息架构重构完成 + 项目模板化（ai_project 分支） |
 | 2026-05-23 | 框架搭建完成：目录结构、权限体系、7 个 Skill |

docs/share/00_项目缘起.md

@@ -1,5 +1,82 @@
-# 项目缘起
+# 项目缘起：为什么我要做一个 AI 错题本
 
-> *（待写：由 Arch AI 在 PRD 完成后撰写）*
+> 一个不会写代码的产品经理，用 AI 从零开发一个 App 的全记录。
->
+
-> 内容包括：为什么要做错题本、解决什么痛点、为什么选择这个技术方案、为什么用 AI 协作模式。
+---
+
+## 起点：一个做了很多年的梦
+
+我一直在做教育相关的事情。
+
+这么多年来，我见过太多学生被同一个问题困扰：**错题整理太痛苦了**。手抄错题、自己分类、凭感觉复习——每一步都在消耗学生的耐心。而传统错题本 App 呢？拍照 OCR 识别率低、分类粗糙、推荐随机。用一个学生的话说：「花了半小时录入，得到的分析和我自己翻两页书差不多。」
+
+我想做一个真正有用的错题本。但问题是：**我不会写代码。**
+
+过去这个想法就只能停留在想法。直到 AI 编程工具出现了。
+
+---
+
+## 核心问题：AI 能写代码，但能做一个完整的产品吗？
+
+2025 年底开始，AI 编程工具层出不穷。Cursor、Copilot、Claude Code——它们能帮你写函数、修 bug、甚至生成整个页面。
+
+但我有一个更大的问题：**一个不会写代码的人，能不能靠 AI 从零做出一个能上线的产品？**
+
+这不仅是写几段代码的问题，而是：
+
+- 产品需求谁定？
+- 架构设计谁做？
+- 多个 AI 之间怎么分工？
+- AI 写的代码质量怎么保证？
+- 遇到 AI 解决不了的 bug 怎么办？
+
+我决定用自己当实验品，把这个过程完整记录下来。
+
+---
+
+## 为什么选错题本
+
+除了个人情结，还有一个技术判断：
+
+**错题本是 AI 编程能力的最佳试金石。**
+
+它需要：
+- 前端（小程序 UI）——考验 AI 的 UI 还原能力
+- 后端（API + 数据库）——考验 AI 的架构能力
+- AI 集成（OCR + 分类 + 推荐）——考验 AI 调用 AI 的能力
+- 图像处理（拍照增强 + 笔迹去除）——考验 AI 的算法能力
+- 数据闭环（用户修正 → 反哺训练）——考验 AI 的系统设计能力
+
+能把这个项目做出来，基本上什么类型的 AI 编程任务都能覆盖了。
+
+---
+
+## 1 人 + 3 AI：我的协作模式
+
+我给自己设计了一套「AI 团队」：
+
+| 角色 | 做什么 | 权限 |
+|------|--------|------|
+| **Arch AI**（Claude） | 架构设计、PRD、技术选型、决策记录 | 读写文档 |
+| **Dev AI**（Claude + Coze） | 写代码、数据库、API、前端页面 | 读写代码 |
+| **QA AI**（Coze 沙盒） | 自动化测试、回归验证 | 只读代码 |
+
+所有 AI 都听我指挥。我只负责三件事：**做决策、验结果、写分享。**
+
+这套模式的核心思想是：人类决定「做什么」和「为什么」，AI 负责「怎么做」。
+
+---
+
+## 这个系列会记录什么
+
+1. **产品从零到一**：PRD 怎么写、架构怎么设计、决策怎么做
+2. **AI 协作的真实体验**：AI 什么时候好用、什么时候翻车、怎么让 AI 配合工作
+3. **技术选型的思考**：为什么选这个不选那个，每一个选择背后的权衡
+4. **踩过的坑**：AI 写的代码跑了但不对、架构设计推翻重来、旧方案合并的痛苦
+5. **数据和思考**：每个阶段的交付物、决策记录、经验教训
+
+这不是一个「AI 太强了帮我做了一切」的爽文。这是一个真实的、有成功有失败、有纠结有突破的开发记录。
+
+---
+
+*下一篇：[框架设计思路](01_框架设计思路.md) — 为什么传统的项目文档结构对 AI 不友好*

docs/share/01_框架设计思路.md

@@ -1,8 +1,106 @@
-# 框架设计思路
+# 框架设计思路：当文档的读者不是人类
 
-> *（待写：信息架构重构稳定后撰写）*
+> 传统项目结构对 AI 不友好——我的信息架构是怎么一步步推到重来的。
->
+
-> 内容包括：为什么传统的项目文档结构对 AI 不友好、分层信息架构的设计思考、token 预算的概念、"一鸡多吃"的分享层设计。
+---
->
+
-> 对应 ADR：ADR-007
+## 问题的起点：AI 看不懂我的项目
-> 背景参考：`.ai/principles.md`
+
+第一次用 Claude Code 时，我兴奋地让它帮我写个功能。结果它盯着我的项目看了半天，然后开始瞎写。
+
+问题不在 AI，在我的项目文档。
+
+一个典型的人类项目文档是这样的：一个巨大的 README.md，里面塞了项目介绍、架构设计、API 文档、部署说明、开发规范……人类会跳着读，挑自己需要的部分。但 AI 不会跳读——它会从头到尾读完，然后在第 5000 行开始「记忆衰减」。
+
+更致命的是：**不同 AI 角色需要的信息完全不同。** Dev AI 需要知道数据库表结构，不需要知道为什么 ADR-007 选了分层架构。但你把这些全混在一个文件里，AI 就只能全部消化。
+
+结论：**为人类设计的文档结构，不适合 AI 协作。**
+
+---
+
+## 第一次尝试：从 README 到 AGENTS.md
+
+我先学着社区的做法，把所有 AI 需要的信息写进一个 `AGENTS.md`。
+
+一开始还行。但越写越长。PRD、架构、技术栈、目录结构、权限矩阵、ADR、Skill 定义……写到 2000 行的时候，AI 开始「忘记」前面的内容。
+
+问题出在 **token 预算**。Claude 的上下文窗口约 200K token，看起来很大，但要同时装下 AGENTS.md + 当前代码文件 + 对话历史 + 输出内容，200K 很快就满了。
+
+而且还有一个更隐蔽的问题：**不该看的东西 AI 也看了。** Dev AI 不需要知道 QA AI 的工作流，Arch AI 不需要知道具体代码实现。把不属于它的信息喂给它，既浪费 token，又容易干扰判断。
+
+---
+
+## 第二次重构：分层信息架构
+
+关键洞察来自一个简单问题：**人类团队怎么分工？**
+
+一个有 3 个人的团队，不会把所有信息贴在一面墙上让每个人读完。而是每人有自己的工作台，只看和自己相关的内容。跨角色共享的信息放在公共区域。
+
+把这个逻辑搬到 AI 协作上：
+
+```
+┌─────────────────────────────────────────┐
+│              DASHBOARD.md                │  ← 人类视角，30 秒了解全貌
+├─────────────────────────────────────────┤
+│              ROADMAP.md                  │  ← 人+AI 共享视野，任务看板
+├────────────────┬────────────┬───────────┤
+│  .ai/roles/    │ .ai/roles/ │ .ai/roles/ │
+│  arch/ ← Arch  │ dev/ ← Dev │ qa/ ← QA   │  ← 每人自己的工作台
+│  今天干啥      │ 今天干啥    │ 今天干啥    │
+│  任务队列      │ 任务队列    │ 测试计划    │
+├────────────────┴────────────┴───────────┤
+│         .ai/knowledge/                   │  ← 共享知识库
+│         decisions.md（ADR）              │
+│         journal/（开发日志）              │
+├──────────────────────────────────────────┤
+│         docs/                            │  ← 项目文档
+│         01_产品需求/PRD.md               │
+│         02_系统架构/                     │
+└──────────────────────────────────────────┘
+```
+
+四层结构，每层有明确的 token 预算：
+
+| 层 | 读者 | 内容 | token 预算 |
+|----|------|------|-----------|
+| 仪表盘 | 人类 | 30 秒全貌 | < 1K |
+| 路线图 | 人+AI | 任务看板 | < 3K |
+| 角色工作台 | 单个 AI | 今天干啥、任务详情 | < 2K |
+| 知识沉淀 | 所有 AI | ADR、经验教训 | 按需加载 |
+
+**核心原则：每个 AI 启动时只加载自己那层的信息，不需要的永远不看。**
+
+---
+
+## Token 预算：把「省着用」变成设计原则
+
+很多人觉得 token 窗口够大就不用省。但我的体验是：**省 token 不是为了省，是为了让 AI 注意力集中。**
+
+给你一组对照实验：
+
+```
+方案 A：把所有文档塞进 context → AI 的回复质量不稳定，后面的任务比前面的差
+方案 B：只给当前任务相关的文档 → AI 的回复质量和速度都明显更好
+```
+
+原因很简单：AI 的注意力也是有限的。信息越多，它在噪音中找信号的难度越大。
+
+分层架构的本质，就是**在正确的时刻，给正确的 AI，提供正确的信息量。**
+
+---
+
+## 「一鸡多吃」：分享层是怎么来的
+
+架构稳定后，我发现一个有趣的事：我做的所有决策记录、项目文档、开发日志，天然就是很好的「对外分享素材」。
+
+于是我的产出分两条线：
+- **内部线**（`.ai/`）：给 AI 看的，简短、结构化、有决策理由
+- **外部线**（`docs/share/`）：给人看的，有背景、有故事、有思考过程
+
+同一份工作，两种产出。内部文档 → 去掉敏感信息 → 加上思考过程 → 对外文章。
+
+这就是「一鸡多吃」——开发过程自动积累内容，阶段结束时翻译为对外语言。不需要「专门抽时间写分享」。
+
+---
+
+*下一篇：[Phase 1 阶段复盘](phase-01/阶段复盘_基础搭建.md) — 基础搭建阶段到底做了什么*

docs/share/README.md

@@ -10,15 +10,17 @@
 
 | 文件 | 说明 | 状态 |
 |------|------|------|
-| [00_项目缘起.md](00_项目缘起.md) | 为什么要做这个项目 | 待写 |
+| [00_项目缘起.md](00_项目缘起.md) | 为什么要做这个项目、1 人+3 AI 协作模式 | ✅ 已完成 |
-| [01_框架设计思路.md](01_框架设计思路.md) | 信息架构为什么这样设计 | 待写 |
+| [01_框架设计思路.md](01_框架设计思路.md) | 信息架构为什么这样设计、token 预算概念 | ✅ 已完成 |
 
 ## 按阶段
 
 | 阶段 | 复盘 | 决策故事 | 状态 |
 |------|------|----------|------|
-| Phase 1: 基础搭建 | [阶段复盘](phase-01/阶段复盘_基础搭建.md) | [ADR-007 故事](phase-01/决策故事_ADR-007.md) | 待写 |
+| Phase 1: 基础搭建 | [阶段复盘](phase-01/阶段复盘_基础搭建.md) | [ADR-007 信息架构](phase-01/决策故事_ADR-007.md) | ✅ |
-| Phase 2: MVP | — | — | 未开始 |
+| | | [ADR-009 人机协同](phase-01/决策故事_ADR-009.md) | ✅ |
+| | | [旧架构合并](phase-01/决策故事_旧架构合并.md) | ✅ |
+| Phase 2: MVP | — | — | 进行中 |
 
 ---
 
@@ -26,7 +28,7 @@
 
 1. **不是做完再写**：开发过程中自动积累，阶段结束时翻译为对外语言
 2. **去掉内部细节**：不暴露 API 密钥、服务器地址、个人信息
-3. **加上思考过程**：不只说"做了什么"，更要说"为什么这么选"
+3. **加上思考过程**：不只说「做了什么」，更要说「为什么这么选」
 4. **可独立阅读**：每篇文章自成一体，不需要读其他文章才能理解
 
 ## 内容来源

docs/share/phase-01/决策故事_ADR-007.md

@@ -1,5 +1,75 @@
-# ADR-007 决策故事
+# ADR-007 决策故事：信息架构为什么从「大文档」变成「分层设计」
 
-> 信息架构为什么从"单体文档"变成"分层设计"
+## 背景
->
+
-> *（Phase 1 完成时撰写，基于 `.ai/knowledge/decisions.md` 中的 ADR-007 扩展）*
+ErrLens 项目从一开始就确定用「1 人 + 3 AI」的协作模式——Arch AI 做架构，Dev AI 写代码，QA AI 做测试。
+
+但怎么让 3 个 AI 高效协作？我最初的做法很朴素：写一个大的 AGENTS.md，把项目介绍、架构设计、开发规范、权限体系全塞进去，每个 AI 启动时都读这一份。
+
+然后问题就来了。
+
+---
+
+## 问题：AI 记不住、看不懂、互相干扰
+
+**第一个问题：记不住。**
+
+AGENTS.md 写到 2000 行时，Claude 的回复开始出现明显的「失忆」——前面提到的决策，后面讨论时就忘了。原因是上下文窗口虽然号称 200K token，但越靠后的内容，AI 的关注权重越低。
+
+**第二个问题：看不懂重点。**
+
+AGENTS.md 里混了所有信息——PRD 摘要、架构图、API 定义、目录结构、权限矩阵、Skill 描述……Dev AI 需要在 2000 行里找到和自己相关的 200 行。人类会跳读，AI 不会——它全读完后，重点已经淹没了。
+
+**第三个问题：互相干扰。**
+
+一个更隐蔽的问题：Dev AI 不需要知道 QA AI 的测试流程，Arch AI 不需要知道具体的代码目录结构。把不该看的信息喂给 AI，不仅浪费 token，更容易让它「想太多」——写出过度设计或不相关的代码。
+
+---
+
+## 选项
+
+| 选项 | 优势 | 劣势 |
+|------|------|------|
+| A: 维持单体文档 | 维护简单，改一处就行 | 越长越差，AI 协作天花板低 |
+| B: 精简 AGENTS.md | 立即可做 | 精简意味着丢掉信息，该有的细节还是要有的 |
+| C: 分层信息架构 | 每个 AI 只看自己的，token 利用率高 | 需要重新设计目录结构，上下游依赖要梳理清楚 |
+
+---
+
+## 思考过程
+
+我一开始想走 B 路线——把 AGENTS.md 精简到 500 行以内。但很快发现不行：精简掉的内容不是「冗余」，是「必要的细节」。比如 Drizzle Schema 定义，对 Dev AI 就是刚需，你不能为了省 token 把它删了。
+
+然后我想到一个类比：**人类团队怎么分工？**
+
+一个有 3 个员工的团队，不会把所有信息贴在一面墙上。而是每人有独立工位，各自维护自己的待办和参考资料。共享的信息放在公共区域。
+
+AI 也应该这样。
+
+选项 C 的核心逻辑：
+
+1. **仪表盘**（DASHBOARD.md）——给人类看，30 秒了解项目全貌，不写代码细节
+2. **路线图**（ROADMAP.md）——人+AI 共享视野，任务分配和进度跟踪
+3. **角色工作台**（`.ai/roles/{arch,dev,qa}/`）——每个 AI 自己的 today.md + queue.md，只加载自己需要的上下文
+4. **知识沉淀**（`.ai/knowledge/`）——ADR（架构决策记录）、journal（开发日志），按需加载
+
+每层有 token 预算。Arch AI 启动时加载约 3K token（today + queue + decisions），Dev AI 类似。比单体 AGENTS.md 的 15K+ token 减少了 80%。
+
+---
+
+## 结果
+
+分层后，几个明显的变化：
+
+- **AI 回复质量更稳定**：不再出现「前面说了后面忘」的情况
+- **上下文切换更快**：Dev AI 启动直接读 dev/today.md，不需要从 PRD 开始消化
+- **人类管理成本降低**：DASHBOARD.md 一眼看到项目状态，不需要翻 10 个文件
+- **「一鸡多吃」变得自然**：内部分层文档 → 去掉敏感信息 → 对外分享文章，流水线化
+
+如果重来一次，我会从第一天就做分层。单体文档阶段浪费了大约 1 天的 AI token 和人类审核精力。
+
+---
+
+## 一句话总结
+
+**为 AI 设计文档和为人设计文档，是完全不同的两件事。人会跳读，AI 不会——所以你的信息架构就是 AI 的注意力分配方案。**

docs/share/phase-01/决策故事_ADR-009.md

@@ -0,0 +1,93 @@
+# ADR-009 决策故事：当 AI 识别不完美时，产品怎么设计
+
+## 背景
+
+ErrLens 的核心功能是：学生拍一张错题照片 → AI 识别题目内容 → 自动归类 → 分析错误原因 → 推荐同类练习。
+
+这个流程看起来很美好，但它建立在一个脆弱的假设上：**AI 能准确识别每一张照片。**
+
+现实是：中小学生的手写体，潦草起来连老师都看不懂。打印体 OCR 准确率可以到 95%+，但手写体的天花板大概在 70-80%。而且不只是 OCR——学科分类、知识点标注、错误类型诊断，每一步都可能出错。
+
+第一个版本的 PRD 里，我完全没考虑这个问题。数据流画得很漂亮：「拍照 → AI 识别 → 入库 → 分析 → 推荐」，仿佛 AI 不会出错。
+
+直到有人问我：「万一 AI 识别错了呢？」
+
+---
+
+## 问题：错误数据会污染整个系统
+
+如果 AI 把「二次函数顶点坐标」错标成「一次函数斜率」，会发生什么？
+
+1. 错题归到错误的知识点
+2. 薄弱点分析显示「一次函数薄弱」，实际是二次函数有问题
+3. 推荐系统给了 10 道一次函数的练习——和学生的真实弱项毫无关系
+4. 学生发现推荐不准确 → 不信任产品 → 弃用
+
+**一条错误数据进入分析管道，污染的是整个推荐飞轮。**
+
+传统方案的思路是「提高 AI 准确率」——换更好的模型、加训练数据、调 prompt。但这条路的天花板很明显：手写体 OCR 准确率从 70% 提升到 85% 已经很难了，90% 在可见的将来都不现实。
+
+而且，即使到了 90%，每 10 道错题就有 1 道是错的。100 道里有 10 道。对学生来说，10 次错误的推荐 = 再也不用了。
+
+---
+
+## 灵感：AI 做不好的事，让人来做
+
+问题的本质是：**AI 做识别很强但不够完美，人做识别很准但太慢。**
+
+那能不能结合起来？
+
+我当时想到一个关键洞察：**学生本来就要看自己拍了什么。** 拍照录入的过程不是「拍完就完了」，用户本来就会确认「这张照片拍清楚了吗」「题目对吗」。这个「确认」动作，天然就是数据校验的机会。
+
+于是设计了这样一个流程：
+
+```
+AI 识别结果不是「答案」，是「草稿」
+    ↓
+每个字段带置信度（这条我有多确定）
+    ↓
+高置信（>90%）：绿色标记，用户看一眼就行
+中置信（70%-90%）：黄色提示，建议检查
+低置信（<70%）：红色高亮，请手动修正
+    ↓
+用户确认/修正后 → 入库 → 进入分析管道
+未经确认的数据 → 仅自己可见，不参与分析和推荐
+```
+
+核心设计原则：**AI 是草稿，用户是编辑。分析管道只吃「干净数据」。**
+
+---
+
+## 隐藏收益：每一次修正都是免费的标注数据
+
+做到这一步后，我发现还有一个更大的收益。
+
+用户修正时，系统记录两个值：
+- `ai_value`：AI 的原始识别结果（比如标注为「二次函数顶点坐标」）
+- `user_value`：用户修正后的值（实际是「二次函数图像性质」）
+- `ai_confidence`：AI 当时对这个判断的置信度（0.72）
+
+这条修正记录（CorrectionLog）就是一条**完美的标注数据**：
+
+- 有原始模型输出（ai_value）
+- 有人工标注结果（user_value）
+- 有模型当时的置信度（可用于误差分析）
+
+传统 AI 训练需要花钱请人标注数据。ErrLens 的标注员是用户——而且他们免费标注，甚至感谢你给了他们一个「修正」的功能。
+
+P02 阶段（自研模型），这些 CorrectionLog 就是核心训练数据。产品用得越多，修正记录越多，模型越强——这是真正的数据飞轮。
+
+---
+
+## 结果
+
+- error_items 表新增 `verification_status`（raw→reviewed→corrected→stale）和 `ai_confidence`（JSONB）
+- 新增 `correction_logs` 表，记录每一条人机修正
+- 分析/推荐查询强制加 `WHERE verification_status != 'raw'`
+- 前端 UI 设计绿/黄/红三级置信度指示
+
+---
+
+## 一句话总结
+
+**AI 的弱点不一定是产品的弱点——如果你能设计一个把「AI 错误」变成「用户价值」的闭环。**

docs/share/phase-01/决策故事_旧架构合并.md

@@ -0,0 +1,87 @@
+# 决策故事：当两个架构要合并——30 项决策是怎么做的
+
+## 背景
+
+ErrLens 不是一个从零开始的项目。
+
+在正式立项之前，我已经花了几周时间写了一个叫「家庭教育小程序」的架构设计——17 份文档，约 60,000 字，覆盖了小程序端、数据库、图像处理、交互设计、UI 规范、测试方案、部署方案等方方面面。
+
+唯一的问题是：那个架构是面向「小学 5-6 年级学生家长 + 仅数学」的，用的是「微信云开发 + 云函数」的技术栈。而 ErrLens 定位已经变成了「小学初中学生 + 数学英语 + 自建后端」。
+
+两套架构，一个旧一个新，重叠但不兼容。旧架构不能直接复用——技术栈变了。但也不能扔掉——里面有很多经过 Spike 验证的工程方案（图像处理管线、打印设计、UI 规范）。
+
+问题变成：**怎么系统地把旧架构中有价值的部分提取出来，合并到新架构里，而不是陷入无休止的细节讨论？**
+
+---
+
+## 方法：结构化对比，逐项决策
+
+我让 Arch AI 把 17 份旧文档全部读完后，把两套架构的差异拆成 30 个独立维度，按性质分成四类：
+
+### 第一类：冲突项（8 项）
+
+两套设计说了不同的话，必须二选一。
+
+| 示例 | 旧架构 | 新架构 | 结论 |
+|------|--------|--------|------|
+| 技术栈 | 微信云开发 | NestJS + PostgreSQL | 选新架构，因为需要 Coze 沙盒自动化测试 |
+| 目标用户 | 家长操作 | 学生本人 | 两者都要，学生和家长都可以操作 |
+| 学科范围 | 仅数学 | 数学+英语 | 新架构已锁定 |
+
+### 第二类：旧有新增（9 项）
+
+旧架构有但新架构缺失的有价值功能。
+
+| 示例 | 旧架构设计 | 决定 |
+|------|-----------|------|
+| 错题打印 | 完整 PDF 生成+下载流程 | 纳入 MVP，P0 |
+| 图像预处理管线 | CLAHE+笔迹去除，经 Spike 验证 | 前置到 OCR 之前 |
+| UI 设计规范 | 完整规范文档，28 个图标 | 整体迁移 |
+
+### 第三类：新有新增（7 项）
+
+新架构创新，旧架构完全没有。直接保留，不讨论。
+
+### 第四类：各有优劣（6 项）
+
+两边方案各有利弊，需要权衡。
+
+| 示例 | 结论 |
+|------|------|
+| 知识点编码：业务编码 vs 数字 ID | 两者并存，ID 内部关联 + code 对外暴露 |
+| 题目匹配：关键词 vs AI 语义 | 两阶段：关键词粗筛 → AI 精排 |
+
+30 项决策，逐条过。人类拍板，AI 记录，一项一项写入架构文档。
+
+---
+
+## 思考：为什么能在一小时内完成 30 个决策？
+
+如果让我一个人对着两份架构文档做合并，至少需要两天——读旧文档需要半天，对比需要一天，写合并方案再半天。
+
+但 AI 可以：
+
+1. **并行阅读**：17 份旧文档在 30 秒内全部读完并提取要点
+2. **结构化拆解**：自动将差异按「冲突/新增/缺失/优劣」分类
+3. **草拟选项**：每个维度列出优劣对比，方便人类判断
+4. **即时落地**：决策一旦确认，5 分钟内更新完所有相关文档
+
+人类的角色非常清晰：**做判断。** AI 负责列出选项、分析利弊、写成文档——人类只需要说「同意」「不同意」或「换个方案」。
+
+这个协作模式的核心是：**人类不需要被 AI 告诉该怎么做，而是让 AI 把所有信息准备好，自己做决定。**
+
+---
+
+## 关键收获
+
+1. **分类框架是决策效率的关键。** 「冲突/新增/缺失/优劣」这个四象限让复杂对比变得可管理。下次遇到类似问题可以直接复用。
+
+2. **决策粒度要适中。** 太细（每个字段风格讨论）浪费精力，太粗（「技术栈全换」一句话）埋隐患。30 项这个数量级刚好——半天做完，该覆盖的都覆盖了。
+
+3. **旧资产不要扔。** 旧架构虽然技术栈变了，但设计思路、工程参数、Spike 验证结论都是真金白银的积累。要有系统的方法提取价值。
+
+---
+
+## 一句话总结
+
+**架构合并不需要你穷尽每一个细节。把它拆成独立的决策单元，人类逐项拍板，AI 负责剩下的——这就是「人机协同」在架构设计上的应用。**

docs/share/phase-01/阶段复盘_基础搭建.md

@@ -1,3 +1,80 @@
-# Phase 1: 基础搭建 — 阶段复盘
+# Phase 1 阶段复盘：基础搭建
 
-> *（Phase 1 完成时由 Arch AI 撰写，基于 `.ai/phases/phase-01-foundation/completion.md` 扩展）*
+## 阶段信息
+
+- 阶段编号：Phase 1/4
+- 阶段名称：基础搭建
+- 时间范围：2026-05-23 ~ 2026-05-26（4 天）
+- 参与角色：人类 + Arch AI（Claude）
+
+## 做了什么
+
+Phase 1 不写一行业务代码。目标是「把骨架搭好，让 AI 知道该做什么」：
+
+1. **信息架构重构**（ADR-007）：从单体 AGENTS.md 到四层分层架构
+2. **PRD 编写**（v0.3.0 → v0.4.0）：完整的错题本产品需求文档，含人机协同数据闭环
+3. **系统架构设计**（v0.3.0 → v0.4.0）：总体架构、技术选型、模块设计、数据模型
+4. **旧架构合并**：将早期「家庭教育小程序」的 17 份架构文档与当前设计对比，30 项决策逐项确认
+5. **Dev AI 工作台初始化**：8 个开发任务入队，含依赖关系图
+
+交付物：10 份文档，约 30,000 字。
+
+## 关键决策
+
+### 决策 1：人机协同数据闭环（ADR-009）
+
+**问题**：AI OCR 对手写体的识别率不可能 100%，错误数据直接进入分析会污染整个系统。
+
+**方案**：「AI 是草稿，用户是编辑。」AI 识别结果带置信度入库，用户确认/修正后才进入分析管道。每一次修正都是免费的标注数据，P02 阶段用于训练自有模型。
+
+**为什么重要**：这是产品数据飞轮的核心设计。没有这个闭环，产品就是普通的拍照 OCR 工具。
+
+### 决策 2：分层信息架构（ADR-007）
+
+**问题**：单体 AGENTS.md 太长，AI 注意力衰减，不同角色的信息混在一起。
+
+**方案**：四层结构——仪表盘（人类）→ 路线图（共享）→ 角色工作台（AI 个人）→ 知识沉淀（共享）。每个 AI 只加载自己需要的信息。
+
+**为什么重要**：这是整个 AI 协作模式的基础。没有好的信息架构，AI 再多也协同不起来。
+
+### 决策 3：旧架构合并
+
+**问题**：之前写的「家庭教育小程序」架构文档（17 份，约 60,000 字）不能白写，但又不能简单照搬——技术栈、用户定位、学科范围全变了。
+
+**方案**：逐项对比，分成「冲突」「旧有新增」「新有新增」「各有优劣」四类，30 项决策逐条确认后统一写入新架构。
+
+**为什么重要**：这是第一次「AI 辅助做架构合并」的实践。30 个决策不是 AI 自己拍板的，是人类逐条确认的。这个流程本身是一个可复用的方法论。
+
+## 踩过的坑
+
+### 坑 1：Edit 工具字符串匹配失败
+
+短字符串替换没问题，但一次替换多个段落时经常找不到。原因是前面的修改已经改变了文件内容，后续匹配的目标字符串已不匹配。
+
+**解法**：大段落修改拆成多次小修改，每次改动后确认文件当前状态再改下一个。宁可多改几次，不要一次写一大段。
+
+### 坑 2：数据飞轮第一版太天真
+
+最初的 PRD 版本假设「AI 拍完照就能完美识别」。被指出后才意识到这是核心风险。后来整个飞轮设计推翻重写——从「AI 完美假设」变成「人机协同闭环」。
+
+**教训**：架构评审中，人的经验和直觉是 AI 替代不了的。AI 擅长帮你把想法落地成文档，但不会主动挑战你的假设。
+
+## 学到的东西
+
+1. **AI 协作的效率瓶颈不在 AI，在信息组织。** 文档写得好，AI 输出质量就高；文档一团乱，再强的模型也白搭。
+2. **人类做决策，AI 做执行，是最佳的协作模式。** 30 项旧架构合并决策，AI 列出选项和优劣，人类逐条拍板，AI 写入文档——这个流程的效率远超纯人工或纯 AI。
+3. **架构文档应该「分层写」。** 不是一份文档覆盖所有细节，而是不同层次的文档给不同角色看。这和代码的「关注点分离」是一个道理。
+4. **旧资产不要扔。** 旧架构文档虽然技术栈变了，但图像处理管线、打印设计、UI 规范、测试用例都是可复用资产。关键是要有一个结构化的对比流程来提取价值。
+
+## 数据
+
+- 新增/更新文档：17 份（不含旧架构原文件）
+- 总字数：约 30,000 字（PRD + 4 份架构文档 + ADR + 看板 + 分享内容）
+- 架构决策记录：10 条（ADR-001 ~ ADR-010）
+- 旧架构合并决策：30 项
+- Dev 任务入队：8 个
+- 代码行数：0（Phase 1 不写代码）
+
+## 下一阶段预告
+
+Phase 2 MVP：数据库 Schema → Auth → Image → Print → User → Upload → 页面骨架。Dev AI 开始写代码，QA AI 启动自动化测试。

projects/P01_errlens_app/docs/01_需求概要.md

@@ -1,21 +1,21 @@
-# P01_errlens_app - 需求概要
+# P01_errlens_app — 需求概要
 
 ## 项目概述
 
-ErrLens 小程序应用是一个基于 **Taro 4 框架**开发的多端小程序项目，支持微信小程序、抖音小程序和 H5 平台。
+ErrLens 小程序是一款面向中小学生的 **AI 错题本**，帮助学生拍照录入错题、自动归类分析、获得针对性练习推荐。
 
 ## 项目定位
 
-- **产品类型**：AI 辅助编程工具的移动端入口
+- **产品类型**: AI 错题本（教育类微信小程序）
-- **目标用户**：开发者、编程学习者、代码审查人员
+- **目标用户**: 中小学生（10-18 岁），以初中生为典型交互设计
-- **核心价值**：随时随地访问 ErrLens 的代码错误检测和修复建议功能
+- **核心价值**: 拍照录入 → AI 分析错误原因 → 识别薄弱知识点 → 推荐同类练习
 
 ## 技术栈
 
 ### 前端框架
 | 技术 | 版本 | 说明 |
 |------|------|------|
-| Taro | 4.1.9 | 跨端开发框架 |
+| Taro | 4.1.x | 跨端开发框架 |
 | React | 18.x | UI 框架 |
 | TypeScript | 5.x | 类型安全 |
 | Tailwind CSS | 4.x | 原子化样式 |
@@ -25,84 +25,82 @@ ErrLens 小程序应用是一个基于 **Taro 4 框架**开发的多端小程序
 | 技术 | 版本 | 说明 |
 |------|------|------|
 | NestJS | 10.x | Node.js 服务端框架 |
-| Express | 5.x | HTTP 服务器 |
 | PostgreSQL | 15+ | 关系数据库 |
 | Drizzle ORM | 0.45.x | ORM 工具 |
 
 ### 集成服务
 | 服务 | 说明 |
 |------|------|
-| Supabase | 数据库连接 |
+| Supabase | 数据库托管 |
-| S3 兼容存储 | 文件存储 |
+| S3 兼容存储 | 错题图片存储 |
-| Coze SDK | AI 能力集成 |
+| Coze SDK | AI OCR + 知识点分类 + 错误诊断 |
+| 微信开放平台 | 微信登录 + 小程序能力 |
 
 ## 核心功能模块
 
-### 1. 首页模块
+### 1. 拍照录入模块
-- [ ] 欢迎页面展示
+- [ ] 拍照/选图 → AI 识别题目文字、学科、知识点
-- [ ] 功能快捷入口
+- [ ] 识别结果展示 + 用户修正
-- [ ] 最新动态/公告
+- [ ] 正确答案录入（可选）
 
-### 2. 代码分析模块
+### 2. 错题管理模块
-- [ ] 代码上传/粘贴
+- [ ] 错题列表（按时间/学科/知识点/错误类型筛选）
-- [ ] 错误检测结果展示
+- [ ] 错题详情（题目 + AI 分析 + 知识点标注）
-- [ ] 修复建议生成
+- [ ] 错题编辑（修正 AI 识别结果）
 
-### 3. 用户模块
+### 3. AI 分析模块
-- [ ] 用户登录/注册
+- [ ] 单题错误诊断（知识点欠缺/粗心/审题偏差/概念混淆）
+- [ ] 薄弱知识点汇总与排序
+- [ ] 学习报告（周/月度趋势）
+
+### 4. 用户模块
+- [ ] 微信授权登录
+- [ ] 年级和学科设置
 - [ ] 个人中心
-- [ ] 历史记录
 
-### 4. 设置模块
+### 5. 练习推荐模块（P1）
-- [ ] 主题切换
+- [ ] 基于薄弱点推荐同类题
-- [ ] 通知设置
+- [ ] 自定义组题练习
-- [ ] 关于我们
 
 ## 页面结构
 
 ```
 pages/
-├── index/          # 首页
+├── index/            # 首页（错题概览 + 快捷入口）
-├── analyze/        # 代码分析
+├── auth/
-├── history/        # 历史记录
+│   └── login/        # 微信授权登录
-├── profile/        # 个人中心
+├── capture/          # 拍照录入
-└── settings/       # 设置页面
+│   ├── index/        # 拍照页
+│   └── review/       # 识别结果确认页
+├── error-list/       # 错题列表
+├── error-detail/     # 错题详情 + AI 分析
+├── weak-points/      # 薄弱点分析
+├── practice/         # 练习推荐 (P1)
+└── profile/          # 个人中心
 ```
 
-## 组件库
-
-项目使用 **Taro 版 shadcn/ui** 组件库，位于 `src/components/ui/`：
-
-| 组件类型 | 示例组件 |
-|---------|---------|
-| 基础组件 | Button, Input, Textarea |
-| 布局组件 | Card, Dialog, Drawer, Sheet |
-| 数据展示 | Table, Badge, Avatar |
-| 导航组件 | Tabs, Breadcrumb |
-| 反馈组件 | Toast, Alert, Progress |
-
 ## 多端支持
 
-| 平台 | 状态 | 说明 |
+| 平台 | 状态 | 优先级 |
-|------|------|------|
+|------|------|--------|
-| 微信小程序 | ✅ 支持 | 主流平台 |
+| 微信小程序 | MVP 唯一平台 | P0 |
-| 抖音小程序 | ✅ 支持 | 字节系平台 |
+| 抖音小程序 | 按需适配 | P3 |
-| H5 | ✅ 支持 | Web 端预览 |
+| H5 | 兜底+开发调试 | P2 |
 
 ## 用户体验目标
 
-- **加载速度**：首屏加载 < 2s
+- **录入效率**: 拍照到保存 < 30s（含 AI 识别 3-5s）
-- **交互流畅**：帧率 >= 60fps
+- **首屏加载**: < 2s
-- **跨端一致**：各端 UI 表现一致
+- **交互流畅**: 60fps，长列表使用虚拟列表
-- **离线可用**：支持本地缓存
+- **离线可用**: 图片本地缓存，网络恢复后上传
 
 ## 安全要求
 
-- 用户数据加密存储
+- 微信 OAuth 登录，不存储密码
-- API 请求鉴权
+- 用户数据严格隔离（API 鉴权）
-- 敏感信息脱敏
+- 图片上传使用签名 URL
+- 敏感信息传输加密
 
 ---
 
-**文档版本**：v1.0.0
+**文档版本**: v0.1.0 | **基于**: [PRD.md](../../../docs/01_产品需求/PRD.md) | **最后更新**: 2026-05-26
-**最后更新**：2026-05-22

projects/P01_errlens_app/docs/02_架构设计.md

@@ -1,207 +1,180 @@
-# P01_errlens_app - 架构设计
+# P01_errlens_app — 架构设计
 
 ## 整体架构
 
 ```
-┌─────────────────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────────────────┐
-│                        小程序客户端                          │
+│                     小程序客户端 (Taro + React)                │
-│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
+│                                                              │
-│  │  首页   │  │  分析   │  │  历史   │  │  我的   │        │
+│  ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
-│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
+│  │  首页  │ │ 拍照录入  │ │ 错题列表  │ │  我的    │          │
-│       │            │            │            │             │
+│  └───┬────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘          │
-│  ┌────┴────────────┴────────────┴────────────┴────┐        │
+│      │           │            │            │                │
-│  │              组件库 (shadcn/ui)                  │        │
+│  ┌───┴───────────┴────────────┴────────────┴─────┐          │
-│  └────────────────────┬─────────────────────────┘        │
+│  │            组件库 (shadcn/ui Taro 适配)         │          │
-│                        │                                  │
+│  └──────────────────────┬───────────────────────┘          │
-│  ┌────────────────────┴─────────────────────────┐        │
+│                         │                                   │
-│  │              状态管理 (Zustand)                 │        │
+│  ┌──────────────────────┴───────────────────────┐          │
-│  └────────────────────┬─────────────────────────┘        │
+│  │           状态管理 (Zustand)                   │          │
-│                        │                                  │
+│  │   auth / error-item / capture / ai-analysis   │          │
-│  ┌────────────────────┴─────────────────────────┐        │
+│  └──────────────────────┬───────────────────────┘          │
-│  │           Network 层 (API 封装)               │        │
+│                         │                                   │
-│  └────────────────────┬─────────────────────────┘        │
+│  ┌──────────────────────┴───────────────────────┐          │
-└───────────────────────┼───────────────────────────────────┘
+│  │           Network 层 (API 封装 + JWT)         │          │
-                        │ HTTP
+│  └──────────────────────┬───────────────────────┘          │
-                        ▼
+└─────────────────────────┼──────────────────────────────────┘
-┌───────────────────────────────────────────────────────────┐
+                          │ HTTPS
-│                      后端服务 (NestJS)                     │
+                          ▼
-│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
+┌──────────────────────────────────────────────────────────────┐
-│  │ 用户模块 │  │ 分析模块 │  │ 历史模块 │  │ 系统模块 │        │
+│                   后端服务 (NestJS)                           │
-│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
+│                                                              │
-│       │            │            │            │             │
+│  ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐              │
-│  ┌────┴────────────┴────────────┴────────────┴────┐        │
+│  │ 用户模块│ │ 错题模块│ │ AI 分析   │ │ 上传    │              │
-│  │              Service 层                         │        │
+│  └───┬────┘ └───┬────┘ └────┬─────┘ └───┬────┘              │
-│  └────────────────────┬─────────────────────────┘        │
+│      │          │           │            │                   │
-│                        │                                  │
+│  ┌───┴──────────┴───────────┴────────────┴─────┐            │
-│  ┌────────────────────┴─────────────────────────┐        │
+│  │              Service 层                      │            │
-│  │              数据层 (Drizzle ORM)             │        │
+│  └──────────────────────┬───────────────────────┘           │
-│  └────────────────────┬─────────────────────────┘        │
+│                         │                                   │
-└───────────────────────┼───────────────────────────────────┘
+│  ┌──────────────────────┴───────────────────────┐          │
-                        │
+│  │          数据层 (Drizzle ORM + PostgreSQL)     │          │
-                        ▼
+│  └──────────────────────┬───────────────────────┘          │
-              ┌─────────────────┐
+└─────────────────────────┼──────────────────────────────────┘
-              │   PostgreSQL    │
+                          │
-              │   Supabase      │
+              ┌───────────┴───────────┐
-              └─────────────────┘
+              ▼                       ▼
+    ┌─────────────────┐    ┌─────────────────┐
+    │   PostgreSQL     │    │   S3 兼容存储    │
+    │   (Supabase)     │    │   (错题图片)     │
+    └─────────────────┘    └─────────────────┘
 ```
 
 ## 目录结构
 
 ```
 P01_errlens_app/
-├── src/                          # 前端源码
+├── src/                          # 前端源码 (Taro)
 │   ├── app.config.ts             # Taro 应用配置
 │   ├── app.tsx                   # 根组件
-│   ├── app.css                   # 全局样式
+│   ├── app.css                   # 全局样式 (Tailwind)
 │   ├── index.html                # H5 入口
 │   │
 │   ├── components/               # 组件
-│   │   └── ui/                   # shadcn/ui 组件库
+│   │   ├── ui/                   # shadcn/ui 组件库 (~50 个)
-│   │       ├── button.tsx
+│   │   └── business/             # 业务组件
-│   │       ├── card.tsx
+│   │       ├── error-card/       # 错题卡片
-│   │       ├── dialog.tsx
+│   │       ├── knowledge-tag/    # 知识点标签
-│   │       └── ... (50+ 组件)
+│   │       └── analysis-chart/   # 分析图表
 │   │
 │   ├── pages/                    # 页面
-│   │   └── index/                # 首页
+│   │   ├── index/                # 首页
-│   │       ├── index.tsx
+│   │   ├── auth/login/           # 登录
-│   │       ├── index.config.ts
+│   │   ├── capture/              # 拍照录入
-│   │       └── index.css
+│   │   │   ├── index/            # 拍照页
+│   │   │   └── review/           # 识别确认页
+│   │   ├── error-list/           # 错题列表
+│   │   ├── error-detail/         # 错题详情
+│   │   ├── weak-points/          # 薄弱点
+│   │   └── profile/              # 个人中心
+│   │
+│   ├── stores/                   # Zustand 状态
+│   │   ├── auth.store.ts
+│   │   ├── error-item.store.ts
+│   │   ├── capture.store.ts      # 拍照流程状态机
+│   │   └── ai-analysis.store.ts
 │   │
 │   ├── lib/                      # 工具库
-│   │   ├── utils.ts              # 通用工具
+│   │   ├── utils.ts
-│   │   ├── platform.ts           # 平台检测
+│   │   ├── platform.ts
-│   │   ├── measure.ts            # 尺寸测量
+│   │   ├── measure.ts
-│   │   └── hooks/                # 自定义 Hooks
+│   │   └── hooks/
 │   │
 │   ├── presets/                  # 预设配置
 │   │   ├── index.tsx
 │   │   ├── env.ts
-│   │   ├── h5-container.tsx
+│   │   └── h5-*.tsx
-│   │   └── ...
 │   │
 │   └── network.ts                # API 请求封装
 │
-│   ├── server/                   # 后端源码 (NestJS)
+├── server/                       # 后端源码 (NestJS)
-│   │   ├── src/
+│   └── src/
-│   │   │   ├── app.module.ts    # 根模块
+│       ├── main.ts               # 启动入口
-│   │   │   ├── app.controller.ts# 根控制器
+│       ├── app.module.ts         # 根模块
-│   │   │   ├── app.service.ts   # 根服务
+│       ├── app.controller.ts     # 根控制器
-│   │   │   └── main.ts          # 入口文件
+│       ├── db/
-│   │   │
+│       │   └── schema.ts         # Drizzle Schema
-│   │   ├── nest-cli.json
+│       ├── modules/
-│   │   ├── tsconfig.json
+│       │   ├── auth/             # 鉴权模块
-│   │   └── package.json
+│       │   ├── user/             # 用户模块
-│   │
+│       │   ├── error-item/       # 错题模块
-│   ├── config/                   # 构建配置
+│       │   ├── ai/               # AI 分析模块
-│   │   ├── index.ts             # 通用配置
+│       │   ├── subject/          # 学科模块
-│   │   ├── dev.ts               # 开发环境配置
+│       │   └── upload/           # 文件上传
-│   │   └── prod.ts              # 生产环境配置
+│       └── common/
-│   │
+│           ├── guards/           # JWT Guard
-│   ├── types/                    # 类型定义
+│           ├── interceptors/     # HTTP 状态拦截器
-│   │   ├── global.d.ts
+│           └── filters/          # 异常过滤器
-│   │   └── lucide.d.ts
 │
-├── tests/                        # 测试代码
+├── tests/                        # 测试
-│   ├── unit/                    # 单元测试
+│   ├── unit/                     # 单元测试
-│   ├── integration/             # 集成测试
+│   │   ├── components/
-│   └── e2e/                    # E2E 测试
+│   │   └── lib/
+│   ├── integration/              # 集成测试
+│   └── e2e/                      # E2E 测试
 │
-├── docs/                        # 项目文档
+├── docs/                         # 项目文档
-│   ├── 01_需求概要.md
+├── package.json
-│   ├── 02_架构设计.md
+├── tsconfig.json
-│   └── 03_接口定义.md
+├── babel.config.js
-│
+├── eslint.config.mjs
-├── package.json                 # 前端依赖
+├── stylelint.config.mjs
-├── tsconfig.json                # TypeScript 配置
+├── project.config.json           # 微信小程序配置
-├── babel.config.js              # Babel 配置
+└── ENVIRONMENT.md
-├── eslint.config.mjs           # ESLint 配置
-├── stylelint.config.mjs        # Stylelint 配置
-├── project.config.json         # 微信小程序配置
-└── ENVIRONMENT.md               # 环境准备指南
 ```
 
-## 核心模块设计
+## 核心流程
 
-### 1. Network 层
+### 拍照录入流程
-
-```typescript
-// src/network.ts
-// API 请求封装，自动添加项目域名前缀
-// 支持 request / uploadFile / downloadFile
-```
-
-**职责**：
-- 统一处理 API 请求
-- 自动添加域名和路径前缀
-- 请求/响应日志打印
-- 错误处理
-
-### 2. 组件库
-
-**位置**：`src/components/ui/`
-
-**组件分类**：
-- 基础组件：Button, Input, Badge, Avatar
-- 布局组件：Card, Dialog, Drawer, Sheet
-- 数据展示：Table, Progress, Skeleton
-- 导航组件：Tabs, Breadcrumb
-- 反馈组件：Toast, Alert, Tooltip
-
-### 3. 状态管理
-
-**方案**：Zustand
-
-**特点**：
-- 轻量级
-- 无 Provider 嵌套
-- TypeScript 友好
-
-### 4. 后端模块
 
 ```
-src/server/src/
+[拍照页] → 拍照/选图
-├── controllers/     # 控制器
+    → [预览页] 确认图片
-├── services/        # 业务逻辑
+    → [Upload] 上传 → S3 返回 URL
-├── modules/         # NestJS 模块
+    → [AI Service] Coze SDK OCR + 知识点分类
-├── entities/        # 数据实体
+    → [确认页] 展示识别结果，允许修正
-├── dto/             # 数据传输对象
+    → [保存] 写入 ErrorItem → 跳转详情页
-└── interceptors/    # 拦截器
+```
+
+### 状态机 (capture.store)
+
+```
+IDLE → CAMERA → PREVIEW → UPLOADING → ANALYZING → REVIEW → SAVING → DONE
+                      ↓              ↓           ↓         ↓
+                    ERROR          ERROR       ERROR     ERROR
+                                     └── 重试 ──┘
 ```
 
 ## 多端适配策略
 
-### 平台检测
+| 场景 | 方案 |
-
+|------|------|
-```typescript
+| 拍照 | 微信: wx.chooseMedia, H5: input[type=file] |
-import { Taro, ENV_TYPE } from '@tarojs/taro'
+| 图片预览 | 微信: wx.previewImage, H5: dialog |
-
+| 登录 | 微信: wx.login → code2session, H5: 扫码 |
-const isWeapp = Taro.getEnv() === ENV_TYPE.WEAPP    // 微信小程序
+| 原生组件 | 平台检测 + 条件渲染 |
-const isTT = Taro.getEnv() === ENV_TYPE.TT           // 抖音小程序
-const isH5 = Taro.getEnv() === ENV_TYPE.WEB          // H5
-```
-
-### 跨端规则
-
-| 场景 | 适配方案 |
-|------|---------|
-| Text 换行 | 添加 `block` 类 |
-| Input 样式 | View 包裹，样式放 View |
-| Fixed + Flex | 使用 inline style |
-| 原生组件 | 平台检测 + 降级方案 |
 
 ## 部署架构
 
 ### 开发环境
-- 前端：H5 端口 5000
+- 前端 H5: port 5000 (Vite dev server)
-- 后端：Node 端口 3000
+- 后端: port 3000 (NestJS)
+- 数据库: Supabase 开发实例
 
 ### 生产环境
-- 微信小程序：构建 weapp 包
+- 微信小程序: `taro build --type weapp` → 上传代码包
-- 抖音小程序：构建 tt 包
+- 后端: Node.js 单实例 (Phase 3 容器化)
-- H5：构建 web 静态资源
+- 图片: S3/MinIO + CDN
 
 ---
 
-**文档版本**：v1.0.0
+**文档版本**: v0.1.0 | **基于**: [系统架构](../../../docs/02_系统架构/) | **最后更新**: 2026-05-26
-**最后更新**：2026-05-22

projects/P01_errlens_app/docs/03_接口定义.md

@@ -1,202 +1,170 @@
-# P01_errlens_app - 接口定义
+# P01_errlens_app — 接口定义
 
 ## 接口规范
 
 ### 基础信息
-- **Base URL**: `/api`（开发环境通过 Vite Proxy 代理到 `http://localhost:3000/api`）
+- **Base URL**: `/api`（开发环境通过 Vite Proxy 到 `http://localhost:3000/api`）
-- **请求格式**: JSON
+- **请求格式**: JSON（文件上传使用 multipart/form-data）
-- **响应格式**: Envelope Pattern `{ code, msg, data }`
+- **响应格式**: `{ code: number, msg: string, data: T | null }`
 
 ### 通用响应结构
 
 ```typescript
-// 成功响应
+// 成功
-{
+{ code: 200, msg: "success", data: { ... } }
-  code: 200,
-  msg: "success",
-  data: { ... }
-}
 
-// 错误响应
+// 客户端错误
-{
+{ code: 400 | 401 | 403 | 404, msg: "错误描述", data: null }
-  code: 400 | 401 | 403 | 404 | 500,
+
-  msg: "错误信息",
+// 服务端错误
-  data: null
+{ code: 500, msg: "服务器内部错误", data: null }
-}
+```
+
+### 鉴权
+
+除登录接口外，所有 API 需在 Header 携带 JWT Token：
+
+```
+Authorization: Bearer <token>
 ```
 
 ---
 
-## 用户模块
+## 1. 鉴权模块
 
-### 1. 用户登录
+### 1.1 微信登录
 
 ```
 POST /api/auth/login
 ```
 
-**请求参数**：
+**请求**:
 ```json
 {
-  "email": "string",
+  "code": "wx.login() 返回的 code"
-  "password": "string"
 }
 ```
 
-**响应示例**：
+**响应**:
 ```json
 {
   "code": 200,
   "msg": "success",
   "data": {
-    "token": "jwt_token_here",
+    "token": "jwt_token",
     "user": {
       "id": "uuid",
-      "email": "user@example.com",
+      "nickname": "微信昵称",
-      "nickname": "用户名"
+      "avatarUrl": "https://..."
     }
   }
 }
 ```
 
+### 1.2 刷新 Token
+
+```
+POST /api/auth/refresh
+```
+
 ---
 
-### 2. 用户注册
+## 2. 用户模块
+
+### 2.1 获取个人信息
 
 ```
-POST /api/auth/register
+GET /api/user/profile
 ```
 
-**请求参数**：
+**响应**:
-```json
-{
-  "email": "string",
-  "password": "string",
-  "nickname": "string"
-}
-```
-
-**响应示例**：
 ```json
 {
   "code": 200,
   "msg": "success",
   "data": {
     "id": "uuid",
-    "email": "user@example.com",
+    "nickname": "微信昵称",
-    "nickname": "用户名"
+    "avatarUrl": "https://...",
+    "grade": "初中二年级",
+    "subjects": ["数学", "英语"],
+    "createdAt": "2026-05-26T00:00:00Z"
   }
 }
 ```
 
+### 2.2 更新个人信息
+
+```
+PATCH /api/user/profile
+```
+
+**请求**:
+```json
+{
+  "grade": "初中三年级",
+  "subjects": ["数学", "英语", "物理"]
+}
+```
+
 ---
 
-### 3. 获取用户信息
+## 3. 错题模块（核心）
+
+### 3.1 创建错题
 
 ```
-GET /api/users/profile
+POST /api/error-items
 ```
 
-**请求头**：
+**请求**:
-```
+```json
-Authorization: Bearer <token>
+{
+  "imageUrl": "https://storage.example.com/errors/abc.png",
+  "thumbnailUrl": "https://storage.example.com/errors/abc_thumb.png",
+  "questionText": "已知二次函数 y = x² - 4x + 3，求顶点坐标...",
+  "wrongAnswer": "顶点坐标 (2, 1)",
+  "correctAnswer": "顶点坐标 (2, -1)",
+  "subjectId": 1,
+  "knowledgePointIds": [1021],
+  "errorType": "knowledge_gap",
+  "difficulty": "medium",
+  "note": ""
+}
 ```
 
-**响应示例**：
+**响应**:
 ```json
 {
   "code": 200,
   "msg": "success",
   "data": {
     "id": "uuid",
-    "email": "user@example.com",
+    "createdAt": "2026-05-26T10:00:00Z"
-    "nickname": "用户名",
-    "avatar": "https://...",
-    "createdAt": "2026-05-22T00:00:00Z"
   }
 }
 ```
 
----
+### 3.2 查询错题列表
-
-## 代码分析模块
-
-### 1. 上传代码分析
 
 ```
-POST /api/analyze
+GET /api/error-items?page=1&pageSize=20&subjectId=1&errorType=knowledge_gap&keyword=二次函数&sort=createdAt&order=desc
 ```
 
-**请求头**：
+**查询参数**:
-```
-Authorization: Bearer <token>
-```
 
-**请求参数**：
+| 参数 | 类型 | 必填 | 说明 |
-```json
+|------|------|------|------|
-{
+| page | int | 否 | 页码，默认 1 |
-  "code": "string",
+| pageSize | int | 否 | 每页条数，默认 20，最大 50 |
-  "language": "javascript | python | typescript | ..."
+| subjectId | int | 否 | 学科筛选 |
-}
+| errorType | string | 否 | 错误类型筛选 |
-```
+| knowledgePointId | int | 否 | 知识点筛选 |
+| keyword | string | 否 | 题目文本搜索 |
+| sort | string | 否 | 排序字段: createdAt/updatedAt |
+| order | string | 否 | asc/desc，默认 desc |
 
-**响应示例**：
+**响应**:
-```json
-{
-  "code": 200,
-  "msg": "success",
-  "data": {
-    "taskId": "uuid",
-    "status": "completed",
-    "results": [
-      {
-        "line": 10,
-        "column": 5,
-        "severity": "error",
-        "message": "缺少分号",
-        "suggestion": "在行末添加分号"
-      }
-    ]
-  }
-}
-```
-
----
-
-### 2. 获取分析结果
-
-```
-GET /api/analyze/:taskId
-```
-
-**响应示例**：
-```json
-{
-  "code": 200,
-  "msg": "success",
-  "data": {
-    "taskId": "uuid",
-    "status": "completed",
-    "results": [...]
-  }
-}
-```
-
----
-
-### 3. 获取历史记录
-
-```
-GET /api/analyze/history
-```
-
-**查询参数**：
-```
-page: number (default: 1)
-pageSize: number (default: 20)
-```
-
-**响应示例**：
 ```json
 {
   "code": 200,
@@ -205,90 +173,286 @@ pageSize: number (default: 20)
     "list": [
       {
         "id": "uuid",
-        "codeSnippet": "function hello() {...}",
+        "thumbnailUrl": "https://...",
-        "language": "javascript",
+        "questionText": "已知二次函数...",
-        "resultCount": 3,
+        "subject": { "id": 1, "name": "数学" },
-        "createdAt": "2026-05-22T00:00:00Z"
+        "knowledgePoints": [
+          { "id": 1021, "name": "顶点坐标" }
+        ],
+        "errorType": "knowledge_gap",
+        "difficulty": "medium",
+        "createdAt": "2026-05-26T10:00:00Z"
       }
     ],
-    "total": 100,
+    "total": 42,
     "page": 1,
     "pageSize": 20
   }
 }
 ```
 
----
+### 3.3 获取错题详情
-
-## 文件上传模块
-
-### 1. 上传文件
 
 ```
-POST /api/upload
+GET /api/error-items/:id
 ```
 
-**请求头**：
+**响应**:
-```
-Authorization: Bearer <token>
-Content-Type: multipart/form-data
-```
-
-**请求参数**：
-```
-file: binary
-```
-
-**响应示例**：
 ```json
 {
   "code": 200,
   "msg": "success",
   "data": {
-    "url": "https://storage.example.com/files/xxx.png",
+    "id": "uuid",
-    "filename": "xxx.png",
+    "imageUrl": "https://...",
-    "size": 1024
+    "thumbnailUrl": "https://...",
+    "questionText": "已知二次函数 y = x² - 4x + 3，求顶点坐标...",
+    "wrongAnswer": "顶点坐标 (2, 1)",
+    "correctAnswer": "顶点坐标 (2, -1)",
+    "subject": { "id": 1, "name": "数学" },
+    "knowledgePoints": [
+      { "id": 1021, "name": "顶点坐标", "relevance": 100 }
+    ],
+    "errorType": "knowledge_gap",
+    "difficulty": "medium",
+    "note": "符号搞反了",
+    "aiAnalysis": {
+      "diagnosis": "将 x=2 代入时，常数项符号计算错误，应为 3-4=-1 而非 3-4=1。建议回顾二次函数配方法求顶点坐标的完整步骤。",
+      "errorType": "knowledge_gap",
+      "confidence": 0.92
+    },
+    "createdAt": "2026-05-26T10:00:00Z",
+    "updatedAt": "2026-05-26T10:00:00Z"
+  }
+}
+```
+
+### 3.4 更新错题
+
+```
+PATCH /api/error-items/:id
+```
+
+**请求**: 同创建参数，所有字段可选。
+
+### 3.5 删除错题
+
+```
+DELETE /api/error-items/:id
+```
+
+**响应**: `{ code: 200, msg: "success", data: null }`
+
+---
+
+## 4. AI 分析模块
+
+### 4.1 分析错题图片
+
+```
+POST /api/ai/analyze
+```
+
+**请求**:
+```json
+{
+  "imageUrl": "https://storage.example.com/errors/abc.png"
+}
+```
+
+**响应**:
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "uuid",
+    "status": "completed",
+    "result": {
+      "questionText": "已知二次函数 y = x² - 4x + 3...",
+      "subjectId": 1,
+      "subjectName": "数学",
+      "knowledgePoints": [
+        { "id": 1021, "name": "顶点坐标", "confidence": 0.95 }
+      ],
+      "errorType": "knowledge_gap",
+      "errorTypeConfidence": 0.88,
+      "difficulty": "medium",
+      "diagnosis": "顶点坐标计算错误，符号混淆..."
+    }
+  }
+}
+```
+
+### 4.2 获取薄弱点报告
+
+```
+GET /api/ai/report?period=week
+```
+
+**查询参数**: `period`: week | month
+
+**响应**:
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "periodStart": "2026-05-19",
+    "periodEnd": "2026-05-26",
+    "totalErrors": 15,
+    "trend": "down",
+    "weakPoints": [
+      {
+        "knowledgePointId": 1021,
+        "name": "二次函数顶点坐标",
+        "errorCount": 5,
+        "weight": 0.85,
+        "trend": "up"
+      }
+    ],
+    "errorTypeDistribution": {
+      "knowledge_gap": 8,
+      "careless": 3,
+      "misread": 2,
+      "concept_confusion": 2
+    }
   }
 }
 ```
 
 ---
 
-## 错误码定义
+## 5. 学科模块
 
-| 错误码 | 说明 |
+### 5.1 获取学科列表
-|-------|------|
-| 200 | 成功 |
-| 400 | 请求参数错误 |
-| 401 | 未授权 / Token 过期 |
-| 403 | 权限不足 |
-| 404 | 资源不存在 |
-| 500 | 服务器内部错误 |
 
----
+```
+GET /api/subjects
+```
 
-## API 测试命令
+**响应**:
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": [
+    { "id": 1, "name": "数学", "icon": "math" },
+    { "id": 2, "name": "英语", "icon": "english" }
+  ]
+}
+```
 
-### 开发环境测试
+### 5.2 获取学科知识点树
 
-```bash
+```
-# 登录接口
+GET /api/subjects/:id/knowledge-points
-curl -X POST http://localhost:3000/api/auth/login \
+```
-  -H "Content-Type: application/json" \
-  -d '{"email":"test@example.com","password":"123456"}'
 
-# 获取用户信息
+**响应**:
-curl -X GET http://localhost:3000/api/users/profile \
+```json
-  -H "Authorization: Bearer <token>"
+{
-
+  "code": 200,
-# 代码分析
+  "msg": "success",
-curl -X POST http://localhost:3000/api/analyze \
+  "data": [
-  -H "Authorization: Bearer <token>" \
+    {
-  -H "Content-Type: application/json" \
+      "id": 10,
-  -d '{"code":"console.log(1)","language":"javascript"}'
+      "name": "代数",
+      "children": [
+        {
+          "id": 102,
+          "name": "二次函数",
+          "children": [
+            { "id": 1021, "name": "顶点坐标", "children": [] }
+          ]
+        }
+      ]
+    }
+  ]
+}
 ```
 
 ---
 
-**文档版本**：v1.0.0
+## 6. 文件上传模块
-**最后更新**：2026-05-22
+
+### 6.1 上传图片
+
+```
+POST /api/upload/image
+Content-Type: multipart/form-data
+```
+
+**请求**: `file: binary`
+
+**响应**:
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "url": "https://storage.example.com/errors/abc.png",
+    "thumbnailUrl": "https://storage.example.com/errors/abc_thumb.png",
+    "size": 204800
+  }
+}
+```
+
+**约束**:
+- 最大 10MB
+- 格式: jpg/png/webp
+- 自动生成缩略图 (200x200)
+
+---
+
+## 7. 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| 200 | 成功 |
+| 400 | 请求参数错误 |
+| 401 | 未授权 / Token 过期 |
+| 403 | 无权访问该资源 |
+| 404 | 资源不存在 |
+| 413 | 文件过大 |
+| 429 | 请求频率超限 |
+| 500 | 服务器内部错误 |
+| 502 | AI 服务不可用 |
+
+---
+
+## 8. API 测试
+
+```bash
+# 微信登录
+curl -X POST http://localhost:3000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"code":"wx_test_code"}'
+
+# 获取错题列表
+curl -X GET "http://localhost:3000/api/error-items?page=1&pageSize=20" \
+  -H "Authorization: Bearer <token>"
+
+# 创建错题
+curl -X POST http://localhost:3000/api/error-items \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "imageUrl": "https://storage.example.com/errors/test.png",
+    "questionText": "已知二次函数 y = x² - 4x + 3，求顶点坐标",
+    "wrongAnswer": "(2, 1)",
+    "subjectId": 1,
+    "knowledgePointIds": [1021],
+    "errorType": "knowledge_gap",
+    "difficulty": "medium"
+  }'
+
+# 上传图片
+curl -X POST http://localhost:3000/api/upload/image \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@/path/to/photo.jpg"
+```
+
+---
+
+**文档版本**: v0.1.0 | **基于**: [模块设计](../../../docs/02_系统架构/模块设计.md) | **最后更新**: 2026-05-26