Neo
b25308c3f4
## P1 数据库基础 - zqyy_app: 创建 auth/biz schema、FDW 连接 etl_feiqiu - etl_feiqiu: 创建 app schema RLS 视图、商品库存预警表 - 清理 assistant_abolish 残留数据 ## P2 ETL/DWS 扩展 - 新增 DWS 助教订单贡献度表 (dws.assistant_order_contribution) - 新增 assistant_order_contribution_task 任务及 RLS 视图 - member_consumption 增加充值字段、assistant_daily 增加处罚字段 - 更新 ODS/DWD/DWS 任务文档及业务规则文档 - 更新 consistency_checker、flow_runner、task_registry 等核心模块 ## P3 小程序鉴权系统 - 新增 xcx_auth 路由/schema（微信登录 + JWT） - 新增 wechat/role/matching/application 服务层 - zqyy_app 鉴权表迁移 + 角色权限种子数据 - auth/dependencies.py 支持小程序 JWT 鉴权 ## 文档与审计 - 新增 DOCUMENTATION-MAP 文档导航 - 新增 7 份 BD_Manual 数据库变更文档 - 更新 DDL 基线快照（etl_feiqiu 6 schema + zqyy_app auth） - 新增全栈集成审计记录、部署检查清单更新 - 新增 BACKLOG 路线图、FDW→Core 迁移计划 ## Kiro 工程化 - 新增 5 个 Spec（P1/P2/P3/全栈集成/核心业务） - 新增审计自动化脚本（agent_on_stop/build_audit_context/compliance_prescan） - 新增 6 个 Hook（合规检查/会话日志/提交审计等） - 新增 doc-map steering 文件 ## 运维与测试 - 新增 ops 脚本：迁移验证/API 健康检查/ETL 监控/集成报告 - 新增属性测试：test_dws_contribution / test_auth_system - 清理过期 export 报告文件 - 更新 .gitignore 排除规则
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
开发指南
环境准备
- 安装微信开发者工具
- 打开本目录（
apps/miniprogram/） - 首次打开后，在工具中执行"构建 npm"以生成
miniprogram_npm/ - 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
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数据库的authSchema
Roadmap
- 完善认证流程页面（登录 → 申请 → 等待审批 → 首页）
- 数据看板页面（助教业绩、客户分析）
- 会员中心页面
- 助教预约功能
- 订单查询功能
- 多门店切换 UI
- 消息通知（微信订阅消息）
- CI/CD（代码检查、自动上传体验版）