# PRD 审阅 Q&A

> 基于 `docs/prd/小程序前后端.txt` 的系统性审阅。
> 请对每个 Q 填写 A，完成后我们据此修订 PRD。

---

## 一、表达不清楚 / 需要补充的部分

### Q1.1 任务系统的核心定义

任务系统是整个小程序的核心，但文档缺少对"任务"概念的正式定义。需要你明确：

- Q1.1a：任务是系统每天自动生成的（如每日凌晨根据指数重新计算），还是有一个持久化的任务池（一旦生成就一直存在直到完成/过期）？
- Q1.1b：任务的完整生命周期是什么？（生成 → 展示 → 完成/放弃/过期？还有其他状态吗？）
- Q1.1c：任务是否有过期机制？比如一个召回任务，客户自己来了但不是该助教服务的，算什么？
- Q1.1d："置顶"和"放弃"是助教个人维度的操作（只影响自己看到的列表），还是全局的（其他人也能看到）？

**A：
首先，任务是每天动态生成的，每天上午4点之后的第一次启动“任务生成器”时，为每个助教，分配任务。生成规则是基于指数和实时计算和若干规则的条件交叉（原文档已说明）。
任务的唯一标识 由客户-助教-类型-生成时间构成。若“任务生成器”生成了一个任务，则读取已存在的 生成时间最晚的 客户-助教-类型 相同的任务进行对比，若客户-助教-类型相同，则跳过，不同则更新任务。这样进行任务更新是否合理？既保证了任务的变更，又可以对持续的任务进行延续。

举例：客户A之于助教甲，第一天“任务生成器”返回“回访”任务，第二天返回“优先召回”任务。第一天的任务就被覆盖掉了。任务更新，记录时间。
若第二天返回“回访”，则最大序号的 客户-助教-类型 任务相同，不做更新。保留任务生成时间。
注意，“回访”类任务需要至少滞留48小时。这个看如何科学合理的实现。
**
---

### Q1.2 消费指数的定义

"新增指数"部分提到"增加一个消费指数，依据：消费能力，消费频率，消费趋势，全部会员卡储值额度"，但没有给出算法框架或权重思路。现有的 NCI/WBI 都有详细的分项说明。

- Q1.2a：这个新消费指数需要达到和 NCI/WBI 同等级别的算法定义吗？还是先给出大致权重方向，实现时再调？
- Q1.2b：它和 `dws_member_consumption_summary` 中已有的 `customer_tier`（客户分层）是什么关系？是替代还是补充？

**A：见文档 docs\prd\SPI 消费力指数.md。用指数替代customer_tier的作用**

---

### Q1.3 新增统计的四个指标命名

文档中多次写"另外，给这个统计，起一个合适的直观易懂的名字"。这些名字需要你定下来，因为它们会成为数据库字段名、API 字段名、前端展示文案的基础。

需要命名的四个指标：
1. 订单流水-助教服务分成（助教参与订单总流水减去助教分成）
2. 助教时效流水（按服务时长折算的助教贡献订单金额）
3. 助教时效流水-助教服务分成（时效流水减去助教分成）
4. 以上三个 + "订单流水"本身，是否需要统一的系列命名？

**A：你帮我定下来吧，就是个命名的工作，要求合适的直观易懂的名字。最好是统一的系列命名。**

---

### Q1.4 board-finance.html 重复

文档中有两段 `## board-finance.html`，内容不同但有重叠：
- 第一段：提到 AI 接口和 DWS 数据快照优化
- 第二段：提到筛选逻辑、预收资产板块消失规则、收入结构过滤

这两段是否应该合并为一段？是否有遗漏的内容？

**A：需要合并，可能是我疏漏了，没有放在一起**

---

### Q1.5 权限列表的完整枚举

你说"权限列表是固定的"，但文档只提到了部分权限。请完整列出所有权限项，例如：

- 任务板块可见
- 看版板块可见
- 看版-财务板块可见
- 看版-客户板块可见
- 看版-助教板块可见
- （还有其他的吗？比如：备注管理、AI 对话、绩效查看、Excel 上传等？）

