ballet-server/README.md

# Ballet Island

同一 Git 仓库中的两个独立项目，分别安装依赖、运行与构建。第一期提供课后练习登记、日历回看、成长统计和练习项目管理，通过微信身份关联 PostgreSQL 中的个人数据。

## 目录

```text
miniprogram/              Taro 4.2.1 + React 18 + TypeScript + Taroify 1.0.6
  src/                    小程序源码
  config/                 小程序构建配置
  package.json            小程序依赖与命令
  pnpm-lock.yaml          小程序依赖锁文件
  node_modules/           小程序本地依赖（不提交）
  .nvmrc                  Node 版本
backend/                  Go 1.26 + PostgreSQL 18
  cmd/server/             服务入口、数据库连接与优雅退出
  internal/httpapi/       HTTP 路由与测试
  internal/identity/      微信身份核验适配器
  internal/practice/      会话、项目、记录与回顾业务
  internal/database/      内嵌版本迁移
  go.mod / go.sum         Go 模块与依赖
  Dockerfile              后端镜像构建
  compose.yaml            API 与数据库编排
  compose.prod.yaml       Gitea 生产部署编排
  DEPLOYMENT.md           生产部署与回退说明
  .env.example            后端环境变量示例
  scripts/dev.sh          本机 Go 开发启动脚本
```

小程序的 Node、pnpm 配置和依赖均位于 `miniprogram/`。后端通过 Go、Docker 和 shell 独立运行。根目录保留 Git、说明文档和通用仓库约定。

## 小程序开发

需要 Node.js 22.12+（`miniprogram/.nvmrc` 指定 22.22.1）、pnpm 9.15.0，以及具有该小程序开发权限的微信开发者工具。

从仓库根目录进入小程序项目：

```sh
cd miniprogram
pnpm install --frozen-lockfile
pnpm dev
```

微信开发者工具导入 `miniprogram/`，AppID 为 `wx6dfbf1021db8aee0`，编译目录为 `dist/`。底部入口为“记录、成长、我的”，日历从记录页进入。“我的”可由用户选择微信头像和昵称，仅保存在本机。首次请求通过 `Taro.login` 取得 code，在后端核验后建立业务会话；登录失败或网络失败会显示重试入口，不会当作空记录。

默认 API 为 `http://127.0.0.1:8080`。使用本地 HTTP 地址时，在开发者工具的本地设置中开启“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”，仅用于本地调试。真机需使用能够访问的接口地址，并按微信要求配置域名。

在 `miniprogram/` 中通过构建时环境变量指定接口地址，修改后重启构建：

```sh
TARO_APP_API_BASE_URL=https://api.example.com pnpm dev
TARO_APP_API_BASE_URL=https://api.example.com pnpm build
```

`TARO_APP_API_BASE_URL` 是公开接口地址，不自动读取后端 `.env`；未设置时使用本机默认地址。

首次登录原子创建八个可编辑项目，练习数据从零开始。表单支持补记、更正和误记删除；项目改名同步显示于历史，有记录的项目移除时归档。近期列表按最后登记或更正时间排序，使刚保存的补记也能立即看到；日历和统计使用实际练习日期，统一按 Asia/Shanghai 解释，周一开始一周。

项目名最多 40 个 Unicode 字符，笔记最多 2000 个字符；前后端使用相同校验。分钟为正整数，按 PostgreSQL integer 存储范围上限为 2147483647。笔记只作为普通文本显示。每次主动新增生成独立提交标识；结果未确认时保留该标识与完整输入，重试不重复累计。首期不提供离线保存队列。

项目可选 18 个内置图标（基础练习 6、专业动作 8、物件 4），也可选择无图标。添加或编辑时与名称一并保存，首页和管理页展示。SVG 原稿位于 `docs/design/project-icons/`，小程序包内使用对应的透明 PNG。后端迁移 002 为已有同名预置项目一次性配图；之后改名、重新登录和服务重启均不重置用户选择。更新小程序前先更新后端，使接口支持 `iconId`。

## 后端开发

