# study-workbench

**Repository Path**: musicofmaple/study-workbench

## Basic Information

- **Project Name**: study-workbench
- **Description**: children study workbench (no real data in repo)
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-29
- **Last Updated**: 2026-11-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 需求文档怎么放

需求与设计文档只放仓库根的 `docs/`。不要再写到 `web-app/docs/`。`web-app/` 是站点根，放在那里会随 Git 发布到公网，也会被打进安装包的排除清单里绕来绕去。

`docs/` 根上只允许这一份 `README.md`。新需求先在下面的索引加一行，再建立目录。

## 一个需求一个目录

目录名：`YYYY-MM-DD-英文短名`。日期用这个需求开始的那天。短名用英文，中间用连字符，不用空格，不用中文。

中文功能名写在本索引里，也写在主文档标题里。目录和文件名保持英文，是因为 Git Bash 遇到中文参数会直接退出，cmd 和 PowerShell 脚本也会把中文路径解错。这个仓库已经为此把应用目录改成了 `web-app/`，把 `打包APK.cmd` 改成了 `make-apk.cmd`。

```text
docs/2026-10-15-reading-70/
├── 2026-10-15-reading-70.md     主文档，文件名与目录同名
├── plan.md                      只有一份实现计划时用这个名字
├── files/                       脚本、解析结果、效果图。没有就不建
└── notes/                       讨论记录、交互或样式的 html。没有就不建
```

- **主文档**记：状态、要做什么、已经拍板的决定、不做什么、本目录文件各是干什么的、谁在读这些文件、修订记录。改代码时以这里的已拍板决定为准。
- **`plan.md`** 记实现步骤、要改的文件、验收勾选。决策不要再抄一遍，开头链到主文档。一个需求有多期计划时，不要挤成一个 `plan.md`，沿用各自的文件名，例如 `2026-10-14-spark-p1-grammar.md`。
- **`files/`** 放这个需求自己的脚本、PDF 解析结果、效果图。全工程还在反复跑的生成器留在仓库根，例如 `gen-reading-passages.js`、`gen-wordbank-2000-ext.js`。它们只是来这里读输入。
- **`notes/`** 放讨论稿。效果图如果是一组 html/css/js，放在 `files/` 里单独一个英文子目录，让相对路径还能用。

状态只用这五个：草案、已拍板、已落地、已退役、未采用。

前后两代需求各留各的目录。旧的标成已退役或未采用，不并进后来那份，也不删。

## 需求变更：改原文档还是开新目录（2026-11-12 定）

**默认改原需求文档；只有"推翻原决策"才开新目录。**

- 追加功能、调阈值、改界面、修 bug 引发的规格变化（目标/数据模型/红线没变）→ **改原文档**。范本：娱乐中心 29 轮迭代都在 `2026-10-20-fun-calendar` 一份规格里。
- 推翻核心决策、整体替换方案 → **开新目录**，旧目录标"已退役"并指向新的，不删。范本：阅读 8 篇故事 → 70 篇短文（`2026-10-15-reading-70`）。这就是上面"前后两代需求各留各的目录"管的场景——代际替换，不是日常迭代。
- 同一需求的大期数（如星火 P1/P2/P3）→ 不算新需求，同目录加各自的 plan 文件，主文档更新。
- 纯修 bug → 不动需求文档，进 changelog/AGENTS；除非修复本身改变了规格行为。

**改原文档的三条纪律：**

1. **正文永远写"当前最新状态"**。不留"原来是 X，后来改成 Y"的叙事——那是修订记录的事。正文是规格，不是考古现场。
2. **修订记录追加一行**：日期 + 改了什么 + 为什么。历史可追溯，正文不膨胀。
3. **编号决策不可变**：需求/验收编号（D16、FR-11、#59、G34 这类）被代码注释和测试直接引用。被推翻的决策标"已被修订 N 取代"，**不删、不复用编号**，新决策续新号。

## changelog/（归档，不是需求）

