在前后端开发联调前 的提交20260223

docs/prd/specs/00-数据依赖矩阵.md

@@ -0,0 +1,269 @@
+# 数据依赖矩阵（页面 → 数据表映射）
+
+> 生成日期：2026-02-23
+> 基于 PRD 审阅 Q&A 两轮结果 + 真实数据库现状
+
+---
+
+## 图例
+
+| 标记 | 含义 |
+|------|------|
+| ✅ | ETL 库已有表，可直接通过 FDW 映射 |
+| 🔧 | ETL 库已有表但需扩展字段 |
+| 🆕 | 需要新建的 ETL 表（DWS/DWD 层） |
+| 📱 | 需要新建的业务库表（`test_zqyy_app`） |
+| 🤖 | 需要 AI 应用调用（百炼） |
+| ⏰ | 需要后台轮询/触发器机制 |
+
+---
+
+## 一、小程序页面 → 数据源
+
+### task-list.html（任务列表）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 助教任务列表 | `zqyy_app.biz.coach_tasks` | 📱 新建 |
+| 任务优先级（max(WBI,NCI)） | `dws.dws_member_winback_index` + `dws.dws_member_newconv_index` | ✅ FDW |
+| 客户-助教关系（RS/OS） | `dws.dws_member_assistant_relation_index` | ✅ FDW |
+| 客户基本信息 | `dwd.dim_member` | ✅ FDW |
+| 助教基本信息 | `dwd.dim_assistant` | ✅ FDW |
+| 任务置顶/放弃状态 | `zqyy_app.biz.coach_tasks` | 📱 新建 |
+| 绩效计算快照 | `dws.dws_assistant_salary_calc` | ✅ FDW |
+| 定档业绩配置 | `dws.cfg_performance_tier` | ✅ FDW |
+| 助教等级单价 | `dws.cfg_assistant_level_price` | ✅ FDW |
+| 跳档激励展示 | `dws.cfg_performance_tier` + `dws.dws_assistant_salary_calc` | ✅ FDW |
+| 定档折算惩罚 | `dws.dws_assistant_daily_detail`（需扩展） | 🔧 扩展 |
+
+### task-detail.html（任务详情）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 任务详情 | `zqyy_app.biz.coach_tasks` | 📱 新建 |
+| 客户全信息 | `dwd.dim_member` + `dws.dws_member_consumption_summary` | ✅ FDW |
+| 客户-助教亲密度 | `dws.dws_member_assistant_intimacy` | ✅ FDW |
+| 近期服务记录 | `dwd.dwd_assistant_service_log` | ✅ FDW |
+| 备注列表 | `zqyy_app.biz.notes` | 📱 新建 |
+| AI 消费习惯分析 | 应用 3 返回结果缓存 | 📱🤖⏰ |
+| AI 关系分析/任务建议 | 应用 4 返回结果缓存 | 📱🤖⏰ |
+| AI 话术参考 | 应用 5 返回结果缓存 | 📱🤖⏰ |
+| AI 备注星级 | 应用 6 返回结果 | 📱🤖⏰ |
+| 客户喜好标签（🎱斯🀅🎤） | `dwd.dwd_table_fee_log`（按房间类型统计） | ✅ FDW |
+
+### performance.html（我的绩效）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 收入与业绩档位 | `dws.dws_assistant_salary_calc` | ✅ FDW |
+| 服务记录明细 | `dwd.dwd_assistant_service_log` | ✅ FDW |
+| 我的新客 | `dws.dws_assistant_customer_stats`（首次服务+次数过滤） | ✅ FDW |
+| 我的常客 | `dws.dws_assistant_customer_stats` | ✅ FDW |
+| 定档折算惩罚展示 | `dws.dws_assistant_daily_detail`（需扩展） | 🔧 扩展 |
+
+### performance-records.html（业绩明细）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 全部业绩记录 | `dwd.dwd_assistant_service_log` | ✅ FDW |
+| 定档折算展示 | `dws.dws_assistant_daily_detail`（需扩展） | 🔧 扩展 |
+| 按天/月归总 | 后端聚合查询 | — |
+
+### board-finance.html（财务看板）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 财务日报 | `dws.dws_finance_daily_summary` | ✅ FDW |
+| 收入结构 | `dws.dws_finance_income_structure` | ✅ FDW |
+| 充值汇总 | `dws.dws_finance_recharge_summary` | ✅ FDW |
+| 折扣明细 | `dws.dws_finance_discount_detail` | ✅ FDW |
+| 支出汇总 | `dws.dws_finance_expense_summary` | ✅ FDW |
+| 平台结算 | `dws.dws_platform_settlement` | ✅ FDW |
+| AI 财务洞察 | 应用 2 返回结果缓存 | 📱🤖⏰ |
+| 环比数据 | 后端聚合计算 | — |
+
+### board-customer.html（客户看板）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 最应召回（WBI 排序） | `dws.dws_member_winback_index` | ✅ FDW |
+| 最大消费潜力（SPI 排序） | `dws.dws_member_spending_power_index` | 🆕 新建 |
+| 最高余额 | `dws.dws_member_consumption_summary` | ✅ FDW |
+| 最近充值 | `dwd.dwd_recharge_order` | ✅ FDW |
+| 最高消费 60 天 | `dws.dws_member_consumption_summary` | ✅ FDW |
+| 最频繁 60 天 | `dws.dws_member_consumption_summary` | ✅ FDW |
+| 最近到店 | `dws.dws_member_visit_detail` | ✅ FDW |
+| 最专一（RS 最大值） | `dws.dws_member_assistant_relation_index` | ✅ FDW |
+| 客户喜好标签 | `dwd.dwd_table_fee_log` | ✅ FDW |
+
+### board-coach.html（助教看板）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 定档业绩排序 | `dws.dws_assistant_salary_calc` | ✅ FDW |
+| 工资排序 | `dws.dws_assistant_salary_calc` | ✅ FDW |
+| 高客源储值额 | `dws.dws_member_assistant_relation_index` + `dws.dws_member_consumption_summary` | ✅ FDW |
+| 任务完成数 | `zqyy_app.biz.coach_tasks`（统计已完成） | 📱 新建 |
+| 助教月度汇总 | `dws.dws_assistant_monthly_summary` | ✅ FDW |
+
+### customer-detail.html（客户详情）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 客户基本信息 | `dwd.dim_member` + `dwd.dim_member_card_account` | ✅ FDW |
+| 消费汇总 | `dws.dws_member_consumption_summary` | ✅ FDW |
+| 消费记录（台桌结账） | `dwd.dwd_settlement_head` + `dwd.dwd_table_fee_log` | ✅ FDW |
+| 消费记录（商城订单） | `dwd.dwd_settlement_head` + `dwd.dwd_store_goods_sale` | ✅ FDW |
+| 消费记录（充值） | `dwd.dwd_recharge_order` | ✅ FDW |
+| 指数总览（WBI/NCI/SPI） | 各指数表 | ✅🆕 FDW |
+| 备注列表 | `zqyy_app.biz.notes` | 📱 新建 |
+| AI 消费习惯分析 | 应用 3 缓存 | 📱🤖⏰ |
+| 生日信息 | `zqyy_app.biz.notes`（type=birthday） | 📱 新建 |
+
+### coach-detail.html（助教详情）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 助教基本信息 | `dwd.dim_assistant` | ✅ FDW |
+| 客户数（RS>2） | `dws.dws_member_assistant_relation_index` | ✅ FDW |
+| 工龄 | `dwd.dim_assistant.hire_date` | ✅ FDW |
+| 备注列表 | `zqyy_app.biz.notes` | 📱 新建 |
+
+### chat.html（AI 对话）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 对话记录 | `zqyy_app.biz.ai_conversations` | 📱 新建 |
+| 来源页面上下文 | 前端传入 | — |
+| AI 应用 1 调用 | 百炼 API | 🤖 |
+
+### notes.html（备注管理）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 备注列表 | `zqyy_app.biz.notes` | 📱 新建 |
+
+### chat-history.html（对话历史）
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 历史对话列表 | `zqyy_app.biz.ai_conversations` | 📱 新建 |
+
+### login/apply/reviewing 等登录流程页
+
+| 数据需求 | 数据源 | 状态 |
+|---------|--------|------|
+| 用户信息 | `zqyy_app.auth.users` | 📱 新建（重构现有 public.users） |
+| 微信登录 | 微信 API（code2Session） | — |
+| 申请记录 | `zqyy_app.auth.user_applications` | 📱 新建 |
+
+---
+
+## 二、租户管理后台 → 数据源
+
+| 功能 | 数据源 | 状态 |
+|------|--------|------|
+| 用户审核列表 | `zqyy_app.auth.user_applications` + `zqyy_app.auth.users` | 📱 新建 |
+| 用户-助教关联建议 | `dwd.dim_assistant`（通过球房ID+手机号匹配） | ✅ FDW |
+| 球房ID映射 | `zqyy_app.auth.site_code_mapping` | 📱 新建 |
+| Excel 上传-财务支出 | `dws.dws_finance_expense_summary`（或新建 staging 表） | 🔧/📱 |
+| Excel 上传-团购收入 | `dws.dws_platform_settlement`（或新建 staging 表） | 🔧/📱 |
+| Excel 上传-助教奖罚 | `zqyy_app.biz.salary_adjustments` | 📱 新建 |
+| Excel 上传-充值业绩归属 | `dws.dws_assistant_recharge_commission`（或新建 staging 表） | 🔧/📱 |
+
+---
+
+## 三、后台轮询/触发器任务 → 数据源
+
+| 触发器/轮询任务 | 触发条件 | 数据源 | 状态 |
+|---------------|---------|--------|------|
+| 任务生成器 | 每日 4:00 后首次运行 | 全部指数表 + `coach_tasks` | 📱⏰ |
+| 任务状态轮询 | 每小时 | `coach_tasks` + 有效期检查 | 📱⏰ |
+| 召回完成检测 | ETL 数据更新后 | `dwd.dwd_assistant_service_log` + `coach_tasks` | ⏰ |
+| 数据回溯（备注重分类） | 召回完成时 | `notes` + `coach_tasks` | 📱⏰ |
+| AI 应用 2 财务洞察 | 每日 | 财务 DWS 表 | 🤖⏰ |
+| AI 应用 3 消费习惯 | 客户新增消费时 | DWD 订单明细 | 🤖⏰ |
+| AI 应用 4 关系分析 | 助教参与新结算时 | DWD 订单明细 | 🤖⏰ |
+| AI 应用 5 话术 | 应用 4 调用时 | 应用 4 输入+输出 | 🤖⏰ |
+| AI 应用 6 备注评分 | 回访任务完成时 | 备注 + 客户信息 | 🤖⏰ |
+
+---
+
+## 四、汇总：需要新建/扩展的数据对象
+
+### ETL 库（`test_etl_feiqiu`）— 新建
+
+| 表名 | Schema | 说明 |
+|------|--------|------|
+| `dws_member_spending_power_index` | dws | SPI 消费力指数 |
+| `dws_assistant_order_contribution` | dws | 助教订单流水四项统计 |
+| `app.*`（RLS 视图） | app | 全部 FDW 映射表的 RLS 视图层 |
+
+### ETL 库 — 扩展
+
+| 表名 | 扩展内容 |
+|------|---------|
+| `dws_member_consumption_summary` | 增加 30/60/90 天充值次数/金额、次均消费 |
+| `dws_assistant_daily_detail` | 增加定档折算惩罚字段（penalty_minutes、penalty_reason、is_exempt） |
+
+### 业务库（`test_zqyy_app`）— 新建
+
+| 表名 | Schema | 说明 |
+|------|--------|------|
+| `users`（重构） | auth | 小程序用户（增加 status、wx_openid、wx_avatar 等） |
+| `user_applications` | auth | 用户申请记录 |
+| `site_code_mapping` | auth | 球房ID ↔ site_id 映射 |
+| `user_assistant_bindng` | auth | 用户-助教绑定关系 |
+| `coach_tasks` | biz | 助教任务（类型、优先级、状态、有效期等） |
+| `coach_task_history` | biz | 任务变更历史（关闭/新建追溯） |
+| `notes` | biz | 统一备注表（type 区分） |
+| `ai_conversations` | biz | AI 对话记录 |
+| `ai_messages` | biz | AI 对话消息明细 |
+| `ai_cache` | biz | AI 应用 2-6 结果缓存 |
+| `salary_adjustments` | biz | 助教奖罚明细（Excel 上传） |
+| `excel_upload_log` | biz | Excel 上传记录与冲突处理日志 |
+| `trigger_jobs` | biz | 触发器/轮询任务配置与执行日志 |
+
+### FDW 映射（`test_zqyy_app.fdw_etl`）
+
+需要映射的 ETL 表（通过 `app` schema RLS 视图）：
+
+| 来源表 | 用途 |
+|--------|------|
+| `dwd.dim_member` | 客户基本信息 |
+| `dwd.dim_assistant` | 助教基本信息 |
+| `dwd.dim_member_card_account` | 会员卡余额 |
+| `dwd.dim_table` | 台桌信息 |
+| `dwd.dwd_settlement_head` | 结算主表 |
+| `dwd.dwd_table_fee_log` | 台费明细 |
+| `dwd.dwd_assistant_service_log` | 助教服务记录 |
+| `dwd.dwd_recharge_order` | 充值订单 |
+| `dwd.dwd_store_goods_sale` | 商品销售 |
+| `dws.dws_member_consumption_summary` | 客户消费汇总 |
+| `dws.dws_member_visit_detail` | 客户到店明细 |
+| `dws.dws_member_winback_index` | WBI 指数 |
+| `dws.dws_member_newconv_index` | NCI 指数 |
+| `dws.dws_member_recall_index` | 召回指数 |
+| `dws.dws_member_spending_power_index` | SPI 指数（新建后映射） |
+| `dws.dws_member_assistant_relation_index` | RS/OS/MS/ML 指数 |
+| `dws.dws_member_assistant_intimacy` | 亲密度 |
+| `dws.dws_assistant_daily_detail` | 助教日明细 |
+| `dws.dws_assistant_monthly_summary` | 助教月汇总 |
+| `dws.dws_assistant_salary_calc` | 薪资计算 |
+| `dws.dws_assistant_customer_stats` | 助教客户统计 |
+| `dws.dws_assistant_order_contribution` | 助教订单流水（新建后映射） |
+| `dws.dws_assistant_finance_analysis` | 助教财务分析 |
+| `dws.dws_finance_daily_summary` | 财务日报 |
+| `dws.dws_finance_income_structure` | 收入结构 |
+| `dws.dws_finance_recharge_summary` | 充值汇总 |
+| `dws.dws_finance_discount_detail` | 折扣明细 |
+| `dws.dws_finance_expense_summary` | 支出汇总 |
+| `dws.dws_platform_settlement` | 平台结算 |
+| `dws.dws_assistant_recharge_commission` | 充值业绩归属 |
+| `dws.cfg_performance_tier` | 定档配置 |
+| `dws.cfg_assistant_level_price` | 助教等级单价 |
+| `dws.cfg_bonus_rules` | 奖金规则 |
+| `dws.cfg_index_parameters` | 指数参数配置 |
+| `dws.dws_order_summary` | 订单汇总 |
+
+---

