docs: 补全 AI 入口/API/路由/现状文档并对齐一致性

新增(Codex 起草,本次纳入并校对):
- AGENTS.md:仓库级 AI 强约束入口
- docs/00-ai-start-here.md:AI 开发入口与导航
- docs/api.md:账号/生词本/进度 API 合约草案
- docs/routes.md:go-app 页面路由与组件归属
- docs/current-state.md:当前实现状态

补充与对齐:
- 验证命令补 bash(WSL/Linux 为主,PowerShell 为备):00-ai-start-here、AGENTS
- 04-architecture:新增第六节"项目结构(包布局)"+ 3.2 建表 SQL 草案
- docs/README 导航补 06-tasks;CLAUDE 目录树补 AGENTS/scripts/design_mockups
- 00-ai-start-here 去除已过时的"需要补齐"段
- 06-tasks:Phase 2/3/4/5 交叉引用 api.md / routes.md / 包布局

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
ila
2026-06-21 19:30:14 +08:00
co-authored by Claude Opus 4.8
parent 39713eb8ac
commit b9bcbf7e6b
11 changed files with 710 additions and 13 deletions
+12 -1
View File
@@ -38,7 +38,7 @@
## 4. 架构纪律
- **技术栈固定**:以 [技术栈](03-tech-stack.md) 为准(前端 go-app、后端 `net/http`、数据库 SQLite)。要加任何第三方依赖,**先说明理由并征求同意**。
- **标"待定"的栈项不要擅自选定**(UI 样式 / 状态管理 / 鉴权方式 / 部署)——先在 tech-stack 文档定下来再用,别在代码里替项目拍板。
- **技术栈以 [技术栈](03-tech-stack.md) 为准**。若未来新增标"待定"的栈项,不要在代码里擅自选定;先在文档中决策,再实现。
- **内容数据 vs 用户数据分清**:教材内容(episodes.json)前端直接读、**不入库**;SQLite **只存**用户态(users / progress / vocab)。别把课程内容写进数据库。
- 把浏览器互操作(`syscall/js`、Audio API)**封装成可复用组件**,不要散落在各处业务代码里。
- 进度 / 生词本的字段以 [架构设计](04-architecture.md) 第 3.2 节为准(按 `episode_id + act` 定位,不是抽象 lesson_id)。
@@ -75,6 +75,17 @@
- [ ] 涉及数据结构变化的,文档(tech-stack / architecture / CLAUDE.md)已同步
- [ ] 如实汇报:跑了什么、结果如何;测试失败就说失败,别粉饰
Windows PowerShell 常用验证命令:
```powershell
$env:GOOS='js'; $env:GOARCH='wasm'; go build -o app.wasm
go build
go vet ./...
python scripts/validate_episodes.py
```
`validate_episodes.py` 仅在改动内容数据或 schema 时必跑。
## 9. 绝不
- 绝不把密钥 / token 写进代码或提交(用环境变量 / 配置)。