Neo-ZQYY/docs/_overview/01-product-overview.md

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 的"设计要点"小节）。本脑图不替代权威文档，仅作为"产品全景索引"。