ilaandClaude Opus 4.8
fd37ff6383
- docs/01-vision 核心目标、目标用户、产品原则、非目标 - docs/02-requirements 产品语言需求 + MVP 验收标准（无技术词） - docs/03-tech-stack go-app / 纯CSS / SQLite / Session Cookie / 单二进制部署 - docs/04-architecture 系统结构、前后端职责、真实 episodes.json 数据模型、技术难点 - docs/05-coding-rules AI 写代码前必读的硬约束（防跑偏） - CLAUDE.md AI 入口：文档地图、真实数据 schema、强制必读编码规则 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
3.1 KiB
3.1 KiB
技术栈（Tech Stack）
"用什么"的统一速查表。选型与理由在此集中维护；"怎么把它们搭起来"见 架构设计。 ⚠️ 标 待定 的项目尚未决策，不要在代码里擅自选定——先在此文档定下来再用。
一、技术栈一览
| 维度 | 选型 | 状态 | 理由 / 说明 |
|---|---|---|---|
| 前端框架 | 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 |
实际目录布局、模块划分、数据模型见 架构设计；真实数据 schema 另见
CLAUDE.md。