docs/prd/specs/01-SPEC任务拆分总览.md

@@ -0,0 +1,332 @@
+# SPEC 任务拆分总览
+
+> 生成日期：2026-02-23
+> 按依赖优先级排序，按 SPEC 边界分组，面向 Kiro SPEC 工作流
+
+---
+
+## 执行顺序总览
+
+```
+P1  基础设施层（数据库 Schema + FDW + RLS）
+P2  ETL 扩展层（DWS 新表 + 字段扩展 + SPI 指数）
+P3  用户认证层（微信登录 + 申请审核 + 权限体系）
+P4  核心业务层（任务系统 + 备注系统 + 触发器机制）
+P5  AI 集成层（百炼对接 + 对话系统 + 轮询缓存）
+P6  小程序前端-任务模块（task-list + task-detail + notes）
+P7  小程序前端-绩效模块（performance + performance-records）
+P8  小程序前端-看板模块（board-finance + board-customer + board-coach）
+P9  小程序前端-详情模块（customer-detail + coach-detail + chat）
+P10 租户管理后台（独立 Web 应用 + Excel 上传）
+P11 部署与上线（环境配置 + 监控 + 灰度）
+```
+
+---
+
+## P1：基础设施层 — 数据库 Schema + FDW + RLS
+
+### SPEC 名称建议：`miniapp-db-foundation`
+
+### 需求概述
+为小程序建立完整的数据库基础设施，包括业务库 Schema 规划、ETL 库 RLS 视图层、FDW 外部表映射。这是所有后续 SPEC 的硬依赖。
+
+### 关键交付物
+1. `test_zqyy_app` 新建 Schema：`auth`（用户认证）、`biz`（业务数据）
+2. `test_etl_feiqiu.app` Schema：为所有需要 FDW 映射的 DWS/DWD 表创建 RLS 视图（按 `site_id` 隔离）
+3. `test_zqyy_app.fdw_etl` Schema：创建全部 FDW 外部表（约 33 张，见数据依赖矩阵）
+4. 迁移脚本：`db/zqyy_app/migrations/` + `db/etl_feiqiu/migrations/`
+
+### 依赖
+- 无前置依赖（第一个 SPEC）
+
+### 验收标准
+- `fdw_etl` 下所有外部表可正常 SELECT
+- RLS 视图按 `site_id` 正确过滤
+- `auth` 和 `biz` Schema 存在且权限正确
+
+---
+
+## P2：ETL 扩展层 — DWS 新表 + 字段扩展 + SPI 指数
+
+### SPEC 名称建议：`etl-dws-miniapp-extensions`
+
+### 需求概述
+扩展 ETL 的 DWS 层以支持小程序的数据需求，包括新建 SPI 指数表、助教订单流水统计表，以及扩展现有表的字段。
+
+### 关键交付物
+1. 新建 `dws.dws_member_spending_power_index`（SPI 消费力指数，含 Level/Speed/Stability 子分）
+2. 新建 `dws.dws_assistant_order_contribution`（助教订单流水四项统计）
+3. 扩展 `dws.dws_member_consumption_summary`：增加 30/60/90 天充值次数/金额、次均消费
+4. 扩展 `dws.dws_assistant_daily_detail`：增加定档折算惩罚字段
+5. 新建 ETL 任务：`SpendingPowerIndexTask`、`AssistantOrderContributionTask`
+6. 扩展现有 ETL 任务以填充新字段
+7. 更新 `app` Schema RLS 视图 + FDW 映射（新表）
+
+### 依赖
+- P1（FDW 基础设施就绪后才能验证端到端）
+
+### 验收标准
+- SPI 指数可正常计算并写入，展示分 0-10 分布合理
+- 四项助教流水统计数值正确（对照 PRD 示例验算）
+- 消费汇总表新字段有值
+- 定档折算惩罚字段在符合条件的订单上正确填充
+
+### 四项统计命名方案（Q1.3）
+
+| 序号 | 中文名 | 英文字段名 | 含义 |
+|------|--------|-----------|------|
+| 1 | 订单总流水 | `order_gross_revenue` | 助教参与订单的全部流水 |
+| 2 | 订单净流水 | `order_net_revenue` | 订单总流水 - 助教服务分成 |
+| 3 | 时效贡献流水 | `time_weighted_revenue` | 按服务时长折算的助教个人贡献 |
+| 4 | 时效净贡献 | `time_weighted_net_revenue` | 时效贡献流水 - 助教服务分成 |
+
+---
+
+## P3：用户认证层 — 微信登录 + 申请审核 + 权限体系
+
+### SPEC 名称建议：`miniapp-auth-system`
+
+### 需求概述
+构建小程序的完整用户认证体系，包括微信登录、用户申请、审核流程、RBAC 权限、用户-助教绑定。
+
+### 关键交付物
+1. 新建表：`auth.users`（重构，增加 wx_openid、status、site_id 等）、`auth.user_applications`、`auth.site_code_mapping`、`auth.user_assistant_binding`
+2. 重构现有 `public.roles`、`public.permissions`、`public.user_roles`、`public.role_permissions` 迁移至 `auth` Schema
+3. 后端 API：微信 code2Session 登录、用户申请提交、JWT 签发
+4. 后端 API：用户状态查询（审核中/通过/拒绝）
+5. 权限中间件：基于角色的 API 访问控制
+
+### 依赖
+- P1（`auth` Schema 已创建）
+
+### 验收标准
+- 微信登录 → 新用户自动创建申请记录
+- 申请状态正确流转（pending → approved/rejected）
+- JWT 签发与验证正常
+- 权限中间件正确拦截无权请求
+
+---
+
+## P4：核心业务层 — 任务系统 + 备注系统 + 触发器机制
+
+### SPEC 名称建议：`miniapp-core-business`
+
+### 需求概述
+实现小程序的核心业务逻辑：助教任务生成/管理、备注系统、后台触发器/轮询机制。
+
+### 关键交付物
+
+#### 任务系统
+1. 新建表：`biz.coach_tasks`、`biz.coach_task_history`
+2. 任务生成器：每日 4:00 后运行，基于指数计算为每个助教分配任务
+3. 任务类型：高优先召回、优先召回、客户回访、关系构建（优先级从高到低）
+4. 任务状态机：有效/无效 + 有效期机制
+5. 48 小时回访滞留逻辑
+6. 召回完成检测（ETL 数据到达后自动标记）
+7. 数据回溯机制（召回完成后回溯备注分类）
+8. 任务置顶/放弃 API
+
+#### 备注系统
+9. 新建表：`biz.notes`（type 区分：普通/回访/生日/放弃原因）
+10. 备注 CRUD API
+11. 生日信息隔离存储（不被 ETL 数据覆盖）
+
+#### 触发器机制
+12. 新建表：`biz.trigger_jobs`（触发器配置与执行日志）
+13. 轮询调度框架：支持按条件触发（数据变更、定时、事件驱动）
+14. 任务状态轮询（每小时检查有效期）
+
+### 依赖
+- P1（数据库基础）
+- P2（指数数据可用，用于任务生成器）
+- P3（用户认证，知道当前助教身份）
+
+### 验收标准
+- 任务生成器正确按指数分配 4 种类型任务
+- 同客户-助教-类型跳过，不同类型关闭旧任务+新建
+- 48 小时滞留机制正常工作
+- 召回完成后自动标记任务完成
+- 数据回溯正确将普通备注重分类为回访备注
+- 备注 CRUD 正常，生日信息独立存储
+
+---
+
+## P5：AI 集成层 — 百炼对接 + 对话系统 + 轮询缓存
+
+### SPEC 名称建议：`miniapp-ai-integration`
+
+### 需求概述
+对接阿里云百炼 6 个 AI 应用，实现对话系统、后台轮询缓存、备注含金量评分。
+
+### 关键交付物
+1. 新建表：`biz.ai_conversations`、`biz.ai_messages`、`biz.ai_cache`
+2. 百炼 API 封装：统一调用层（支持流式/非流式）
+3. 应用 1：通用对话 API（SSE 流式返回）
+4. 应用 2：财务洞察轮询任务（每日更新，多时间维度交叉）
+5. 应用 3：客户消费习惯分析轮询（客户新增消费时触发）
+6. 应用 4：客户-助教关系分析轮询（助教参与新结算时触发）
+7. 应用 5：话术参考（应用 4 调用时联动）
+8. 应用 6：备注含金量评分（回访任务完成时触发）
+9. AI 结果缓存读写 API
+10. 页面内容文本化工具（将页面数据转为 AI 可读文本）
+
+### 依赖
+- P3（用户身份，AI 信息隔离需要传入身份参数）
+- P4（备注系统 + 触发器机制，应用 6 依赖回访任务完成事件）
+
+### 验收标准
+- 应用 1 流式对话正常
+- 应用 2-5 轮询任务按条件触发并缓存结果
+- 应用 6 在回访备注提交后自动评分，6 分以上标记完成
+- 所有 AI 对话记录持久化（含系统调用）
+
+---
+
+## P6：小程序前端 — 任务模块
+
+### SPEC 名称建议：`miniapp-fe-tasks`
+
+### 需求概述
+实现小程序任务相关页面：task-list、task-detail、notes。
+
+### 关键交付物
+1. task-list.html → 小程序页面：任务列表（按优先级分组）、长按操作（置顶/放弃/AI）、绩效计算展示、跳档激励
+2. task-detail.html → 小程序页面：任务详情、近期服务记录、备注入口、AI 分析展示（消费习惯/关系分析/话术/备注星级）
+3. notes.html → 小程序页面：备注列表、删除（二次确认）
+4. 通用组件：爱心 icon（💖🧡💛💙）、喜好标签（🎱斯🀅🎤）、跟/弃 icon、预估标记
+
+### 依赖
+- P3（登录态）
+- P4（任务/备注 API）
+- P5（AI 缓存数据展示）
+
+---
+
+## P7：小程序前端 — 绩效模块
+
+### SPEC 名称建议：`miniapp-fe-performance`
+
+### 需求概述
+实现绩效相关页面：performance、performance-records。
+
+### 关键交付物
+1. performance.html → 小程序页面：收入与业绩档位、服务记录明细（按天归总）、我的新客、我的常客
+2. performance-records.html → 小程序页面：按口径展示全部业绩、定档折算惩罚展示
+3. 后端 API：绩效数据聚合查询（按天/月归总）
+
+### 依赖
+- P3（登录态）
+- P2（定档折算字段）
+
+---
+
+## P8：小程序前端 — 看板模块
+
+### SPEC 名称建议：`miniapp-fe-boards`
+
+### 需求概述
+实现三个看板页面：board-finance、board-customer、board-coach。
+
+### 关键交付物
+1. board-finance.html → 小程序页面：财务数据展示、多维度筛选交叉、环比、AI 洞察、预收资产条件隐藏
+2. board-customer.html → 小程序页面：8 个维度筛选（最应召回/最大消费潜力/最高余额/最近充值/最高消费/最频繁/最近到店/最专一）、类型筛选、前 100 名列表
+3. board-coach.html → 小程序页面：维度筛选（定档业绩/工资/高客源储值/任务完成）、项目筛选、日期维度筛选
+4. 后端 API：看板数据聚合查询 + 缓存层
+5. 通用组件：时间筛选器、维度筛选器、环比展示
+
+### 依赖
+- P3（登录态 + 权限控制看板可见性）
+- P2（SPI 指数用于"最大消费潜力"排序）
+- P5（AI 财务洞察缓存）
+
+---
+
+## P9：小程序前端 — 详情与对话模块
+
+### SPEC 名称建议：`miniapp-fe-details`
+
+### 需求概述
+实现详情页和 AI 对话页：customer-detail、coach-detail、customer-service-records、chat、chat-history。
+
+### 关键交付物
+1. customer-detail.html → 小程序页面：客户信息、消费记录（台桌/商城/充值三种样式）、指数总览、备注、AI 入口
+2. coach-detail.html → 小程序页面：助教信息、客户数、工龄、备注
+3. customer-service-records.html → 小程序页面：服务记录列表
+4. chat.html → 小程序页面：AI 对话（流式展示）、来源展示、历史消息
+5. chat-history.html → 小程序页面：对话历史列表
+6. 后端 API：消费记录分页查询（懒加载，每次 10 条）
+
+### 依赖
+- P3（登录态）
+- P5（AI 对话系统）
+- P4（备注系统）
+
+---
+
+## P10：租户管理后台
+
+### SPEC 名称建议：`tenant-admin-web`
+
+### 需求概述
+独立的租户管理 Web 应用，提供用户审核、用户管理、Excel 数据上传功能。
+
+### 关键交付物
+1. 独立 Web 应用（React + Vite + Ant Design，类似 `apps/admin-web/` 技术栈）
+2. 租户管理员登录（独立凭据体系）
+3. 用户审核页面：申请列表、状态筛选、关联建议（球房ID+手机号匹配助教）、审核操作
+4. 用户管理页面：用户列表、身份编辑、店铺归属编辑
+5. Excel 上传页面：4 种模板（财务支出/团购收入/助教奖罚/充值业绩归属）
+6. Excel 校验：必填、金额精度、表头格式、类型合法
+7. 冲突处理：前端 diff 交互（逐条确认替换/保留）
+8. 后端 API：Excel 解析、校验、冲突检测、确认写入
+9. 新建表：`biz.salary_adjustments`、`biz.excel_upload_log`
+
+### 依赖
+- P1（数据库基础）
+- P3（用户体系，共享 `auth` Schema）
+
+### 验收标准
+- 租户管理员只能看到自己租户下的店铺数据
+- Excel 上传校验正确，冲突 diff 交互可用
+- 用户审核流程完整（申请→审核→分配身份→关联助教）
+
+---
+
+## P11：部署与上线
+
+### SPEC 名称建议：`deployment-launch`
+
+### 需求概述
+完成部署环境配置、监控、灰度上线。参考 `docs/deployment/LAUNCH-CHECKLIST.md`。
+
+### 关键交付物
+1. 生产环境数据库初始化（`etl_feiqiu` + `zqyy_app`）
+2. FDW 生产环境配置
+3. 后端部署（FastAPI + Uvicorn）
+4. 小程序审核与发布
+5. 租户管理后台部署
+6. ETL 定时调度配置（每小时增量）
+7. 监控与告警
+8. 灰度上线方案
+
+### 依赖
+- P1-P10 全部完成
+
+---
+
+## 附：SPEC 依赖关系图
+
+```
+P1 ─────┬──→ P2 ──→ P7
+        │          ↘
+        ├──→ P3 ──→ P4 ──→ P5 ──→ P6
+        │     │           ↗       ↘
+        │     └──→ P10    P8 ←── P9
+        │
+        └──→ P11（全部完成后）
+```
+
+可并行的 SPEC 组合：
+- P2 和 P3 可并行（无互相依赖）
+- P6、P7、P8、P9 在后端 API 就绪后可部分并行
+- P10 在 P1+P3 完成后即可启动，与 P4-P9 并行

