389 lines
17 KiB
Markdown
389 lines
17 KiB
Markdown
# SPEC 任务拆分总览
|
||
|
||
> 生成日期：2026-02-23
|
||
> 按依赖优先级排序，按 SPEC 边界分组，面向 Kiro SPEC 工作流
|
||
|
||
> **数据字段权威参考**：各 SPEC 涉及的 DWD/DWS 层字段来源、金额口径、业务逻辑，
|
||
> 以 `docs/reports/DWD-DOC/` 校准文档为准（数据快照 2026-03-06）。
|
||
> 核心规则：
|
||
> - `consume_money` 存在三种历史口径混合，不可直接使用；应使用 `items_sum`（= table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money）
|
||
> - 收入结构拆分为台桌费、陪打费、超休费、商品费、电费五项，不使用笼统的 `service_fee`
|
||
> - 详见 [consume_money 口径说明](../reports/DWD-DOC/consume/consume-money-caliber.md)、[财务全景](../reports/DWD-DOC/03-financial-panorama.md)
|
||
|
||
---
|
||
|
||
## 执行顺序总览
|
||
|
||
```
|
||
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`（增加 `staff_id` 字段支持员工绑定）
|
||
2. 重构现有 `public.roles`、`public.permissions`、`public.user_roles`、`public.role_permissions` 迁移至 `auth` Schema
|
||
3. 后端 API：微信 code2Session 登录、用户申请提交、JWT 签发
|
||
4. 后端 API：用户状态查询（审核中/通过/拒绝）
|
||
5. 权限中间件：基于角色的 API 访问控制
|
||
6. 人员匹配：用户申请时同时在助教表（`dim_assistant`）和员工信息表（`dim_staff` + `dim_staff_ex`）中匹配
|
||
|
||
### 依赖
|
||
- 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. 数据回溯机制（召回完成后回溯备注分类 + 触发 AI 备注分析）
|
||
8. 任务置顶/放弃 API
|
||
|
||
#### 备注系统
|
||
9. 新建表：`biz.notes`（type 区分：普通/回访/放弃原因，含星星评分字段 `rating_service_willingness`、`rating_revisit_likelihood` 各 1-5 可空）
|
||
10. 备注 CRUD API（含星星评分的存储与读取）
|
||
11. 生日信息已迁移至维客线索系统（`member_retention_clue`），不再作为 notes type
|
||
|
||
#### 触发器机制
|
||
12. 新建表：`biz.trigger_jobs`（触发器配置与执行日志）
|
||
13. 轮询调度框架：支持按条件触发（数据变更、定时、事件驱动）
|
||
14. 任务状态轮询（每小时检查有效期）
|
||
|
||
### 依赖
|
||
- P1（数据库基础）
|
||
- P2（指数数据可用，用于任务生成器）
|
||
- P3（用户认证，知道当前助教身份）
|
||
|
||
### 验收标准
|
||
- 任务生成器正确按指数分配 4 种类型任务
|
||
- 同客户-助教-类型跳过，不同类型关闭旧任务+新建
|
||
- 48 小时滞留机制正常工作
|
||
- 召回完成后自动标记任务完成
|
||
- 数据回溯正确将普通备注重分类为回访备注
|
||
- 备注 CRUD 正常，维客线索独立于 ETL 数据
|
||
- 备注星星评分正确存储（不参与完成判定，不参与应用 6 分析，仅辅助数据）
|
||
- 回访任务默认展开评分区域，其他任务类型默认隐藏可手动展开
|
||
|
||
---
|
||
|
||
## P5：AI 集成层 — 百炼对接 + 对话系统 + 轮询缓存
|
||
|
||
### SPEC 名称建议：`miniapp-ai-integration`
|
||
|
||
### ⚠️ 两阶段交付策略（2026-03-07 评审决定）
|
||
|
||
应用 3/4/5/6/7 的首条 Prompt JSON 结构包含占位符字段（`consumption_records`、`service_history`、`objective_data` 等），这些字段的具体结构取决于对应页面 API 的数据格式。因此 P5 拆分为两个阶段：
|
||
|
||
- P5-A（当前阶段）：建表、百炼封装、缓存 API、SSE 框架 + Prompt 已确定的应用（应用 2、应用 8）+ 应用 3/4/5/6/7 的触发机制和调用骨架
|
||
- P5-B（Prompt 细化）：分散到对应页面 spec 中同步完成（P6-T4 细化应用 4/5，P9-T1 细化应用 3/6/7）
|
||
|
||
### 需求概述
|
||
对接阿里云百炼 8 个 AI 应用，实现对话系统、后台轮询缓存、备注分析。
|
||
|
||
### 关键交付物
|
||
1. 新建表：`biz.ai_conversations`、`biz.ai_messages`、`biz.ai_cache`
|
||
2. 百炼 API 封装：统一调用层（支持流式/非流式）
|
||
3. 应用 1：通用对话 API（SSE 流式返回）
|
||
4. 应用 2：财务洞察轮询任务（每日更新，多时间维度交叉）【P5-A，Prompt 已确定】
|
||
5. 应用 3：客户维客线索分析轮询（客户新增消费时触发）【P5-A 骨架 + P9-T1 细化 Prompt】
|
||
6. 应用 4：客户-助教关系分析轮询（助教参与新结算时触发）【P5-A 骨架 + P6-T4 细化 Prompt】
|
||
7. 应用 5：话术参考（应用 4 调用时联动）【P5-A 骨架 + P6-T4 细化 Prompt】
|
||
8. 应用 6：备注分析（每个备注提交时触发）【P5-A 骨架 + P9-T1 细化 Prompt】
|
||
9. 应用 7：客户分析（结账单触发）【P5-A 骨架 + P9-T1 细化 Prompt】
|
||
10. 应用 8：维客线索整理（应用 3/6 产出后触发）【P5-A，Prompt 已确定】
|
||
11. AI 结果缓存读写 API
|
||
12. 页面内容文本化工具（随 P6-P9 各页面逐步实现）
|
||
|
||
### 依赖
|
||
- P3（用户身份，AI 信息隔离需要传入身份参数）
|
||
- P4（备注系统 + 触发器机制，应用 6 依赖回访任务完成事件）
|
||
|
||
### 验收标准
|
||
- 应用 1 流式对话正常
|
||
- 应用 2-5 轮询任务按条件触发并缓存结果
|
||
- 应用 6 在每个备注提交后自动分析，返回评分+维客线索
|
||
- 应用 7 在客户结账单出现后触发，生成运营策略
|
||
- 应用 8 在应用 3/6 产出后触发，整合去重维客线索
|
||
- 所有 AI 对话记录持久化（含系统调用）
|
||
- P5-A 验收：应用 2/8 完整可用，应用 3/4/5/6/7 触发机制和调用框架就绪（Prompt 拼接为 TODO 接口）
|
||
- P5-B 验收：随 P6-T4、P9-T1 完成后，对应应用的 Prompt 拼接函数实现并联调通过
|
||
|
||
---
|
||
|
||
## P5.1：MCP Server AI 扩展 — 查库手册 + 业务库接入
|
||
|
||
### SPEC 名称建议：`mcp-server-ai-extension`
|
||
|
||
### 分批执行（2026-03-07 评审决定）
|
||
|
||
- 批次 A（立即可执行）：重写 ETL 库查库手册（DWD-DOC 已完成）
|
||
- 批次 B（P5-A 之后）：MCP Server 新增 `zqyy_app` 连接 + 业务库手册
|
||
- 批次 C（批次 B 后）：手册上传百炼验证
|
||
|
||
### 需求概述
|
||
扩展 MCP Server 支持 `zqyy_app` 业务库查询，重写查库手册供百炼平台 AI 应用作为知识库。
|
||
|
||
### 依赖
|
||
- 批次 A：无（DWD-DOC 已完成）
|
||
- 批次 B：P1 + P4 + P5-A（biz 表已建）
|
||
- 批次 C：批次 B
|
||
|
||
---
|
||
|
||
## 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-A（AI 缓存数据展示 + 应用 4/5 调用骨架）
|
||
|
||
> P6-T4 同时承担 P5-B 的应用 4/5 Prompt 细化任务（服务记录结构确定后实现拼接函数）
|
||
|
||
---
|
||
|
||
## 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-A（AI 对话系统 + 应用 3/6/7 调用骨架）
|
||
- P4（备注系统）
|
||
|
||
> P9-T1 同时承担 P5-B 的应用 3/6/7 Prompt 细化任务（消费记录结构确定后实现拼接函数）
|
||
|
||
---
|
||
|
||
## P10：租户管理后台
|
||
|
||
### SPEC 名称建议：`tenant-admin-web`
|
||
|
||
### 需求概述
|
||
独立的租户管理 Web 应用，提供用户审核、用户管理、Excel 数据上传功能。
|
||
|
||
### 关键交付物
|
||
1. 独立 Web 应用（React + Vite + Ant Design，类似 `apps/admin-web/` 技术栈）
|
||
2. 租户管理员登录（独立凭据体系，账号由系统管理后台 `apps/admin-web/` 创建，不可自行注册）
|
||
3. 用户审核页面：申请列表、状态筛选、关联建议（球房ID+手机号匹配助教）、审核操作
|
||
4. 用户管理页面：用户列表、身份编辑、店铺归属编辑
|
||
5. Excel 上传页面：4 种模板（财务支出/团购收入/助教奖罚/充值业绩归属）
|
||
6. Excel 校验：必填、金额精度、表头格式、类型合法
|
||
7. 冲突处理：前端 diff 交互（逐条确认替换/保留）
|
||
8. 后端 API：Excel 解析、校验、冲突检测、确认写入
|
||
9. 新建表：`biz.salary_adjustments`、`biz.excel_upload_log`
|
||
10. 维客线索管理页面：按客户列出全部线索（标签/摘要/提供人/备注原文），支持修改、删除、隐藏操作
|
||
|
||
### 依赖
|
||
- P1（数据库基础）
|
||
- P3（用户体系，共享 `auth` Schema）
|
||
- admin-web-console 需求 11（租户管理员账号管理功能，提供账号创建入口）
|
||
|
||
### 验收标准
|
||
- 租户管理员账号由系统管理后台创建，租户管理员不可自行注册
|
||
- 租户管理员只能看到自己租户下的店铺数据（由 Operator 分配的 `site_id` 列表决定）
|
||
- 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-A ──→ P6（含 P5-B 应用4/5 Prompt 细化）
|
||
│ │ ↘
|
||
│ └──→ P10 P8
|
||
│ ↘
|
||
│ P9（含 P5-B 应用3/6/7 Prompt 细化）
|
||
│
|
||
└──→ P11（全部完成后）
|
||
```
|
||
|
||
> P5-A 交付管道和骨架后，P6/P8/P9 即可启动。
|
||
> P5-B 的 Prompt 细化任务嵌入 P6-T4（应用4/5）和 P9-T1（应用3/6/7），不作为独立阶段。
|
||
|
||
可并行的 SPEC 组合：
|
||
- P2 和 P3 可并行（无互相依赖）
|
||
- P6、P7、P8、P9 在 P5-A 完成后可部分并行
|
||
- P10 在 P1+P3 完成后即可启动，与 P4-P9 并行
|