**A：其他权限都是通用的了。直接从入口卡死即可。Excel 上传是每个店的WEB管理端，单独指定用户名密码。**

---

### Q1.6 users 表和申请审核流程

数据库中 `users` 表没有申请状态字段，LAUNCH-CHECKLIST 中提到需要建 `user_application` 表但还没建。

- Q1.6a：`users` 表是审核通过后才创建记录，还是申请时就创建（用 status 字段区分状态）？
- Q1.6b：`users` 表目前没有 `avatar_url` 字段，小程序是否需要展示用户头像？如果需要，头像从哪来（微信授权 or 自行上传）？

**A：这引出了一个很大的话题，小程序的用户系统还未搭建。需要你帮我策划，我现在可以给到的信息：申请时就要创建用户，用 status 字段区分状态；头像通过微信授权获取，暂不支持自行上传，暂时没有必要。**

---

### Q1.7 助教和小程序用户的映射

ETL 中的助教是 `dwd.dim_assistant`（来自上游飞球 SaaS），小程序用户是 `zqyy_app.users`。

- Q1.7a：一个助教登录小程序后，系统怎么知道他对应 ETL 中的哪个 `assistant_id`？是通过手机号匹配、管理员手动绑定、还是其他方式？
- Q1.7b：同理，小程序中的"客户"（member）和 ETL 中的 `dim_member` 是通过什么关联的？客户是否也需要登录小程序？

**A：这里我需要更改一些信息表单。
申请时，需要先验证微信号登录。并填写表单（由一个文本框，改为若干字段）：球房ID、申请身份、手机号、编号、昵称。
球房ID：输入框，必填。区别于SiteID，这里的球房ID更偏向于业务侧使用。是一组简单的，由2个字母+3个数字组成的球房代号。和SiteID一一对应。
申请身份：输入框，必填。
手机号：点击调用微信已记录的用户手机号进行填入。
编号：收入框，选填。
昵称：收入框，必填。

申请后，在租户的管理后台（还未建设），新增用户管理页面。其中列出用户列表，可以筛选不同状态的用户。在未审核列表中，管理员可以看到申请信息。系统通过球房ID + 手机号，提示词申请用户与当前助教或员工的对应关系，方便管理员审核。

注意!客户不用小程序，小程序的用户群体仅为球房管理人员，助教等球房工作人员。是一个TOB的垂直小程序。
**

---

### Q1.8 备注系统的数据模型

文档多处提到"备注"（客户备注、放弃任务备注、回访备注），但没有定义备注表的结构。

- Q1.8a：备注存在哪个库？`zqyy_app` 还是 ETL 库？
- Q1.8b：是否需要区分备注类型（普通备注 vs 生日信息 vs 回访备注 vs 放弃任务原因）？还是统一一张表用 `type` 字段区分？
- Q1.8c：备注是否支持富文本/图片，还是纯文本？

**A：对的，小程序的所有数据库，所有Schema，所有表均没有建立。需要完善所有小程序功能需求文档后，你来帮我做数据库的架构和后端服务架构，接口等内容的规划，并一步步完成小程序前后端的开发。

备注是登录的用户对客户/助教的备注行为，我认为在test_zqyy_app更合理
我建议用一张表，type字段区分即可。其中，回访备注，普通备注，生日信息都是通过一个操作口径进行的，使用其他条件进行隔离：
回访备注：“回访”类型任务中，添加备注，即为回访备注。走AI含金量判断的流程。完成备注后，即标记此任务完成。这里有个特殊情况需要处理，若某助教完成了召回的任务，顺手做了备注。因为数据不及时的问题，系统还不知道完成了召回认为，此条备注被当做了普通备注。这种情况要单独处理。当发现某助教完成了召回任务，任务应改变为用户回访，但助教也完成了回访（在召回任务数据到达之前），则应标记再次完成回访任务，完成召回任务后的第一条备注当做回访任务完成的依据（走AI含金量判定等流程），然后需要再次刷新，生成任务。做一个数据回溯机制。
备注当前是纯文本。
**

---

### Q1.9 "跟"和"弃"icon 的触发条件

