diff --git a/.ai/knowledge/journal/2026-05-26.md b/.ai/knowledge/journal/2026-05-26.md new file mode 100644 index 0000000..4e8dd60 --- /dev/null +++ b/.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 节） diff --git a/.ai/roles/arch/queue.md b/.ai/roles/arch/queue.md index b340c8f..0ee7ce4 100644 --- a/.ai/roles/arch/queue.md +++ b/.ai/roles/arch/queue.md @@ -4,11 +4,14 @@ | # | 任务 | 优先级 | 状态 | 依赖 | |---|------|--------|------|------| -| 1 | 信息架构重构 | P0 | DOING | — | -| 2 | 错题本 PRD 编写 | P0 | TODO | 1 | -| 3 | 系统架构设计 | P1 | TODO | 2 | -| 4 | P01 文档改写 | P1 | TODO | 2 | -| 5 | 架构提示词模板 | P2 | TODO | — | +| 1 | 信息架构重构 | P0 | DONE | — | +| 2 | 错题本 PRD 编写 | P0 | DONE | 1 | +| 3 | 系统架构设计 | P0 | DONE | 2 | +| 4 | P01 文档改写 | P1 | DONE | 2 | +| 5 | PRD 修订（根据人类反馈） | P0 | TODO | 人类审阅 | +| 6 | 将 Dev 任务写入 Dev 工作台 | P1 | TODO | 3 | +| 7 | 补充 ADR-009 技术选型决策 | P1 | TODO | 3 | +| 8 | 架构提示词模板 | P2 | TODO | — | ## 未来阶段预留 diff --git a/.ai/roles/arch/today.md b/.ai/roles/arch/today.md index c1b8bff..022ad1d 100644 --- a/.ai/roles/arch/today.md +++ b/.ai/roles/arch/today.md @@ -1,18 +1,44 @@ -# Arch AI · 今日任务 · 2026-05-25 +# Arch AI · 今日任务 · 2026-05-26 ## 已完成 -- [x] 信息架构重构 — 四层分层架构全部落地 -- [x] DASHBOARD.md + ROADMAP.md + docs/使用手册.md -- [x] 项目模板化（ai_project 分支）+ 同步机制 -- [x] 知识沉淀：ADR-007, ADR-008, P-001~003, L-001 +- [x] **[P0]** 编写 `docs/01_产品需求/PRD.md` v0.3.0 — 错题本产品需求文档（已锁定） +- [x] **[P0]** 设计 `docs/02_系统架构/` — 总体架构、技术选型、模块设计、数据模型（v0.3.0） +- [x] **[P1]** 将 P01 项目文档从"代码检测"改写为"错题本" +- [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 项目文档从"代码检测"改写为"错题本" -4. **[P1]** 更新 ROADMAP.md 任务看板（PRD 完成后分配 Dev 任务） +| 动作 | 状态 | +|------|------| +| ROADMAP Phase 1 → DONE 100% | ✅ | +| 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. 根据人类反馈做修订 ## 阻塞 diff --git a/.ai/roles/dev/queue.md b/.ai/roles/dev/queue.md index 65a22d8..ea16539 100644 --- a/.ai/roles/dev/queue.md +++ b/.ai/roles/dev/queue.md @@ -1,17 +1,36 @@ # Dev AI · 任务队列 -## 当前阶段 (Phase 1) 可执行任务 +## Phase 2 MVP 任务 | # | 任务 ID | 项目 | 描述 | 优先级 | 状态 | |---|---------|------|------|--------|------| -| 1 | P03-001 | Web | 项目初始化 | LOW | TODO | -| 2 | CROSS-001 | 共享 | 共享工具库更新 | HIGH | TODO | -| 3 | P01-001 | App | 用户登录 | HIGH | TODO | -| 4 | P01-002 | App | 代码分析 API | MEDIUM | TODO | -| 5 | P02-001 | 训练 | 数据预处理 | MEDIUM | TODO | +| 1 | P01-001 | App | 数据库 Schema 实现 + 迁移脚本 | P0 | TODO | +| 2 | P01-002 | App | Auth 模块（微信登录 + JWT） | P0 | TODO | +| 3 | CROSS-001 | 共享 | 共享工具库日期格式 bug 修复 | P0 | TODO | +| 4 | P01-005 | App | Image 模块（图像预处理管线） | P0 | 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` -影响范围 → `review/active/{任务ID}/impact.md` +``` +P01-001 (DB Schema) + ├─→ 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) diff --git a/.ai/roles/dev/today.md b/.ai/roles/dev/today.md index 7b92a15..3a8b55b 100644 --- a/.ai/roles/dev/today.md +++ b/.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 项目初始化（无依赖，可立即开始） | -| 2 | CROSS-001 | `review/active/CROSS-001/` | 共享工具库更新（等待已有 bug 修复） | +| # | 任务 | 优先级 | 说明 | +|---|------|--------|------| +| 1 | P01-001 | P0 | 数据库 Schema 实现 + Drizzle 迁移脚本。参考 [数据模型.md](../../../docs/02_系统架构/数据模型.md) 全部表定义 | +| 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） +## 关键架构文档 -| # | 任务 | 阻塞原因 | -|---|------|----------| -| 1 | P01-001 用户登录 | 等待 PRD | -| 2 | P01-002 代码分析API | 等待 PRD | -| 3 | P02-001 数据预处理 | 等待 PRD | +- [数据模型.md](../../../docs/02_系统架构/数据模型.md) — 所有表定义、索引、Drizzle Schema 示例 +- [模块设计.md](../../../docs/02_系统架构/模块设计.md) — API 接口、模块结构 +- [总体架构.md](../../../docs/02_系统架构/总体架构.md) — 数据流、部署架构 +- [技术选型.md](../../../docs/02_系统架构/技术选型.md) — 技术栈版本 ## 已完成 -（无） +（Phase 2 暂无） diff --git a/.trae/skills/share-context/SKILL.md b/.trae/skills/share-context/SKILL.md new file mode 100644 index 0000000..1a89eee --- /dev/null +++ b/.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**: 将内部开发文档自动转化为对外分享内容，实现「开发即内容」的闭环 diff --git a/DASHBOARD.md b/DASHBOARD.md index 5cf5817..fc52be0 100644 --- a/DASHBOARD.md +++ b/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% | ← 当前 | 搭骨架：框架、权限、信息架构 | -| 2. MVP | 0% | 未开始 | 做核心：错题录入、AI 分析 | +| 1. 基础搭建 | 100% | ✅ | 搭骨架：PRD 锁定、架构文档完成、旧架构合并 | +| 2. MVP | 0% | ← 当前 | 做核心：错题录入、AI 分析、PDF 打印、图像预处理 | | 3. 功能完善 | 0% | 未开始 | 加功能：推荐、多端、训练迭代 | | 4. 打磨发布 | 0% | 未开始 | 提质量：性能、安全、文档 | @@ -25,16 +25,15 @@ ## 现在在做什么 -- **信息架构重构** — 让 AI 能高效协作的文档体系（进行中） -- **5 个开发任务待启动** — 都在等待产品需求文档 +- **Dev AI 启动编码** — 数据库 Schema → Auth → Image → Print → User → Upload → 页面骨架 +- **Arch AI 补尾** — ADR-010（题库抽象层）、UI 规范迁移 +- **Phase 2 目标** — 拍照录入 + AI 分析 + PDF 输出 + 用户系统完整闭环 --- ## 需要你关注的事 -- [ ] 确认信息架构设计方向是否符合预期 -- [ ] 审阅角色工作台（`.ai/roles/`）是否合理 -- [ ] 决定 P01 项目方向：坚持"错题本"还是调整定位 +- [ ] 无。30 项决策已全部确认，Phase 2 由 AI 执行开发。 --- @@ -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/) | diff --git a/ROADMAP.md b/ROADMAP.md index ed92194..af4a2d8 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -7,44 +7,61 @@ ## 阶段总览 ``` -Phase 1 [=====-----] 基础搭建 ← 当前 (40%) -Phase 2 [----------] MVP (0%) +Phase 1 [==========] 基础搭建 ✅ 已完成 (100%) +Phase 2 [----------] MVP ← 当前 (0%) Phase 3 [----------] 功能完善 (0%) Phase 4 [----------] 打磨发布 (0%) ``` | 阶段 | 名称 | 状态 | 进度 | 预计重点 | |------|------|------|------|----------| -| 1 | 基础搭建 | ACTIVE | ~40% | 框架、脚手架、权限、信息架构 | -| 2 | MVP | PLANNED | 0% | 错题录入、AI 分析、基础展示 | -| 3 | 功能完善 | PLANNED | 0% | 个性化推荐、多端适配、训练迭代 | +| 1 | 基础搭建 | DONE | 100% | 框架、脚手架、PRD、架构设计、旧架构合并 | +| 2 | MVP | ACTIVE | 0% | 错题录入、AI 分析、PDF 打印、图像预处理 | +| 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 | P01 文档内容仍是"代码检测"模板 | P01-002 定位错误 | Arch AI | 2026-05-23 | -| YELLOW | CROSS-001 P01 日期格式 bug | CROSS-001 无法关闭 | Dev AI | 2026-05-23 | +| YELLOW | CROSS-001 日期格式 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 | diff --git a/docs/share/00_项目缘起.md b/docs/share/00_项目缘起.md index d632f6a..62d40c8 100644 --- a/docs/share/00_项目缘起.md +++ b/docs/share/00_项目缘起.md @@ -1,5 +1,82 @@ -# 项目缘起 +# 项目缘起：为什么我要做一个 AI 错题本 -> *（待写：由 Arch AI 在 PRD 完成后撰写）* -> -> 内容包括：为什么要做错题本、解决什么痛点、为什么选择这个技术方案、为什么用 AI 协作模式。 +> 一个不会写代码的产品经理，用 AI 从零开发一个 App 的全记录。 + +--- + +## 起点：一个做了很多年的梦 + +我一直在做教育相关的事情。 + +这么多年来，我见过太多学生被同一个问题困扰：**错题整理太痛苦了**。手抄错题、自己分类、凭感觉复习——每一步都在消耗学生的耐心。而传统错题本 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 不友好* diff --git a/docs/share/01_框架设计思路.md b/docs/share/01_框架设计思路.md index 9c320c6..3e5291f 100644 --- a/docs/share/01_框架设计思路.md +++ b/docs/share/01_框架设计思路.md @@ -1,8 +1,106 @@ -# 框架设计思路 +# 框架设计思路：当文档的读者不是人类 -> *（待写：信息架构重构稳定后撰写）* -> -> 内容包括：为什么传统的项目文档结构对 AI 不友好、分层信息架构的设计思考、token 预算的概念、"一鸡多吃"的分享层设计。 -> -> 对应 ADR：ADR-007 -> 背景参考：`.ai/principles.md` +> 传统项目结构对 AI 不友好——我的信息架构是怎么一步步推到重来的。 + +--- + +## 问题的起点：AI 看不懂我的项目 + +第一次用 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) — 基础搭建阶段到底做了什么* diff --git a/docs/share/README.md b/docs/share/README.md index dbdf3a8..3d3951e 100644 --- a/docs/share/README.md +++ b/docs/share/README.md @@ -10,15 +10,17 @@ | 文件 | 说明 | 状态 | |------|------|------| -| [00_项目缘起.md](00_项目缘起.md) | 为什么要做这个项目 | 待写 | -| [01_框架设计思路.md](01_框架设计思路.md) | 信息架构为什么这样设计 | 待写 | +| [00_项目缘起.md](00_项目缘起.md) | 为什么要做这个项目、1 人+3 AI 协作模式 | ✅ 已完成 | +| [01_框架设计思路.md](01_框架设计思路.md) | 信息架构为什么这样设计、token 预算概念 | ✅ 已完成 | ## 按阶段 | 阶段 | 复盘 | 决策故事 | 状态 | |------|------|----------|------| -| Phase 1: 基础搭建 | [阶段复盘](phase-01/阶段复盘_基础搭建.md) | [ADR-007 故事](phase-01/决策故事_ADR-007.md) | 待写 | -| Phase 2: MVP | — | — | 未开始 | +| Phase 1: 基础搭建 | [阶段复盘](phase-01/阶段复盘_基础搭建.md) | [ADR-007 信息架构](phase-01/决策故事_ADR-007.md) | ✅ | +| | | [ADR-009 人机协同](phase-01/决策故事_ADR-009.md) | ✅ | +| | | [旧架构合并](phase-01/决策故事_旧架构合并.md) | ✅ | +| Phase 2: MVP | — | — | 进行中 | --- @@ -26,7 +28,7 @@ 1. **不是做完再写**：开发过程中自动积累，阶段结束时翻译为对外语言 2. **去掉内部细节**：不暴露 API 密钥、服务器地址、个人信息 -3. **加上思考过程**：不只说"做了什么"，更要说"为什么这么选" +3. **加上思考过程**：不只说「做了什么」，更要说「为什么这么选」 4. **可独立阅读**：每篇文章自成一体，不需要读其他文章才能理解 ## 内容来源 diff --git a/docs/share/phase-01/决策故事_ADR-007.md b/docs/share/phase-01/决策故事_ADR-007.md index 1de9c2d..fd4b9a2 100644 --- a/docs/share/phase-01/决策故事_ADR-007.md +++ b/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 的注意力分配方案。** diff --git a/docs/share/phase-01/决策故事_ADR-009.md b/docs/share/phase-01/决策故事_ADR-009.md new file mode 100644 index 0000000..cb1b9bd --- /dev/null +++ b/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 错误」变成「用户价值」的闭环。** diff --git a/docs/share/phase-01/决策故事_旧架构合并.md b/docs/share/phase-01/决策故事_旧架构合并.md new file mode 100644 index 0000000..3bb9d65 --- /dev/null +++ b/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 负责剩下的——这就是「人机协同」在架构设计上的应用。** diff --git a/docs/share/phase-01/阶段复盘_基础搭建.md b/docs/share/phase-01/阶段复盘_基础搭建.md index 73a9f48..88385a9 100644 --- a/docs/share/phase-01/阶段复盘_基础搭建.md +++ b/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 启动自动化测试。 diff --git a/projects/P01_errlens_app/docs/01_需求概要.md b/projects/P01_errlens_app/docs/01_需求概要.md index f89f72c..92f5c25 100644 --- a/projects/P01_errlens_app/docs/01_需求概要.md +++ b/projects/P01_errlens_app/docs/01_需求概要.md @@ -1,21 +1,21 @@ -# P01_errlens_app - 需求概要 +# P01_errlens_app — 需求概要 ## 项目概述 -ErrLens 小程序应用是一个基于 **Taro 4 框架**开发的多端小程序项目，支持微信小程序、抖音小程序和 H5 平台。 +ErrLens 小程序是一款面向中小学生的 **AI 错题本**，帮助学生拍照录入错题、自动归类分析、获得针对性练习推荐。 ## 项目定位 -- **产品类型**：AI 辅助编程工具的移动端入口 -- **目标用户**：开发者、编程学习者、代码审查人员 -- **核心价值**：随时随地访问 ErrLens 的代码错误检测和修复建议功能 +- **产品类型**: AI 错题本（教育类微信小程序） +- **目标用户**: 中小学生（10-18 岁），以初中生为典型交互设计 +- **核心价值**: 拍照录入 → 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 | 数据库连接 | -| S3 兼容存储 | 文件存储 | -| Coze SDK | AI 能力集成 | +| Supabase | 数据库托管 | +| S3 兼容存储 | 错题图片存储 | +| Coze SDK | AI OCR + 知识点分类 + 错误诊断 | +| 微信开放平台 | 微信登录 + 小程序能力 | ## 核心功能模块 -### 1. 首页模块 -- [ ] 欢迎页面展示 -- [ ] 功能快捷入口 -- [ ] 最新动态/公告 +### 1. 拍照录入模块 +- [ ] 拍照/选图 → AI 识别题目文字、学科、知识点 +- [ ] 识别结果展示 + 用户修正 +- [ ] 正确答案录入（可选） -### 2. 代码分析模块 -- [ ] 代码上传/粘贴 -- [ ] 错误检测结果展示 -- [ ] 修复建议生成 +### 2. 错题管理模块 +- [ ] 错题列表（按时间/学科/知识点/错误类型筛选） +- [ ] 错题详情（题目 + AI 分析 + 知识点标注） +- [ ] 错题编辑（修正 AI 识别结果） -### 3. 用户模块 -- [ ] 用户登录/注册 +### 3. AI 分析模块 +- [ ] 单题错误诊断（知识点欠缺/粗心/审题偏差/概念混淆） +- [ ] 薄弱知识点汇总与排序 +- [ ] 学习报告（周/月度趋势） + +### 4. 用户模块 +- [ ] 微信授权登录 +- [ ] 年级和学科设置 - [ ] 个人中心 -- [ ] 历史记录 -### 4. 设置模块 -- [ ] 主题切换 -- [ ] 通知设置 -- [ ] 关于我们 +### 5. 练习推荐模块（P1） +- [ ] 基于薄弱点推荐同类题 +- [ ] 自定义组题练习 ## 页面结构 ``` pages/ -├── index/ # 首页 -├── analyze/ # 代码分析 -├── history/ # 历史记录 -├── profile/ # 个人中心 -└── settings/ # 设置页面 +├── index/ # 首页（错题概览 + 快捷入口） +├── auth/ +│ └── login/ # 微信授权登录 +├── capture/ # 拍照录入 +│ ├── 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 | - ## 多端支持 -| 平台 | 状态 | 说明 | -|------|------|------| -| 微信小程序 | ✅ 支持 | 主流平台 | -| 抖音小程序 | ✅ 支持 | 字节系平台 | -| H5 | ✅ 支持 | Web 端预览 | +| 平台 | 状态 | 优先级 | +|------|------|--------| +| 微信小程序 | MVP 唯一平台 | P0 | +| 抖音小程序 | 按需适配 | P3 | +| H5 | 兜底+开发调试 | P2 | ## 用户体验目标 -- **加载速度**：首屏加载 < 2s -- **交互流畅**：帧率 >= 60fps -- **跨端一致**：各端 UI 表现一致 -- **离线可用**：支持本地缓存 +- **录入效率**: 拍照到保存 < 30s（含 AI 识别 3-5s） +- **首屏加载**: < 2s +- **交互流畅**: 60fps，长列表使用虚拟列表 +- **离线可用**: 图片本地缓存，网络恢复后上传 ## 安全要求 -- 用户数据加密存储 -- API 请求鉴权 -- 敏感信息脱敏 +- 微信 OAuth 登录，不存储密码 +- 用户数据严格隔离（API 鉴权） +- 图片上传使用签名 URL +- 敏感信息传输加密 --- -**文档版本**：v1.0.0 -**最后更新**：2026-05-22 +**文档版本**: v0.1.0 | **基于**: [PRD.md](../../../docs/01_产品需求/PRD.md) | **最后更新**: 2026-05-26 diff --git a/projects/P01_errlens_app/docs/02_架构设计.md b/projects/P01_errlens_app/docs/02_架构设计.md index b66ac72..3173e9d 100644 --- a/projects/P01_errlens_app/docs/02_架构设计.md +++ b/projects/P01_errlens_app/docs/02_架构设计.md @@ -1,207 +1,180 @@ -# P01_errlens_app - 架构设计 +# P01_errlens_app — 架构设计 ## 整体架构 ``` -┌─────────────────────────────────────────────────────────────┐ -│ 小程序客户端 │ -│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ -│ │ 首页 │ │ 分析 │ │ 历史 │ │ 我的 │ │ -│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ -│ │ │ │ │ │ -│ ┌────┴────────────┴────────────┴────────────┴────┐ │ -│ │ 组件库 (shadcn/ui) │ │ -│ └────────────────────┬─────────────────────────┘ │ -│ │ │ -│ ┌────────────────────┴─────────────────────────┐ │ -│ │ 状态管理 (Zustand) │ │ -│ └────────────────────┬─────────────────────────┘ │ -│ │ │ -│ ┌────────────────────┴─────────────────────────┐ │ -│ │ Network 层 (API 封装) │ │ -│ └────────────────────┬─────────────────────────┘ │ -└───────────────────────┼───────────────────────────────────┘ - │ HTTP - ▼ -┌───────────────────────────────────────────────────────────┐ -│ 后端服务 (NestJS) │ -│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ -│ │ 用户模块 │ │ 分析模块 │ │ 历史模块 │ │ 系统模块 │ │ -│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ -│ │ │ │ │ │ -│ ┌────┴────────────┴────────────┴────────────┴────┐ │ -│ │ Service 层 │ │ -│ └────────────────────┬─────────────────────────┘ │ -│ │ │ -│ ┌────────────────────┴─────────────────────────┐ │ -│ │ 数据层 (Drizzle ORM) │ │ -│ └────────────────────┬─────────────────────────┘ │ -└───────────────────────┼───────────────────────────────────┘ - │ - ▼ - ┌─────────────────┐ - │ PostgreSQL │ - │ Supabase │ - └─────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ 小程序客户端 (Taro + React) │ +│ │ +│ ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ 首页 │ │ 拍照录入 │ │ 错题列表 │ │ 我的 │ │ +│ └───┬────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ +│ │ │ │ │ │ +│ ┌───┴───────────┴────────────┴────────────┴─────┐ │ +│ │ 组件库 (shadcn/ui Taro 适配) │ │ +│ └──────────────────────┬───────────────────────┘ │ +│ │ │ +│ ┌──────────────────────┴───────────────────────┐ │ +│ │ 状态管理 (Zustand) │ │ +│ │ auth / error-item / capture / ai-analysis │ │ +│ └──────────────────────┬───────────────────────┘ │ +│ │ │ +│ ┌──────────────────────┴───────────────────────┐ │ +│ │ Network 层 (API 封装 + JWT) │ │ +│ └──────────────────────┬───────────────────────┘ │ +└─────────────────────────┼──────────────────────────────────┘ + │ HTTPS + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ 后端服务 (NestJS) │ +│ │ +│ ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ │ +│ │ 用户模块│ │ 错题模块│ │ AI 分析 │ │ 上传 │ │ +│ └───┬────┘ └───┬────┘ └────┬─────┘ └───┬────┘ │ +│ │ │ │ │ │ +│ ┌───┴──────────┴───────────┴────────────┴─────┐ │ +│ │ Service 层 │ │ +│ └──────────────────────┬───────────────────────┘ │ +│ │ │ +│ ┌──────────────────────┴───────────────────────┐ │ +│ │ 数据层 (Drizzle ORM + PostgreSQL) │ │ +│ └──────────────────────┬───────────────────────┘ │ +└─────────────────────────┼──────────────────────────────────┘ + │ + ┌───────────┴───────────┐ + ▼ ▼ + ┌─────────────────┐ ┌─────────────────┐ + │ 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 组件库 -│ │ ├── button.tsx -│ │ ├── card.tsx -│ │ ├── dialog.tsx -│ │ └── ... (50+ 组件) +│ │ ├── ui/ # shadcn/ui 组件库 (~50 个) +│ │ └── business/ # 业务组件 +│ │ ├── error-card/ # 错题卡片 +│ │ ├── knowledge-tag/ # 知识点标签 +│ │ └── analysis-chart/ # 分析图表 │ │ │ ├── pages/ # 页面 -│ │ └── index/ # 首页 -│ │ ├── index.tsx -│ │ ├── index.config.ts -│ │ └── index.css +│ │ ├── index/ # 首页 +│ │ ├── auth/login/ # 登录 +│ │ ├── capture/ # 拍照录入 +│ │ │ ├── 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 # 通用工具 -│ │ ├── platform.ts # 平台检测 -│ │ ├── measure.ts # 尺寸测量 -│ │ └── hooks/ # 自定义 Hooks +│ │ ├── utils.ts +│ │ ├── platform.ts +│ │ ├── measure.ts +│ │ └── hooks/ │ │ │ ├── presets/ # 预设配置 │ │ ├── index.tsx │ │ ├── env.ts -│ │ ├── h5-container.tsx -│ │ └── ... +│ │ └── h5-*.tsx │ │ │ └── network.ts # API 请求封装 │ -│ ├── server/ # 后端源码 (NestJS) -│ │ ├── src/ -│ │ │ ├── app.module.ts # 根模块 -│ │ │ ├── app.controller.ts# 根控制器 -│ │ │ ├── app.service.ts # 根服务 -│ │ │ └── main.ts # 入口文件 -│ │ │ -│ │ ├── nest-cli.json -│ │ ├── tsconfig.json -│ │ └── package.json -│ │ -│ ├── config/ # 构建配置 -│ │ ├── index.ts # 通用配置 -│ │ ├── dev.ts # 开发环境配置 -│ │ └── prod.ts # 生产环境配置 -│ │ -│ ├── types/ # 类型定义 -│ │ ├── global.d.ts -│ │ └── lucide.d.ts +├── server/ # 后端源码 (NestJS) +│ └── src/ +│ ├── main.ts # 启动入口 +│ ├── app.module.ts # 根模块 +│ ├── app.controller.ts # 根控制器 +│ ├── db/ +│ │ └── schema.ts # Drizzle Schema +│ ├── modules/ +│ │ ├── auth/ # 鉴权模块 +│ │ ├── user/ # 用户模块 +│ │ ├── error-item/ # 错题模块 +│ │ ├── ai/ # AI 分析模块 +│ │ ├── subject/ # 学科模块 +│ │ └── upload/ # 文件上传 +│ └── common/ +│ ├── guards/ # JWT Guard +│ ├── interceptors/ # HTTP 状态拦截器 +│ └── filters/ # 异常过滤器 │ -├── tests/ # 测试代码 -│ ├── unit/ # 单元测试 -│ ├── integration/ # 集成测试 -│ └── e2e/ # E2E 测试 +├── tests/ # 测试 +│ ├── unit/ # 单元测试 +│ │ ├── components/ +│ │ └── lib/ +│ ├── integration/ # 集成测试 +│ └── e2e/ # E2E 测试 │ -├── docs/ # 项目文档 -│ ├── 01_需求概要.md -│ ├── 02_架构设计.md -│ └── 03_接口定义.md -│ -├── package.json # 前端依赖 -├── tsconfig.json # TypeScript 配置 -├── babel.config.js # Babel 配置 -├── eslint.config.mjs # ESLint 配置 -├── stylelint.config.mjs # Stylelint 配置 -├── project.config.json # 微信小程序配置 -└── ENVIRONMENT.md # 环境准备指南 +├── docs/ # 项目文档 +├── package.json +├── tsconfig.json +├── babel.config.js +├── eslint.config.mjs +├── stylelint.config.mjs +├── 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/ # 业务逻辑 -├── modules/ # NestJS 模块 -├── entities/ # 数据实体 -├── dto/ # 数据传输对象 -└── interceptors/ # 拦截器 +[拍照页] → 拍照/选图 + → [预览页] 确认图片 + → [Upload] 上传 → S3 返回 URL + → [AI Service] Coze SDK OCR + 知识点分类 + → [确认页] 展示识别结果，允许修正 + → [保存] 写入 ErrorItem → 跳转详情页 +``` + +### 状态机 (capture.store) + +``` +IDLE → CAMERA → PREVIEW → UPLOADING → ANALYZING → REVIEW → SAVING → DONE + ↓ ↓ ↓ ↓ + ERROR ERROR ERROR ERROR + └── 重试 ──┘ ``` ## 多端适配策略 -### 平台检测 - -```typescript -import { Taro, ENV_TYPE } from '@tarojs/taro' - -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 | -| 原生组件 | 平台检测 + 降级方案 | +| 场景 | 方案 | +|------|------| +| 拍照 | 微信: wx.chooseMedia, H5: input[type=file] | +| 图片预览 | 微信: wx.previewImage, H5: dialog | +| 登录 | 微信: wx.login → code2session, H5: 扫码 | +| 原生组件 | 平台检测 + 条件渲染 | ## 部署架构 ### 开发环境 -- 前端：H5 端口 5000 -- 后端：Node 端口 3000 +- 前端 H5: port 5000 (Vite dev server) +- 后端: port 3000 (NestJS) +- 数据库: Supabase 开发实例 ### 生产环境 -- 微信小程序：构建 weapp 包 -- 抖音小程序：构建 tt 包 -- H5：构建 web 静态资源 +- 微信小程序: `taro build --type weapp` → 上传代码包 +- 后端: Node.js 单实例 (Phase 3 容器化) +- 图片: S3/MinIO + CDN --- -**文档版本**：v1.0.0 -**最后更新**：2026-05-22 +**文档版本**: v0.1.0 | **基于**: [系统架构](../../../docs/02_系统架构/) | **最后更新**: 2026-05-26 diff --git a/projects/P01_errlens_app/docs/03_接口定义.md b/projects/P01_errlens_app/docs/03_接口定义.md index 5751325..bf8885a 100644 --- a/projects/P01_errlens_app/docs/03_接口定义.md +++ b/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`） -- **请求格式**: JSON -- **响应格式**: Envelope Pattern `{ code, msg, data }` +- **Base URL**: `/api`（开发环境通过 Vite Proxy 到 `http://localhost:3000/api`） +- **请求格式**: JSON（文件上传使用 multipart/form-data） +- **响应格式**: `{ code: number, msg: string, data: T | null }` ### 通用响应结构 ```typescript -// 成功响应 -{ - code: 200, - msg: "success", - data: { ... } -} +// 成功 +{ code: 200, msg: "success", data: { ... } } -// 错误响应 -{ - code: 400 | 401 | 403 | 404 | 500, - msg: "错误信息", - data: null -} +// 客户端错误 +{ code: 400 | 401 | 403 | 404, msg: "错误描述", data: null } + +// 服务端错误 +{ code: 500, msg: "服务器内部错误", data: null } +``` + +### 鉴权 + +除登录接口外，所有 API 需在 Header 携带 JWT Token： + +``` +Authorization: Bearer ``` --- -## 用户模块 +## 1. 鉴权模块 -### 1. 用户登录 +### 1.1 微信登录 ``` POST /api/auth/login ``` -**请求参数**： +**请求**: ```json { - "email": "string", - "password": "string" + "code": "wx.login() 返回的 code" } ``` -**响应示例**： +**响应**: ```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 ``` -**请求头**： -``` -Authorization: Bearer +**请求**: +```json +{ + "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", - "nickname": "用户名", - "avatar": "https://...", - "createdAt": "2026-05-22T00:00:00Z" + "createdAt": "2026-05-26T10:00:00Z" } } ``` ---- - -## 代码分析模块 - -### 1. 上传代码分析 +### 3.2 查询错题列表 ``` -POST /api/analyze +GET /api/error-items?page=1&pageSize=20&subjectId=1&errorType=knowledge_gap&keyword=二次函数&sort=createdAt&order=desc ``` -**请求头**： -``` -Authorization: Bearer -``` +**查询参数**: -**请求参数**： -```json -{ - "code": "string", - "language": "javascript | python | typescript | ..." -} -``` +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| page | int | 否 | 页码，默认 1 | +| pageSize | int | 否 | 每页条数，默认 20，最大 50 | +| 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() {...}", - "language": "javascript", - "resultCount": 3, - "createdAt": "2026-05-22T00:00:00Z" + "thumbnailUrl": "https://...", + "questionText": "已知二次函数...", + "subject": { "id": 1, "name": "数学" }, + "knowledgePoints": [ + { "id": 1021, "name": "顶点坐标" } + ], + "errorType": "knowledge_gap", + "difficulty": "medium", + "createdAt": "2026-05-26T10:00:00Z" } ], - "total": 100, + "total": 42, "page": 1, "pageSize": 20 } } ``` ---- - -## 文件上传模块 - -### 1. 上传文件 +### 3.3 获取错题详情 ``` -POST /api/upload +GET /api/error-items/:id ``` -**请求头**： -``` -Authorization: Bearer -Content-Type: multipart/form-data -``` - -**请求参数**： -``` -file: binary -``` - -**响应示例**： +**响应**: ```json { "code": 200, "msg": "success", "data": { - "url": "https://storage.example.com/files/xxx.png", - "filename": "xxx.png", - "size": 1024 + "id": "uuid", + "imageUrl": "https://...", + "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. 学科模块 -| 错误码 | 说明 | -|-------|------| -| 200 | 成功 | -| 400 | 请求参数错误 | -| 401 | 未授权 / Token 过期 | -| 403 | 权限不足 | -| 404 | 资源不存在 | -| 500 | 服务器内部错误 | +### 5.1 获取学科列表 ---- +``` +GET /api/subjects +``` -## API 测试命令 +**响应**: +```json +{ + "code": 200, + "msg": "success", + "data": [ + { "id": 1, "name": "数学", "icon": "math" }, + { "id": 2, "name": "英语", "icon": "english" } + ] +} +``` -### 开发环境测试 +### 5.2 获取学科知识点树 -```bash -# 登录接口 -curl -X POST http://localhost:3000/api/auth/login \ - -H "Content-Type: application/json" \ - -d '{"email":"test@example.com","password":"123456"}' +``` +GET /api/subjects/:id/knowledge-points +``` -# 获取用户信息 -curl -X GET http://localhost:3000/api/users/profile \ - -H "Authorization: Bearer " - -# 代码分析 -curl -X POST http://localhost:3000/api/analyze \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d '{"code":"console.log(1)","language":"javascript"}' +**响应**: +```json +{ + "code": 200, + "msg": "success", + "data": [ + { + "id": 10, + "name": "代数", + "children": [ + { + "id": 102, + "name": "二次函数", + "children": [ + { "id": 1021, "name": "顶点坐标", "children": [] } + ] + } + ] + } + ] +} ``` --- -**文档版本**：v1.0.0 -**最后更新**：2026-05-22 +## 6. 文件上传模块 + +### 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 " + +# 创建错题 +curl -X POST http://localhost:3000/api/error-items \ + -H "Authorization: Bearer " \ + -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 " \ + -F "file=@/path/to/photo.jpg" +``` + +--- + +**文档版本**: v0.1.0 | **基于**: [模块设计](../../../docs/02_系统架构/模块设计.md) | **最后更新**: 2026-05-26