chore(docs): Wave 0 调研产出 + P0/P1/P2 反馈调研
建立项目级标杆文档 docs/_overview/ 作为产品全景索引, 解决"PRD 零碎、文档膨胀、跨子系统调研无入口"的问题。 主要内容: - 00-index 总索引 + 维护协议 + 与 CLAUDE.md 关系 - 01-product-overview 产品全景脑图(6 角色 / 6 子系统 / 数据流 / 7 业务概念 / 8+1 AI 矩阵 / 22 术语) - 02a-miniprogram-page-matrix 小程序 21 页业务指纹 - 02b-adminweb-page-matrix admin-web 19 路由业务指纹 - 03-test-spec 测试规范 (L1-L5 分层 + 走查模板 + 75-95 case 估算) - 04-doc-conflicts 39 条冲突索引(P0×8 / P1×13 / P2×13 + 5 子项) - 04a/b/c-conflicts-*-detail 业务故事卡(7 字段:关联/逻辑/影响/选项/判定) - 05-orphan-pages-cleanup admin-web 6 孤儿页面处置(1 归档 + 4 保留) - WAVES-MASTER-PLAN.md 全 Wave 主计划(0-5,共 22-32 工作日) - WAVE-1-KICKOFF.md Wave 1 实施 kickoff - GLOBAL-DECISION-DASHBOARD.md 全局决策仪表板 反馈调研产物: - 04a-feedback/ P0 两轮反馈(8+8 项决策 + D-1/2/3 + F-1/2 子代理产出) - 04b-feedback/ P1 两轮反馈(13+1+5 项 + E-1/2/3/4 + G-1/2 子代理产出) - 04c-feedback/ P2 反馈(13 项 + 5 子项 + H-1/2/3 子代理产出) - NEO-DECISIONS-LOG 累积决策记录 关键追加发现 8 处 D Bug(原蓝本 0): - P0-3 看板沙箱接入(Wave 1 W1-T1) - P0-5 致命 1 (4 处 fdw_etl 残留, 已修 commit17f045a) - P0-5 致命 2 (JWT aud 缺失, 已修 commit17f045a) - P0-6 clearAllTasks 守卫 (Wave 3) - P0-8 DBViewer 黑名单漏 (已修 commit17f045a) - P1-3 task-detail 跳转传 task_id 而非 customer_id - P2-7 board-finance 隐式 null - 2 个独立 Bug (page_context.created_at + ClueCategory 字典) 参考: docs/_overview/00-index.md
This commit is contained in:
326
docs/_overview/01-product-overview.md
Normal file
326
docs/_overview/01-product-overview.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# NeoZQYY 产品全景脑图
|
||||
|
||||
> 生成日期：2026-05-04 / 维护者：Wave 0 调研子代理 / 后续修订归 Neo
|
||||
> 信息来源：`docs/prd/specs/01-SPEC任务拆分总览.md`、`docs/prd/specs/00-数据依赖矩阵.md`、`P1`-`P12` 各 SPEC、`docs/prd/AI需求2.md`、`docs/prd/SPI 消费力指数.md`、`docs/prd/后端接口需求说明_数据需求PRD.md`、`docs/prd/2026-04-08__board-finance-optimization.md`、`CLAUDE.md`、`db/CLAUDE.md`、`apps/etl/connectors/feiqiu/CLAUDE.md`
|
||||
|
||||
---
|
||||
|
||||
## 一、产品定位与目标用户
|
||||
|
||||
NeoZQYY 是一个面向**台球门店连锁经营**的全栈数据与运营平台。它从 SaaS 系统「飞球」抽取门店原始业务数据（结算、台费、助教服务、充值、会员等），经过六层数据仓库治理，叠加自研指数体系（WBI/NCI/RS/OS/MS/ML/SPI/亲密度等）与 AI 应用矩阵（阿里云百炼 8 个 APP），向门店一线助教、管理者与系统运维分别提供匹配视角的工具。
|
||||
|
||||
核心解决的问题：
|
||||
1. 飞球原始数据口径混乱（如 `consume_money` 三种历史口径并存），缺乏可直接用于经营决策的可信指标 — 由 ETL 六层治理 + DWD-DOC 校准清单解决（参考：`apps/etl/connectors/feiqiu/CLAUDE.md` 12 条 DWD 强制规则）。
|
||||
2. 助教不知道"现在该联系哪个客户、用什么策略" — 由助教任务体系（4 类优先级任务 + AI 关系/话术/备注分析）解决（参考：`docs/prd/specs/01-SPEC任务拆分总览.md` P4-P5）。
|
||||
3. 门店管理者缺少跨维度的财务/客户/助教看板与 AI 洞察 — 由小程序三大看板 + 应用 2 财务洞察解决（参考：`docs/prd/specs/01-SPEC任务拆分总览.md` P8、`docs/prd/2026-04-08__board-finance-optimization.md`）。
|
||||
4. 多门店连锁的数据隔离与租户管理诉求 — 由 `site_id` + RLS 双 schema 视图 + 租户管理后台解决（参考：`CLAUDE.md` 架构模式、`db/CLAUDE.md` RLS 双 schema 规则）。
|
||||
|
||||
目标用户：单店或连锁台球门店的助教、会籍顾问、店长、租户管理员、系统运维与产品负责人。领域语言为中文，金额币种为 CNY，金额精度 `numeric(2)`。
|
||||
|
||||
---
|
||||
|
||||
## 二、用户角色矩阵
|
||||
|
||||
| 角色 | 端 | 主要职责 | 关键操作 | 不可见的内容 |
|
||||
|---|---|---|---|---|
|
||||
| 教练 / 助教（coach） | 小程序 | 完成系统派发的客户维护任务、写备注、查看个人绩效与服务记录 | 任务列表的置顶/放弃/AI、写备注（含星星评分）、查看自己的绩效与档位、与 AI 对话 | 不能看财务看板、不能看其他助教的私人备注与工资明细（参考：`docs/prd/specs/P3-miniapp-auth-system.md` AC5） |
|
||||
| 顾问 / 会籍（consultant，PRD 未单列实体表） | 小程序 | 与助教类似但侧重客户维护与销售线索 | 同助教，权限按 `auth.user_site_roles` 分配 | 视权限而定，财务看板默认不可见 |
|
||||
| site_admin（单店管理员） | tenant-admin Web | 审核小程序用户申请、维护用户-助教绑定、上传 Excel、管理维客线索 | 用户审核、用户管理、4 种 Excel 上传（财务支出/团购收入/助教奖罚/充值业绩归属）、维客线索 CRUD | 只能看自己被分配的 `site_id` 列表内的店铺数据，看不到其他租户、看不到 ETL 库 schema（参考：`docs/prd/specs/P10-tenant-admin-web.md` AC2） |
|
||||
| tenant_admin（集团/连锁管理员） | tenant-admin Web | 同 site_admin，但管辖全部租户下店铺 | 同 site_admin 但跨多店 | 看不到 ETL 库 schema、看不到其他租户 |
|
||||
| 系统运维 / Operator | admin-web | 创建租户管理员账号、配置 ETL 调度、监控数据质量、运维 ETL 库 | 创建 tenant 管理员账号（含分配 `site_id` 列表）、ETL 配置、数据质量监控、系统监控 | 不参与一线门店业务操作、不写小程序备注（参考：`docs/prd/specs/P10-tenant-admin-web.md` 设计要点 - 登录体系） |
|
||||
| AI 应用（系统主体） | 后端 + 百炼 | 自动化生成维客线索、备注分析、关系分析、话术、客户分析、财务洞察 | 通过 MCP Server 工具查库、按 `User_ID` 做信息隔离 | 助教身份的 AI 仅能查与该助教相关的客户数据（参考：`docs/prd/AI需求2.md` 应用 1 权限限制） |
|
||||
|
||||
---
|
||||
|
||||
## 三、子系统职责与边界
|
||||
|
||||
### 子系统职责
|
||||
|
||||
- **apps/miniprogram（C 端小程序）**：助教/顾问的工作台，承载任务列表、任务详情、备注、绩效、三大看板、客户/助教详情、AI 对话页等共 13+ 个页面（参考：`docs/prd/specs/01-SPEC任务拆分总览.md` P6-P9）。技术栈 Donut + TDesign，原型图位于 `docs/h5_ui/`。WXML/WXSS 严禁使用 HTML/CSS 语法，TDesign 优先（参考：`docs/prd/specs/P3-miniapp-auth-system.md` 强制规范第 1-6 条）。
|
||||
|
||||
- **apps/admin-web（系统管理后台）**：开发与运维视角，操作 ETL 库（`etl_feiqiu`），提供 ETL 配置、数据质量、系统监控、租户管理员账号管理（参考：`CLAUDE.md` 子系统目录、`docs/prd/specs/P10-tenant-admin-web.md` 设计要点）。
|
||||
|
||||
- **apps/tenant-admin（租户管理后台）**：门店管理员视角（`site_admin` / `tenant_admin`），独立 Web 应用，承担用户审核、Excel 上传、维客线索管理。技术栈 React + Vite + Ant Design，独立登录入口、独立凭据，账号由 admin-web 创建，不能自助注册（参考：`docs/prd/specs/P10-tenant-admin-web.md` AC1.1）。
|
||||
|
||||
- **apps/backend（FastAPI 后端）**：所有前端共用的后端服务。承担 JWT 双认证（`apps/backend/CLAUDE.md`）、统一响应包装、WebSocket、AI 集成（百炼 SSE / 缓存 / 触发器）、TaskQueue/Scheduler、FDW 访问 ETL 数据。所有看板/任务/备注 API 在此实现（参考：`docs/prd/后端接口需求说明_数据需求PRD.md` §8 接口分组）。
|
||||
|
||||
- **apps/etl/connectors/feiqiu（ETL 飞球连接器）**：六层数据仓库 ODS → DWD → DWS（→ DWD-DOC 标杆）。负责把飞球 API 数据治理成可信指标。包含 12 条 DWD 强制规则（如 `consume_money` 不可直接用、必须用 `items_sum`），DWS 层落地 SPI/WBI/NCI/RS/OS/MS/ML/亲密度等指数（参考：`apps/etl/connectors/feiqiu/CLAUDE.md`）。
|
||||
|
||||
- **apps/mcp-server（MCP 工具服务）**：PostgreSQL 只读工具，供阿里云百炼 AI 应用作为知识库使用。当前只接 `etl_feiqiu`；P5.1 批次 B 后扩展到 `zqyy_app`，自动按 schema 名做数据库路由（参考：`docs/prd/specs/P5.1-mcp-server-ai-extension.md` 设计要点）。
|
||||
|
||||
### 子系统职责对比表
|
||||
|
||||
| 子系统 | 主要使用者 | 主要数据库 | 技术栈 | 与其他子系统关系 |
|
||||
|---|---|---|---|---|
|
||||
| apps/miniprogram | 助教 / 顾问 / 店长（C 端） | 通过 backend 间接访问 zqyy_app + ETL（FDW） | Donut + TDesign（小程序原生 WXML/WXSS） | 后端依赖 apps/backend；UI 标杆来自 apps/demo-miniprogram（MOCK 禁改） |
|
||||
| apps/admin-web | 系统运维 / Operator | etl_feiqiu | React + Vite + Ant Design | 创建 tenant-admin 账号；配置 ETL 调度 |
|
||||
| apps/tenant-admin | site_admin / tenant_admin | zqyy_app（auth + biz）+ ETL FDW 只读 | React + Vite + Ant Design | 与小程序共用 auth schema；账号由 admin-web 创建 |
|
||||
| apps/backend | 所有前端 | zqyy_app（主）+ etl_feiqiu（FDW） | FastAPI + Uvicorn | 唯一对外 API 出口；JWT/响应包装/AI 集成 |
|
||||
| apps/etl/connectors/feiqiu | ETL 调度 / 数据团队 | etl_feiqiu | uv workspace（Python 3.10+） | 数据生产者；通过 RLS 视图 + FDW 暴露给 zqyy_app |
|
||||
| apps/mcp-server | 百炼 AI 应用 | etl_feiqiu（A）+ zqyy_app（B 期） | Python + MCP SDK | 仅只读；为 AI 应用提供查库工具 + 手册 |
|
||||
|
||||
---
|
||||
|
||||
## 四、数据流全景
|
||||
|
||||
```
|
||||
飞球 SaaS API
|
||||
│
|
||||
│ ETL 抽取（每小时增量；冬季月初前 5 天宽限期）
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ etl_feiqiu / test_etl_feiqiu │
|
||||
│ ┌──────────┐ │
|
||||
│ │ meta │ 元数据（任务调度、字典、配置参数） │
|
||||
│ ├──────────┤ │
|
||||
│ │ ods │ 原始落地（API 字段保真，不做业务逻辑） │
|
||||
│ ├──────────┤ │
|
||||
│ │ dwd │ 明细治理：dim_*（SCD2 维度）+ dwd_*（事实）│
|
||||
│ ├──────────┤ │
|
||||
│ │ core │ 跨域基础事实（如客户主表） │
|
||||
│ ├──────────┤ │
|
||||
│ │ dws │ 业务汇总 + 指数：WBI/NCI/RS/OS/MS/ML/SPI │
|
||||
│ ├──────────┤ │
|
||||
│ │ app │ RLS 视图层（按 site_id + 会话变量过滤） │
|
||||
│ └──────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ FDW 跨库只读映射（通过 RLS 视图 v_*，非裸 dws/dwd 表）
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ zqyy_app / test_zqyy_app │
|
||||
│ ┌──────────┐ │
|
||||
│ │ public │ 历史系统管理表（admin_users 等） │
|
||||
│ │ │ + member_retention_clue（维客线索） │
|
||||
│ ├──────────┤ │
|
||||
│ │ auth │ 用户认证：users/user_applications/ │
|
||||
│ │ │ site_code_mapping/user_assistant_binding │
|
||||
│ ├──────────┤ │
|
||||
│ │ biz │ 业务表：coach_tasks/notes/ai_*/ │
|
||||
│ │ │ trigger_jobs/excel_upload_log/ │
|
||||
│ │ │ salary_adjustments │
|
||||
│ ├──────────┤ │
|
||||
│ │ fdw_etl │ ~33 张外部表，映射 etl_feiqiu.app.v_* │
|
||||
│ └──────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ FastAPI（apps/backend）查询
|
||||
│ 设置 SET app.current_site_id = <user.site_id>
|
||||
▼
|
||||
小程序 / tenant-admin / admin-web（按角色加载视图）
|
||||
```
|
||||
|
||||
关键约束（参考：`CLAUDE.md` 架构模式、`db/CLAUDE.md` RLS 双 Schema 规则）：
|
||||
1. 多门店通过 `site_id` 列 + `app.current_site_id` 会话变量过滤；新建 DWS/DWD 表的 RLS 视图必须**同时**在 `dws`（或 `dwd`）和 `app` 双 schema 创建，否则后端查询失败。
|
||||
2. zqyy_app 只通过 FDW 只读访问 ETL；不允许 zqyy_app 写 ETL 库。
|
||||
3. ETL 任务的金额字段统一使用 `items_sum` 替代 `consume_money`（参考：`apps/etl/connectors/feiqiu/CLAUDE.md` DWD 规则 1）。
|
||||
|
||||
---
|
||||
|
||||
## 五、核心业务概念
|
||||
|
||||
### 5.1 SPI 消费力指数（Spending Power Index）
|
||||
|
||||
参考：`docs/prd/SPI 消费力指数.md`、`docs/prd/specs/P2-etl-dws-miniapp-extensions.md`。
|
||||
|
||||
- **定位**：客户级（粒度 `(site_id, member_id)`）每日刷新的"消费能力代理值"，回答"这个客户消费层级如何 / 近期推进速度 / 稳定还是偶发"。
|
||||
- **三个子分**：
|
||||
- `Level`（消费水平）权重 0.60：基于 `spend_30`、`spend_90`、`avg_ticket_90`、`recharge_90` 的 log1p 加权。
|
||||
- `Speed`（消费速度）权重 0.30：绝对速度（每消费日强度）+ 相对速度（30d vs 90d 加速）+ EWMA 平滑速度。
|
||||
- `Stability`（消费稳定性）权重 0.10：90 天内有消费的周覆盖率（`active_weeks_90 / 13`）。窗口最长 90 天，**不使用 180 天**。
|
||||
- **展示分映射**：复用 `BaseIndexTask` 的 P5/P95 Winsorize → 压缩（log1p/asinh）→ MinMax 0-10 → 可选 EWMA 分位平滑。
|
||||
- **配置**：`cfg_index_parameters` 中 `index_type='SPI'`，27 个参数（含权重、压缩基数、窗口天数等），已落地（参考：`P2-etl-dws-miniapp-extensions.md` T3 ✅）。
|
||||
- **使用规则**：SPI 不单独决定"要不要触达"，而是与 NCI/WBI（紧急度）+ RS/OS/MS/ML（关系归属）组合，用于"投入多大资源、用什么档位策略"。
|
||||
|
||||
### 5.2 助教任务体系（4 类 + 状态机）
|
||||
|
||||
参考：`docs/prd/specs/01-SPEC任务拆分总览.md` P4、`docs/prd/后端接口需求说明_数据需求PRD.md` §3.2。
|
||||
|
||||
- **任务类型（优先级从高到低）**：
|
||||
- `high_priority` 高优先召回
|
||||
- `priority` 优先召回
|
||||
- `callback` 客户回访
|
||||
- `relationship` 关系构建
|
||||
- **生成器**：每日 04:00 后运行，基于客户级指数（max(WBI, NCI)）+ 关系指数（RS/OS/MS/ML）为每个助教分配任务。同客户-助教-类型跳过；不同类型则关闭旧任务并新建。
|
||||
- **状态**：`pending / completed / abandoned / pinned`（pinned 是排序属性而非互斥状态）。
|
||||
- **特殊机制**：
|
||||
- 48 小时回访滞留：超期回访任务的状态化处理。
|
||||
- 召回完成检测：ETL 数据到达后由后台轮询自动标记。
|
||||
- 数据回溯：召回完成时回溯近期备注，把"普通备注"重分类为"回访备注"，并触发应用 6（备注分析）。
|
||||
- **任务表**：`biz.coach_tasks` + `biz.coach_task_history`（变更历史，关闭/新建可追溯）。
|
||||
|
||||
### 5.3 备注与星星评分体系
|
||||
|
||||
参考：`docs/prd/specs/01-SPEC任务拆分总览.md` P4 第 9-11 项、`docs/prd/specs/P10-tenant-admin-web.md` 维客线索管理、`docs/prd/后端接口需求说明_数据需求PRD.md` §5.1。
|
||||
|
||||
- **统一备注表**：`biz.notes`，`type` 区分 普通 / 回访 / 放弃原因 三类。生日类信息**不再**作为 notes type，已迁移到维客线索系统。
|
||||
- **星星评分字段**：
|
||||
- `rating_service_willingness`（再次服务意愿，1-5，可空）
|
||||
- `rating_revisit_likelihood`（再来店可能性，1-5，可空）
|
||||
- PRD §3.2 接口示例还提到 `intention / relation / service` 三项 — 与 SPEC 中两项不一致（登记到 §八 待 Neo 确认）。
|
||||
- **不参与判定**：星星评分**不参与**任务完成判定、**不参与**应用 6 备注分析输入，仅作辅助。
|
||||
- **UI 默认**：回访任务默认展开评分区域，其他任务类型默认隐藏可手动展开。
|
||||
|
||||
### 5.4 维客线索系统（member_retention_clue）
|
||||
|
||||
参考：`docs/prd/specs/00-数据依赖矩阵.md`、`docs/prd/specs/P10-tenant-admin-web.md` 维客线索管理、`docs/prd/AI需求2.md` 应用 8。
|
||||
|
||||
- **存储**：`zqyy_app.public.member_retention_clue`（已建表）。注意是 `public` schema，不是 `biz`（与"业务表迁移到 biz"的总体方向略有差异，登记到 §八）。
|
||||
- **字段（已确定）**：标签（大类枚举：客户基础 / 消费习惯 / 玩法偏好 / 促销接受 / 社交关系 / 重要反馈）、摘要、详情、提供人 `recorded_by_name`、来源 `source`（manual / ai_consumption / ai_note）、记录时间、Emoji 二级标签。
|
||||
- **待新增字段（SPEC 记录暂不执行）**：
|
||||
- `is_hidden BOOLEAN DEFAULT false`：tenant-admin 隐藏功能（小程序不展示但保留）。
|
||||
- `source VARCHAR(20) DEFAULT 'manual'`：当前 SPEC 已设但实际表是否已有需 §六校验。
|
||||
- **来源**：人工录入 / 应用 3（AI 消费分析）/ 应用 6（AI 备注分析）。应用 8 负责整合去重，最终落库时保留每条线索的 source。
|
||||
|
||||
### 5.5 飞球 consume_money 三种口径混淆问题
|
||||
|
||||
参考：`apps/etl/connectors/feiqiu/CLAUDE.md` DWD 规则 1、`docs/reports/DWD-DOC/consume/consume-money-caliber.md`、`docs/prd/specs/01-SPEC任务拆分总览.md` 总览的"金额口径"提示。
|
||||
|
||||
- **根因**：飞球上游 `consume_money` 字段在不同时间段使用了 A/B/C 三种不同口径，直接 SUM 会导致数据失真。
|
||||
- **解决方案**：DWS 层及下游统一改用 `items_sum`，定义为：
|
||||
```
|
||||
items_sum = table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money
|
||||
```
|
||||
- **关联铁律**：
|
||||
- 收入结构必须拆为 5 项（台桌费 / 陪打费 / 超休费 / 商品费 / 电费），不允许笼统的 `service_fee`（`service_fee` 仅在平台结算表中表示"平台服务费"）。
|
||||
- 助教费用必须拆 `assistant_pd_money` + `assistant_cx_money`，禁止用 `ASSISTANT_BASE / ASSISTANT_BONUS`。
|
||||
- 取数优先级：DWS > DWD > 禁止 ODS。
|
||||
|
||||
### 5.6 多门店隔离（site_id + RLS）
|
||||
|
||||
参考：`CLAUDE.md` 架构模式、`db/CLAUDE.md` RLS 双 Schema 规则、`docs/prd/specs/P1-miniapp-db-foundation.md` AC4。
|
||||
|
||||
- 所有事实/汇总表都带 `site_id` 列。
|
||||
- ETL 库 `app` schema 暴露的视图都加 `WHERE site_id = current_setting('app.current_site_id')::bigint` 过滤。
|
||||
- 后端在每个请求处理开始时执行 `SET app.current_site_id = <用户当前店铺>`，PostgreSQL 自动按视图过滤数据。
|
||||
- **强制铁律**：新建 DWS/DWD 表必须**同时**在原 schema（dws/dwd）和 `app` schema 创建 RLS 视图。回滚时逆序 DROP。
|
||||
|
||||
### 5.7 沙箱 / Runtime Context（虚拟时间）
|
||||
|
||||
参考：根 `CLAUDE.md` 历史追溯（"2026-04-15~05-02 累积变更基线 — AI 重构 + Runtime Context + DWS 修复"）、用户 memory（`project_rs_param_tuning.md` 等）。
|
||||
|
||||
PRD specs 文档未直接覆盖此模块，已知信息：
|
||||
- 系统支持运行时注入虚拟时间，用于 ETL 回填、影子跑数、AI 应用历史复现。
|
||||
- 与 SPI 影子跑数（参考：`docs/prd/SPI 消费力指数.md` Phase 1）和数据回溯机制配合使用。
|
||||
|
||||
详细机制建议查阅 `docs/audit/changes/2026-04-15*` 至 `2026-05-02*` 的审计记录（本调研范围未深入），登记到 §八。
|
||||
|
||||
---
|
||||
|
||||
## 六、AI 应用矩阵（8 个 APP + MCP）
|
||||
|
||||
参考：`docs/prd/AI需求2.md`（详细提示词与传参规范）、`docs/prd/specs/01-SPEC任务拆分总览.md` P5、`docs/prd/specs/P5.1-mcp-server-ai-extension.md`。所有应用使用 Qwen3.5-Plus 模型，部署在阿里云百炼平台。
|
||||
|
||||
| APP | 名称 | 服务对象 | 输入（Prompt 参数） | 输出 | 缓存桶 / 持久化 |
|
||||
|---|---|---|---|---|---|
|
||||
| 应用 1 | 通用对话（chat） | chat 页面用户 | User_ID + 花名 + Role + Nickname；前端动态传入页面上下文（来源页面+内容摘要+视野内容） | 自然语言流式（SSE 逐字） | `biz.ai_conversations` + `biz.ai_messages` |
|
||||
| 应用 2 | 财务洞察 | board-finance 页面 | 店铺 ID + 时间维度（本月/上月/本周/上周/前 3 月不含本月/本季/上季/近 6 月不含本月）+ 同周期与上周期数据（收入结构、预收资产、支出汇总、平台结算） | JSON 数组（序号 + 标题 + 正文详情） | `biz.ai_cache`，每日轮询 |
|
||||
| 应用 3 | 客户维客线索分析（消费侧客观） | customer-detail / task-detail | 客户昵称 + 近 3 月全维度消费数据（DWD/DWS）+ 会员卡明细 + 余额 + 应到店日期 + 距上次到店间隔 + 应用 6 历史 + 应用 8 历史（最近 2 套，附生成时间） | JSON 数组（详情 ≤120 字 / 分类标签 / 摘要 ≤20 字 / Emoji） | `biz.ai_cache`，客户新增消费触发 |
|
||||
| 应用 4 | 关系分析 / 任务建议 | task-detail | 助教信息 + 助教服务该客户历史 + 任务分配依据 + 客户客观数据（系统提供）+ 备注全文（备注创建者提供）+ 应用 8 维客线索 + 历史 2 套（附时间） | JSON：与我的关系一句话 + 任务描述与依据 + 行动建议数组 + 一句话总结 | `biz.ai_cache`，新结算单 / 优先召回 / 高优先召回触发 |
|
||||
| 应用 5 | 话术参考 | task-detail | 应用 4 输入 + 应用 4 返回 + 应用 8 历史 2 套（附时间） | JSON 数组（话术内容） | `biz.ai_cache`，应用 4 调用时联动 |
|
||||
| 应用 6 | 备注分析（主观侧） | 备注提交时 | 本次备注 + 客户昵称 + 近 3 月消费（DWD/DWS）+ 会员卡明细 + 余额 + 应到店 + 间隔 + 该客户全部备注 + 应用 3 历史 + 应用 8 历史 2 套（附时间） | JSON：维客线索数组（分类 / Emoji / 详情 / 摘要）+ 评分（1-10，6 分为标准；低价值/被多人备注过/时效低酌情扣分） | `biz.ai_cache`，每条备注提交触发 |
|
||||
| 应用 7 | 客户分析（运营策略） | customer-detail / task-detail | 客户客观数据（同应用 3）+ 该客户全部备注（创建者+全文）+ 应用 8 历史 2 套 | JSON：策略数组（标题+正文）+ 总结 | `biz.ai_cache`，结账单出现后触发 |
|
||||
| 应用 8 | 维客线索整理（去重合并） | 应用 3/6 后置 | 当前最新应用 3 + 应用 6 内容 | JSON 数组（详情 / 分类 / 摘要 / Emoji / 提供者，多个用逗号隔开） | 写入 `member_retention_clue` + `biz.ai_cache` |
|
||||
| MCP Server | 查库工具 | 应用 1（直接调用）+ 全部应用（手册引用） | SQL / 表名 / schema | 查询结果 / 表结构 / 手册 | 无（无状态） |
|
||||
|
||||
关键技术要点（参考：`docs/prd/AI需求2.md` 末尾）：
|
||||
|
||||
1. 应用 1 是**唯一**支持流式（SSE）返回的应用；其余应用返回结构化 JSON。
|
||||
2. 应用 2-8 的 JSON 输出由后端解析后写入 `member_retention_clue` 表（应用 8 整合后）或 `ai_cache`（按页面读取）。
|
||||
3. 信息隔离：所有应用通过 `biz_params.user_prompt_params` 传入身份；助教身份的 AI 仅可查与该助教相关数据，权限范围外的请求要驳回（应用 1 提示词强约束）。
|
||||
4. 持久化：所有对话（含系统调用）写入 `ai_conversations` + `ai_messages`，含 tokens 消耗统计。
|
||||
5. P5 拆为两阶段：P5-A 完成 Prompt 已确定的应用 2/8 + 应用 3/4/5/6/7 的触发与调用骨架；P5-B 在 P6-T4（应用 4/5）和 P9-T1（应用 3/6/7）页面 SPEC 内细化 Prompt 拼接函数。
|
||||
|
||||
---
|
||||
|
||||
## 七、关键术语词典
|
||||
|
||||
| 术语 | 含义 | 来源 |
|
||||
|---|---|---|
|
||||
| `consume_money` | 飞球原始消费金额字段，存在三种历史口径混合，**禁止直接使用** | `apps/etl/connectors/feiqiu/CLAUDE.md` 规则 1 |
|
||||
| `items_sum` | DWS 替代口径，= 台桌费 + 商品费 + 陪打费 + 超休费 + 电费 | 同上 |
|
||||
| `assistant_pd_money` / `assistant_cx_money` | 助教陪打费 / 超休费，**必须拆分**，不可用 `service_fee` | DWD 规则 2 |
|
||||
| `settle_type` | 结算类型枚举：1=台桌结账(78.6%) / 3=商城订单(21.4%) / 5=充值 / 6=结算退款 / 7=充值退款 | DWD-DOC 业务全景 |
|
||||
| WBI | Winback Index 老客召回紧迫度指数，客户级 | `docs/prd/SPI 消费力指数.md` 引言 |
|
||||
| NCI | New Conversion Index 新客欢迎/转化优先级，客户级，含 `NCI_welcome` 与 `NCI_convert` 子项 | 同上 |
|
||||
| SPI | Spending Power Index 消费力指数，客户级，含 Level/Speed/Stability 三子分 | 同上 |
|
||||
| RS | Relationship Strength 关系强度，客户-助教对粒度 | 同上 |
|
||||
| OS | Ownership 归属，客户-助教对粒度（决定责任边界，避免撞单） | 同上 |
|
||||
| MS | Momentum 关系动量，客户-助教对粒度 | 同上 |
|
||||
| ML | Monetary Link 付费关联（充值由谁推更容易成），客户-助教对粒度 | 同上 |
|
||||
| 亲密度 | `dws_member_assistant_intimacy`，客户-助教对粒度 | `00-数据依赖矩阵.md` task-detail |
|
||||
| 跳档激励 | 助教绩效档位接近升档时的激励展示 | `docs/prd/specs/01-SPEC任务拆分总览.md` P6-T1 |
|
||||
| 定档折算惩罚 | 同台桌同时段 >2 名助教时按比例折算单人贡献 | `docs/prd/specs/P2-etl-dws-miniapp-extensions.md` 设计要点 |
|
||||
| RLS 双 Schema | 新建 DWS/DWD 表的 RLS 视图必须同时在原 schema 和 `app` schema 创建 | `db/CLAUDE.md` |
|
||||
| 应用 1-8 | 阿里云百炼平台上的 8 个 AI 应用 | `docs/prd/AI需求2.md` |
|
||||
| 维客线索 | Member Retention Clue 客户维护线索（人工 + AI 产出，应用 8 整合落库） | `docs/prd/AI需求2.md` 应用 8 |
|
||||
| 球房 ID | site_code，`auth.site_code_mapping` 中的 2 字母+3 数字编码，对应 ETL 的 bigint `site_id` | `docs/prd/specs/P3-miniapp-auth-system.md` 设计要点 |
|
||||
| Operator | admin-web 中的系统运维角色，负责创建租户管理员账号 | `docs/prd/specs/P10-tenant-admin-web.md` 登录体系 |
|
||||
| SCD2 | Slowly Changing Dimension Type 2，缓慢变化维度，DWD 维度表通过 `scd2_start_time/scd2_end_time/scd2_is_current` 记录历史版本 | `apps/etl/connectors/feiqiu/CLAUDE.md` |
|
||||
| 影子跑数 | SPI/指数上线前的后台计算阶段（不展示给运营） | `docs/prd/SPI 消费力指数.md` Phase 1 |
|
||||
|
||||
---
|
||||
|
||||
## 八、文档冲突待确认清单
|
||||
|
||||
以下是阅读过程中识别到的**文档之间矛盾**或**文档与 CLAUDE.md/项目现状不一致**之处，标 `待 Neo 确认`，不做擅自结论。
|
||||
|
||||
1. **【备注星星评分字段命名不一致】 待 Neo 确认**
|
||||
- SPEC `P4` 与数据依赖矩阵：明确两个字段 `rating_service_willingness`、`rating_revisit_likelihood`，各 1-5 可空。
|
||||
- PRD `后端接口需求说明_数据需求PRD.md` 接口 I 与 J1 示例：用 `intention`、`relation`、`service` 三项。
|
||||
- 影响：前端 mock 与后端 schema 可能不一致，需要统一字段名（建议以 SPEC 为准，因为 SPEC 是数据库口径）。
|
||||
|
||||
2. **【member_retention_clue 所在 schema】 待 Neo 确认**
|
||||
- 数据依赖矩阵与 P10 SPEC：标注 `zqyy_app.public.member_retention_clue`（已建）。
|
||||
- 总体设计方向：业务表归 `biz`（参考：`P1-miniapp-db-foundation.md` Schema 规划）。
|
||||
- 影响：是历史遗留还是有意保留在 `public`？如果保留，需要在文档中说明原因；如果是迁移待办，需登记。
|
||||
|
||||
3. **【应用编号与 AI 需求 2.md 的差异】 待 Neo 确认**
|
||||
- SPEC 总览（`01-SPEC任务拆分总览.md` P5）：列出 8 个应用（1-8）。
|
||||
- `AI需求2.md` 表头标注"6 个 AI 应用的详细需求"，但表格实际列出 8 个（应用 1-8）。
|
||||
- 影响：`AI需求2.md` 文档第 26 行的"6 个"是历史遗留笔误（实际表格 8 个），不影响实现。建议修正文档表述。
|
||||
|
||||
4. **【应用 4 触发条件不一致】 待 Neo 确认**
|
||||
- `AI需求2.md`：触发条件为"有助教参与的新结算单出现时、优先召回任务分配时、高优先召回任务分配时"（共 3 种）。
|
||||
- 数据依赖矩阵 §三：触发条件为"助教参与新结算时"（仅 1 种）。
|
||||
- 影响：实现 P5-A 应用 4 调用骨架时需明确，可能漏掉两类任务分配触发。
|
||||
|
||||
5. **【P5.1 批次 B 是否有未解决的前置问题】 待 Neo 确认**
|
||||
- SPEC `P5.1-mcp-server-ai-extension.md` 自述"批次 B 依赖 P5-A 完成"。
|
||||
- 任务说明（用户原文）提到"P5.2 标了 prerequisite-fixes 说明 P5.1 有问题" — 但本调研范围内没有找到 `P5.2` 文件（仅有 `P5.1`）。
|
||||
- 影响：是否有 `P5.2-prerequisite-fixes.md` 应该存在但缺失？需要 Neo 确认是否有该 SPEC 文件、放在哪里。
|
||||
|
||||
6. **【应用 1 传参中 `User_ID` 与 `userId` 风格差异】 待 Neo 确认**
|
||||
- `AI需求2.md` 用 `User_ID`（蛇形大写下划线），符合百炼平台占位符风格。
|
||||
- PRD `后端接口需求说明_数据需求PRD.md` 用 `userId`（驼峰）。
|
||||
- 影响：前端 → 后端 → 百炼的字段映射需要明确转换层在哪里。建议后端做双向映射，对外接口用 camelCase，对百炼传 `User_ID`。
|
||||
|
||||
7. **【运行时 Runtime Context / 虚拟时间机制无 SPEC 文档】 待 Neo 确认**
|
||||
- 根 `CLAUDE.md` 历史追溯提到"2026-04-15~05-02 累积变更基线 — AI 重构 + Runtime Context + DWS 修复"。
|
||||
- 当前 `docs/prd/specs/` 下没有 Runtime Context 的独立 SPEC。
|
||||
- 影响：调研者无法了解虚拟时间的接口契约、传参方式、与 ETL 影子跑数的衔接细节。建议补 SPEC 或指向已有审计记录路径。
|
||||
|
||||
8. **【SPI 默认参数数量：26 vs 27】 待 Neo 确认**
|
||||
- 数据依赖矩阵 §四 / FDW 映射列表注释："cfg_index_parameters（含 SPI 26 个参数 ✅）"。
|
||||
- SPEC `P2-etl-dws-miniapp-extensions.md` T3 已完成项注释："已完成，27 个参数含 Level/Speed/Stability 权重..."。
|
||||
- 影响：实际数据库里是 26 还是 27？需要直接 `SELECT COUNT(*) FROM cfg_index_parameters WHERE index_type='SPI'` 校验。
|
||||
|
||||
9. **【4.1 财务看板优化与 P11 进度衔接】 待 Neo 确认**
|
||||
- `docs/prd/2026-04-08__board-finance-optimization.md` 列出 5 项 P1/P2 修复（卡余额快照不变、首充/续费全 0、文案、3 个新指标、优惠占比、充值笔数、团购标签）。
|
||||
- SPEC `P11-deployment-launch.md` AC6 要求"ETL 定时调度正常运行" — 卡余额快照修复属于 ETL 任务级 bug，可能影响生产数据准确性。
|
||||
- 影响：P11 上线前是否要先解决 4.1/4.2 的两个 P2 bug？还是允许带 bug 上线？需要 Neo 决策。
|
||||
|
||||
10. **【人员匹配范围：助教 vs 员工】 待 Neo 确认**
|
||||
- SPEC `P3` AC7：用户申请同时匹配 `dwd.dim_assistant`（助教）和 `dwd.dim_staff` + `dwd.dim_staff_ex`（员工）。
|
||||
- 数据依赖矩阵 §四"新增 FDW 映射（员工信息表）"：列出 `dim_staff` / `dim_staff_ex`。
|
||||
- 但当前 P1 SPEC 文档里 RLS 视图列表（`00-数据依赖矩阵.md` §四）未明确包含 `dim_staff` / `dim_staff_ex`。
|
||||
- 影响：是否已经为这两张员工表建好 `app.v_*` 视图与 FDW 外部表？P3 实施前需先校验或补建。
|
||||
|
||||
11. **【飞球 consume_money 三种口径混淆 vs 看板优化 PRD】 待 Neo 确认**
|
||||
- `apps/etl/connectors/feiqiu/CLAUDE.md` 强制规则 1：DWS 层及下游统一用 `items_sum`。
|
||||
- `2026-04-08__board-finance-optimization.md` 3.1 经营一览补充指标：使用 `confirmed_income`（确认收入），与 `items_sum` 是否一致需要校验（`confirmed_income` 是 `items_sum - 优惠后` 还是另一口径？文档未明示）。
|
||||
- 影响：客单价 / 日均额 的分子口径需要在落地前明确，否则数据失真。
|
||||
|
||||
---
|
||||
|
||||
> 备注：本脑图聚焦"是什么"与"为什么这样设计"。**字段级精确定义**应回到对应源文档（特别是 `apps/etl/connectors/feiqiu/CLAUDE.md` 的 12 条 DWD 规则、`docs/reports/DWD-DOC/` 校准清单、各 SPEC 的"设计要点"小节）。本脑图不替代权威文档，仅作为"产品全景索引"。
|
||||
Reference in New Issue
Block a user