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
+78
View File
@@ -0,0 +1,78 @@
# 路由与页面结构
> 本文约定 MVP 的前端页面路由和组件归属。具体 go-app 写法以实现时的代码结构为准。
## 页面路由
| 路由 | 页面 | MVP 说明 |
| --- | --- | --- |
| `/` | 课程列表页 | 默认首页,展示 26 集和各幕状态 |
| `/episode/{episode_id}/act/{act}` | 播放页 | 播放某一集某一幕,支持字幕同步和点句跳转 |
| `/vocab` | 生词本页 | 登录后查看个人生词 |
| `/login` | 登录页 | 登录入口 |
| `/register` | 注册页 | 注册入口 |
后续如果 go-app 路由实现需要 hash 路由,语义仍保持一致。
## 页面职责
### 课程列表页
读取 `episodes.json` 渲染:
- 26 集课程。
- 每集下的 act。
- 是否有音频。
- 后续接入进度后显示学习进度。
视觉参考:`design_mockups/list.html`。
### 播放页
根据 URL 参数定位 `episode_id + act`:
- 有音频时显示播放器、字幕列表、当前句高亮。
- 点击字幕句子时 seek 到该句 `t`。
- 无音频时优雅降级,只显示文本和无音频提示。
- 后续接入生词本后支持点词加入。
- 后续接入进度后读写 `last_position`。
视觉参考:`design_mockups/play.html`。
### 生词本页
通过 `GET /api/vocab` 获取当前登录用户生词:
- 展示单词。
- 展示来源:episode、act、上下文句子。
- 支持删除。
MVP 不展示词典释义。
### 登录 / 注册页
通过账号 API 建立 httpOnly Session Cookie:
- 登录成功后返回原目标页或首页。
- 未登录访问需要账号的页面时,引导登录。
## 组件建议
| 组件 | 归属 | 说明 |
| --- | --- | --- |
| `EpisodeList` | 课程列表页 | 渲染 episode 和 act 列表 |
| `AudioPlayer` | 播放页 | 封装浏览器 Audio API 互操作 |
| `TranscriptView` | 播放页 | 渲染字幕、当前句高亮、点句跳转 |
| `VocabList` | 生词本页 | 渲染当前用户生词 |
| `AuthForm` | 登录 / 注册页 | 复用账号表单 |
`AudioPlayer` 和 `TranscriptView` 是后续多教材可复用的核心组件,但 MVP 不提前实现多教材逻辑。
## 导航规则
- 首页进入播放页:点击某一幕。
- 播放页返回首页:保留简单返回入口。
- 生词本入口:可以放在全局导航或列表页顶部。
- 未登录时:课程内容可否浏览仍待产品确认;需要账号数据的生词本和进度接口必须登录。
如果游客浏览策略未确认,实现账号相关任务前先回到 [`02-requirements.md`](02-requirements.md) 的待确认项做决策。