文档说"跟代表此客户出现在了该助教的任务列表中，且任务类型为高优先召回或优先召回"。

- Q1.9a："弃"代表什么？是该助教主动放弃了这个客户的任务？
- Q1.9b：如果一个客户同时属于多个助教，每个助教看到的"跟/弃"状态是独立的吗？

**A："弃"是该助教手动放弃了此任务。每个助教与客户的关系都是独立的，任务是独立的，所以"跟/弃"状态是独立的。**

---

### Q1.10 Excel 上传的具体需求

文档最后提到"管理后台 - Excel数据上传"，几乎没有细节。

- Q1.10a：哪些 DWS 表支持 Excel 导入？目前看 `dws_ml_manual_order_alloc` 和 `dws_ml_manual_order_source` 是 Excel 导入的，还有其他的吗？
- Q1.10b：校验规则是什么？（字段类型、必填、外键引用、金额精度？）
- Q1.10c：导入是覆盖还是追加？主键冲突怎么处理？
- Q1.10d：你提到"针对每个连接器下的租户（tenant 下有 site）的后端管理系统"，这个租户/站点管理的范围是什么？只是 Excel 上传的入口，还是包含租户 CRUD、站点配置等？

**A：
EXCEL导入内容类型：
财务类-支出类，按月提交：主键为支出维度：房租；水电；物业；食品饮料进货；耗材；报销；固定人员工资；其他费用；
财务类-团购类，按月提交：逐渐为平台名称：平台-收入；
工资类-助教工资，按月提交：主键为助教姓名+助教编号+维度（扣款/奖金）：扣款-金额-原因；奖金-金额-原因。
每个类型，有一个Excel模版。

校验规则：必填，金额精度，表头格式，类型合法。提交的月份+主键冲突。
发现导入的月份+类型冲突，则默认追加，发现主键冲突的进行提示，类似IDE的diff确认交互。
这个针对租户的后台管理系统，现在仅有很少功能：用户审核/用户管理/Excel上传.
租户 CRUD、站点配置是通过系统管理后台操作的。
**

---

## 二、与项目现状的冲突

### Q2.1 fdw_etl schema 为空

`zqyy_app` 数据库中 `fdw_etl` schema 存在但没有任何表或视图。小程序后端无法读取 ETL 数据。PRD 中大量页面（task-list、board-finance、board-customer、board-coach、performance 等）都依赖 ETL 数据。

- Q2.1：你是否已经意识到这个问题？FDW 映射是否作为第一优先级处理？需要映射哪些表？（我可以根据 PRD 页面需求帮你整理完整的 FDW 映射清单）

**A：为我整理完整的FDW映射清单。注意我们在开发环境，全部使用测试库。**

---

### Q2.2 ETL app schema 为空

ETL 库中的 `app` schema（设计为 RLS 视图层）也没有任何对象。

- Q2.2：`app` schema 的 RLS 视图是否还在计划中？还是改为在 FDW 层面做数据隔离？

**A：RLS和FDW两层都要做。注意我们在开发环境，全部使用测试库。**

---

### Q2.3 tasks 表结构与 PRD 需求不匹配

`zqyy_app.public.tasks` 表只有通用字段（id, title, description, status, assignee_id, creator_id, site_id）。PRD 中的任务系统需要：任务类型、优先级、关联 member_id、关联 assistant_id、指数快照值、完成条件、放弃原因、置顶标记等。

- Q2.3：现有 `tasks` 表是为管理后台的 ETL 任务管理设计的，和小程序的助教任务是两个完全不同的概念。是否同意新建一张专用的助教任务表（如 `coach_tasks`），而不是改造现有表？

**A：tasks是ETL的调度任务，和小程序的助教任务完全两回事。
如我上文所说，支撑小程序的数据库，Schema，表都还没有开始建设，根据需求文档的确定和定稿，逐一进行建立，而且要和ETL的业务进行隔离。仅必要结果通过FDW传递。注意我们在开发环境，全部使用测试库。**

---

### Q2.4 dws_member_consumption_summary 缺少字段

