Appearance
1.1 需求拆解与验收条件
AI CODING · STAGE 1 · REQUIREMENTS
先把四段用户路径写进需求文件。页面、状态、数据和验收没有对齐前，不发编码任务。
时间 40–60 分钟改动 docs/requirements.md切片 4
本节只改一份文件
docs/requirements.md不改业务代码不改 package / config
需求文件先写什么
Starter 没有 docs/requirements.md。创建它，记录阶段 1 的页面、状态、数据和验收结果。后面的 architecture、component contract 和 test 都以这份文件为准。
首页保存当前阶段，按阶段过滤推荐；详情页根据 URL 中的推荐 ID 查找数据。查不到时显示“没有找到这条推荐”。
收藏、浏览历史、local persistence、API、database 和 AI 解释不写入本阶段需求。
固定阶段契约
四个 ID 和名称原样写进 docs/requirements.md：
| ID | 名称 | 短名称 |
|---|---|---|
pregnancy | 孕期 | 孕期 |
baby-0-6 | 宝宝 0–6 月 | 0–6 月 |
baby-6-12 | 宝宝 6–12 月 | 6–12 月 |
toddler-1-3 | 宝宝 1–3 岁 | 1–3 岁 |
不要创建四个 contract 之外的阶段别名。后续 StageId 会从这组 canonical data 推导。
拆成四个垂直切片
| 切片 | 输入 | 行为 | 可观察结果 |
|---|---|---|---|
| 阶段选择 | 4 个固定阶段 | 点击切换 | 选中态和列表一起变化 |
| 推荐列表 | 阶段 ID | 按 stageIds 过滤 | 卡片数量与内容正确 |
| 推荐详情 | 推荐 ID | 携带 ID 跳转，详情页按 ID 查找 | 展示推荐依据和注意事项 |
| 无效详情 | 不存在的 ID | 查找失败 | 显示明确空状态 |
默认阶段固定为 baby-6-12。首次打开首页应有两条推荐；切到 pregnancy 后只保留“产检资料收纳清单”。
验收要写成可观察结果
下面左侧无法直接验收，右侧可以：
| 不要这样写 | 改成这样 |
|---|---|
| 支持阶段化推荐 | 首次打开默认选中“6–12 月”，显示 2 条推荐 |
| 支持切换阶段 | 点击“孕期”后，选中态变化，列表只显示“产检资料收纳清单” |
| 完成详情页 | 打开“南瓜泥入门”，页面出现“推荐依据”和“注意事项” |
| 做好异常处理 | URL 使用不存在的 ID 时显示“没有找到这条推荐” |
“体验流畅”“结构合理”“功能正常”都不能单独放进验收。Reviewer 无法根据这些词判断通过还是退回。
docs/requirements.md 完整样例
markdown
# 阶段 1 需求简报
## 目标
使用 Mock 数据完成阶段选择、推荐列表、推荐详情和无效详情空状态。
## 阶段契约
- `pregnancy`：孕期
- `baby-0-6`：宝宝 0–6 月
- `baby-6-12`：宝宝 6–12 月
- `toddler-1-3`：宝宝 1–3 岁
## 验收
1. 默认阶段为 `baby-6-12`，显示 2 条推荐。
2. 切换阶段后，列表只显示包含该阶段 ID 的推荐。
3. 点击卡片进入详情，展示推荐依据和注意事项。
4. 推荐 ID 不存在时显示“没有找到这条推荐”。
5. `npm run test:web` 和 `npm run build:web` 均通过。
## 阶段 1 不做
- 收藏和浏览历史
- 本地持久化
- 后端 API 和数据库
- AI 解释可以调整措辞，不能更换 ID、默认阶段或四条用户行为。后续 test 会直接使用这些值。
需求怎样落到检查
| 需求 | 自动检查 | 人工检查 |
|---|---|---|
| 四个 canonical stage | stages.test.ts：合法 ID、未知值、名称 | 阶段选择器显示四个短名称 |
baby-6-12 有两条推荐 | recommendations.test.ts：筛选结果为 2 | 首次打开首页 |
| 推荐详情按 ID 查找 | recommendations.test.ts：找到南瓜泥、未知 ID 返回空 | 打开详情并修改 URL |
| component event 与页面导航 | unit test 不覆盖 | 切换阶段、打开卡片 |
| H5 能生成 | npm run build:web | 不验证业务行为 |
这张表也解释了为什么要同时保留 test、build 和四条浏览器路径：三者检查的故障面不同。
把任务交给 AI
先让 AI 复述，别让它直接写文件：
text
先不要写业务代码。
请按“页面、状态、数据、验收”四栏复述阶段 1 需求。
确认后，在 learner/week-01 创建 docs/requirements.md。
文件必须包含：
- pregnancy、baby-0-6、baby-6-12、toddler-1-3 的 ID、名称和短名称
- 阶段选择、推荐列表、推荐详情、无效详情四个切片
- 默认两条、孕期一条、成功详情、无效详情空状态四条验收
- npm run test:web 与 npm run build:web 两条周检查
- 阶段 1 不做项
不要创建阶段别名，不要修改其他文件。
先返回准备写入的内容，等我确认。Review 复述时只查四项：
- 页面职责有没有混进 component 或 domain。
- 四个阶段 ID 是否完整。
- 四条验收是否可直接观察。
- 是否夹带收藏、API 或 AI 回复。
有一项不对，先改任务。不要在错误需求上继续生成代码。
提交需求文件
AI 写入后检查 working tree 和 cached diff：
bash
git status --short
git add docs/requirements.md
git diff --cached -- docs/requirements.md只应看到 docs/requirements.md。Diff 中逐项核对四个阶段、四个切片、四条验收、周检查和不做项，然后提交：
bash
git commit -m "docs: add week one requirements"这时还没有业务代码。Starter 的 passWithNoTests 或一次成功 build 只能说明工具链能启动。
1.4 会按下面四条路径验收实现：
- 默认
baby-6-12，显示 2 条推荐。 - 切到
pregnancy，只显示“产检资料收纳清单”。 - 打开存在的推荐，显示“推荐依据”和“注意事项”。
- 打开不存在的推荐 ID，显示“没有找到这条推荐”。
需求 commit 准备好后，进入 1.2 技术选型与项目结构。