203 lines
7.8 KiB
Markdown
203 lines
7.8 KiB
Markdown
# 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/ # 首页
|
||
│ │ ├── login/ # 登录页
|
||
│ │ ├── apply/ # 入驻申请页
|
||
│ │ ├── reviewing/ # 审核中等待页
|
||
│ │ ├── no-permission/ # 无权限提示页
|
||
│ │ ├── dev-tools/ # 开发调试面板（仅 develop 环境）
|
||
│ │ └── logs/ # 日志页
|
||
│ ├── components/ # 全局组件
|
||
│ │ └── dev-fab/ # 浮动调试按钮（仅 develop 环境显示）
|
||
│ ├── 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/login/login` | 登录页 |
|
||
| `pages/apply/apply` | 入驻申请页 |
|
||
| `pages/reviewing/reviewing` | 审核中等待页 |
|
||
| `pages/no-permission/no-permission` | 无权限提示页 |
|
||
| `pages/dev-tools/dev-tools` | 开发调试面板（仅 develop 环境，通过 dev-fab 浮动按钮进入） |
|
||
| `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（受限令牌，status=new）
|
||
↓
|
||
POST /api/xcx-auth/apply → 提交入驻申请（球房ID + 身份 + 手机号，status → pending）
|
||
↓
|
||
管理员在后台审批
|
||
↓
|
||
GET /api/xcx-auth/status → 查询审批结果
|
||
↓
|
||
POST /api/xcx-auth/login → 重新登录获取完整令牌（含 site_id + roles）
|
||
↓
|
||
正常使用业务功能
|
||
```
|
||
|
||
用户状态流转：
|
||
- `new`：新用户，尚未提交申请
|
||
- `pending`：已提交申请，等待审批
|
||
- `approved`：审批通过，可正常使用
|
||
- `rejected`：审批拒绝，可重新申请
|
||
- `disabled`：账号禁用
|
||
|
||
令牌类型：
|
||
- 受限令牌（`limited=True`）：new/pending/rejected 用户，仅可访问申请和状态查询端点
|
||
- 完整令牌：approved 用户，包含 `user_id` + `site_id` + `roles`
|
||
|
||
### 开发模式
|
||
|
||
后端支持开发模式（`WX_DEV_MODE=true`），提供 mock 登录端点跳过微信 code2Session：
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/xcx-auth/dev-login` | POST | 开发模式 mock 登录（仅开发环境） |
|
||
|
||
参数：
|
||
- `openid`：模拟的微信 openid
|
||
- `status`：可选，指定用户状态（new/pending/approved/rejected）
|
||
|
||
### 关键 API 端点
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/xcx-auth/login` | POST | 微信登录（code → JWT） |
|
||
| `/api/xcx-auth/dev-login` | POST | 开发模式 mock 登录（仅开发环境） |
|
||
| `/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/tasks` | GET | 获取任务列表 |
|
||
| `/api/xcx/tasks/{task_id}/pin` | POST | 置顶/取消置顶任务 |
|
||
| `/api/xcx/tasks/{task_id}/abandon` | POST | 放弃/取消放弃任务 |
|
||
| `/api/xcx/notes` | GET/POST/DELETE | 备注 CRUD |
|
||
| `/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
|
||
|
||
## 开发调试面板（dev-tools）
|
||
|
||
仅在 develop 环境可用的调试工具，通过页面底部浮动按钮（dev-fab 组件）进入。
|
||
|
||
功能：
|
||
- 展示当前用户上下文（角色、权限、绑定关系、门店信息）
|
||
- 一键切换角色（coach / staff / site_admin / tenant_admin），后端真实修改 `user_site_roles` 并重签 token
|
||
- 一键切换用户状态（new / pending / approved / rejected / disabled），后端真实修改 `users.status` 并重签 token
|
||
- 页面跳转列表，点击可跳转到任意已注册页面
|
||
|
||
安全保障：
|
||
- dev-fab 组件通过 `wx.getAccountInfoSync().miniProgram.envVersion` 判断环境，仅 `develop` 时渲染
|
||
- 后端 dev 端点仅在 `WX_DEV_MODE=true` 时注册路由，生产环境不可访问
|
||
|
||
依赖的后端端点（均需 JWT）：
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/xcx/dev-context` | GET | 获取当前用户调试上下文 |
|
||
| `/api/xcx/dev-switch-role` | POST | 切换角色 |
|
||
| `/api/xcx/dev-switch-status` | POST | 切换用户状态 |
|
||
| `/api/xcx/dev-switch-binding` | POST | 切换绑定关系 |
|
||
|
||
## Roadmap
|
||
|
||
- [ ] 完善认证流程页面（登录 → 申请 → 等待审批 → 首页）
|
||
- [ ] 任务管理页面（任务列表、置顶、放弃、备注）
|
||
- [ ] 数据看板页面（助教业绩、客户分析）
|
||
- [ ] 会员中心页面
|
||
- [ ] 助教预约功能
|
||
- [ ] 订单查询功能
|
||
- [ ] 多门店切换 UI
|
||
- [ ] 消息通知（微信订阅消息）
|
||
- [ ] CI/CD（代码检查、自动上传体验版）
|