# 技术栈（Tech Stack）

> "用什么"的统一速查表。选型与理由在此集中维护；"怎么把它们搭起来"见 [架构设计](04-architecture.md)。
> ⚠️ 标 **待定** 的项目尚未决策，**不要在代码里擅自选定**——先在此文档定下来再用。

## 一、技术栈一览

| 维度 | 选型 | 状态 | 理由 / 说明 |
| --- | --- | --- | --- |
| 前端框架 | 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 通道。

> 选型不臆造、未定先标待定的纪律见 [编码规则](05-coding-rules.md)；取舍方向见 [项目愿景](01-vision.md) 的"产品原则"。

## 三、构建与运行命令

| 用途 | 命令 |
| --- | --- |
| 构建前端（wasm） | `GOOS=js GOARCH=wasm go build -o app.wasm` |
| 构建 / 运行后端 | `go build` / `go run .` |
| 格式化 / 静态检查 | `gofmt -w .` · `go vet ./...` |
| 校验内容数据 | `python3 scripts/validate_episodes.py` |

> 实际目录布局、模块划分、数据模型见 [架构设计](04-architecture.md)；真实数据 schema 另见 `CLAUDE.md`。