docs/prd/specs/P1-miniapp-db-foundation.md

@@ -0,0 +1,63 @@
+# P1：基础设施层 — miniapp-db-foundation
+
+> 优先级：P1（最高，无前置依赖）
+> 预估工作量：中等
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为后端开发者，我需要 `test_zqyy_app` 中有清晰的 Schema 划分（`auth` + `biz`），以便按功能组织业务表。
+2. 作为后端开发者，我需要通过 FDW 从 `test_zqyy_app` 读取 ETL 库的 DWS/DWD 数据，以便小程序页面展示 ETL 计算结果。
+3. 作为系统管理员，我需要 RLS 视图按 `site_id` 隔离数据，以便多门店数据安全。
+
+### 验收标准
+
+- AC1：`test_zqyy_app` 中存在 `auth` 和 `biz` 两个 Schema，权限配置正确
+- AC2：`test_etl_feiqiu.app` Schema 中为数据依赖矩阵列出的所有表创建了 RLS 视图
+- AC3：`test_zqyy_app.fdw_etl` 中所有外部表可正常 `SELECT`，数据与源表一致
+- AC4：RLS 视图在设置 `app.current_site_id` 后正确过滤数据
+- AC5：所有变更有对应的迁移脚本（`db/zqyy_app/migrations/` + `db/etl_feiqiu/migrations/`）
+
+---
+
+## 设计要点
+
+### Schema 规划
+
+```
+test_zqyy_app
+├── auth        — 用户认证、权限、映射
+├── biz         — 业务数据（任务、备注、AI、Excel）
+├── fdw_etl     — FDW 外部表（只读，映射 ETL app schema）
+└── public      — 保留现有系统管理表（admin_users 等）
+```
+
+### RLS 实现方案
+
+```sql
+-- ETL 库 app schema 示例
+CREATE VIEW app.v_dws_member_consumption_summary AS
+SELECT * FROM dws.dws_member_consumption_summary
+WHERE site_id = current_setting('app.current_site_id')::bigint;
+```
+
+### FDW 映射
+
+- 使用 `postgres_fdw` 扩展
+- 外部服务器指向 `test_etl_feiqiu`
+- 外部表映射 `app` schema 的 RLS 视图（而非直接映射 dws/dwd 表）
+- 映射表清单见 `00-数据依赖矩阵.md` 第四节
+
+---
+
+## 任务清单
+
+- [ ] T1：创建 `auth` 和 `biz` Schema + 权限配置
+- [ ] T2：在 `test_etl_feiqiu.app` 中创建全部 RLS 视图（约 33 张）
+- [ ] T3：配置 `postgres_fdw` 外部服务器和用户映射
+- [ ] T4：在 `fdw_etl` 中创建全部外部表
+- [ ] T5：编写验证脚本（检查所有外部表可查询）
+- [ ] T6：编写迁移脚本并归档

