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.3 KiB
3.3 KiB
技术栈（Tech Stack）
"用什么"的统一速查表。选型与理由在此集中维护；"怎么把它们搭起来"见 架构设计。 当前 MVP 技术栈已全部定稿。若未来新增待定项，先在本文决策，再进入代码。
一、技术栈一览
| 维度 | 选型 | 状态 | 理由 / 说明 |
|---|---|---|---|
| 前端框架 | go-app (Go → WebAssembly) | ✅ 已定 | 纯 Go 写全栈，组件化 PWA，可安装 / 离线 |
| UI 样式方案 | 纯 CSS 文件（移动优先） | ✅ 已定 | 经 Handler.Styles 引入；零构建、全控制、可随 PWA 离线缓存。设计 token 用 CSS 变量 |
| 状态管理 | go-app 原生 | ✅ 已定 | 组件局部状态 + ctx.SetState/ObserveState 全局观察者（当前播放句 / 生词本 / 登录态），零依赖、控 wasm 体积。不够再议 |
| 后端 | Go net/http 标准库 |
✅ 已定 | 最轻、依赖少、好维护 |
| 数据库 | SQLite | ✅ 已定 | 起步足够、零运维，后续可换 Postgres |
| 鉴权方式 | httpOnly Session Cookie | ✅ 已定 | 服务端会话，cookie 不暴露给 JS、抗 XSS；登出简单。跨设备同步靠后端，与鉴权方式无关 |
| 音频控制 | 浏览器 Audio API（经 syscall/js） |
✅ 已定 | go-app 通过 JS 互操作调用 |
| 离线 / 安装 | PWA manifest + Service Worker | ✅ 已定 | 可安装到主屏、缓存音频与文稿 |
| 部署方式 | 单 Go 二进制自托管 | ✅ 已定 | 一个二进制供 wasm + 静态 + 音频 + API，运维最省，与 SQLite"零运维"一致；前置反代上 TLS。带宽吃紧后再把音频外挂 CDN / 对象存储 |
| 参考实现 | go-app 官方 examples、lofimusic | ✅ 参考 | 前者提供骨架；后者参考播放器组织（但它无"按时间戳同步字幕"逻辑，需自写） |
二、决策记录与后续可能的演进
MVP 的技术栈已全部敲定（上表均为 ✅）。以下是几条"现在这么选、将来可能调整"的备注：
- 状态管理：先用 go-app 原生；若跨组件状态变复杂（如全局播放器 + 多页联动），再评估抽一层轻量 store，但不提前引第三方库。
- 数据库：SQLite 起步；用户量 / 并发上来后可平滑迁 Postgres（表结构保持兼容）。
- 音频分发：MVP 由单二进制直接提供；带宽吃紧后把
audio/外挂到对象存储 / CDN，仅改静态资源路由。 - 鉴权：Session Cookie 起步；若将来要做第三方客户端 / 开放 API，再考虑补 JWT 通道。
三、构建与运行命令
| 用途 | 命令 |
|---|---|
| 构建前端（wasm） | GOOS=js GOARCH=wasm go build -o app.wasm |
| 构建 / 运行后端 | go build / go run . |
| 格式化 / 静态检查 | gofmt -w . · go vet ./... |
| 校验内容数据 | python3 scripts/validate_episodes.py |
Windows PowerShell 等价命令：
$env:GOOS='js'; $env:GOARCH='wasm'; go build -o app.wasm
go build
go vet ./...
python scripts/validate_episodes.py
实际目录布局、模块划分、数据模型见 架构设计；真实数据 schema 另见
CLAUDE.md。