PRD 要求"30天/60天/90天内的累计充值次数/累计充值金额"和"次均消费额度"，但现有表没有这些字段。

- Q2.4：这些字段是在现有 `dws_member_consumption_summary` 表上扩展，还是新建一张表？

**A：这个的字段增补方式的决定权给你，分析一个较为科学合理的方式进行扩张或新建表。我认为那些累计的可以放一个表问题不大。但次均消费额度和其他的不一样吧？**

---

### Q2.5 助教流水统计表不存在

PRD 中的"订单流水"、"助教时效流水"等四个新统计指标在 DWS 中完全不存在。

- Q2.5：这些统计是新建一张 DWS 表（如 `dws_assistant_order_contribution`），还是扩展到现有的 `dws_assistant_customer_stats` 或 `dws_assistant_daily_detail` 中？

**A：新建表进行实现**

---

### Q2.6 绩效计算中的"定档折算惩罚"

`dws_assistant_salary_calc` 有 `effective_hours` 等字段，但 PRD 中提到的"定档折算30分钟"这种惩罚机制在表结构中没有对应字段。

- Q2.6：定档折算的具体规则是什么？是否需要在 salary_calc 表中增加 `penalty_minutes` 或类似字段？

**A：折算触发与规则如下，需要适当的进行数据库建设和后端代码计算支持：

业绩惩罚补充规则（定档业绩折算）：
目的：防止助教利用低价团购/低台费订单/台费拼单等方式，低成本的“补时长、冲档位”，减少作弊空间，保障定档公平与球房收益。
 
实施方案：
一、助教行为规范
【规则1】禁止团购自开台挂本人专业课
助教不得使用任何团购/低价套餐/代金券，在适用区域内进行开台/开房。并购买助教专业课，将订单用于计入助教专业课服务时长。
适用区域：大厅（A、B、C、S、TV）和 麻将房（M1–M7）。
【规则2】指定区域内同一时间仅允许2名助教挂台
在指定区域内，同一订单下，同一台/房，同一时间段最多挂2名助教。
指定区域：大厅（A、B、C、S、TV）和 麻将房（M1–M7）。
若客人购买多人同时的专业课，则必须走“豁免流程”（见下）。
*老客户或熟人，需要3助教及以上的，前厅引导另外开台/房。

二、惩罚豁免（仅针对“真实客需”）
【豁免适用条件】
若触发了上述 规则1或规则2，但事实为客人真实提出的服务需求（例如：客人指定三名助教同场服务；或团购客人确需助教服务等）。
【豁免操作要求】
客户结账时，前台需核对真实客人在场，并将订单明确绑定到该真实客人名下。若新客则需要注册新会员。*可配合新客充值优惠或其他新客福利的营销活动。

未按要求留存客人信息的，一律不视为豁免。按以下方式进行惩罚处理。

三、惩罚处理
【核心原则】
本规则仅影响“定档业绩时长”的统计，不影响助教当月实际服务时长的工资结算。只影响定档，不影响实际工资时长。
举例说明：某中级助教本月实际服务基础课 140小时。
系统按本规则折算后，定档业绩时长被扣除 15小时，则：
定档业绩时长 = 140 − 15 = 125小时 → 归入 1档
工资档位确定后，工资仍按实际服务时长结算：
中级工资单价 = 108 − 18 = 90元/小时
工资 = 140 × 90 = 12,600元

【核算方式】
系统将符合处罚条件的订单，按照“每小时每名助教贡献的台费/房费流水”，并据此确定该单可计入的定档业绩时长。
步骤：
	计算台费会房费的每小时实收单价。
	上步骤的单价 ÷ 本次基础课助教人数 记做 单人贡献流水。
	若 单人贡献流水 ≥ 24元：每位助教按照课程服务时长，按满额计入定档业绩时长（=实际时长）；
若 单人贡献流水 ≤ 24元，该单按比例折算计入定档业绩时长，即：
定档业绩时长 = 实际时长 × （单人贡献流水 / 24）

示例：
订单：12.12元团购，A区，时长2小时，购买3个助教服务，2小时后离店，未保留客户信息，疑似助教团购拼单。每小时每名助教贡献：
r=(12.12*2)/(2×3)=4.04"元"

