root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
Neo-ZQYY/docs/prd/specs/01-SPEC任务拆分总览.md

13 KiB
Raw Permalink Blame History

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

备注系统

  1. 新建表：biz.notes（type 区分：普通/回访/生日/放弃原因）
  2. 备注 CRUD API
  3. 生日信息隔离存储（不被 ETL 数据覆盖）

触发器机制

  1. 新建表：biz.trigger_jobs（触发器配置与执行日志）
  2. 轮询调度框架：支持按条件触发（数据变更、定时、事件驱动）
  3. 任务状态轮询（每小时检查有效期）

依赖

  • 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 并行
Reference in New Issue View Git Blame Copy Permalink