# apps/miniprogram — 微信小程序

微信小程序前端项目，基于 Donut 多端框架 + TDesign 组件库，为台球门店会员提供移动端服务入口。

## 技术栈

- 微信小程序原生 + Donut 多端（`projectArchitecture: multiPlatform`）
- TDesign 小程序版（`tdesign-miniprogram ^1.12.2`）
- TypeScript
- 类型定义：`miniprogram-api-typings`

## 目录结构

```
apps/miniprogram/
├── miniprogram/              # 小程序主体代码
│   ├── app.ts                # 应用入口（wx.login 获取 code）
│   ├── app.json              # 全局配置（页面路由、窗口样式）
│   ├── app.wxss              # 全局样式
│   ├── pages/                # 页面目录
│   │   ├── mvp/              # MVP 全链路验证页
│   │   ├── index/            # 首页
│   │   └── logs/             # 日志页
│   ├── utils/                # 工具函数
│   │   ├── config.ts         # 环境配置（API 地址自动切换）
│   │   └── util.ts           # 通用工具（日期格式化等）
│   ├── miniprogram_npm/      # 构建后的 npm 包（TDesign 组件）
│   ├── i18n/                 # 国际化资源
│   └── miniapp/              # Donut 多端原生资源
├── typings/                  # TypeScript 类型定义
├── project.config.json       # 微信开发者工具项目配置
├── project.miniapp.json      # Donut 多端配置
├── tsconfig.json             # TypeScript 编译配置
├── package.json              # npm 依赖声明
└── README.md
```

## 开发指南

### 环境准备

1. 安装微信开发者工具
2. 打开本目录（`apps/miniprogram/`）
3. 首次打开后，在工具中执行"构建 npm"以生成 `miniprogram_npm/`
4. AppID：`wx7c07793d82732921`

### 页面路由

当前注册页面（`app.json`）：

| 路径 | 说明 |
|------|------|
| `pages/mvp/mvp` | MVP 全链路验证（从后端读取测试数据） |
| `pages/index/index` | 首页（待开发） |
| `pages/logs/logs` | 日志页（框架默认） |

## 后端 API 集成

### API 地址配置

`utils/config.ts` 根据小程序运行环境自动切换 API 地址：

| 环境 | API 地址 |
|------|----------|
| develop（开发版） | `http://127.0.0.1:8000` |
| trial（体验版） | `https://api.langlangzhuoqiu.cn` |
| release（正式版） | `https://api.langlangzhuoqiu.cn` |

### 认证流程

小程序用户的完整生命周期：

```
wx.login() 获取 code
       ↓
POST /api/xcx-auth/login  →  获取 JWT（受限令牌）
       ↓
POST /api/xcx-auth/apply  →  提交入驻申请（球房ID + 身份 + 手机号）
       ↓
管理员在后台审批
       ↓
GET /api/xcx-auth/status  →  查询审批结果
       ↓
POST /api/xcx-auth/login  →  重新登录获取完整令牌（含 site_id + roles）
       ↓
正常使用业务功能
```

令牌类型：
- 受限令牌（`limited=True`）：pending 用户，仅可访问申请和状态查询端点
- 完整令牌：approved 用户，包含 `user_id` + `site_id` + `roles`

### 关键 API 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/xcx-auth/login` | POST | 微信登录（code → JWT） |
| `/api/xcx-auth/apply` | POST | 提交入驻申请 |
| `/api/xcx-auth/status` | GET | 查询用户状态和申请记录 |
| `/api/xcx-auth/sites` | GET | 获取关联门店列表 |
| `/api/xcx-auth/switch-site` | POST | 切换当前门店 |
| `/api/xcx-auth/refresh` | POST | 刷新令牌 |
| `/api/xcx-test` | GET | MVP 全链路验证 |

> 完整 API 文档见 [`apps/backend/docs/API-REFERENCE.md`](../backend/docs/API-REFERENCE.md)

## MVP 页面

`pages/mvp/mvp` 是全链路验证页面，从后端 `/api/xcx-test` 读取 `test."xcx-test"` 表数据并显示，用于验证：
- 小程序 → 后端 API → 数据库 的完整链路
- 网络请求、错误处理、加载状态

## 权限模型

小程序用户通过 RBAC 模型控制功能访问：

| 角色 | 可见功能 |
|------|----------|
| coach（助教） | 查看任务、助教看板 |
| staff（员工） | 查看任务、数据看板 |
| site_admin（店铺管理员） | 全部看板 |
| tenant_admin（租户管理员） | 全部权限 |

多门店支持：用户可关联多个门店，通过 `/api/xcx-auth/switch-site` 切换。

## 与 Monorepo 的关系

- 本项目为独立前端工程，不参与 Python uv workspace
- 通过 FastAPI 后端（`apps/backend/`）与数据层交互
- H5 原型设计稿位于 `docs/h5_ui/`
- 认证数据存储在 `zqyy_app` 数据库的 `auth` Schema

## Roadmap

- [ ] 完善认证流程页面（登录 → 申请 → 等待审批 → 首页）
- [ ] 数据看板页面（助教业绩、客户分析）
- [ ] 会员中心页面
- [ ] 助教预约功能
- [ ] 订单查询功能
- [ ] 多门店切换 UI
- [ ] 消息通知（微信订阅消息）
- [ ] CI/CD（代码检查、自动上传体验版）