ilaandClaude Opus 4.8
b9bcbf7e6b
新增（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>
2.5 KiB
2.5 KiB
路由与页面结构
本文约定 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 的待确认项做决策。