折算系数：
(4.04)/24=0.1683

定档业绩时长：
2"小时"×0.1683=0.3367"小时"=20.2"分钟  则定档业绩记录为20分钟"



**

---

## 三、文档内容的疑问

### Q3.1 订单流水计算示例数值不一致

文档中写"订单流水 = 200+400+600+320+100+800 = 2420元。也就是3个助教，每人+2820的订单流水"。

- Q3.1：2420 和 2820 不一致，正确值应该是 2420 对吧？

**A：对的，我写错了，不好意思。**

---

### Q3.2 客户归属的 RS 差距阈值

"如果多个助教对某客户的RS没有很大的差距（50%）以上，则此客户属于多个助教"。

- Q3.2a：50% 是指 RS 值的绝对差还是相对差？例如助教A的RS=8，助教B的RS=5，差距按什么算？
- Q3.2b：这和 `dws_member_assistant_relation_index` 中已有的 `os_label`（MAIN/COMANAGE/POOL）机制是什么关系？OS 已经实现了类似的归属逻辑，是否直接复用 OS 而不是用 RS 差距来判断？

**A：50% 是指 RS 值的相对差。(8-5)/8<0.5，则2个客户都能跟踪一个客户。**

---

### Q3.3 任务优先级0的公式

"根据(WBI+NCI)指数展示列表。>7为高优先召回。>5为优先召回"。

- Q3.3：WBI 和 NCI 都是 0-10 的分数，直接相加范围是 0-20。阈值 7 和 5 是对相加后的值判断，还是取 max(WBI, NCI) 判断，还是分别判断？

**A：取max(WBI, NCI)进行判断**

---

### Q3.4 回访任务的"2天内备注有效"

"出现过客户回访后，2天内备注有效。2天内再次出现客户回访任务，则旧的回访任务被顶替"。

- Q3.4a："2天"是自然日还是 48 小时？
- Q3.4b："顶替"是指旧任务自动标记为完成、取消、还是其他状态？

**A：48小时。"顶替"是指“任务生成器”生成了新认为，进行了顶替。**

---

### Q3.5 AI 应用6的评分阈值

"低于5则不算完成。高于等于5记做完成"，但后面又说"6分为标准分"。

- Q3.5：5 分是完成的最低线，6 分是"合格"的标准？两个阈值分别用在什么场景？

**A：统一使用6分为完成，几个线**

---

### Q3.6 performance.html 中"我的新客"定义

"首次服务过的客户在最近2月内，且服务总次数小于等于2"。

- Q3.6a："首次服务"是指该助教首次服务该客户，还是该客户首次到店？
- Q3.6b："服务总次数"是该助教对该客户的服务次数，还是该客户被所有助教服务的总次数？

**A："首次服务"是指该助教首次服务该客户。"服务总次数"是该助教对该客户的服务次数。**

---

## 四、修改优化建议

### Q4.1 拆分 PRD 为多个模块文档

当前 PRD 是一个巨大的 txt 文件，混合了指数算法、页面需求、AI 接口、权限系统、管理后台等完全不同的领域。建议拆分为：
- `prd/指数与算法.md` — 指数定义、计算逻辑、场景映射
- `prd/小程序页面.md` — 每个页面的数据源、交互、权限
- `prd/AI集成.md` — 6 个 AI 应用的输入输出定义
- `prd/权限与用户.md` — 登录、审核、RBAC
- `prd/管理后台扩展.md` — Excel 上传、租户管理

- Q4.1：你是否同意这个拆分方案？有需要调整的吗？

