Neo-ZQYY/apps/miniprogram

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/task-list/task-list	任务列表页（H5 原型 1:1 重写，四种任务类型分组）
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

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

• 完善认证流程页面（登录 → 申请 → 等待审批 → 首页）
• 任务列表页面（task-list，H5 原型 1:1 重写，含四种任务类型分组、上下文菜单、备注弹窗）
• 任务管理功能联调（置顶、放弃、备注 API 对接）
• 数据看板页面（助教业绩、客户分析）
• 会员中心页面
• 助教预约功能
• 订单查询功能
• 多门店切换 UI
• 消息通知（微信订阅消息）
• CI/CD（代码检查、自动上传体验版）