`docs/changelog/` 放从 AGENTS.md 瘦身迁出的历史记录（2026-11-11 P2 起）：

- `agents-update-log.md`：AGENTS.md §10 的完整更新记录（2026-09-24 起）。**每次维护 AGENTS.md 时往这里追加一行**，AGENTS.md 里只留最近两条。
- `agents-round-history.md`：历史轮次实施记录（第十一~二十九轮、娱乐中心各轮与发布记录，重复段已去重）。长期有效的约定仍在 AGENTS.md §6/§7，查历史改动来这里。

这个目录不是需求目录，不走"一个需求一个目录"的编号规矩；docs/ 整体不进站点。

## 索引

| 目录 | 功能 | 状态 |
| --- | --- | --- |
| [2026-09-28-english-reading](./2026-09-28-english-reading/2026-09-28-english-reading.md) | 英语阅读（8 篇自写故事） | 已退役。当前阅读是 70 篇 |
| [2026-09-29-edgeone-sync](./2026-09-29-edgeone-sync/2026-09-29-edgeone-sync.md) | 云端同步 | 已落地 |
| [2026-09-29-apk-capacitor](./2026-09-29-apk-capacitor/2026-09-29-apk-capacitor.md) | 安卓壳（Capacitor） | 未采用。现网是 WebView 壳 |
| [2026-10-01-touch-timer-content](./2026-10-01-touch-timer-content/2026-10-01-touch-timer-content.md) | 触屏、计时与内容 | 已落地 |
| [2026-10-08-english-hub](./2026-10-08-english-hub/2026-10-08-english-hub.md) | 英语模块合并 | 已落地 |
| [2026-10-13-habit-checkin](./2026-10-13-habit-checkin/2026-10-13-habit-checkin.md) | 习惯打卡 | 已落地 |
| [2026-10-14-per-child-archive](./2026-10-14-per-child-archive/2026-10-14-per-child-archive.md) | 按孩子拆档 | 已落地 |
| [2026-10-14-spark-words](./2026-10-14-spark-words/2026-10-14-spark-words.md) | 星火词库 | 已落地。P4 多义词未做。转写底稿在 `files/spark-p3-transcript/`，`gen-wordbank-2000-ext.js` 读它 |
| [2026-10-15-reading-70](./2026-10-15-reading-70/2026-10-15-reading-70.md) | 英语阅读 70 篇 | 已落地。当前阅读以这份为准。抽取底稿在 `files/reading-70-transcript/`，`gen-reading-passages.js` 读它 |
| [2026-10-16-apk-publish](./2026-10-16-apk-publish/2026-10-16-apk-publish.md) | 安装包自动发布 | 已落地 |
| [2026-10-20-fun-calendar](./2026-10-20-fun-calendar/2026-10-20-fun-calendar.md) | 娱乐中心日历拼图 | 已落地。效果图在 `files/fun-center-mockup/` |
| [2026-10-26-pet-maze](./2026-10-26-pet-maze/2026-10-26-pet-maze.md) | 宠物迷宫 | 已落地（未发布/未打APK；暂停缩放修复与桌面沙箱验收通过，装扮视觉反馈仍待专项确认；见验收报告）。五主题五轮廓、30组≥40秒且旧参考±20秒；撤掉强制双环，41×41五不同轮廓。逐区域9–18格/深入5–10格/无岔路≤8格，困难组合允许1格余量，修真例外已逐项标注；A微缩模型、8格镜头/5格穿墙圆窗，未接入游戏 |
| [2026-11-11-hardening-infra-refactor](./2026-11-11-hardening-infra-refactor/2026-11-11-hardening-infra-refactor.md) | 安全加固 / 基建 / 结构重构（P0–P2）+ 规范批 | 已落地（工作区未发布）。决策 D1–D18；8 套回归全绿；wbcloud 备份 / QuizKit 抽取 / AGENTS<100KB / zs-* 重写另排 |