ballet-server/README.md

Ballet Island

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

目录

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，以及具有该小程序开发权限的微信开发者工具。

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

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/ 中通过构建时环境变量指定接口地址，修改后重启构建：

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。

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

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 接口核验身份，不接受客户端自报的用户标识；业务会话为随机 bearer token，有效期 30 天，数据库只存 token 摘要，过期后小程序自动重新登录一次。

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

Docker 运行与部署

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

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 主机部署时，按 生产部署说明 配置 Runner、仓库密钥与反向代理；工作流位于 .gitea/workflows/deploy-backend.yaml。 生产数据库连接使用单个 DATABASE_URL 密钥；本地开发仍使用 backend/.env 中的 PG* 变量。

PostgreSQL 18 数据卷按官方镜像说明挂载到 /var/lib/postgresql。已有数据库卷的密码不会因修改 .env 自动更新；需按数据库流程修改，不要为更新密码删除数据卷。

验证与构建

在 miniprogram/ 中：

pnpm typecheck
pnpm test:client
pnpm build

在 backend/ 中：

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 时停止接收请求并关闭连接池。