# Phase 1 阶段复盘：基础搭建

## 阶段信息

- 阶段编号：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 启动自动化测试。