docs: add design spec for pilates booking mini-program

Initial design document covering architecture (monorepo with pnpm),
page design, data models, business flows, and API endpoints for
the private Pilates lesson booking WeChat mini-program.

docs/superpowers/specs/2026-04-02-pilates-booking-miniprogram-design.md

@@ -0,0 +1,419 @@
+# 普拉提私教约课小程序 — 设计文档
+
+## 概述
+
+为单人普拉提工作室开发的微信小程序约课系统。核心功能：学员在线预约私教课、购买会员卡、查看训练记录；教练管理可约时段和会员。
+
+### 约束
+
+- 单一工作室、单一教练，不涉及多场馆/多教练切换
+- 仅私教课，不涉及小班课
+- 微信小程序为唯一客户端
+
+---
+
+## 技术架构
+
+### Monorepo 结构
+
+```
+mp-pilates/
+├── packages/
+│   ├── app/              # uni-app 微信小程序前端
+│   ├── server/           # NestJS 后端
+│   └── shared/           # 前后端共享类型和常量
+├── package.json          # 根 workspace 配置
+├── pnpm-workspace.yaml
+└── tsconfig.base.json
+```
+
+### 技术选型
+
+| 层 | 选型 |
+|---|---|
+| 包管理 | pnpm workspace |
+| 前端 | uni-app + Vue 3 + TypeScript + Pinia + uni-ui |
+| 后端 | NestJS + TypeScript + Prisma ORM |
+| 数据库 | PostgreSQL |
+| 共享层 | `@mp-pilates/shared`（类型、常量、枚举） |
+
+### 角色体系
+
+| 角色 | 说明 |
+|------|------|
+| MEMBER | 学员（默认），约课、查看记录、购卡 |
+| ADMIN | 管理员/教练，排课、管理会员、查看订单 |
+
+管理员通过数据库标记，小程序内根据角色展示不同菜单入口。
+
+---
+
+## 页面设计
+
+### 底部 Tab 导航（3 个）
+
+| Tab | 路径 | 说明 |
+|-----|------|------|
+| 首页 | /pages/home/index | 品牌展示 + 快捷入口 |
+| 课程预约 | /pages/booking/index | 私教时段 + 预约 |
+| 我的 | /pages/profile/index | 个人中心 |
+
+### 1. 首页
+
+**顶部**：品牌 banner（Logo + 名称 + 背景图）
+
+**场馆信息**：
+- 场馆照片横滑轮播
+- 地址（点击跳转地图导航）+ 电话（点击拨打）
+
+**快捷入口卡片**（根据用户状态智能展示）：
+- 新用户 → 「预约体验课」醒目入口
+- 已有私教卡/时间卡 → 「一键约课」跳转课程预约页
+- 卡次即将用完 → 「续卡」提醒入口
+- 无卡用户 → 「购买会员卡」入口
+
+**今日/近期课程**：已预约课程卡片，快速查看。
+
+**会员卡商城**：卡种列表（私教次卡、月卡/季卡/年卡、体验课包），点击进入购买详情。
+
+### 2. 课程预约页
+
+**顶部日期选择器**：横向滚动，展示未来 7 天，标注星期几。
+
+**筛选栏**（简化版）：
+- 时段筛选（全部 / 上午 / 下午 / 晚上）
+- 单教练，无需老师筛选
+
+**时段列表**：
+- 时段卡片：时间段、剩余名额、预约按钮
+- 已约满 → 灰色置灰
+- 已预约 → 显示「已预约」+「取消」
+
+**预约流程**：
+1. 点击「预约」→ 检查是否有有效卡 → 无卡则引导购卡
+2. 有卡 → 确认预约弹窗（时段信息 + 扣卡信息）
+3. 确认 → 扣减卡次 / 验证时间卡有效期 → 预约成功
+
+**取消规则**：
+- 开课前 N 小时可免费取消（N 在 StudioConfig 中配置，默认 2 小时）
+- 超时取消仍扣卡次
+
+### 3. 个人中心
+
+**顶部用户卡片**：头像 + 昵称 + 手机号 + 累计训练天数 / 训练次数
+
+**本月训练统计**：训练次数 / 训练天数 / 训练时长
+
+**功能入口**：
+- 我的会员卡 → 持有卡列表、有效期、剩余次数
+- 我的预约 → 预约记录（即将上课 / 历史）
+- 个人信息 → 编辑昵称、手机号
+
+### 4. 管理功能（ADMIN 角色可见）
+
+个人中心底部显示「管理中心」入口：
+
+- **周模板设置** → 7 天网格，每天添加多个时间段，开关启用/停用
+- **临时调整** → 日历视图，点某天关闭/新增时段
+- **会员管理** → 所有会员列表、卡状态、预约记录
+- **订单管理** → 购卡订单列表、支付状态
+- **卡种管理** → 设置卡种、价格、有效期
+- **工作室设置** → 名称、Logo、地址、电话、照片
+
+### 子页面清单
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 卡种详情/购买 | /pages/card/detail | 卡种信息 + 购买按钮 |
+| 预约确认 | 弹窗组件 | 确认预约信息 |
+| 我的会员卡 | /pages/profile/membership | 持有卡列表 |
+| 我的预约 | /pages/profile/bookings | 预约记录 |
+| 个人信息 | /pages/profile/info | 编辑个人信息 |
+| 管理中心 | /pages/admin/index | 管理功能入口 |
+| 周模板管理 | /pages/admin/week-template | 设置周课表 |
+| 临时时段调整 | /pages/admin/slot-adjust | 按日期调整时段 |
+| 会员管理 | /pages/admin/members | 会员列表与详情 |
+| 订单管理 | /pages/admin/orders | 订单列表 |
+| 卡种管理 | /pages/admin/card-types | 管理卡种 |
+| 工作室设置 | /pages/admin/studio | 编辑工作室信息 |
+
+---
+
+## 数据模型
+
+### User（用户）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | UUID | 主键 |
+| openid | String | 微信 openid，唯一 |
+| unionid | String? | 微信 unionid |
+| phone | String? | 手机号（微信授权获取） |
+| nickname | String | 昵称 |
+| avatarUrl | String? | 头像 |
+| role | Enum(MEMBER, ADMIN) | 角色，默认 MEMBER |
+| createdAt | DateTime | 注册时间 |
+| updatedAt | DateTime | 更新时间 |
+
+### CardType（卡种定义）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | UUID | 主键 |
+| name | String | 卡名，如「私教 10 次卡」 |
+| type | Enum(TIMES, DURATION, TRIAL) | 次卡 / 时间卡 / 体验课 |
+| totalTimes | Int? | 总次数（TIMES / TRIAL 用） |
+| durationDays | Int | 有效天数 |
+| price | Decimal | 售价（分） |
+| originalPrice | Decimal? | 原价（划线价，分） |
+| description | String? | 描述 |
+| isActive | Boolean | 是否上架，默认 true |
+| sortOrder | Int | 排序权重，默认 0 |
+| createdAt | DateTime | 创建时间 |
+| updatedAt | DateTime | 更新时间 |
+
+### Membership（用户持有的卡）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | UUID | 主键 |
+| userId | UUID | 关联用户 |
+| cardTypeId | UUID | 关联卡种 |
+| remainingTimes | Int? | 剩余次数（次卡用） |
+| startDate | DateTime | 生效日期 |
+| expireDate | DateTime | 到期日期 |
+| status | Enum(ACTIVE, EXPIRED, USED_UP) | 状态 |
+| createdAt | DateTime | 创建时间 |
+| updatedAt | DateTime | 更新时间 |
+
+### WeekTemplate（周模板时段）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | UUID | 主键 |
+| dayOfWeek | Int | 星期几（1=周一 ~ 7=周日） |
+| startTime | String | 开始时间，如 "09:00" |
+| endTime | String | 结束时间，如 "10:00" |
+| capacity | Int | 容量，默认 1 |
+| isActive | Boolean | 是否启用，默认 true |
+| createdAt | DateTime | 创建时间 |
+| updatedAt | DateTime | 更新时间 |
+
+### TimeSlot（实际可约时段）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | UUID | 主键 |
+| date | Date | 具体日期 |
+| startTime | String | 开始时间 |
+| endTime | String | 结束时间 |
+| capacity | Int | 容量 |
+| bookedCount | Int | 已预约数，默认 0 |
+| status | Enum(OPEN, FULL, CLOSED) | 状态 |
+| source | Enum(TEMPLATE, MANUAL) | 来源：模板生成 / 手动添加 |
+| templateId | UUID? | 关联周模板（模板生成时） |
+| createdAt | DateTime | 创建时间 |
+| updatedAt | DateTime | 更新时间 |
+
+**生成逻辑**：定时任务每天按周模板自动生成未来 7-14 天的 TimeSlot。教练可手动添加/关闭某天的特定时段。
+
+### Booking（预约记录）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | UUID | 主键 |
+| userId | UUID | 关联用户 |
+| timeSlotId | UUID | 关联时段 |
+| membershipId | UUID | 扣的哪张卡 |
+| status | Enum(CONFIRMED, CANCELLED, COMPLETED, NO_SHOW) | 状态 |
+| cancelledAt | DateTime? | 取消时间 |
+| createdAt | DateTime | 预约时间 |
+| updatedAt | DateTime | 更新时间 |
+
+### Order（购卡订单）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | UUID | 主键 |
+| userId | UUID | 关联用户 |
+| cardTypeId | UUID | 购买的卡种 |
+| orderNo | String | 订单号，唯一 |
+| amount | Decimal | 支付金额（分） |
+| status | Enum(PENDING, PAID, REFUNDED) | 支付状态 |
+| wxTransactionId | String? | 微信支付单号 |
+| paidAt | DateTime? | 支付时间 |
+| createdAt | DateTime | 下单时间 |
+| updatedAt | DateTime | 更新时间 |
+
+### StudioConfig（工作室配置）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | UUID | 主键（仅一条记录） |
+| name | String | 工作室名称 |
+| logo | String? | Logo URL |
+| bannerUrl | String? | 背景图 URL |
+| address | String | 地址 |
+| phone | String | 联系电话 |
+| latitude | Decimal? | 纬度 |
+| longitude | Decimal? | 经度 |
+| cancelHoursLimit | Int | 免费取消截止小时数，默认 2 |
+| photos | Json | 场馆照片 URL 列表 |
+| updatedAt | DateTime | 更新时间 |
+
+---
+
+## 业务流程
+
+### 用户登录
+
+```
+小程序 wx.login() 获取 code
+  → 服务端用 code 换取 openid
+  → 查找/创建用户 → 签发 JWT
+  → 需要手机号时，前端 getPhoneNumber 按钮授权
+  → 服务端解密手机号 → 更新用户信息
+```
+
+### 预约
+
+```
+学员点击「预约」
+  → 检查登录（未登录引导登录）
+  → 检查有效会员卡
+    → 无卡 → 引导购卡
+    → 有卡 → 确认弹窗（时段 + 扣卡信息）
+      → 服务端校验（时段可约 + 卡有效 + 无重复预约）
+        → 成功 → 扣减卡次 → 预约成功
+        → 失败 → 提示原因
+```
+
+### 取消预约
+
+```
+学员点击「取消」
+  → 检查距开课时间
+    → >= cancelHoursLimit → 免费取消，退还卡次
+    → < cancelHoursLimit → 提示超时取消不退卡次，二次确认
+  → 更新 Booking 状态 → 释放 TimeSlot 名额
+```
+
+### 购卡支付
+
+```
+选择卡种 → 创建 Order（PENDING）
+  → 调用微信支付统一下单 → 返回支付参数
+  → 前端 wx.requestPayment
+    → 支付成功 → 微信回调服务端 → 验签
+      → 更新 Order 为 PAID → 创建 Membership
+    → 支付失败 → 保持 PENDING，可重新支付
+```
+
+### 时段自动生成
+
+```
+定时任务（每天凌晨执行）
+  → 读取所有 isActive 的 WeekTemplate
+  → 生成未来 7-14 天的 TimeSlot（跳过已存在的日期）
+  → 检查过期 Membership，标记 EXPIRED
+  → 检查已过期 TimeSlot，标记 CLOSED
+```
+
+---
+
+## API 端点
+
+### 认证 `/auth`
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | /auth/login | 微信 code 登录，返回 JWT |
+| POST | /auth/phone | 绑定手机号 |
+
+### 用户 `/user`
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /user/profile | 获取个人信息 |
+| PUT | /user/profile | 更新个人信息 |
+| GET | /user/stats | 训练统计（本月/累计） |
+
+### 时段 `/time-slot`
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /time-slot/available | 查询可约时段（按日期范围） |
+| GET | /time-slot/:id | 时段详情 |
+
+### 预约 `/booking`
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | /booking | 创建预约 |
+| PUT | /booking/:id/cancel | 取消预约 |
+| GET | /booking/my | 我的预约列表 |
+| GET | /booking/my/upcoming | 即将上课的预约 |
+
+### 会员卡 `/membership`
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /membership/card-types | 可购买的卡种列表 |
+| GET | /membership/my | 我持有的卡列表 |
+
+### 支付 `/payment`
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | /payment/create-order | 创建购卡订单 + 发起微信支付 |
+| POST | /payment/wx-notify | 微信支付回调 |
+| GET | /payment/orders | 我的订单列表 |
+
+### 管理 `/admin`（ADMIN 角色）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /admin/week-template | 获取周模板 |
+| PUT | /admin/week-template | 更新周模板（全量替换） |
+| POST | /admin/time-slot/manual | 手动添加时段 |
+| PUT | /admin/time-slot/:id/close | 关闭某个时段 |
+| GET | /admin/members | 会员列表 |
+| GET | /admin/members/:id | 会员详情 |
+| GET | /admin/bookings | 所有预约记录 |
+| GET | /admin/card-types | 卡种列表 |
+| POST | /admin/card-types | 创建卡种 |
+| PUT | /admin/card-types/:id | 更新卡种 |
+| DELETE | /admin/card-types/:id | 删除卡种 |
+| POST | /admin/generate-slots | 手动触发生成时段 |
+
+### 工作室 `/studio`
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /studio/info | 获取工作室信息 |
+| PUT | /admin/studio/info | 更新工作室信息 |
+
+---
+
+## 关键业务规则
+
+1. **预约扣卡**：次卡 → remainingTimes - 1；时间卡 → 仅检查 expireDate 有效性；体验课 → 同次卡逻辑
+2. **取消退还**：距开课 >= cancelHoursLimit 小时 → 次卡退还次数；否则不退
+3. **时段状态**：bookedCount >= capacity → 自动标记 FULL
+4. **卡过期检测**：定时任务每天检查，过期卡标记 EXPIRED，次数用完标记 USED_UP
+5. **重复预约**：同一用户不可重复预约同一时段
+6. **金额单位**：所有金额以「分」存储，避免浮点精度问题
+
+---
+
+## 不做的事项（YAGNI）
+
+- 多场馆切换
+- 小班课
+- 多教练筛选
+- 积分系统
+- 拼团功能
+- 美团/抖音验券
+- 体测记录
+- 签到功能
+- 代金券