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>
This commit is contained in:
tupingr
@@ -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 节）
|
||||
@@ -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 | — |
|
||||
|
||||
## 未来阶段预留
|
||||
|
||||
|
||||
+36
-10
@@ -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. 根据人类反馈做修订
|
||||
|
||||
## 阻塞
|
||||
|
||||
|
||||
+29
-10
@@ -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)
|
||||
|
||||
+19
-14
@@ -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 暂无）
|
||||
|
||||
@@ -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**: 将内部开发文档自动转化为对外分享内容，实现「开发即内容」的闭环
|
||||
+10
-9
@@ -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/) |
|
||||
|
||||
+38
-21
@@ -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 |
|
||||
|
||||
+81
-4
@@ -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 不友好*
|
||||
|
||||
+105
-7
@@ -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) — 基础搭建阶段到底做了什么*
|
||||
|
||||
@@ -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. **可独立阅读**：每篇文章自成一体，不需要读其他文章才能理解
|
||||
|
||||
## 内容来源
|
||||
|
||||
@@ -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 的注意力分配方案。**
|
||||
|
||||
@@ -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 错误」变成「用户价值」的闭环。**
|
||||
@@ -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 负责剩下的——这就是「人机协同」在架构设计上的应用。**
|
||||
@@ -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 启动自动化测试。
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -1,207 +1,180 @@
|
||||
# P01_errlens_app - 架构设计
|
||||
# P01_errlens_app — 架构设计
|
||||
|
||||
## 整体架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 小程序客户端 │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ 首页 │ │ 分析 │ │ 历史 │ │ 我的 │ │
|
||||
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 小程序客户端 (Taro + React) │
|
||||
│ │
|
||||
│ ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ 首页 │ │ 拍照录入 │ │ 错题列表 │ │ 我的 │ │
|
||||
│ └───┬────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ ┌────┴────────────┴────────────┴────────────┴────┐ │
|
||||
│ │ 组件库 (shadcn/ui) │ │
|
||||
│ └────────────────────┬─────────────────────────┘ │
|
||||
│ ┌───┴───────────┴────────────┴────────────┴─────┐ │
|
||||
│ │ 组件库 (shadcn/ui Taro 适配) │ │
|
||||
│ └──────────────────────┬───────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────────┴─────────────────────────┐ │
|
||||
│ ┌──────────────────────┴───────────────────────┐ │
|
||||
│ │ 状态管理 (Zustand) │ │
|
||||
│ └────────────────────┬─────────────────────────┘ │
|
||||
│ │ auth / error-item / capture / ai-analysis │ │
|
||||
│ └──────────────────────┬───────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────────┴─────────────────────────┐ │
|
||||
│ │ Network 层 (API 封装) │ │
|
||||
│ └────────────────────┬─────────────────────────┘ │
|
||||
└───────────────────────┼───────────────────────────────────┘
|
||||
│ HTTP
|
||||
│ ┌──────────────────────┴───────────────────────┐ │
|
||||
│ │ Network 层 (API 封装 + JWT) │ │
|
||||
│ └──────────────────────┬───────────────────────┘ │
|
||||
└─────────────────────────┼──────────────────────────────────┘
|
||||
│ HTTPS
|
||||
▼
|
||||
┌───────────────────────────────────────────────────────────┐
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 后端服务 (NestJS) │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ 用户模块 │ │ 分析模块 │ │ 历史模块 │ │ 系统模块 │ │
|
||||
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
||||
│ │
|
||||
│ ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ │
|
||||
│ │ 用户模块│ │ 错题模块│ │ AI 分析 │ │ 上传 │ │
|
||||
│ └───┬────┘ └───┬────┘ └────┬─────┘ └───┬────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ ┌────┴────────────┴────────────┴────────────┴────┐ │
|
||||
│ ┌───┴──────────┴───────────┴────────────┴─────┐ │
|
||||
│ │ 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 组件库
|
||||
│ │ ├── 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/ # 测试代码
|
||||
├── 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 配置
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── babel.config.js
|
||||
├── eslint.config.mjs
|
||||
├── stylelint.config.mjs
|
||||
├── project.config.json # 微信小程序配置
|
||||
└── ENVIRONMENT.md # 环境准备指南
|
||||
└── 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
|
||||
|
||||
@@ -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 <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 用户模块
|
||||
## 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 <token>
|
||||
**请求**:
|
||||
```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 <token>
|
||||
```
|
||||
**查询参数**:
|
||||
|
||||
**请求参数**：
|
||||
```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 <token>
|
||||
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. 学科模块
|
||||
|
||||
### 5.1 获取学科列表
|
||||
|
||||
```
|
||||
GET /api/subjects
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": [
|
||||
{ "id": 1, "name": "数学", "icon": "math" },
|
||||
{ "id": 2, "name": "英语", "icon": "english" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 获取学科知识点树
|
||||
|
||||
```
|
||||
GET /api/subjects/:id/knowledge-points
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": [
|
||||
{
|
||||
"id": 10,
|
||||
"name": "代数",
|
||||
"children": [
|
||||
{
|
||||
"id": 102,
|
||||
"name": "二次函数",
|
||||
"children": [
|
||||
{ "id": 1021, "name": "顶点坐标", "children": [] }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 | 权限不足 |
|
||||
| 403 | 无权访问该资源 |
|
||||
| 404 | 资源不存在 |
|
||||
| 413 | 文件过大 |
|
||||
| 429 | 请求频率超限 |
|
||||
| 500 | 服务器内部错误 |
|
||||
| 502 | AI 服务不可用 |
|
||||
|
||||
---
|
||||
|
||||
## API 测试命令
|
||||
|
||||
### 开发环境测试
|
||||
## 8. API 测试
|
||||
|
||||
```bash
|
||||
# 登录接口
|
||||
# 微信登录
|
||||
curl -X POST http://localhost:3000/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"test@example.com","password":"123456"}'
|
||||
-d '{"code":"wx_test_code"}'
|
||||
|
||||
# 获取用户信息
|
||||
curl -X GET http://localhost:3000/api/users/profile \
|
||||
# 获取错题列表
|
||||
curl -X GET "http://localhost:3000/api/error-items?page=1&pageSize=20" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
|
||||
# 代码分析
|
||||
curl -X POST http://localhost:3000/api/analyze \
|
||||
# 创建错题
|
||||
curl -X POST http://localhost:3000/api/error-items \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"code":"console.log(1)","language":"javascript"}'
|
||||
-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"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**文档版本**：v1.0.0
|
||||
**最后更新**：2026-05-22
|
||||
**文档版本**: v0.1.0 | **基于**: [模块设计](../../../docs/02_系统架构/模块设计.md) | **最后更新**: 2026-05-26
|
||||
|
||||
Reference in New Issue
Block a user