feat: add growth tracking page and related functionality
- Implemented a new Growth page to track practice time and trends. - Added API integration for fetching review data. - Created components for displaying practice statistics and trends. - Updated navigation titles for the main index and growth pages. - Removed unused styles from the index page. - Introduced a Projects management page for adding and editing practice projects. - Developed a Record form for logging practice sessions with validation. - Added utility functions for date manipulation and duration formatting. - Implemented error handling and session management in the practice service. - Created unit tests for the practice service to ensure reliability.
This commit is contained in:
yuxuanhui
@@ -1,6 +1,6 @@
|
||||
# Ballet Island
|
||||
|
||||
同一 Git 仓库中的两个独立项目，分别安装依赖、运行与构建。当前提供项目骨架、欢迎页和服务健康检查，业务需求后续补充。
|
||||
同一 Git 仓库中的两个独立项目，分别安装依赖、运行与构建。第一期提供课后练习登记、日历回看、成长统计和练习项目管理，通过微信身份关联 PostgreSQL 中的个人数据。
|
||||
|
||||
## 目录
|
||||
|
||||
@@ -12,10 +12,12 @@ miniprogram/ Taro 4.2.1 + React 18 + TypeScript + Taroify 1.0.6
|
||||
pnpm-lock.yaml 小程序依赖锁文件
|
||||
node_modules/ 小程序本地依赖（不提交）
|
||||
.nvmrc Node 版本
|
||||
.agents/skills/taroify/ Taroify Agent Skill
|
||||
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 与数据库编排
|
||||
@@ -37,7 +39,7 @@ pnpm install --frozen-lockfile
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
微信开发者工具导入 `miniprogram/`，AppID 为 `wx6dfbf1021db8aee0`，编译目录为 `dist/`。首页“检查连接”请求后端 `/readyz`，同时检查数据库是否可用。
|
||||
微信开发者工具导入 `miniprogram/`，AppID 为 `wx6dfbf1021db8aee0`，编译目录为 `dist/`。底部入口为“记录、日历、成长”。首次请求通过 `Taro.login` 取得 code，在后端核验后建立业务会话；登录失败或网络失败会显示重试入口，不会当作空记录。
|
||||
|
||||
默认 API 为 `http://127.0.0.1:8080`。使用本地 HTTP 地址时，在开发者工具的本地设置中开启“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”，仅用于本地调试。真机需使用能够访问的接口地址，并按微信要求配置域名。
|
||||
|
||||
@@ -50,6 +52,10 @@ 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。笔记只作为普通文本显示。每次主动新增生成独立提交标识；结果未确认时保留该标识与完整输入，重试不重复累计。首期不提供离线保存队列。
|
||||
|
||||
## 后端开发
|
||||
|
||||
需要 Go 1.26 或更高版本，以及 Docker Compose。仅使用 Docker 运行后端时无需本机 Go。
|
||||
@@ -67,6 +73,10 @@ docker compose up -d --wait postgres
|
||||
|
||||
后端全程无需 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 运行与部署
|
||||
|
||||
以下命令在 `backend/` 中执行：
|
||||
@@ -95,6 +105,7 @@ PostgreSQL 18 数据卷按[官方镜像说明](https://hub.docker.com/_/postgres
|
||||
|
||||
```sh
|
||||
pnpm typecheck
|
||||
pnpm test:client
|
||||
pnpm build
|
||||
```
|
||||
|
||||
@@ -104,13 +115,33 @@ pnpm build
|
||||
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}` |
|
||||
| `POST /v1/projects` / `PUT /v1/projects/{id}` | 新增 / 改名，JSON `{name}` | 最新项目 |
|
||||
| `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` 时停止接收请求并关闭连接池。
|
||||
|
||||
Reference in New Issue
Block a user