docs/prd/specs/P10-tenant-admin-web.md

@@ -0,0 +1,133 @@
+# P10：租户管理后台 — tenant-admin-web
+
+> 优先级：P10（依赖 P1 + P3，可与 P4-P9 并行）
+> 预估工作量：中等
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为租户管理员，我需要独立的 Web 管理后台来审核用户申请。
+2. 作为租户管理员，我需要管理用户（编辑身份、店铺归属、关联助教）。
+3. 作为租户管理员，我需要上传 Excel 数据（财务支出/团购收入/助教奖罚/充值业绩归属）。
+4. 作为租户管理员，上传 Excel 时如果发现主键冲突，我需要逐条确认替换或保留（类似 diff 交互）。
+5. 作为系统，租户管理员只能看到自己租户下的店铺数据。
+
+### 验收标准
+
+- AC1：租户管理后台是独立 Web 应用，独立登录入口
+- AC2：租户管理员只能看到自己租户下的店铺和用户
+- AC3：用户审核页面：申请列表、状态筛选、球房ID+手机号关联建议、审核操作
+- AC4：Excel 上传校验：必填、金额精度、表头格式、类型合法
+- AC5：主键冲突时前端展示 diff 交互，逐条确认后保存
+- AC6：助教奖罚支持同一助教同月多笔
+
+---
+
+## 设计要点
+
+### 技术栈
+
+- 独立 Web 应用：React + Vite + Ant Design（与 `apps/admin-web/` 同技术栈）
+- 部署路径：`apps/tenant-admin/`
+- 后端复用 `apps/backend/` 的 FastAPI，新增租户管理路由模块
+
+### 登录体系
+
+- 独立凭据：每个租户有若干管理员账号（用户名+密码）
+- 租户级管理员：可管理租户下所有店铺
+- 店铺级管理员：只能管理指定店铺
+- 与系统管理后台（`apps/admin-web/`）完全隔离
+
+### Excel 4 种模板
+
+#### 1. 财务支出（按月）
+
+| 列名 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| 月份 | YYYY-MM | 是 | 提交月份 |
+| 支出类别 | 文本 | 是 | 房租/水电/物业/食品饮料进货/耗材/报销/固定人员工资/其他费用 |
+| 金额 | 数值(2) | 是 | 支出金额 |
+| 备注 | 文本 | 否 | |
+
+主键：月份 + 支出类别
+
+#### 2. 团购平台收入（按月）
+
+| 列名 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| 月份 | YYYY-MM | 是 | |
+| 平台名称 | 文本 | 是 | |
+| 收入金额 | 数值(2) | 是 | |
+| 备注 | 文本 | 否 | |
+
+主键：月份 + 平台名称
+
+#### 3. 助教奖罚（按月）
+
+| 列名 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| 月份 | YYYY-MM | 是 | |
+| 助教姓名 | 文本 | 是 | |
+| 助教编号 | 文本 | 是 | |
+| 类型 | 文本 | 是 | 扣款/奖金 |
+| 金额 | 数值(2) | 是 | |
+| 原因 | 文本 | 是 | |
+
+主键：月份 + 助教姓名 + 助教编号 + 类型 + 原因（同一助教同月可多笔）
+
+#### 4. 充值业绩归属（按月）
+
+| 列名 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| 充值日期 | YYYY-MM-DD | 是 | |
+| 会员名称 | 文本 | 是 | |
+| 充值金额 | 数值(2) | 是 | |
+| 归属助教 | 文本 | 是 | |
+| 奖励金额 | 数值(2) | 是 | |
+
+主键：充值日期 + 会员名称 + 归属助教
+
+### 冲突处理流程
+
+```
+上传 Excel → 后端解析+校验 → 返回校验结果
+  ├── 无冲突 → 直接写入
+  └── 有冲突 → 返回冲突列表（旧值 vs 新值）
+        → 前端展示 diff 交互
+        → 用户逐条选择"替换"或"保留"
+        → 提交确认 → 后端按选择写入
+```
+
+### 新建表
+
+```
+biz.salary_adjustments
+  - id, site_id, assistant_id, assistant_name, assistant_number
+  - salary_month, adjustment_type (deduction/bonus)
+  - amount, reason
+  - upload_batch_id, created_at
+
+biz.excel_upload_log
+  - id, site_id, upload_type (expense/platform_income/salary_adj/recharge_commission)
+  - file_name, uploaded_by, row_count
+  - conflict_count, resolved_count
+  - status (pending/confirmed/failed)
+  - created_at
+```
+
+---
+
+## 任务清单
+
+- [ ] T1：创建 `apps/tenant-admin/` 项目骨架（React + Vite + Ant Design）
+- [ ] T2：实现租户管理员登录（独立凭据）
+- [ ] T3：实现用户审核页面（申请列表 + 状态筛选 + 关联建议 + 审核操作）
+- [ ] T4：实现用户管理页面（用户列表 + 身份编辑 + 店铺归属）
+- [ ] T5：创建 `biz.salary_adjustments` + `biz.excel_upload_log` 表
+- [ ] T6：实现 Excel 上传后端（解析 + 校验 + 冲突检测）
+- [ ] T7：实现 Excel 上传前端（模板下载 + 上传 + diff 交互 + 确认）
+- [ ] T8：实现 4 种 Excel 模板的校验规则
+- [ ] T9：实现助教姓名+编号匹配校验（对照 `dim_assistant`）

