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

docs/prd/PRD审阅-Q&A-R2.md

@@ -0,0 +1,297 @@
+# PRD 审阅 Q&A — 第二轮
+
+> 基于第一轮 Q&A 回答中的新信息，进一步澄清和细化。
+> 请对每个 Q 填写 A，完成后进入数据依赖矩阵和 SPEC 任务拆分阶段。
+
+---
+
+## 一、任务系统深化（基于 Q1.1 回答）
+
+### Q2.1 任务生成器的"跳过 vs 更新"逻辑
+
+你说"客户-助教-类型相同则跳过，不同则更新"。这里有几个边界需要确认：
+
+- Q2.1a：如果类型相同但优先级变了怎么办？例如昨天是"优先召回"（max(WBI,NCI)=6），今天指数涨到 8 变成"高优先召回"。类型都是"召回"，但优先级不同。这种情况是跳过还是更新？
+- Q2.1b："更新"是指修改原任务记录（保留原 ID，更新类型和时间），还是关闭旧任务、创建新任务？这影响任务历史追溯。
+- Q2.1c：任务类型的完整枚举是什么？根据 PRD 我整理出以下类型，请确认是否完整：
+  1. 高优先召回（max(WBI,NCI) > 7）
+  2. 优先召回（max(WBI,NCI) > 5）
+  3. 客户回访（完成召回后未备注）
+  4. 关系构建（RS < 6）
+  5. 还有其他类型吗？比如"新客欢迎"、"充值未回访"是否作为独立任务类型？
+
+**A：例如昨天是"优先召回"（max(WBI,NCI)=6），今天指数涨到 8 变成"高优先召回"，这是2个类型的任务。任务类型有4种："高优先召回""优先召回""客户回访""关系构建"。
+"更新"是指关闭旧任务、创建新任务。
+你列全了，就4个条件，优先级从上往下。没有其他任务类型。
+**
+
+---
+
+### Q2.2 回访任务 48 小时滞留机制
+
+你说"回访类任务需要至少滞留 48 小时"。需要明确：
+
+- Q2.2a：48 小时是从任务生成时间算起，还是从任务最后一次更新时间算起？
+- Q2.2b：48 小时内如果任务生成器计算出该客户不再需要回访（比如指数变化），是保留任务不动，还是标记为"待过期"？
+- Q2.2c：48 小时到期后，如果助教仍未完成回访，任务是自动消失还是降级为其他类型？
+
+**A：
+48小时是从任务生成时间算起。
+我认为，还要加一个机制，对每条产生的任务，有个状态，和有效期（有效期默认为空）。
+比如，48小时内如果任务生成器计算出该客户不再需要回访（比如指数变化）的情况。先将此任务的有效期填充为任务生成时间+48小时。标记状态为"有效"。
+每小时会有数据轮询更新（使用系统管理后台控制），轮询到超过48小时的任务，则标记状态为"无效"。
+新的回访任务会顶替老的回访任务。
+
+其他可能性：
+A:优先召回，变更为高优先召回：直接新建一个任务，原优先召回的任务标记无效，有效期始终为空。
+B:回访任务，5小时变更为高优先召回，24小时后又变回回访任务：5小时时新建一个任务，原回访任务标记为有效，增加有效期。24小时后，发现存在一个有效的回访任务且有有效期，则将原回访任务标记为无效，新建一个新的有效状态的回访任务。
+
+
+**
+
+---
+
+### Q2.3 任务完成的数据时效问题
+
+你在 Q1.8 中提到了一个关键场景：助教完成召回任务后顺手做了备注，但系统还不知道召回已完成。需要进一步明确：
+
+- Q2.3a："系统还不知道"是因为 ETL 数据延迟（上游 API 数据还没同步到 DWD），对吗？这个延迟通常是多久？
+- Q2.3b：数据回溯机制的触发时机是什么？是每次任务生成器运行时检查，还是有独立的回溯任务？
+- Q2.3c：回溯后，原来的"普通备注"需要重新走 AI 应用 6 的含金量评分吗？
+
+**A：是的，是因为 ETL 数据延迟（上游 API 数据还没同步到 DWD），通常延迟24小时内。数据回溯机制的触发时机是完成了召回认为时，进行回溯查看召回服务结束后（服务结束时间）有无新的备注，判断是否完成了一个回访任务。回溯后，原来的"普通备注"变为"回访备注"，走AI应用含金量评分。**
+
+---
+
+## 二、用户系统与租户管理（基于 Q1.7 回答）
+
+### Q2.4 球房 ID 与 site_id 的映射
+
+你说球房 ID 是"2 字母 + 3 数字"的业务代号，和 site_id 一一对应。
+
+- Q2.4a：这个映射关系存在哪里？是需要新建一张映射表（如 `site_code_mapping`），还是在现有的某个表上加字段？
+- Q2.4b：球房 ID 是谁来创建和维护的？系统管理员在系统管理后台创建租户/站点时指定？
+- Q2.4c：如果用户输入了一个不存在的球房 ID，申请流程怎么处理？直接拒绝还是允许提交但标记为"待确认"？
+
+**A：在系统管路后台进行管理，需要建立映射表。申请流程不是自动的，申请的用户可能填入任何字符，任何信息，最终还是由租户管理员进行审核通过，并关联球房里的助教或员工，当然也支持不关联，直接给身份。所以，如果用户输入了一个不存在的球房 ID，对流程无任何影响，仅在租户的管理后台关联信息处显示“没有找到关联信息”的提示即可。**
+
+---
+
+### Q2.5 租户管理后台的定位
+
+你提到"租户管理后台还未建设"，且功能为：用户审核/用户管理/Excel 上传。需要确认：
+
+- Q2.5a：租户管理后台是独立的 Web 应用，还是集成到现有的 `apps/admin-web/`（系统管理后台）中作为一个模块？
+- Q2.5b：租户管理后台的登录方式是什么？你说"单独指定用户名密码"，这是每个店铺一套凭据，还是每个管理员一个账号？
+- Q2.5c：租户管理后台和系统管理后台的权限边界是什么？系统管理后台能看所有店铺，租户管理后台只能看自己店铺？
+
+**A：apps/admin-web/和租户管理后台完全是两套应用。
+租户管理后台是独立的 Web 应用。
+租户管理后台的登录方式是独立的入口。单独指定用户名密码是指每个租户有一套凭据，一个租户有若干管理员，每个管理员一个账号。
+租户管理后台和系统管理后台的权限边界是：系统管理后台能看所有店铺，并监控管理所有连接器整个ETL系统，管理所有租户的后台管理员，为系统级维护平台。租户管理后台是开放给租户管理员的，则只能查看管理自己店铺。**
+
+---
+
+### Q2.6 用户申请中的"申请身份"
+
+你说申请表单有"申请身份"字段。
+
+- Q2.6a：这个"身份"是自由文本输入，还是从预定义列表中选择？如果是列表，有哪些选项？（助教、前台、店长、管理员？）
+- Q2.6b：申请的身份和审核后实际分配的身份可以不同吗？（比如申请"助教"但管理员审核时改为"前台"）
+- Q2.6c：一个用户可以同时属于多个店铺吗？（比如连锁店的区域经理）
+
+**A："身份"是自由输入的文本。仅为申请时文本，审核时需要管理员指定权限管理体系里的身份。一个用户可以同时属于多个店铺，这里有重要补充，租户和店铺是2个概念。比如租户下有连锁店铺。所以在权限管理里，存在租户级的管理员和店铺级的管理员。由租户级管理员进行管理。**
+
+---
+
+## 三、Excel 上传细化（基于 Q1.10 回答）
+
+### Q2.7 Excel 模板与冲突处理
+
+- Q2.7a：三种 Excel 类型（财务支出、团购收入、助教工资调整）的模板，是否需要我来设计表头结构？还是你已有模板？
+- Q2.7b：你说"发现主键冲突的进行提示，类似 IDE 的 diff 确认交互"。这个 diff 交互是在前端实现（上传后立即展示冲突），还是后端先存为"待确认"状态，管理员再逐条处理？
+- Q2.7c：财务支出的维度列表（房租、水电、物业等）是固定的还是可扩展的？如果管理员想加一个新的支出类别怎么办？
+
+**A：还有一个表要补充，充值业绩归属表，每行将记录充值的日期，会员名称，金额，分配给哪个助教，记多少奖励金额。
+共4种模版，你来帮我设计表头结构，注意使用中文，设计好后，我来校对。 diff 交互是在前端实现。确认每个替换或保留项目，然后以保存为准进行修改。财务支出的维度列表（房租、水电、物业等）是固定的，若想扩展需要代码级改动，还需要更新小程序UI。
+再补充下前文，第一轮QA，助教的奖罚，在一个助教，一个月的周期内，可以存在多笔奖罚。
+
+**
+
+---
+
+### Q2.8 助教工资调整的数据流
+
+- Q2.8a：Excel 上传的扣款/奖金数据，最终写入哪里？是写入 `dws_assistant_salary_calc` 表的某些字段，还是新建一张调整表？
+- Q2.8b：助教姓名+编号的匹配逻辑是什么？如果 Excel 中的姓名/编号和 ETL 中的 `dim_assistant` 不匹配怎么处理？
+- Q2.8c：扣款/奖金是否影响定档业绩？还是只影响最终工资金额？
+
+**A：是写入 `dws_assistant_salary_calc` 表的某些字段，还是新建一张调整表？这个你来分析，看最科学合理的做法。如果 Excel 中的姓名/编号和 ETL 中的 `dim_assistant` 不匹配，在上传时就会校验提醒。扣款/奖金只影响最终工资金额，不影响定档业绩。**
+
+---
+
+## 四、定档折算惩罚细化（基于 Q2.6 回答）
+
+### Q2.9 惩罚规则的数据实现
+
+你给出了非常详细的惩罚规则，我需要确认几个实现细节：
+
+- Q2.9a：规则 1（禁止团购自开台挂本人专业课）的检测逻辑：系统如何判断"是助教自己开的台"？是通过订单中的会员 ID = 助教关联的会员 ID 来判断，还是需要其他标识？
+- Q2.9b：规则 2（同一时间最多 2 名助教挂台）的"同一时间"如何定义？是课程时间段有重叠即算，还是完全相同的开始/结束时间？
+- Q2.9c：豁免流程在数据层面如何记录？是在订单上打一个"已豁免"标记，还是有独立的豁免审批记录？
+- Q2.9d：惩罚计算是在 ETL 的 DWS 层自动完成，还是需要人工触发？计算频率是每日还是每月？
+
+**A：规则1 实际上忽略吧，靠日常运营，前台来控制，系统无法监测。"同一时间"，是课程时间段有重叠即算。豁免不需要审批，在响应的表中做标记记录即可，目的是让业绩和薪酬计算正确无误。惩罚计算是在 ETL 的 DWS 层自动完成，计算频率是每日。**
+
+---
+
+## 五、AI 应用细化
+
+### Q2.10 AI 应用的调用架构
+
+- Q2.10a：6 个 AI 应用都是阿里云百炼的独立应用（各有自己的 app_id），对吗？还是共用一个应用通过 prompt 区分？
+- Q2.10b：AI 应用 1（通用对话）需要做信息隔离。这个隔离是在 prompt 层面控制（只传入该用户有权看到的数据），还是在百炼平台侧配置？
+- Q2.10c：AI 的流式返回，前端是通过 SSE（Server-Sent Events）还是 WebSocket 实现？后端是直接透传百炼的流式响应，还是有中间缓存？
+
+**A：6 个 AI 应用都是阿里云百炼的独立应用，每个应用都有独立的app_id。AI 应用 1（通用对话）需要做信息隔离，这个隔离是通过传参数给AI 应用实现的。参数有3个 身份（助教/管理者）、昵称 和 ID。然后百炼平台侧根据参数进行数据查询的隔离。AI 的流式返回所有信息，需要你在web上查文档获得**
+
+---
+
+### Q2.11 AI 对话入口梳理
+
+PRD 中提到多个页面有 AI 入口，我整理如下，请确认是否完整：
+
+| 入口页面 | 触发方式 | 使用的 AI 应用 | 传入上下文 |
+|---------|---------|-------------|---------|
+| task-list.html | 长按任务 → "问问AI助手" | 应用 4 + 应用 5 | 任务详情 + 客户-助教关系数据 |
+| task-detail.html | 页面内 AI 按钮 | 应用 4 + 应用 5 | 任务详情 + 客户-助教关系数据 |
+| board-finance.html | 页面内"问问助手" | 应用 2 | 当前筛选条件下的财务数据 |
+| customer-detail.html | 页面内 AI 按钮 | 应用 3 | 客户全信息 |
+| chat.html | 直接对话 | 应用 1 | 来源页面上下文 |
+| performance.html | 有 AI 入口吗？ | ？ | ？ |
+| board-customer.html | 有 AI 入口吗？ | ？ | ？ |
+| board-coach.html | 有 AI 入口吗？ | ？ | ？ |
+
+- Q2.11a：上表是否正确？有遗漏或错误吗？
+- Q2.11b：应用 6（备注含金量判断）是系统自动调用的（提交备注时后台触发），不需要用户手动触发，对吗？
+- Q2.11c：从非 chat.html 页面跳转到 chat.html 时，是新开一个对话，还是可以继续之前的对话？
+
+**A：更新：
+
+| 入口页面 | 触发方式 | 使用的 AI 应用 | 传入上下文 |
+|---------|---------|-------------|---------|
+| task-list.html | 长按任务 → "问问AI助手" | 应用 1 | 任务详情 + 客户-助教关系数据 |
+| board-coach.html；board-customer.html；board-finance.html ；customer-service-records.html；my-profile.html；performance-records.html；performance.html；task-list.html | 右下角AI 按钮 | 应用 1 | 页面内容 |
+| task-detail.html；coach-detail.html；customer-detail.html | 页面内"问问助手" | 应用 1 | 页面内容 |
+
+通过以上入口，进入chat.html，新开一个对话，第一条信息就是传入的上下文内容。
+
+
+用于页面信息更新的：
+
+| 页面-内容 | 触发方式 | 使用的 AI 应用 | 传入上下文 |
+|---------|---------|-------------|---------|
+| board-finance.html - 交叉筛选条件 各结果 AI 智能洞察 | 建立轮询任务，最小间隔：每日更新 | 应用 2 | 页面查询结果原始数据 与 环比数据 |
+| customer-detail.html - 消费习惯 ， task-detail.html - 消费习惯 | 建立轮询任务：当发现当前客户有新增消费结算时更新 | 应用 3 | 客户60天订单详情（***这里需要整理订单信息详情，你需要做一个文档，整理DWD层暂时只用feiqiu的连接器的DWD***），客户应该到店日期，当前与上次到店的间隔日期。 | 
+| task-detail.html - 客户和我的关系分析、任务建议、一句话总结、我的关系情况总结。 | 建立轮询任务：当发现当前客户有新增消费，且发生了当前助教参与的结算时，进行更新。 | 应用 4 | 客户与我的关系相关60天订单详情（***同应用3的一样，只不过要筛选出与当前助教有关的订单***），客户应该到店日期，当前与上次到店的间隔日期，该助教对此客户的全部备注列表。 | 
+| task-detail.html - 5条话术参考 | 建立轮询任务：应用4调用时。 | 应用 5 | 应用4上传的内容以及应用4返回的内容。 | 
+| task-detail.html - 备注星级 | 建立轮询任务：当完成回访任务时。| 应用 6 | 触发回访任务的备注；本客户的全部信息（客户详情页内容）；所有助教对本客户的全部备注。 | 
+
+**
+
+---
+
+## 六、页面与数据细节
+
+### Q2.12 board-customer.html 的"最大消费潜力"
+
+你在 PRD 中写"通过统计注册用户日期、最近30天充值与金额、最近30/10天消费金额总和、最近30天消费频率变化，分析出每个客户的消费潜力"。
+
+- Q2.12a：这个"消费潜力"和新增的 SPI（消费力指数）是什么关系？SPI 已经涵盖了消费水平、消费速度、消费稳定性。是否可以直接用 SPI 替代这个"最大消费潜力"排序维度？
+- Q2.12b：如果不用 SPI 替代，这个"消费潜力"需要单独建模还是用简单的加权公式？
+
+**A：SPI 就是"消费潜力"，可以用此维度进行排序**
+
+---
+
+### Q2.13 绩效计算中的"到达 XXX 即得 YYY"
+
+PRD 中的跳档激励计算示例我理解了，但需要确认：
+
+- Q2.13a：跳档线的时长阈值（Tier0→1: 120h, Tier1→2: 150h, Tier2→3: 180h, Tier3→4: 210h）是固定值还是可配置的？存在哪里？
+- Q2.13b：打赏课的激励系数（如 0.5-0.4=0.1, 0.4-0.35=0.05）是什么含义？是不同档位的打赏课提成比例差？
+- Q2.13c：这个"到达即得"的展示，是实时计算的（每次打开页面都重新算），还是基于 DWS 预计算的快照？
+
+**A：跳档线阈值存在DWS里啊，你去数据库里找找。打赏课的激励系数做减法，是不同档位的打赏课提成比例变化的差值。这个应该是快照，当发现有新的助教服务记录时，计算并落到快照**
+
+---
+
+### Q2.14 customer-detail.html 的消费记录展示
+
+PRD 中区分了"台桌结账"和"商城订单"两种样式。
+
+- Q2.14a：除了这两种 settle_type，还有其他类型吗？（比如充值、退款、团购核销等）这些类型在消费记录中如何展示？
+- Q2.14b："正价金额，（若有团购，或折扣，展示实付金额）"——这里的正价金额从哪个字段取？是 `original_amount` 还是 `total_amount`？
+- Q2.14c：消费记录的时间范围是多少？展示全部历史还是最近 N 天？
+
+**A：充值需要加入，但我不确定，你要在数据库里寻找下，能否区分"台桌结账"，"商城订单"和"充值"，退款先不用管，团购核销会集成在"台桌结账"中。对于正价金额，我在财务看版设计时，好像一些文档那个中有规定，查询下文档和数据库DWS相关的内容，确定是哪个字段，这个一定要我复核！。customer-detail.html默认显示最近10条，拉到底再懒加载，一次10条。**
+
+---
+
+## 七、数据架构确认
+
+### Q2.15 小程序数据库 Schema 规划
+
+你确认了小程序的所有表都还没建。在我开始设计之前，需要确认几个架构方向：
+
+- Q2.15a：`test_zqyy_app` 中的表是全部放在 `public` schema，还是按功能分 schema（如 `auth`、`biz`、`notes`）？
+- Q2.15b：小程序的业务表（任务、备注、AI 对话等）和现有的 RBAC 表（users、roles、permissions 等）是否在同一个 schema？
+- Q2.15c：FDW 外部表统一放在 `fdw_etl` schema，这个不变对吧？
+
+**A：按功能分 schema更合理吧。业务表和用户表应该不在同一个schema。fdw机制不变。**
+
+---
+
+### Q2.16 数据新鲜度与缓存策略
+
+小程序的很多页面依赖 ETL 数据（通过 FDW 读取），ETL 数据的更新频率会影响用户体验。
+
+- Q2.16a：ETL 的全量刷新频率是多少？每天一次？多次？
+- Q2.16b：对于实时性要求较高的数据（如任务完成状态、备注），是否需要绕过 ETL 直接从上游 API 获取？
+- Q2.16c：看板页面（finance/customer/coach）的数据是否需要缓存层？还是每次都实时查询 FDW？
+
+**A：上线后，ETL 不会全量刷新，仅会间隔1小时，全量刷新最近2小时的数据。不要直接绕过API。看板页面我希望能有缓存层。**
+
+---
+
+## 八、遗留操作项确认
+
+### Q2.17 API Key 迁移
+
+第一轮 Q4.4 你同意将 API Key 移到 `.env`。确认以下操作：
+
+- 将 `sk-6def29cab3474cc797e52b82a46a5dba` 添加到 `.env` 中，变量名建议 `BAILIAN_API_KEY`
+- 将 `541edb3d5fcd4c18b13cbad81bb5fb9d` 添加到 `.env` 中，变量名建议 `BAILIAN_TEST_APP_ID`
+- 从 PRD 文档中移除这两个值，替换为变量名引用
+- 同步更新 `.env.template`
+
+- Q2.17：变量名是否同意？还是你有其他命名偏好？
+
+**A：同意！**
+
+---
+
+### Q2.18 PRD 文档合并
+
+第一轮 Q1.4 你确认 board-finance.html 两段需要合并。
+
+- Q2.18：这个合并操作是否等全部 Q&A 完成后，在最终修订 PRD 时一并处理？
+
+**A：**
+
+
+
+
+## 补充
+本次补充的内容中，以及第一轮QA涉及到很多条件触发，可以考虑为这些条件触发的，单独做一个触发器机制。
+---