**A：对的，这个也是我所担心的。
我的开发场景将完全基于 Kiro推进。请按以下规则为我进行任务拆分与文档整理：
1、按依赖优先级排序并编号
- 先做基础依赖、公共能力、前置模块；
- 后做依赖其上的功能模块；
- 输出结果需带明确序号（如 P1、P2、P3… 或 1、2、3…）。
2、按可归属为同一个 SPEC 的任务进行分组
- 将能够归入同一项 SPEC 的相关任务归类到同一份文档中；
- 每组任务应具备清晰边界，避免跨 SPEC 混杂。
3、按顺序支持我逐个创建 SPEC 任务
- 我会按照你给出的顺序，依次创建多个 SPEC，由 Kiro 协助完成开发；
- 因此你的拆分结果必须具备明确的执行先后关系和可落地性。
4、表达方式面向 Kiro SPEC 启动与落地
- 文档表述请尽量采用便于启动 Kiro SPEC 的方式撰写；
- 内容应有利于后续生成/整理需求、设计与任务拆解（Kiro 的 Specs 通常围绕 requirements、design、tasks 结构展开）。
5、统一放置在单独目录下
- 请将上述拆分后的文档统一整理到一个独立目录中，便于我按顺序创建和管理多个 SPEC。
**

---

### Q4.2 建立数据依赖矩阵

建议建立一个"页面 → 数据表"的依赖矩阵，明确每个页面需要哪些 DWS/DWD 表，哪些已有，哪些需要新建或扩展。

- Q4.2：是否需要我在你回答完 Q&A 后生成这个矩阵？

**A：是的，在4.1之前生成。或单列为单独任务前的准备工作**

---

### Q4.3 AI 接口的结构化定义

目前 6 个 AI 应用的描述都是散文式的。建议每个应用用统一格式：
- 触发场景
- 输入字段列表（含数据源表）
- 输出字段列表
- 调用频率预估

- Q4.3：是否同意这个格式？

**A：同意！**

---

### Q4.4 API 密钥不应出现在 PRD 文档中

文档中直接写了阿里云百炼的 `api-key`。这个应该移到 `.env` 中，PRD 只写变量名引用。

- Q4.4：是否同意？我在后续修订时直接移除。

**A：同意，当前的KEY是临时的，帮我将API-KEY放到.env 中，然后在文档中移除。**

---

## 五、缺失的前置依赖

以下按阻塞程度排序，请确认优先级是否合理：

### Q5.1 FDW 映射（阻塞级）

`zqyy_app.fdw_etl` 没有任何外部表，后端无法读取 ETL 数据。需要先建立 FDW 外部表映射 DWS/DWD 关键表。

- Q5.1：是否同意这是第一优先级？

**A：是的，我同意这个第一优先级的任务。注意我们在开发环境，全部使用测试库。**

---

### Q5.2 用户-助教映射机制（阻塞级）

小程序用户登录后，系统需要知道他是哪个助教（或哪个角色）。需要建立映射关系。

- Q5.2：同 Q1.7，确认映射方式后才能设计。

**A：这个在前文已经说明，使用租户管理后台进行。**

---

### Q5.3 备注表（阻塞级）

任务系统、回访系统、AI 评分都依赖备注数据。

- Q5.3：同 Q1.8，确认数据模型后才能建表。

**A：同意这个第一优先级的任务。注意我们在开发环境，全部使用测试库。**

---

### Q5.4 任务表重构（阻塞级）

现有 `tasks` 表不适合 PRD 中的助教任务系统。

- Q5.4：同 Q2.3，确认方案后才能实施。

**A：同意，见上文。**

---

### Q5.5 AI 对话记录表（高优先）

PRD 要求"智能体的信息发送和返回内容都要在数据库中保留"。

- Q5.5：这张表建在 `zqyy_app` 中对吧？需要记录哪些字段？（我的建议：conversation_id, message_id, app_id, user_id, role, content, tokens_used, created_at, site_id）

**A：支持你的建议，另外，再额外增加 用户昵称，系统的话，昵称为“系统”**

---

### Q5.6 新增 DWS 统计字段/表（高优先）

消费指数、助教流水统计、充值时间窗口统计等。

- Q5.6：这些 DWS 变更是否需要等 ETL 流程稳定后再做？还是可以并行？

**A：可以并行，现在ETL相对稳定了。**

---

### Q5.7 dws_member_consumption_summary 扩展

补充充值次数/金额的时间窗口字段和次均消费。

- Q5.7：同 Q2.4。

**A：见上文，同意并支持。**