docs/prd/specs/P11-deployment-launch.md

@@ -0,0 +1,59 @@
+# P11：部署与上线 — deployment-launch
+
+> 优先级：P11（依赖 P1-P10 全部完成）
+> 预估工作量：中等
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为运维，我需要将全部系统部署到生产环境并完成上线。
+2. 作为运维，我需要监控系统运行状态和告警。
+3. 作为产品经理，我需要灰度上线方案以降低风险。
+
+### 验收标准
+
+- AC1：生产环境数据库初始化完成（`etl_feiqiu` + `zqyy_app`）
+- AC2：FDW 生产环境配置正确
+- AC3：后端 API 可正常访问
+- AC4：小程序审核通过并发布
+- AC5：租户管理后台可正常访问
+- AC6：ETL 定时调度正常运行（每小时增量）
+- AC7：监控告警配置完成
+
+---
+
+## 关键交付物
+
+1. 生产环境数据库初始化脚本
+2. FDW 生产环境配置（`etl_feiqiu` → `zqyy_app`）
+3. 后端部署配置（FastAPI + Uvicorn + Nginx）
+4. 小程序审核材料准备与提交
+5. 租户管理后台部署
+6. ETL 定时调度配置（cron / systemd timer）
+7. 监控方案（数据库连接、API 响应、ETL 执行状态）
+8. 灰度上线方案（先单店 → 多店 → 全量）
+9. 回滚方案
+
+---
+
+## 参考
+
+- 现有部署清单：`docs/deployment/LAUNCH-CHECKLIST.md`
+- 环境配置：`.env.template`
+
+---
+
+## 任务清单
+
+- [ ] T1：生产环境数据库初始化（Schema + 表 + 种子数据）
+- [ ] T2：生产环境 FDW 配置
+- [ ] T3：后端部署（含 HTTPS、CORS、JWT 生产配置）
+- [ ] T4：小程序审核与发布
+- [ ] T5：租户管理后台部署
+- [ ] T6：ETL 定时调度配置
+- [ ] T7：监控与告警配置
+- [ ] T8：灰度上线执行
+- [ ] T9：更新 `LAUNCH-CHECKLIST.md`

docs/prd/specs/P2-etl-dws-miniapp-extensions.md

@@ -0,0 +1,69 @@
+# P2：ETL 扩展层 — etl-dws-miniapp-extensions
+
+> 优先级：P2（依赖 P1）
+> 预估工作量：大
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为产品经理，我需要 SPI 消费力指数来评估客户消费层级，替代现有的 `customer_tier` 分层。
+2. 作为产品经理，我需要助教订单流水四项统计（订单总流水/订单净流水/时效贡献流水/时效净贡献），以便评估助教个人能力。
+3. 作为产品经理，我需要客户 30/60/90 天充值次数和金额、次均消费，以便在客户看板中展示。
+4. 作为产品经理，我需要定档折算惩罚数据，以便在绩效页面展示折算详情。
+
+### 验收标准
+
+- AC1：`dws_member_spending_power_index` 表存在，SPI 展示分 0-10 分布合理
+- AC2：`dws_assistant_order_contribution` 表存在，四项统计数值可对照 PRD 示例验算
+- AC3：`dws_member_consumption_summary` 新增字段有值（`recharge_count_30d/60d/90d`、`recharge_amount_30d/60d/90d`、`avg_ticket_amount`）
+- AC4：`dws_assistant_daily_detail` 新增字段在符合惩罚条件的订单上正确填充
+- AC5：新表的 RLS 视图和 FDW 映射已同步创建
+- AC6：`cfg_index_parameters` 中新增 `SPI` 类型的配置行
+
+---
+
+## 设计要点
+
+### SPI 指数
+- 完整算法见 `docs/prd/SPI 消费力指数.md`
+- 新建 ETL 任务 `SpendingPowerIndexTask`，继承 `BaseIndexTask`
+- 粒度：`(site_id, member_id)`，每日计算
+
+### 助教订单流水四项统计
+- 新建 ETL 任务 `AssistantOrderContributionTask`
+- 粒度：`(site_id, assistant_id, stat_date)`
+- 计算逻辑见 PRD "新增统计"节
+
+### 命名方案
+
+| 中文名 | 字段名 | 含义 |
+|--------|--------|------|
+| 订单总流水 | `order_gross_revenue` | 助教参与订单的全部流水 |
+| 订单净流水 | `order_net_revenue` | 总流水 - 助教服务分成 |
+| 时效贡献流水 | `time_weighted_revenue` | 按服务时长折算的个人贡献 |
+| 时效净贡献 | `time_weighted_net_revenue` | 时效贡献 - 助教服务分成 |
+
+### 定档折算惩罚
+- 扩展 `dws_assistant_daily_detail`：`penalty_minutes`、`penalty_reason`、`is_exempt`、`per_hour_contribution`
+- 检测逻辑：同一台桌同一时段 >2 名助教 → 计算单人贡献流水 → <24 元则按比例折算
+- 豁免标记：在订单级别打标（`is_exempt` 字段）
+- 每日 ETL 自动计算
+
+---
+
+## 任务清单
+
+- [ ] T1：设计并创建 `dws_member_spending_power_index` 表
+- [ ] T2：实现 `SpendingPowerIndexTask`（含 Level/Speed/Stability 子分）
+- [ ] T3：在 `cfg_index_parameters` 中插入 SPI 默认参数
+- [ ] T4：设计并创建 `dws_assistant_order_contribution` 表
+- [ ] T5：实现 `AssistantOrderContributionTask`
+- [ ] T6：扩展 `dws_member_consumption_summary`（充值窗口 + 次均消费字段）
+- [ ] T7：修改 `MemberConsumptionSummaryTask` 填充新字段
+- [ ] T8：扩展 `dws_assistant_daily_detail`（定档折算惩罚字段）
+- [ ] T9：实现定档折算惩罚检测与计算逻辑
+- [ ] T10：为新表创建 RLS 视图 + FDW 映射
+- [ ] T11：影子跑数验证（SPI 分布、流水统计对账）

docs/prd/specs/P3-miniapp-auth-system.md

