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>
51 lines
3.3 KiB
Markdown
51 lines
3.3 KiB
Markdown
# 技术栈（Tech Stack）
|
||
|
||
> "用什么"的统一速查表。选型与理由在此集中维护；"怎么把它们搭起来"见 [架构设计](04-architecture.md)。
|
||
> 当前 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 通道。
|
||
|
||
> 选型不臆造、未定先写入文档决策的纪律见 [编码规则](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` |
|
||
|
||
Windows PowerShell 等价命令：
|
||
|
||
```powershell
|
||
$env:GOOS='js'; $env:GOARCH='wasm'; go build -o app.wasm
|
||
go build
|
||
go vet ./...
|
||
python scripts/validate_episodes.py
|
||
```
|
||
|
||
> 实际目录布局、模块划分、数据模型见 [架构设计](04-architecture.md)；真实数据 schema 另见 `CLAUDE.md`。
|