feat: P1-P3 全栈集成 — 数据库基础 + DWS 扩展 + 小程序鉴权 + 工程化体系

## 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/README.md

@@ -1,57 +1,142 @@
-# 小程序前端（miniprogram）
+# apps/miniprogram — 微信小程序
 
-微信小程序前端项目，基于 **Donut 多端框架 + TDesign 组件库** 技术栈，为台球门店会员提供移动端服务入口。
+微信小程序前端项目，基于 Donut 多端框架 + TDesign 组件库，为台球门店会员提供移动端服务入口。
 
 ## 技术栈
 
-- **框架**：微信小程序原生 + Donut 多端（`projectArchitecture: multiPlatform`）
-- **UI 组件**：TDesign 小程序版（`tdesign-miniprogram ^1.12.2`）
-- **语言**：TypeScript
-- **类型定义**：`miniprogram-api-typings`
+- 微信小程序原生 + Donut 多端（`projectArchitecture: multiPlatform`）
+- TDesign 小程序版（`tdesign-miniprogram ^1.12.2`）
+- TypeScript
+- 类型定义：`miniprogram-api-typings`
 
 ## 目录结构
 
 ```
 apps/miniprogram/
 ├── miniprogram/              # 小程序主体代码
-│   ├── app.ts                # 应用入口
-│   ├── app.json              # 全局配置（页面路由、窗口、TabBar 等）
+│   ├── 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 多端原生资源
-│   └── utils/                # 工具函数
-├── miniapp/                  # 顶层 Donut 原生资源
+│   └── miniapp/              # Donut 多端原生资源
 ├── typings/                  # TypeScript 类型定义
-├── doc/                      # 项目文档（PRD 等）
-├── i18n/                     # 顶层国际化资源
-├── reports/                  # 报表输出
 ├── project.config.json       # 微信开发者工具项目配置
 ├── project.miniapp.json      # Donut 多端配置
 ├── tsconfig.json             # TypeScript 编译配置
 ├── package.json              # npm 依赖声明
-└── README.md                 # 本文件
+└── README.md
 ```
 
 ## 开发指南
 
-1. 使用 **微信开发者工具** 打开本目录（`apps/miniprogram/`）
-2. 首次打开后，在工具中执行"构建 npm"以生成 `miniprogram_npm/`
-3. AppID：`wx7c07793d82732921`
+### 环境准备
+
+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
-- H5 原型设计稿位于 `docs/h5_ui/`（从原 `Prototype/` 目录迁移）
-- 未来将通过 FastAPI 后端（`apps/backend/`）与 ETL 数据层交互
+- 通过 FastAPI 后端（`apps/backend/`）与数据层交互
+- H5 原型设计稿位于 `docs/h5_ui/`
+- 认证数据存储在 `zqyy_app` 数据库的 `auth` Schema
 
 ## Roadmap
 
-- [ ] 接入 FastAPI 后端 API，替换当前静态/模拟数据
-- [ ] TDesign 组件库升级至最新版本
-- [ ] 完善页面路由与业务功能（会员中心、助教预约、订单查询等）
-- [ ] 集成 CI/CD（代码检查、自动上传体验版）
-- [ ] 多门店支持（基于 `site_id` 的数据隔离）
+- [ ] 完善认证流程页面（登录 → 申请 → 等待审批 → 首页）
+- [ ] 数据看板页面（助教业绩、客户分析）
+- [ ] 会员中心页面
+- [ ] 助教预约功能
+- [ ] 订单查询功能
+- [ ] 多门店切换 UI
+- [ ] 消息通知（微信订阅消息）
+- [ ] CI/CD（代码检查、自动上传体验版）