@@ -0,0 +1,88 @@
+# P3：用户认证层 — miniapp-auth-system
+
+> 优先级：P3（依赖 P1，可与 P2 并行）
+> 预估工作量：中等
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为球房工作人员，我需要通过微信登录小程序，首次登录时填写申请表单（球房ID、申请身份、手机号、编号、昵称）。
+2. 作为租户管理员，我需要审核用户申请，将用户关联到对应的助教/员工，并分配身份权限。
+3. 作为系统，我需要通过球房ID+手机号自动建议用户与助教的对应关系。
+4. 作为用户，我需要看到自己的申请状态（审核中/通过/拒绝）。
+5. 作为用户，我可以同时属于多个店铺（连锁场景），权限按店铺独立。
+
+### 验收标准
+
+- AC1：微信 code2Session 登录正常，返回 JWT
+- AC2：新用户首次登录后进入申请页面，提交后状态为 pending
+- AC3：管理员审核通过后，用户状态变为 approved，可正常访问小程序
+- AC4：球房ID 不存在时，申请仍可提交，管理端显示"未找到关联信息"
+- AC5：权限中间件正确拦截无权请求（如助教不能看财务看板）
+- AC6：一个用户可关联多个店铺，切换店铺后数据正确隔离
+
+---
+
+## 设计要点
+
+### 表结构
+
+```
+auth.users
+  - id, wx_openid, wx_union_id, wx_avatar_url, nickname, phone
+  - status (pending/approved/rejected/disabled)
+  - created_at, updated_at
+
+auth.user_applications
+  - id, user_id, site_code (球房ID文本), applied_role_text (自由文本)
+  - employee_number (选填), status, reviewer_id, review_note
+  - created_at, reviewed_at
+
+auth.site_code_mapping
+  - id, site_code (2字母+3数字), site_id (ETL bigint), site_name
+  - tenant_id, created_at
+
+auth.user_site_roles
+  - id, user_id, site_id, role_id
+  - created_at
+
+auth.user_assistant_binding
+  - id, user_id, site_id, assistant_id (ETL dim_assistant)
+  - binding_type (assistant/staff/manager)
+  - created_at
+```
+
+### 权限列表（固定）
+
+| 权限 code | 说明 |
+|-----------|------|
+| `view_tasks` | 任务板块可见 |
+| `view_board` | 看板板块可见 |
+| `view_board_finance` | 财务板块可见 |
+| `view_board_customer` | 客户板块可见 |
+| `view_board_coach` | 助教板块可见 |
+
+### 租户层级
+
+```
+租户 (tenant)
+  └── 店铺 (site) ← site_code 映射
+        └── 用户 (user) ← 可属于多个 site
+              └── 角色 (role) ← 按 site 独立分配
+```
+
+---
+
+## 任务清单
+
+- [ ] T1：创建 `auth` Schema 下全部表（users, user_applications, site_code_mapping, user_site_roles, user_assistant_binding）
+- [ ] T2：迁移现有 RBAC 表到 `auth` Schema（或保留 public 但建立关联）
+- [ ] T3：实现微信 code2Session 登录 API
+- [ ] T4：实现用户申请提交 API
+- [ ] T5：实现 JWT 签发与刷新
+- [ ] T6：实现权限中间件（基于 user_site_roles）
+- [ ] T7：实现用户状态查询 API
+- [ ] T8：种子数据：预置权限列表和默认角色

docs/prd/specs/P4-miniapp-core-business.md

@@ -0,0 +1,102 @@
+# P4：核心业务层 — miniapp-core-business
+
+> 优先级：P4（依赖 P1 + P2 + P3）
+> 预估工作量：大（本 SPEC 是业务核心）
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为助教，我每天打开小程序能看到系统为我分配的任务列表，按优先级排序。
+2. 作为助教，我可以置顶/放弃任务，放弃时必须填写原因。
+3. 作为助教，我完成召回任务后（客户到店被服务），系统自动标记任务完成。
+4. 作为助教，我给客户添加回访备注后，系统自动评估备注含金量（≥6 分算完成）。
+5. 作为系统，回访任务至少保留 48 小时，到期后自动失效。
+6. 作为系统，当 ETL 数据延迟导致召回完成晚于备注提交时，需要回溯重分类备注。
+
+### 验收标准
+
+- AC1：任务生成器每日 4:00 后运行，正确按 max(WBI,NCI) 分配 4 种任务类型
+- AC2：同客户-助教-类型的任务跳过；不同类型则关闭旧任务+新建
+- AC3：回访任务 48 小时滞留机制正常（生成时间算起）
+- AC4：任务有效/无效状态 + 有效期字段正确流转
+- AC5：召回完成检测在 ETL 数据到达后自动触发
+- AC6：数据回溯将普通备注重分类为回访备注并触发 AI 评分
+- AC7：备注 CRUD 正常，type 字段正确区分
+- AC8：生日信息独立于 ETL 数据，不被覆盖
+
+---
+
+## 设计要点
+
+### 任务类型与优先级
+
+| 优先级 | 类型 | 触发条件 | 完成条件 |
+|--------|------|---------|---------|
+| 0 | 高优先召回 | max(WBI,NCI) > 7 | 助教为该客户服务（ETL 检测） |
+| 0 | 优先召回 | max(WBI,NCI) > 5 | 同上 |
+| 1 | 客户回访 | 完成召回后未备注 | 提交备注且 AI 评分 ≥ 6 |
+| 2 | 关系构建 | RS < 6 | 无自动完成条件（手动标记或指数变化） |
+
+### 任务状态机
+
+```
+[生成] → 有效(无有效期)
+  ├── 类型变更 → 旧任务无效(无有效期) + 新任务有效
+  ├── 指数不再满足 → 有效(填充有效期=生成时间+48h)
+  │     └── 轮询检查 → 超过有效期 → 无效
+  ├── 新回访任务顶替 → 旧任务无效 + 新任务有效
+  ├── 助教放弃 → 无效(记录放弃原因)
+  └── 完成 → 已完成(记录完成时间和完成时状态)
+```
+
+### coach_tasks 表核心字段
+
+```
+biz.coach_tasks
+  - id, site_id, assistant_id, member_id
+  - task_type (high_priority_recall / priority_recall / follow_up_visit / relationship_building)
+  - status (active / inactive / completed / abandoned)
+  - priority_score (max(WBI,NCI) 快照)
+  - expires_at (有效期，默认 NULL)
+  - is_pinned (置顶)
+  - abandon_reason (放弃原因)
+  - completed_at, completed_task_type (完成时的任务类型快照)
+  - parent_task_id (被顶替的旧任务 ID)
+  - created_at, updated_at
+```
+
+### 触发器机制
+
+```
+biz.trigger_jobs
+  - id, job_type, job_name
+  - trigger_condition (cron / event / interval)
+  - trigger_config (JSON: cron表达式 / 事件名 / 间隔秒数)
+  - last_run_at, next_run_at
+  - status (enabled / disabled)
+  - created_at
+```
+
+预置触发器：
+1. `task_generator` — cron: 每日 04:00
+2. `task_expiry_check` — interval: 每小时
+3. `recall_completion_check` — event: ETL 数据更新后
+4. `note_reclassify_backfill` — event: 召回完成时
+
+---
+
+## 任务清单
+
+- [ ] T1：创建 `biz.coach_tasks` + `biz.coach_task_history` 表
+- [ ] T2：创建 `biz.notes` 表（type: normal/follow_up/birthday/abandon_reason）
+- [ ] T3：创建 `biz.trigger_jobs` 表 + 轮询调度框架
+- [ ] T4：实现任务生成器（读取指数 → 分配任务 → 跳过/更新逻辑）
+- [ ] T5：实现 48 小时滞留机制 + 有效期轮询
+- [ ] T6：实现召回完成检测（ETL 数据到达后匹配 service_log）
+- [ ] T7：实现数据回溯机制（普通备注 → 回访备注 + 触发 AI 评分）
+- [ ] T8：实现任务 CRUD API（列表/详情/置顶/放弃/取消置顶/取消放弃）
+- [ ] T9：实现备注 CRUD API（创建/列表/删除）
+- [ ] T10：实现生日信息隔离存储逻辑

docs/prd/specs/P5-miniapp-ai-integration.md

