docs: 新增任务看板(AI 的 Jira)并配置 .gitignore
- docs/06-tasks.md:MVP 拆为 22 个任务 / 7 个 Phase,带依赖与验收; 强制"一次只做一个任务、做完即停",避免一次生成整个项目 - CLAUDE.md:文档地图加入任务看板,并增加按看板单任务开发的规则 - .gitignore:忽略内容素材 family-album-usa/、Notion 导出 notion_docs/、 备份 *.bak、构建产物 *.wasm Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
+12
@@ -25,3 +25,15 @@ go.work.sum
|
|||||||
# env file
|
# env file
|
||||||
.env
|
.env
|
||||||
|
|
||||||
|
# 内容素材(含大体积音频,不纳入版本库;如需可改用 Git LFS / 对象存储)
|
||||||
|
/family-album-usa/
|
||||||
|
|
||||||
|
# Notion 原始导出(只读存档,不纳入版本库)
|
||||||
|
/notion_docs/
|
||||||
|
|
||||||
|
# 数据修正脚本生成的备份
|
||||||
|
*.bak
|
||||||
|
|
||||||
|
# 前端构建产物
|
||||||
|
*.wasm
|
||||||
|
|
||||||
|
|||||||
@@ -3,6 +3,8 @@
|
|||||||
> 给 AI 编程助手的项目上下文。先读本文件,再按需查 `docs/`。
|
> 给 AI 编程助手的项目上下文。先读本文件,再按需查 `docs/`。
|
||||||
>
|
>
|
||||||
> ⚠️ **写任何代码前,必须先读完 [`docs/05-coding-rules.md`](docs/05-coding-rules.md)(编码规则)。** 这是保证代码不跑偏、质量稳定的硬约束。
|
> ⚠️ **写任何代码前,必须先读完 [`docs/05-coding-rules.md`](docs/05-coding-rules.md)(编码规则)。** 这是保证代码不跑偏、质量稳定的硬约束。
|
||||||
|
>
|
||||||
|
> 🧭 **按 [`docs/06-tasks.md`](docs/06-tasks.md) 任务看板开发:每轮只领取并完成一个任务(依赖已 DONE 的最靠前 TODO),做完即停、汇报、等指令——不要一次生成整个项目。**
|
||||||
|
|
||||||
## 一句话
|
## 一句话
|
||||||
|
|
||||||
@@ -20,6 +22,7 @@
|
|||||||
| [`docs/03-tech-stack.md`](docs/03-tech-stack.md) | **用什么**:框架 / 数据库 / UI / 状态管理 / 部署(速查,含待定项) | 想知道某层用哪个技术 |
|
| [`docs/03-tech-stack.md`](docs/03-tech-stack.md) | **用什么**:框架 / 数据库 / UI / 状态管理 / 部署(速查,含待定项) | 想知道某层用哪个技术 |
|
||||||
| [`docs/04-architecture.md`](docs/04-architecture.md) | **怎么搭**:系统结构、职责划分、**数据模型**、技术难点 | 实际写代码、查数据结构与字段 |
|
| [`docs/04-architecture.md`](docs/04-architecture.md) | **怎么搭**:系统结构、职责划分、**数据模型**、技术难点 | 实际写代码、查数据结构与字段 |
|
||||||
| [`docs/05-coding-rules.md`](docs/05-coding-rules.md) | **编码规则**:写代码的硬约束与"完成"的定义 | ⚠️ 动手写代码**之前**必读 |
|
| [`docs/05-coding-rules.md`](docs/05-coding-rules.md) | **编码规则**:写代码的硬约束与"完成"的定义 | ⚠️ 动手写代码**之前**必读 |
|
||||||
|
| [`docs/06-tasks.md`](docs/06-tasks.md) | **任务看板**(AI 的 Jira):MVP 拆解、依赖、状态 | 决定"这次做什么"时 |
|
||||||
|
|
||||||
> 写代码前的判断链路:`vision`(方向对不对)→ `requirements`(要做成什么样、怎么算对)→ `tech-stack`(用什么)→ `architecture` + 本文件(怎么搭、查字段)→ `coding-rules`(怎么写)。
|
> 写代码前的判断链路:`vision`(方向对不对)→ `requirements`(要做成什么样、怎么算对)→ `tech-stack`(用什么)→ `architecture` + 本文件(怎么搭、查字段)→ `coding-rules`(怎么写)。
|
||||||
>
|
>
|
||||||
|
|||||||
@@ -0,0 +1,103 @@
|
|||||||
|
# 任务看板(Tasks · AI 的 Jira)
|
||||||
|
|
||||||
|
> 把 MVP 拆成**小步、可独立交付**的任务,让 AI **一步一步**开发,**避免一次生成整个项目**。
|
||||||
|
|
||||||
|
## ⛔ 使用规则(最重要,必须遵守)
|
||||||
|
|
||||||
|
1. **一次只做一个任务**:每轮只领取**一个**状态为 `TODO`、且其**依赖均已 `DONE`** 的任务——取最靠前的那个。
|
||||||
|
2. **做完即停**:完成该任务、自测通过其"验收"、把状态改成 `DONE` 后,**停下来汇报**,等待下一步指令。**不要**顺手往下做后续任务,**不要**一次铺开多个任务。
|
||||||
|
3. **不跳步**:依赖未 `DONE` 的任务不能开工;如果发现顺序不合理,先提出来,别擅自重排。
|
||||||
|
4. **完成的定义**:以 [编码规则](05-coding-rules.md) 第 8 节"改完之前"清单为准(能构建、过校验、对得上验收、文档同步、如实汇报)。
|
||||||
|
5. **动手前**先读 `CLAUDE.md` 与 [编码规则](05-coding-rules.md);范围以 [需求](02-requirements.md)、做法以 [技术栈](03-tech-stack.md) + [架构设计](04-architecture.md) 为准。
|
||||||
|
|
||||||
|
## 状态图例
|
||||||
|
|
||||||
|
`TODO` 待开始 · `DOING` 进行中(同一时间最多 1 个)· `DONE` 已完成并验收 · `BLOCKED` 受阻(注明原因)
|
||||||
|
|
||||||
|
> 改状态时直接编辑本文件对应行。`DOING` 全局只允许有一个。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 0 · 地基(必须最先完成)
|
||||||
|
|
||||||
|
先有最小可运行骨架,才能在上面验证最难的字幕同步。
|
||||||
|
|
||||||
|
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| T-001 | 初始化 go 模块 + go-app 最小可运行页面 | — | `go.mod` 就位;`GOOS=js GOARCH=wasm go build` 通过;浏览器打开能看到一个最简页面 | TODO |
|
||||||
|
| T-002 | 后端静态服务 + **音频路径映射** | T-001 | 访问 `/family-album/audio/u0101.mp3` 能播到磁盘 `family-album-usa/audio/u0101.mp3`;wasm/静态资源正常加载 | TODO |
|
||||||
|
| T-003 | 加载并解析 `episodes.json` 为 Go 结构体 | T-001 | struct 与真实 schema 一致(line 仅 `{t,en}`,无 zh);启动时成功载入 26 集;前端可拿到课程数据 | TODO |
|
||||||
|
|
||||||
|
> T-003 范围:只做数据加载与类型定义,**不做** UI 渲染(那是 Phase 2)。
|
||||||
|
|
||||||
|
## Phase 1 · 核心验证:字幕同步原型(最难,先攻)
|
||||||
|
|
||||||
|
先用**写死的一幕**把同步跑通,验证可行性,再谈页面。
|
||||||
|
|
||||||
|
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| T-101 | 单幕音频播放器组件(播放/暂停/拖动) | T-002, T-003 | 选一个有音频的 act(如 ep1 act1),能播放、暂停、拖动进度 | TODO |
|
||||||
|
| T-102 | 字幕逐句渲染 + 当前句高亮 | T-101 | 播放时高亮句与人耳听到的一致;定位用 `currentTime` 在 `lines[].t` 上**二分查找** | TODO |
|
||||||
|
| T-103 | 点句跳转 | T-102 | 点任一句,音频在约 1 秒内 seek 到该句 `t` 开头并继续播放 | TODO |
|
||||||
|
| T-104 | 容错:非单调时间戳 / 无音频降级 | T-103 | 时间戳乱序/相等不崩(已知 ep18/ep25);`hasAudio=false` 的 act 只显示文本并标注无音频 | TODO |
|
||||||
|
|
||||||
|
> 对应需求验收:02-requirements 第五节"逐句同步"。这是 P0 核心,务必先单独跑通。
|
||||||
|
|
||||||
|
## Phase 2 · 课程列表 + 播放页
|
||||||
|
|
||||||
|
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| T-201 | 课程列表页(读 episodes.json 渲染) | T-003 | 列出 26 集 / 各幕;标出哪些幕有音频;移动优先布局 | TODO |
|
||||||
|
| T-202 | 路由:列表 → 选集选幕 → 播放页 | T-201 | 点列表项进入对应播放页,可返回 | TODO |
|
||||||
|
| T-203 | 播放页接入 Phase 1 同步组件 | T-202, T-104 | 任选有音频的幕,播放 + 逐句同步 + 点句跳转全部可用 | TODO |
|
||||||
|
|
||||||
|
## Phase 3 · 后端账号体系(Session Cookie)
|
||||||
|
|
||||||
|
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| T-301 | SQLite 初始化 + 建表(users/progress/vocab) | T-002 | 按 04-architecture 第 3.2 节建表;首次启动自动建库 | TODO |
|
||||||
|
| T-302 | 注册 / 登录 API + httpOnly Session Cookie | T-301 | 注册、登录成功后下发 httpOnly cookie;带 cookie 的请求能识别用户;登出失效 | TODO |
|
||||||
|
| T-303 | 前端登录 / 注册界面 + 登录态 | T-302 | 能注册登录;刷新后保持登录;未登录访问需登录的页面会被引导登录 | TODO |
|
||||||
|
|
||||||
|
## Phase 4 · 生词本
|
||||||
|
|
||||||
|
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| T-401 | 生词本 API(增 / 删 / 查) | T-302 | 登录用户可增删查自己的生词;按 `episode_id+act` 记录出处 | TODO |
|
||||||
|
| T-402 | 点词加入生词本(播放页交互) | T-401, T-203 | 在字幕里点单词即可加入;有反馈 | TODO |
|
||||||
|
| T-403 | 生词本列表页 | T-401 | 查看自己的生词列表;刷新/重进仍在 | TODO |
|
||||||
|
|
||||||
|
> 对应需求验收:02-requirements 第五节"生词本"。MVP 只存单词,不接词典释义。
|
||||||
|
|
||||||
|
## Phase 5 · 进度同步
|
||||||
|
|
||||||
|
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| T-501 | 进度 API(读写 last_position / completed) | T-302 | 按用户 + `episode_id+act` 读写播放进度 | TODO |
|
||||||
|
| T-502 | 播放时上报进度 + 列表显示进度 | T-501, T-203, T-201 | 播放中断点被记录;课程列表显示学习进度(如"2/3 幕") | TODO |
|
||||||
|
| T-503 | 跨设备验证 | T-502 | A 设备学习后,B 设备登录同账号看到相同进度与生词本 | TODO |
|
||||||
|
|
||||||
|
> 对应需求验收:02-requirements 第五节"账号与同步"。
|
||||||
|
|
||||||
|
## Phase 6 · PWA 离线化
|
||||||
|
|
||||||
|
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| T-601 | PWA manifest + 可安装 | T-203 | 可安装到手机主屏,有图标与名称 | TODO |
|
||||||
|
| T-602 | Service Worker 缓存 app shell | T-601 | 二次访问离线也能打开界面 | TODO |
|
||||||
|
| T-603 | 离线缓存音频与文稿 + 离线可用验证 | T-602 | 断网后能打开**已学过**的课程并播放 | TODO |
|
||||||
|
|
||||||
|
> 对应需求验收:02-requirements 第五节"离线可用"。MVP 内容锁定 **ep1–17**(ep18–26 缺音频,见 02-requirements / 数据校验)。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 里程碑
|
||||||
|
|
||||||
|
- **M1 · 同步可行性**:Phase 0 + Phase 1 完成 → 字幕同步原型跑通(最高风险解除)
|
||||||
|
- **M2 · 可用闭环**:+ Phase 2/3/4/5 → 列表/播放/账号/生词/进度的最小闭环
|
||||||
|
- **M3 · MVP 达成**:+ Phase 6 → 可安装、离线可用,对齐 02-requirements 全部 P0 验收
|
||||||
|
|
||||||
|
## 待办池(Backlog · V2+,暂不排期)
|
||||||
|
|
||||||
|
复读/精听(AB 复读、变速)、测验、学习打卡、激励模块、多教材扩展、中英对照、生词 SRS。
|
||||||
|
(来源见 02-requirements"后续迭代";**MVP 阶段一律不做**。)
|
||||||
Reference in New Issue
Block a user