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>
3.1 KiB
3.1 KiB
API 合约草案
本文定义 MVP 后端 API 的目标形状。实现前可按任务细化，但不要在代码里另起一套不兼容的接口。
通用约定
- 传输：JSON over HTTPS。
- 鉴权：httpOnly Session Cookie。
- 未登录访问需要登录的接口时返回
401。 - 请求体和响应体均使用 UTF-8 JSON。
- 内容数据不通过数据库 API 管理；课程内容来自静态
episodes.json。
通用错误响应：
{
"error": {
"code": "unauthorized",
"message": "需要登录"
}
}
账号
POST /api/auth/register
注册账号并建立登录会话。
请求：
{
"email": "learner@example.com",
"password": "password"
}
成功响应：
{
"user": {
"id": 1,
"email": "learner@example.com"
}
}
POST /api/auth/login
登录并设置 httpOnly Session Cookie。
请求：
{
"email": "learner@example.com",
"password": "password"
}
成功响应同注册。
POST /api/auth/logout
清除当前会话。
成功响应：
{
"ok": true
}
GET /api/me
返回当前登录用户。
成功响应：
{
"user": {
"id": 1,
"email": "learner@example.com"
}
}
生词本
GET /api/vocab
返回当前用户的生词列表。
成功响应：
{
"items": [
{
"id": 1,
"course_id": "family-album",
"word": "excuse",
"episode_id": 1,
"act": 1,
"context_sentence": "Excuse me. My name is Richard Stewart.",
"created_at": "2026-06-21T10:00:00Z"
}
]
}
POST /api/vocab
添加一个生词。
请求：
{
"word": "excuse",
"episode_id": 1,
"act": 1,
"context_sentence": "Excuse me. My name is Richard Stewart."
}
说明：
course_id由服务端固定写入"family-album"。- MVP 不接词典，不要求释义字段。
成功响应返回新增项。
DELETE /api/vocab/{id}
删除当前用户自己的一个生词。
成功响应：
{
"ok": true
}
学习进度
GET /api/progress
返回当前用户全部学习进度。
成功响应：
{
"items": [
{
"course_id": "family-album",
"episode_id": 1,
"act": 1,
"last_position": 42.5,
"completed": false,
"updated_at": "2026-06-21T10:00:00Z"
}
]
}
PUT /api/progress
写入或更新某一幕的学习进度。
请求：
{
"episode_id": 1,
"act": 1,
"last_position": 42.5,
"completed": false
}
说明：
course_id由服务端固定写入"family-album"。- 定位维度是
episode_id + act，不是lesson_id。
成功响应返回更新后的进度项。
静态内容
课程内容和音频由静态路由提供：
GET /family-album/episodes.jsonGET /family-album/audio/u0101.mp3
服务端需要把 /family-album/audio/... 映射到磁盘 family-album-usa/audio/...。
待实现时确认
- 密码强度和错误文案。
- Session 存储方式和过期时间。
- 生词重复添加时返回已有项还是幂等更新。
- 进度上报频率由前端任务决定，API 保持幂等写入。