@@ -0,0 +1,96 @@
+# P5：AI 集成层 — miniapp-ai-integration
+
+> 优先级：P5（依赖 P3 + P4）
+> 预估工作量：大
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为助教，我可以在任意页面点击 AI 按钮，跳转到对话页面与 AI 交流，AI 了解当前页面上下文。
+2. 作为助教，我在任务详情页能看到 AI 生成的消费习惯分析、关系分析、话术参考。
+3. 作为助教，我提交回访备注后，系统自动通过 AI 评估备注含金量。
+4. 作为管理者，我在财务看板能看到 AI 生成的财务洞察分析。
+5. 作为系统，所有 AI 对话（含系统调用）都要持久化记录。
+
+### 验收标准
+
+- AC1：应用 1 通用对话支持流式返回（SSE），前端逐字展示
+- AC2：应用 2 财务洞察每日自动更新，覆盖 8 个时间维度
+- AC3：应用 3 消费习惯在客户新增消费时自动更新
+- AC4：应用 4+5 在助教参与新结算时联动更新
+- AC5：应用 6 在回访备注提交后自动评分，返回 1-10 分 + 评价文本
+- AC6：所有 AI 调用记录持久化（conversation_id, message_id, app_id, user_id/系统, role, content, tokens_used, nickname, created_at, site_id）
+
+---
+
+## 设计要点
+
+### 6 个 AI 应用
+
+| 应用 | 用途 | 调用方式 | 触发条件 |
+|------|------|---------|---------|
+| 应用 1 | 通用对话 | 用户主动（流式） | 点击 AI 入口 |
+| 应用 2 | 财务洞察 | 后台轮询 | 每日 |
+| 应用 3 | 消费习惯分析 | 后台轮询 | 客户新增消费 |
+| 应用 4 | 关系分析/任务建议 | 后台轮询 | 助教参与新结算 |
+| 应用 5 | 话术参考 | 后台联动 | 应用 4 调用时 |
+| 应用 6 | 备注含金量 | 后台事件 | 回访任务完成时 |
+
+### 信息隔离
+
+应用 1 通过 `biz_params.user_prompt_params` 传入：
+- `User_ID`：当前用户 ID
+- `Role`：身份（助教/管理者）
+- `Nickname`：昵称
+
+百炼平台侧根据参数做数据查询隔离。
+
+### AI 入口汇总
+
+所有入口统一使用应用 1，跳转 chat.html，第一条消息为页面上下文：
+
+| 来源页面 | 触发方式 | 上下文内容 |
+|---------|---------|-----------|
+| task-list | 长按任务 → AI | 任务详情 + 客户-助教关系 |
+| task-detail / coach-detail / customer-detail | "问问助手" | 页面完整内容 |
+| board-* / performance-* / customer-service-records / my-profile | 右下角 AI 按钮 | 页面内容摘要 |
+
+### 表结构
+
+```
+biz.ai_conversations
+  - id, user_id, nickname, app_id, site_id
+  - source_page, source_context (JSON)
+  - created_at
+
+biz.ai_messages
+  - id, conversation_id, role (user/assistant/system)
+  - content, tokens_used
+  - created_at
+
+biz.ai_cache
+  - id, cache_type (app2_finance/app3_habit/app4_analysis/app5_tactics/app6_score)
+  - site_id, target_id (member_id 或 assistant_id 或 pair)
+  - result_json, score (应用6专用)
+  - triggered_by (trigger_job_id)
+  - created_at, expires_at
+```
+
+---
+
+## 任务清单
+
+- [ ] T1：创建 `biz.ai_conversations` + `biz.ai_messages` + `biz.ai_cache` 表
+- [ ] T2：实现百炼 API 统一封装层（流式/非流式、重试、日志）
+- [ ] T3：实现应用 1 通用对话 API（SSE 流式返回）
+- [ ] T4：实现页面内容文本化工具（各页面数据 → AI 可读文本）
+- [ ] T5：实现应用 2 财务洞察轮询任务
+- [ ] T6：实现应用 3 消费习惯分析轮询任务
+- [ ] T7：实现应用 4 关系分析轮询任务
+- [ ] T8：实现应用 5 话术参考联动任务
+- [ ] T9：实现应用 6 备注含金量评分（集成到回访完成事件）
+- [ ] T10：实现 AI 缓存读写 API（前端读取缓存结果）
+- [ ] T11：查阅百炼文档确认流式返回技术方案（SSE vs WebSocket）

docs/prd/specs/P6-miniapp-fe-tasks.md

@@ -0,0 +1,58 @@
+# P6：小程序前端 — 任务模块 — miniapp-fe-tasks
+
+> 优先级：P6（依赖 P3 + P4 + P5）
+> 预估工作量：大
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为助教，我打开小程序首页看到按优先级排序的任务列表，高优先召回在最上面。
+2. 作为助教，我长按任务可以置顶、放弃（需填原因）、或问 AI。
+3. 作为助教，我点击任务进入详情页，看到客户信息、近期服务记录、AI 分析、备注入口。
+4. 作为助教，我在绩效区域看到当月业绩、档位、工资预估、跳档激励。
+5. 作为助教，我能管理自己的备注（查看、删除需二次确认）。
+
+### 验收标准
+
+- AC1：任务列表按优先级 0→1→2 分组展示，每组内按分数降序
+- AC2：置顶任务固定在列表顶部，已放弃任务在独立列表
+- AC3：爱心 icon 正确展示（💖>8.5 / 🧡>7 / 💛>5 / 💙<5）
+- AC4：喜好标签正确展示（🎱/斯/🀅/🎤）
+- AC5：跟/弃 icon 正确展示
+- AC6：当月数据显示"预估"标记
+- AC7：跳档激励"到达XXX即得YYY"计算正确
+
+---
+
+## 页面清单
+
+### task-list（任务列表 + 绩效）
+- 任务列表：优先级分组、长按操作
+- 绩效区域：当月业绩/档位/工资/跳档激励
+- 通用组件：爱心 icon、喜好标签、跟/弃 icon
+
+### task-detail（任务详情）
+- 客户信息卡片
+- 近期服务记录（时间+时长）
+- AI 区域：消费习惯（应用3缓存）、关系分析+任务建议+一句话总结（应用4缓存）、话术参考（应用5缓存）、备注星级（应用6）
+- 备注入口（提交后触发回访完成判定）
+- "问问助手"按钮 → chat.html
+
+### notes（备注管理）
+- 备注列表
+- 删除操作（二次确认弹窗）
+
+---
+
+## 任务清单
+
+- [ ] T1：实现 task-list 页面（任务列表 + 分组 + 排序）
+- [ ] T2：实现长按操作（置顶/放弃/AI）
+- [ ] T3：实现绩效展示区域（业绩/档位/工资/跳档激励）
+- [ ] T4：实现 task-detail 页面（客户信息 + 服务记录 + AI 区域）
+- [ ] T5：实现备注提交功能（集成回访完成判定）
+- [ ] T6：实现 notes 页面（列表 + 删除）
+- [ ] T7：实现通用组件（爱心 icon、喜好标签、跟/弃 icon、预估标记）

docs/prd/specs/P7-miniapp-fe-performance.md

@@ -0,0 +1,67 @@
+# P7：小程序前端 — 绩效模块 — miniapp-fe-performance
+
+> 优先级：P7（依赖 P2 + P3）
+> 预估工作量：中等
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为助教，我在绩效页面能看到当月收入、业绩档位、工资预估。
+2. 作为助教，我能看到本月/上月的服务记录明细，按天归总。
+3. 作为助教，我能看到"我的新客"（首次服务且 2 月内服务 ≤2 次的客户）和"我的常客"（2 月内服务次数最多的客户）。
+4. 作为助教，我在业绩明细页能看到每条服务的详情，包括定档折算惩罚展示。
+
+### 验收标准
+
+- AC1：收入与业绩档位数据从 `dws_assistant_salary_calc` 正确读取
+- AC2：服务记录按天归总展示，支持本月/上月切换
+- AC3："我的新客"筛选逻辑正确（该助教首次服务 + 2 月内 + 服务次数 ≤2）
+- AC4："我的常客"按服务次数降序，展示次数、小时数、工资合计
+- AC5：业绩明细每条展示：结账时间、课程类型、台桌/房间、会员昵称、开始/结束时间、业绩分钟
+- AC6：有定档折算惩罚时展示"120分钟（定档折算30分钟）"格式
+- AC7：当月数据显示"预估"标记
+
+---
+
+## 页面清单
+
+### performance（我的绩效）
+
+- 收入与业绩档位卡片
+- 服务记录明细（按天归总，本月/上月切换）
+- 我的新客列表（按最后服务时间排列）
+- 我的常客列表（按服务次数降序）
+- 服务明细：按天/月归总整合数据
+
+### performance-records（业绩明细）
+
+- 口径选择（本月/上月/本周/上周等）
+- 业绩列表（每条含：结账时间、课程类型、台桌/房间、会员昵称、开始/结束时间、业绩分钟+折算展示）
+- 按天/月归总整合
+
+---
+
+## 后端 API 需求
+
+| API | 说明 | 数据源 |
+|-----|------|--------|
+| `GET /api/performance/summary` | 当月绩效汇总 | `fdw_etl.dws_assistant_salary_calc` |
+| `GET /api/performance/service-records` | 服务记录明细（分页） | `fdw_etl.dwd_assistant_service_log` |
+| `GET /api/performance/my-new-customers` | 我的新客列表 | `fdw_etl.dws_assistant_customer_stats` |
+| `GET /api/performance/my-regulars` | 我的常客列表 | `fdw_etl.dws_assistant_customer_stats` |
+| `GET /api/performance/records` | 业绩明细（按口径） | `fdw_etl.dwd_assistant_service_log` + `fdw_etl.dws_assistant_daily_detail` |
+
+---
+
+## 任务清单
+
+- [ ] T1：实现绩效汇总 API（含定档、工资、档位）
+- [ ] T2：实现服务记录明细 API（按天归总 + 分页）
+- [ ] T3：实现我的新客/常客 API
+- [ ] T4：实现业绩明细 API（含定档折算惩罚字段）
+- [ ] T5：实现 performance 小程序页面
+- [ ] T6：实现 performance-records 小程序页面
+- [ ] T7：实现"预估"标记组件（当月/本周数据自动标记）

