feat: initialize Ballet Island 微信小程序 with basic structure and functionality

- Add project configuration for WeChat mini program. - Create skills lock file for Taroify integration. - Set up app configuration and styles. - Implement main app component and index page with welcome message. - Add health check service to verify backend readiness. - Configure TypeScript settings and global types.
2026-09-28 13:41:48 +08:00
commit 4b42b55928
32 changed files with 12054 additions and 0 deletions
@@ -0,0 +1,116 @@
+# 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` 时停止接收请求并关闭连接池。