# Ballet Island

同一 Git 仓库中的两个独立项目，分别安装依赖、运行与构建。当前提供项目骨架、欢迎页和服务健康检查，业务需求后续补充。

## 目录

```text
miniprogram/              Taro 4.2.1 + React 18 + TypeScript + Taroify 1.0.6
  src/                    小程序源码
  config/                 小程序构建配置
  package.json            小程序依赖与命令
  pnpm-lock.yaml          小程序依赖锁文件
  node_modules/           小程序本地依赖（不提交）
  .nvmrc                  Node 版本
  .agents/skills/taroify/  Taroify Agent Skill
backend/                  Go 1.26 + PostgreSQL 18
  cmd/server/             服务入口、数据库连接与优雅退出
  internal/httpapi/       HTTP 路由与测试
  go.mod / go.sum         Go 模块与依赖
  Dockerfile              后端镜像构建
  compose.yaml            API 与数据库编排
  .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/`。首页“检查连接”请求后端 `/readyz`，同时检查数据库是否可用。

默认 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`；未设置时使用本机默认地址。

## 后端开发

需要 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。

## Docker 运行与部署

以下命令在 `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 部署后端和数据库。

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

## 验证与构建

在 `miniprogram/` 中：

```sh
pnpm typecheck
pnpm build
```

在 `backend/` 中：

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

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

| 接口 | 用途 | 响应 |
| --- | --- | --- |
| `GET /healthz` | HTTP 服务存活检查 | `200 {"status":"ok"}` |
| `GET /readyz` | 实际检查 PostgreSQL 连接 | 可用时 200，不可用时 `503 {"status":"unavailable"}` |

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