docs/prd/specs/P8-miniapp-fe-boards.md

@@ -0,0 +1,85 @@
+# P8：小程序前端 — 看板模块 — miniapp-fe-boards
+
+> 优先级：P8（依赖 P2 + P3 + P5）
+> 预估工作量：大
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为管理者，我在财务看板能看到多维度交叉筛选的财务数据、环比、AI 洞察。
+2. 作为管理者，我在客户看板能按 8 个维度排序查看前 100 名客户。
+3. 作为管理者，我在助教看板能按业绩/工资/客源储值/任务完成等维度排序查看助教。
+4. 作为系统，看板数据需要缓存层以提升查询性能。
+
+### 验收标准
+
+- AC1：财务看板支持 2 组筛选交叉（区域 × 时间），选择非"全部区域"时预收资产板块消失
+- AC2：财务看板环比数据正确计算
+- AC3：财务看板 AI 洞察从缓存读取（应用 2 每日更新）
+- AC4：客户看板 8 个维度筛选正确（最应召回/最大消费潜力/最高余额/最近充值/最高消费60天/最频繁60天/最近到店/最专一）
+- AC5：客户看板"最专一"维度下类型筛选锁定为"不限"
+- AC6：助教看板维度×项目×日期三重筛选交叉正确
+- AC7：看板数据有缓存层，非每次实时查询 FDW
+
+---
+
+## 页面清单
+
+### board-finance（财务看板）
+
+- 筛选器：区域筛选 + 时间筛选（本月/上月/本周/上周/前3月/本季/上季/近6月）
+- 数据板块：收入结构、预收资产（条件隐藏）、支出汇总、平台结算
+- 环比展示
+- AI 智能洞察（应用 2 缓存结果）
+- "问问助手"入口 → chat.html
+
+### board-customer（客户看板）
+
+- 维度筛选（8 个维度，默认"最应召回"）
+- 类型筛选（全部/台球/斯诺克/麻将/团建 + 台费包厢流水过滤）
+- 筛选互斥规则："最专一"锁定类型为"不限"
+- 客户列表（前 100 名）
+- 每个客户卡片：昵称、爱心 icon、喜好标签、关键指标值
+- 右下角 AI 按钮 → chat.html
+
+### board-coach（助教看板）
+
+- 维度筛选：定档业绩最高/最低、工资最高/最低、高客源储值额最高、任务完成最多
+- 项目筛选：全部/中🎱/斯诺克/麻将/团建
+- 日期维度筛选：本月/上月/本周/上周/前3月/本季/上季/近6月
+- 助教列表
+- 右下角 AI 按钮 → chat.html
+
+---
+
+## 后端 API 需求
+
+| API | 说明 | 缓存 |
+|-----|------|------|
+| `GET /api/board/finance` | 财务看板数据（交叉筛选） | 是 |
+| `GET /api/board/finance/ai-insight` | 财务 AI 洞察 | 是（应用2缓存） |
+| `GET /api/board/customers` | 客户看板（维度+类型筛选） | 是 |
+| `GET /api/board/coaches` | 助教看板（维度×项目×日期） | 是 |
+
+### 缓存策略
+
+- 看板数据缓存层：Redis 或内存缓存
+- 缓存粒度：`site_id` + 筛选条件组合
+- 缓存过期：ETL 数据更新后失效（约 1 小时）
+- AI 洞察缓存：从 `biz.ai_cache` 读取（应用 2 每日更新）
+
+---
+
+## 任务清单
+
+- [ ] T1：实现看板缓存层（Redis/内存，按 site_id + 筛选条件）
+- [ ] T2：实现财务看板 API（交叉筛选 + 环比 + 预收资产条件隐藏）
+- [ ] T3：实现客户看板 API（8 维度排序 + 类型筛选 + 互斥规则）
+- [ ] T4：实现助教看板 API（维度×项目×日期三重筛选）
+- [ ] T5：实现 board-finance 小程序页面
+- [ ] T6：实现 board-customer 小程序页面
+- [ ] T7：实现 board-coach 小程序页面
+- [ ] T8：实现通用筛选器组件（时间/维度/项目）

docs/prd/specs/P9-miniapp-fe-details.md

@@ -0,0 +1,108 @@
+# P9：小程序前端 — 详情与对话模块 — miniapp-fe-details
+
+> 优先级：P9（依赖 P3 + P4 + P5）
+> 预估工作量：大
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为助教，我在客户详情页能看到客户全信息、消费记录（三种样式）、指数总览、备注、AI 分析。
+2. 作为助教，我在助教详情页能看到助教信息、客户数、工龄、备注。
+3. 作为助教，我在 AI 对话页能与 AI 流式对话，看到来源页面信息。
+4. 作为助教，我能查看历史 AI 对话记录。
+
+### 验收标准
+
+- AC1：消费记录区分三种样式（台桌结账→下沉台费明细、商城订单、充值）
+- AC2：消费记录默认 10 条，拉到底懒加载（每次 10 条）
+- AC3：金额为 0 的项不展示；有团购/折扣时展示正价+实付
+- AC4：总金额仅在消费条目 >1 时出现
+- AC5：AI 对话支持流式展示（逐字输出）
+- AC6：从其他页面进入 chat.html 时新开对话，第一条消息为页面上下文
+- AC7：对话历史列表可查看、可继续对话
+
+---
+
+## 页面清单
+
+### customer-detail（客户详情）
+
+- 客户信息卡片（昵称、手机、会员卡等级、余额、注册日期）
+- 指数总览（WBI/NCI/SPI 展示分 + 爱心 icon）
+- 消费记录列表（三种样式，懒加载）
+  - 台桌结账：下沉到 `dwd_table_fee_log`，每条台费详情，关联总金额汇总
+  - 商城订单：助教列表（花名+级别+课程类型+服务时长+定档绩效）、支付金额、食品酒水总金额
+  - 充值：充值金额、支付方式
+- 备注列表
+- AI 消费习惯分析（应用 3 缓存）
+- "问问助手"入口 → chat.html
+
+### coach-detail（助教详情）
+
+- 助教信息卡片（花名、级别、工龄）
+- 客户数（RS > 2 的客户数量）
+- 备注按钮（查看此助教为该客户做的备注）
+
+### customer-service-records（客户服务记录）
+
+- 服务记录列表（时间 + 持续时长）
+
+### chat（AI 对话）
+
+- 来源展示（来源页面 title + 基本信息）
+- 对话界面（IM 风格）
+- AI 回复流式展示（SSE）
+- 消息输入 + 发送
+
+### chat-history（对话历史）
+
+- 历史对话列表（按时间倒序）
+- 点击进入继续对话
+
+---
+
+## 后端 API 需求
+
+| API | 说明 |
+|-----|------|
+| `GET /api/customers/:id` | 客户详情 |
+| `GET /api/customers/:id/consumption-records` | 消费记录（分页，懒加载） |
+| `GET /api/customers/:id/indexes` | 客户指数总览 |
+| `GET /api/coaches/:id` | 助教详情 |
+| `GET /api/coaches/:id/customer-count` | 助教客户数（RS>2） |
+| `GET /api/customers/:id/service-records` | 客户服务记录 |
+| `POST /api/chat/conversations` | 创建对话 |
+| `POST /api/chat/conversations/:id/messages` | 发送消息（SSE 流式返回） |
+| `GET /api/chat/conversations` | 对话历史列表 |
+| `GET /api/chat/conversations/:id/messages` | 对话消息列表 |
+
+### 消费记录 settle_type 区分
+
+需要查库确认的字段（待 P1 完成后验证）：
+- 台桌结账：`settle_type` 对应值（需查 `dwd_settlement_head`）
+- 商城订单：`settle_type` 对应值
+- 充值：从 `dwd_recharge_order` 单独查询
+
+### 正价金额字段（待用户复核）
+
+需要在 `dwd_settlement_head` 或相关 DWS 表中确认：
+- `original_amount` vs `total_amount` vs 其他字段
+- 此项标记为"需用户复核"
+
+---
+
+## 任务清单
+
+- [ ] T1：实现客户详情 API
+- [ ] T2：实现消费记录分页 API（三种样式区分 + 懒加载）
+- [ ] T3：实现客户指数总览 API
+- [ ] T4：实现助教详情 API
+- [ ] T5：实现对话 API（创建/发送/历史/消息列表，SSE 流式）
+- [ ] T6：实现 customer-detail 小程序页面
+- [ ] T7：实现 coach-detail 小程序页面
+- [ ] T8：实现 customer-service-records 小程序页面
+- [ ] T9：实现 chat 小程序页面（流式展示 + 来源信息）
+- [ ] T10：实现 chat-history 小程序页面