需要 Go 1.26 或更高版本，以及 Docker Compose。仅使用 Docker 运行后端时无需本机 Go。

另开终端，从仓库根目录进入后端项目：

```sh
cd backend
test -f .env || cp .env.example .env
docker compose up -d --wait postgres
./scripts/dev.sh
```

`backend/.env` 已被 Git 忽略。启动脚本读取其中的 PostgreSQL 标准 `PG*` 变量与 `HTTP_ADDR`，先构建再启动 Go 服务；修改代码后需重启命令。脚本只应读取可信的本地配置，`.env` 使用 shell 赋值语法，含空格或 `$` 等特殊字符的值须用单引号包裹。直接运行 Go 或二进制时需自行注入环境变量。

后端全程无需 Node.js 或 pnpm。

在可信的 `backend/.env` 中设置 `WECHAT_APP_ID` 和 `WECHAT_APP_SECRET`，AppID 必须与小程序一致。AppSecret 只存在于服务端配置中，不能放入小程序源码或构建变量。通过[微信官方 code2Session 接口](https://developers.weixin.qq.com/miniprogram/dev/server/API/user-login/api_code2session.html)核验身份，不接受客户端自报的用户标识；业务会话为随机 bearer token，有效期 30 天，数据库只存 token 摘要，过期后小程序自动重新登录一次。

服务启动会在一个带锁的事务中运行尚未应用的版本迁移，初始化用户、会话、项目、练习和幂等回执表。后续启动不会重置数据或补回已移除项目。迁移文件位于 `backend/internal/database/`，已经应用的迁移应保留不改，通过新增版本演进结构。没有微信凭据时健康检查仍可运行，登录返回 503；配置缺失不提供模拟身份或开发后门。

## Docker 运行与部署

以下本地默认 Compose 命令在 `backend/` 中执行：

```sh
docker compose up -d --build --wait
curl http://127.0.0.1:8080/healthz
curl http://127.0.0.1:8080/readyz
docker compose logs -f
docker compose down
```

Compose 等待数据库健康后启动 API，并等待两个服务就绪。API 容器使用非 root 用户；数据库写入命名卷，`docker compose down` 保留数据。Compose 项目名固定为 `ballet-island`，沿用现有数据库卷。

默认仅向宿主机回环地址开放 API 和数据库。部署到服务器时，可让 HTTPS 反向代理连接 `127.0.0.1:${API_PORT}`；如确需其他机器直接访问 API，可在 `backend/.env` 调整 `API_BIND`。数据库端口始终只绑定本机。Compose 内部使用 `PGHOST=postgres`、`PGPORT=5432`，宿主机数据库端口由 `.env` 的 `PGPORT` 控制。

`API_PORT` 控制 Docker API 的宿主机端口，`HTTP_ADDR` 控制本机 Go 服务的监听地址；修改后应同步小程序的 API 地址。本机 Go 服务与 Docker API 不应同时占用同一端口。

正式上线需配置 HTTPS、微信 request 合法域名、数据库连接密钥与备份。小程序由微信开发者工具发布；生产 Docker Compose 只部署后端 API，连接已有 PostgreSQL 服务器。

使用 Gitea Actions 在目标 Docker 主机部署时，按 [生产部署说明](backend/DEPLOYMENT.md) 配置 Runner、仓库密钥与反向代理；工作流位于 `.gitea/workflows/deploy-backend.yaml`。
生产数据库连接使用单个 `DATABASE_URL` 密钥；本地开发仍使用 `backend/.env` 中的 `PG*` 变量。

PostgreSQL 18 数据卷按[官方镜像说明](https://hub.docker.com/_/postgres)挂载到 `/var/lib/postgresql`。已有数据库卷的密码不会因修改 `.env` 自动更新；需按数据库流程修改，不要为更新密码删除数据卷。

## 验证与构建

在 `miniprogram/` 中：

```sh
pnpm typecheck
pnpm test:client
pnpm build
```

在 `backend/` 中：

```sh
go vet ./...
go test -race ./...
go build -o bin/api ./cmd/server

# 真实 PostgreSQL 18 HTTP 集成验证，自动创建和清理临时测试容器。
./scripts/test-integration.sh
```

集成脚本只使用独立、内存存储的 PostgreSQL 容器，不读取业务 `.env`，不挂载 Compose 数据卷。每个用例创建自己的 schema 并在结束后清理。已有独立测试数据库时可通过 `TEST_DATABASE_URL` 指定（用户须有创建 schema 的权限）；`REQUIRE_TEST_DATABASE=1` 可让缺少配置直接失败。单独执行 `go test` 而未提供测试数据库时，会明确跳过数据库集成用例，不能据此宣称业务集成通过。

集成测试经过真实 HTTP handler、业务会话和 PostgreSQL，仅在微信网络核验处使用受控响应，覆盖首次初始化、重复登录、身份隔离、归档与更正、分钟汇总、周/月边界、分页、提交重试和并发。`pnpm test:client` 使用 Node 内置测试工具验证请求层重新登录、待确认输入与提交标识保留、失败反馈和成功写入通知；只替换 Taro 网络与本地存储调用，不引入小程序端到端框架。

保存未确认时不能通过表单取消；系统返回会提示，待确认输入只在当前小程序进程内暂存，再次登记会恢复原提交。完全退出小程序会失去该临时表单，重新进入后应先查看云端历史；这不提供离线队列或进程重启后的草稿持久化。微信开发者工具中的键盘/滚动/窄屏表现、真实微信首次登录、跨设备恢复及断网流程仍需独立验收，构建和模拟微信响应均不能替代这些验证。

产物分别在 `miniprogram/dist/` 和 `backend/bin/api`，均不进入版本控制。

| 接口 | 用途 | 响应 |
| --- | --- | --- |
| `GET /healthz` | HTTP 服务存活检查 | `200 {"status":"ok"}` |
| `GET /readyz` | 实际检查 PostgreSQL 连接 | 可用时 200，不可用时 `503 {"status":"unavailable"}` |
| `POST /v1/session` | 微信 code 换业务会话 | `{token, expiresAt}` |
| `GET /v1/projects` | 活跃项目；`includeArchived=true` 包含归档 | `{projects, today}` |
| `PUT /v1/projects/order` | 按完整活跃项目 ID 列表保存显示顺序，JSON `{projectIds: string[]}` | `{action: "reordered"}` |
| `POST /v1/projects` / `PUT /v1/projects/{id}` | 新增 / 编辑，JSON `{name, iconId?}`；空字符串取消图标，省略保留现有图标 | 最新项目（含 `iconId`） |
| `DELETE /v1/projects/{id}` | 删除未使用项目或归档 | `{action: "deleted" / "archived"}` |
| `GET /v1/records` | `from` / `to` 日期范围、`limit`（1–100，默认20）、`cursor` | `{records, nextCursor}` |
| `GET /v1/records/{id}` | 读取本人单条记录 | 项目当前名称、日期、分钟、笔记 |
| `POST /v1/records` / `PUT /v1/records/{id}` | 新增 / 更正 | `{projectId, date, minutes, note}`；新增另需 `requestId`（16–128位字母、数字、下划线或短横线） |
| `DELETE /v1/records/{id}` | 删除误记，可安全重试 | `{action: "deleted"}` |
| `GET /v1/review?period=week&date=YYYY-MM-DD` | `week` / `month`，日期默认业务今天 | 累计、选定周期、每日分钟与项目分布 |

除会话交换和健康检查外，接口均需 `Authorization: Bearer <token>`。失败以 `{error:{code,message}}` 返回：401 重新登录、400 输入无效、404 对象不可用、409 归档项目或提交内容冲突、410 已删除记录的旧提交、503 暂时性失败。错误响应不返回数据库细节、微信密钥或其他用户的数据。移除/记录写入在用户范围内串行化，防止并发删除项目损坏历史。

Go 服务启动时检查数据库连接，收到 `SIGINT` / `SIGTERM` 时停止接收请求并关闭连接池。