root/Neo-ZQYY

Fork 0

Files

Neo fafc95e64c 在前后端开发联调前的提交20260223

2026-02-23 23:02:20 +08:00

24 KiB

Raw Blame History

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 字段名、前端展示文案的基础。

需要命名的四个指标：

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

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：见上文，同意并支持。

24 KiB Raw Blame History Unescape Escape