Neo-ZQYY/docs/_overview/04b-conflicts-P1-detail.md

# P1 文档冲突业务故事卡(13 条详细版)

> 生成日期:2026-05-04 / 来源:`04-doc-conflicts.md` § 一 P1 表 + Wave 0 三份产出
> 用途:把 P1 级别的 13 条文档冲突重写为业务故事卡,便于 Neo 决策
> 判定标记:A=过期-改文档 / B=现状对-归档 / C=待补 SPEC / D=Bug-改代码
> 注:本文件**不下结论**,仅给推荐选项与一句话理由,最终判定由 Neo 拍板

---

### P1-1. 维客线索表 schema 归属(public vs biz)

**关联页面/接口**:
- 数据表:`zqyy_app.public.member_retention_clue`(已建)
- 涉及页面:`task-detail`(L141 维客线索 8 条)、`customer-detail`(L268 维客线索 7 条)、`tenant-admin` 维客线索 CRUD
- 涉及 AI 应用:应用 3(消费分析)、应用 6(备注分析)、应用 8(整合去重落库)
- 涉及 SPEC:`docs/prd/specs/P10-tenant-admin-web.md`、`docs/prd/specs/00-数据依赖矩阵.md`

**业务背景**:
维客线索是门店与客户长期维护关系的关键资产(标签 + 摘要 + 详情 + 来源 + 提供人),既由门店管理员手工录入,也由 AI 应用 3/6 自动产出后经应用 8 去重整合落库。表已建在 `public` schema,但项目总体设计方向是"业务表归 `biz`"。

**冲突逻辑**:
- 数据依赖矩阵 / P10 SPEC:`zqyy_app.public.member_retention_clue`(已建,在 `public`)
- `P1-miniapp-db-foundation.md` Schema 规划:业务表应放 `biz`
- 现状(数据库):实际表在 `public.member_retention_clue`

**业务联系**:
- 上游:应用 8 写入 / tenant-admin 增删改
- 下游:小程序 task-detail / customer-detail 读取展示;后端 FDW 与 RLS 视图绑定该表 schema

**修改影响**:
- 若迁移到 `biz`:需要 DDL 迁移 + 更新所有 SQL 引用(估计后端 5-8 处) + RLS 视图重建 + 文档同步,工作量**中**
- 若保留 `public`:仅需在 `P1-miniapp-db-foundation.md` 加例外说明,工作量**小**

**推荐选项**:
1. **选项 A(迁移到 biz)**: 优:符合"业务表归 biz"总原则,长期一致 / 劣:需要 DDL 迁移 + 数据复制,有破坏现有 FDW 与 RLS 风险
2. **选项 B(保留 public + 文档说明)**: 优:零代码改动,稳定 / 劣:破坏总原则,后人困惑
3. **选项 C(迁移并保留 public 兼容视图)**: 优:平滑过渡 / 劣:双 schema 维护成本

**建议判定**: **C 待补** + 一句理由:Neo 决策保留还是迁移,本身是项目总规划取舍

**Wave 验证锚点**: 跑 `\dt zqyy_app.public.member_retention_clue` 与 `\dt zqyy_app.biz.member_retention_clue` 校验现状

*反馈：选项A,理由是保证项目工程的规范性。至于代价：需要 DDL 迁移 + 数据复制,有破坏现有 FDW 与 RLS 风险，可以单独起一个任务进行调研和风险评估。但要保持项目工程的规范性原则。*
---

### P1-2. login 跳转 approved 的目标页

**关联页面/接口**:
- `apps/miniprogram/miniprogram/pages/login/login.ts`
- `docs/miniprogram-dev/api-audit/login.md` L84-L94
- `docs/miniprogram-dev/api-audit/reviewing.md` L52
- `docs/miniprogram-dev/api-audit/no-permission.md` L50
- `docs/miniprogram-dev/api-audit/apply.md` L57
- `docs/miniprogram-dev/_hardcode-summary.md` 第 16-18 项

**业务背景**:
小程序员工登录后,后端返回 `user_status`,前端按状态路由到下一页。`approved`(已审核通过)状态应直接落到工作台。历史曾用 `/pages/mvp/mvp` 做最小可用版本(MVP)的工作台,后改名为 `task-list`。

**冲突逻辑**:
- 现状(代码 + `_hardcode-summary.md`):approved → `/pages/task-list/task-list`
- 旧文档(`reviewing.md` L52 / `no-permission.md` L50 / `apply.md` L57):仍写 `/pages/mvp/mvp`

**业务联系**:
- 上游:任何状态变化触发的 reLaunch(login / apply / reviewing 三处)
- 下游:用户从此进入任务工作台

**修改影响**:
- 仅文档同步:替换 3 处 `mvp/mvp` → `task-list/task-list`,工作量**小**
- 不涉及代码改动(代码已是 task-list)

**推荐选项**:
1. **选项 A(改文档)**: 优:与代码对齐,零功能风险 / 劣:无
2. **选项 B(保留旧路由别名)**: 优:旧版本兼容 / 劣:无意义,小程序无版本兼容压力

**建议判定**: **A 过期-改文档** + 一句理由:`mvp` 是历史命名,`task-list` 是当前唯一正确目标,旧文档 3 处批量替换即可

**Wave 验证锚点**: 检查 `apps/miniprogram/miniprogram/pages/login/login.ts` reLaunch 调用,确认仅有 `task-list`

*反馈：选项A,修改文档。并检查是否还有遗留代码，一并删除处理。*
---

### P1-3. task-detail 跳 chat / customer-service-records 时传 detail.id 而非 customerId

**关联页面/接口**:
- `apps/miniprogram/miniprogram/pages/task-detail/task-detail.ts`
- `apps/miniprogram/miniprogram/pages/chat/chat.ts`
- `apps/miniprogram/miniprogram/pages/customer-service-records/customer-service-records.ts`
- API 契约:TASK-2(`GET /api/xcx/tasks/{id}` 响应)
- `docs/miniprogram-dev/api-audit/task-detail.md` L67-L130

**业务背景**:
助教在 task-detail 页可点"问问助手"或"查看服务记录",分别跳到 chat 与 customer-service-records 页。这两个目标页都按"客户(customerId)"组织数据(查这个客户的对话历史 / 查这个客户的服务流水),但 task-detail 当前传的是 `detail.id`(任务 id),目标页拿到后语义错位。

**冲突逻辑**:
- 现状(代码):`navigateTo({ url: 'chat?customerId=' + detail.id })` — 但 `detail.id` 是 taskId
- 期望(目标页 chat.loadMessages):应传真正的 customerId
- 根因:TASK-2 响应未明确返回 `customer_id` 字段,前端只能拿 task 的 id

**业务联系**:
- 上游:task-detail 接口需在 TASK-2 响应里增加 `customer_id`
- 下游:chat 与 customer-service-records 拿到正确 customerId 才能加载

**修改影响**:
- 后端:TASK-2 响应增加 `customer_id` 字段(SQL JOIN dim_member)
- 前端:跳转参数改为 `customerId=detail.customer_id`
- 工作量**小**

**推荐选项**:
1. **选项 A(后端补字段 + 前端改跳转参数)**: 优:语义清晰,从源头修正 / 劣:需要后端发版
2. **选项 B(目标页同时支持 taskId 入口)**: 优:前端单边改 / 劣:目标页需双路径加载,复杂度上升

**建议判定**: **D Bug** + 一句理由:这是数据传参错误的实质 bug,不是文档问题,后端补 `customer_id` 字段是最干净的修法

**Wave 验证锚点**: 测试 task-detail 跳转后能否正确加载客户对话与服务记录


---

### P1-4. performance 跳 task-detail 时传 customerName 而非 task_id

**关联页面/接口**:
- `apps/miniprogram/miniprogram/pages/performance/performance.ts`
- `apps/miniprogram/miniprogram/pages/task-detail/task-detail.ts`
- `docs/miniprogram-dev/api-audit/performance.md` L82-L99
- 02a 矩阵 GAP-17

**业务背景**:
助教在 performance(绩效页)看到"我的服务记录明细"或"我的新客 / 常客"列表,期望点条目能跳到对应任务详情。但当前实现传的是 `customerName`(客户名字符串),task-detail 页根本无法用 customerName 定位到具体任务,因为同一客户可能有多条任务。

**冲突逻辑**:
- 现状(代码):`navigateTo({ url: 'task-detail?customerName=' + record.customerName })`
- 期望(task-detail.onLoad):应通过 `taskId` 拉取 TASK-2 响应
- 副作用:跳转后 task-detail 拿不到任务,只能 toast 失败

**业务联系**:
- 上游:performance 的服务记录条目(后端 PERF-1 响应)需要有 `task_id` 字段
- 下游:task-detail 按 task_id 加载

**修改影响**:
- 后端:PERF-1 响应增加 `task_id`(若该服务记录关联任务的话;部分历史记录可能无关联)
- 前端:跳转参数改为 `id=record.task_id`
- 工作量**小**

**推荐选项**:
1. **选项 A(后端补 task_id + 前端改参数)**: 优:语义正确 / 劣:历史无关联记录该字段为 null,需前端处理无 task 情况
2. **选项 B(取消跳转)**: 优:零工作 / 劣:体验损失,助教看不到任务上下文

**建议判定**: **D Bug** + 一句理由:与 P1-3 同源的传参错误,从源头补 `task_id` 字段最干净

**Wave 验证锚点**: 测试 performance 服务记录点击 → task-detail 是否正确加载


*P1-3 和 P1-4 一同反馈：同意你的初步判断，但谨慎起见，还是要从页面和产品设计出发，对业务进行理解的情况下，在深入调研这个问题（尤其整个APP页面与角色的传值规范性方面），如果最后结论不变，则进行修后端补字段及可能的前端改跳转参数处理。*


---

### P1-5. board-finance "AI 洞察" 12 项指标的 cache_type

**关联页面/接口**:
- `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts`(AI 洞察 12 项)
- 后端表:`biz.ai_cache`
- `docs/miniprogram-dev/api-audit/board-finance.md`
- AI 应用 2(财务洞察)
- 02a 矩阵 C13

**业务背景**:
财务看板底部展示"AI 洞察"12 项指标卡(优惠率 Top / 差异最大 / 建议关注等),来源是 AI 应用 2 的财务洞察输出,缓存在 `biz.ai_cache` 表(每日轮询)。前端区分这 12 项指标时需要按 `cache_type` 字段查询,但当前是前端 3 行硬编码,后端 `biz.ai_cache` 表对 `cache_type` 字段没有约定枚举。

**冲突逻辑**:
- 现状(前端):board-finance 用 3 个固定 cache_type 字符串硬编码取 12 项指标
- 现状(后端):`biz.ai_cache.cache_type` 无枚举约定文档
- 期望:统一定义 cache_type 枚举,前后端共享

**业务联系**:
- 上游:AI 应用 2(每日轮询写 ai_cache)
- 下游:board-finance 读取展示

**修改影响**:
- 新增 SPEC / 数据字典:cache_type 枚举表(估计 5-8 项)
- 后端:写入 ai_cache 时按枚举写入
- 前端:从硬编码改为枚举常量
- 工作量**中**

**推荐选项**:
1. **选项 A(新建枚举字典 + 共享 packages/shared)**: 优:前后端单一数据源 / 劣:需要新增枚举文件
2. **选项 B(后端 SPEC 文档定义,前端引用)**: 优:轻量 / 劣:无运行时校验
3. **选项 C(保持现状)**: 优:零工作 / 劣:加新指标必崩

**建议判定**: **C 待补** + 一句理由:这是真冲突,需要在 SPEC 中定义 ai_cache 的 cache_type 枚举,Neo 决策放哪份 SPEC

**Wave 验证锚点**: 跑 `SELECT DISTINCT cache_type FROM biz.ai_cache` 看现状有哪些值


*反馈：是的，在开发过程中，进行了若干次调优，你可以看下相关的历史Session。反复优化后的结果，从百炼AI接口返回的内容和前端页面呈现方面来看，现在的结果我比较满意。**但是！正如你说的，“统一定义 cache_type 枚举,前后端共享”的方式才是规范可靠的。这个修改是否需要让AI返回一些标准的标记，以进行信息对齐？深入调研，给我一个修正方案，然后再考虑文档同步问题。***



---

### P1-6. AI 触发器双 API:/admin/ai/triggers vs /trigger-jobs

**关联页面/接口**:
- `apps/admin-web/src/api/adminAI.ts`(`/api/admin/ai/triggers`)
- `apps/admin-web/src/api/triggerJobs.ts`(`/api/trigger-jobs`)
- 前端组件:`AITriggers.tsx`(用前者) / `BizTriggersTab` in `TriggerManager.tsx`(用后者)
- 后端表:`biz.trigger_jobs`(同一张表)
- 02b 矩阵 §五-3

**业务背景**:
admin-web 触发器管理页有两个 API 操作同一张 `biz.trigger_jobs` 表:`/api/admin/ai/triggers`(带 job_type 过滤,只返 AI 类) 与 `/api/trigger-jobs`(全量,返回所有触发器)。前者用于 AI 触发器编辑,后者用于业务触发器编辑,两者编辑的字段名也不一致(`cron/desc` vs `cron_expression/interval_seconds`)。

**冲突逻辑**:
- API A(adminAI.ts):`GET /admin/ai/triggers` + `PATCH /admin/ai/triggers/:id`,操作字段 `cron/desc`
- API B(triggerJobs.ts):`GET /trigger-jobs` + `PATCH /trigger-jobs/:id/config`,操作字段 `cron_expression/interval_seconds`
- 数据底层:同一张 `biz.trigger_jobs`

**业务联系**:
- 上游:无(直接对表)
- 下游:AI 触发器 / 业务触发器的启停与配置

**修改影响**:
- 若合并:前端两组件适配同一 API,后端一个 API 处理两种字段格式;工作量**中**
- 若保留分离:在 NS1 / NS-admin-web-backend-api 文档中明文写出"AI 用 A,业务用 B"
- 工作量**小**

**推荐选项**:
1. **选项 A(合并为一套 API)**: 优:DRY,长期清晰 / 劣:有迁移代码改动,容易引入回归
2. **选项 B(明文区分使用边界,保留双 API)**: 优:不动现有代码 / 劣:维护两套
3. **选项 C(API B 标记弃用,新代码全部走 A)**: 优:渐进迁移 / 劣:中间态较长

**建议判定**: **C 待补** + 一句理由:Neo 决策合并还是双轨,本身是后端架构取舍,不能擅自下结论

**Wave 验证锚点**: 检查 adminAI.ts 与 triggerJobs.ts 的 PATCH 字段差异,确认是否真有不可调和的 schema 差异


*反馈：个人倾向合并为一套API，但要进行调研，看下数据获取的泛用性，如果合适（我记得页面内容基本一致），则合并，完成后进行case编写和测试。*
---

### P1-7. NS1 未覆盖 /api/admin/*,admin-web API 无独立 PRD

**关联页面/接口**:
- `docs/prd/Neo_Specs/NS1-*.md`(主要描述 `/api/xcx/*` 小程序接口)
- `apps/backend/app/routers/admin_*.py`(实际实现)
- admin-web 全部 API 来自 `apps/backend/app/routers/admin_*.py` + `app/routers/*.py`
- 02b 矩阵 §五-1

**业务背景**:
admin-web 后台有 19 个路由、80+ 后端 API,目前没有独立的 API PRD 文档,只能从代码 (`routers/admin_*.py`) 反查实际行为。NS1(Neo Spec 1)聚焦小程序 `/api/xcx/*` 接口,完全没覆盖 `/api/admin/*`。

**冲突逻辑**:
- 现状(NS1):仅描述小程序接口
- 现状(代码):admin-web API 走 `/api/admin/*`,无 PRD
- 影响:Wave 1 走查时无判据,运维新人无文档可读

**业务联系**:
- 上游:无
- 下游:admin-web 全部页面、未来 API 变更的回归判据

**修改影响**:
- 新增 SPEC `NS-admin-web-backend-api.md`,从代码反向梳理 80+ API
- 工作量**大**(预计需要 2-3 天集中梳理)

**推荐选项**:
1. **选项 A(立刻补一份完整 PRD)**: 优:补齐文档体系 / 劣:工作量大,过去半年仍以代码为准
2. **选项 B(只补"约定 + 关键 API"摘要文档)**: 优:轻量,聚焦 / 劣:仍有未覆盖 API
3. **选项 C(自动化生成 OpenAPI 后再人工校对)**: 优:与代码同步 / 劣:需要先做 OpenAPI 装备
4. **选项 D(暂不补,以代码为准)**: 优:零工作 / 劣:Wave 1 走查无据

**建议判定**: **C 待补** + 一句理由:这是 SPEC 缺失,Neo 决策补的形式(完整 / 摘要 / 自动化)

**Wave 验证锚点**: 02b 矩阵 §二映射表已是事实摘要,可作为补 PRD 的起点

*反馈：选项 A。在梳理完整PRD时，我希望你能顺便发现一些API的问题，比如API设计是否合理，架构是否合理，API背后的处理是否合理清晰，性能可用性稳定性安全性是否需要优化，一些糟糕的API是否需要重构合并等评估。*

---

### P1-8. 应用 4 触发条件:AI 需求 2 写 3 种,数据依赖矩阵写 1 种

**关联页面/接口**:
- `docs/prd/AI需求2.md`(应用 4 章节)
- `docs/prd/specs/00-数据依赖矩阵.md` §三
- 后端实现入口:`apps/backend/app/services/ai_*`(P5-A 应用 4 调用骨架)
- AI 应用 4(关系分析 / 任务建议)
- 01 全景 §八-4

**业务背景**:
AI 应用 4 是给 task-detail 页展示"与我的关系 + 任务建议 + 行动建议"的核心 AI,触发条件决定多少次调用、消耗多少 token。两份文档对触发条件描述不一致:`AI需求2.md` 写 3 种触发(新结算单 / 优先召回任务分配 / 高优先召回任务分配),数据依赖矩阵只写 1 种(助教参与新结算时)。

**冲突逻辑**:
- AI 需求 2.md(应用 4):3 种触发条件
- 数据依赖矩阵 §三:1 种触发条件
- 实现影响:若按 1 种实现,会漏掉两类任务分配触发(高优先召回 / 优先召回)

**业务联系**:
- 上游:结算单写入 / 任务分配生成
- 下游:应用 4 输出(关系分析 + 任务建议)写入 ai_cache,task-detail 读取

**修改影响**:
- 若按 3 种:每天调用次数估算可能 ×2-3,token 消耗对应增加
- 若按 1 种:任务分配时 task-detail 看不到最新关系分析,体验降低

**推荐选项**:
1. **选项 A(以 AI 需求 2.md 为准:3 种触发)**: 优:体验好,任务分配即时刷新 / 劣:token 消耗高
2. **选项 B(以数据依赖矩阵为准:1 种触发)**: 优:成本低 / 劣:任务分配场景下分析过期
3. **选项 C(分级:新结算必触发,任务分配走缓存或 1 小时去重)**: 优:折中 / 劣:逻辑稍复杂

**建议判定**: **C 待补** + 一句理由:Neo 决策成本与体验取舍,涉及 AI token 预算,不能擅自下结论

**Wave 验证锚点**: 检查 P5-A 应用 4 调用骨架已实现的触发点数量

*反馈：选项 A。Token成本付出是必要且能接受的。*
---

### P1-9. User_ID(蛇形)vs userId(驼峰)风格混用

**关联页面/接口**:
- `docs/prd/AI需求2.md`(用 `User_ID` 蛇形大写)
- `docs/prd/后端接口需求说明_数据需求PRD.md`(用 `userId` 驼峰)
- 后端:`apps/backend/app/api/*`(对外 camelCase) → `apps/backend/app/services/ai_*`(对百炼 `User_ID`)
- 01 全景 §八-6

**业务背景**:
AI 应用 1(通用对话)的传参里用户身份字段名,在百炼平台占位符规范是 `User_ID`(蛇形大写下划线,百炼 SDK 习惯),在前后端 REST API 是 `userId`(驼峰,JS 习惯)。两份 PRD 用了不同写法,实现层需要做映射转换,但无明文约定转换在哪一层。

**冲突逻辑**:
- AI 需求 2.md:`User_ID`(百炼平台占位符风格)
- 数据需求 PRD.md:`userId`(REST 驼峰)
- 现状(项目):后端 CamelModel 默认对外 camelCase,对百炼 SDK 内部转 `User_ID`

**业务联系**:
- 上游:前端传 `userId` → 后端
- 下游:后端转 `User_ID` 传百炼

**修改影响**:
- 仅文档同步:在 AI 需求 2.md 加注"对外 API 用 userId,百炼 prompt 占位符用 User_ID"
- 工作量**小**

**推荐选项**:
1. **选项 A(改文档明文约定:对外 camelCase / 对百炼 User_ID)**: 优:对齐现状,清晰 / 劣:无
2. **选项 B(统一一边)**: 优:简单 / 劣:违反百炼平台默认占位符规范

**建议判定**: **A 过期-改文档** + 一句理由:现状(后端做映射)是正确的,文档补一段说明即可

**Wave 验证锚点**: 检查 `apps/backend/app/services/ai_*` 是否有 userId → User_ID 的映射转换层


*反馈：选项 A。且同意你的建议。*

---

### P1-10. customer-detail "查看消费记录" 跳 customer-records vs customer-service-records

**关联页面/接口**:
- `apps/miniprogram/miniprogram/pages/customer-detail/customer-detail.ts`
- `apps/miniprogram/miniprogram/pages/customer-records/customer-records.ts`(2026-03-29 新建,**消费**视角)
- `apps/miniprogram/miniprogram/pages/customer-service-records/customer-service-records.ts`(**服务**视角)
- 02a 矩阵 §3.14、§3.15、§3.16、C8

**业务背景**:
小程序 customer-detail 页底部有两个入口都关联"客户的历史记录":一个跳 customer-records(消费记录,支付/充值视角,2026-03-29 新建),一个跳 customer-service-records(服务记录,助教服务流水视角)。两者数据来源不同:customer-records 是消费支付,customer-service-records 是助教服务时长。问题是:页面文案"查看消费记录"具体跳哪个目前不清晰。

**冲突逻辑**:
- 入口 A:客户消费视角(谁在哪天消费了多少 + 充值)
- 入口 B:客户服务视角(哪个助教服务了几小时 + 收入贡献)
- 文案"消费记录"语义偏 A,但历史代码可能跳 B

**业务联系**:
- 上游:customer-detail 客户档案
- 下游:两条页面流(消费分析 / 服务分析)

**修改影响**:
- 若两入口都保留:UI 加两个按钮,每个文案明确(消费记录 / 服务记录),工作量**小**
- 若合并为一个:删除一个页面 + 重定向,工作量**中**

**推荐选项**:
1. **选项 A(两入口都保留,文案区分)**: 优:语义清晰,两视角并存 / 劣:UI 增加一个按钮
2. **选项 B(合并为一个综合页 with Tab 切换)**: 优:UI 简洁 / 劣:实现成本中
3. **选项 C(保留 customer-records,废弃 customer-service-records)**: 优:消费视角更核心 / 劣:服务视角丢失,助教详情视角无法访问

**建议判定**: **C 待补** + 一句理由:两个页面同时存在但语义不同,Neo 决策保留还是合并

**Wave 验证锚点**: 跑 customer-detail.ts 看当前"查看消费记录"按钮的 navigateTo 路径

*反馈：customer-detail页面上，我没有找到customer-service-records的跳转入口，你再仔细调研这个页面的作用及可能的上游跳转入口。*

---

### P1-11. chat 多入口参数语义(customerId/historyId/coachId)与 loadMessages 仅用 customerId

**关联页面/接口**:
- `apps/miniprogram/miniprogram/pages/chat/chat.ts`(`loadMessages` 实现)
- 入口 1:`task-detail` → `chat?customerId=` + chatId
- 入口 2:`chat-history` → `chat?historyId=` + chatId
- 入口 3:`coach-detail` → `chat?coachId=` + chatId
- API 契约:`GET /api/xcx/chat/{chatId}/messages`
- 02a 矩阵 C9、§3.19

**业务背景**:
chat 页是 AI 对话页,从 3 个不同入口可以进入(任务详情问话 / 历史对话恢复 / 助教档案问话),每个入口传的 url 参数语义不同(customerId / historyId / coachId)。但 `chat.loadMessages` 当前只读 `customerId`,导致从 chat-history 或 coach-detail 进来的会话无法正常加载历史消息。

**冲突逻辑**:
- 入口语义:3 种(围绕客户对话 / 恢复历史会话 / 围绕助教对话)
- 现状(loadMessages):只用 customerId,不识别 historyId / coachId
- API 契约:`GET /api/xcx/chat/{chatId}/messages` 是按 chatId 查,但前端没有正确区分 chatId 来源

**业务联系**:
- 上游:3 个入口
- 下游:chat 消息列表加载 + AI 流式回复

**修改影响**:
- 前端:loadMessages 增加 historyId / coachId 路由分支,各自对应不同的 chatId 派生逻辑
- 后端:可能需要根据入口给一个 `GET /chat/by-context?customerId|coachId|historyId` 派生 chatId 的接口
- 工作量**中**

**推荐选项**:
1. **选项 A(前端三分支 + 后端补 by-context API)**: 优:语义清晰 / 劣:工作量中
2. **选项 B(统一为 chatId,所有入口先调 API 拿 chatId 再跳)**: 优:协议简单 / 劣:多一次往返
3. **选项 C(只支持 historyId,其他入口废弃)**: 优:简单 / 劣:体验差,问问助手按钮失效

**建议判定**: **C 待补** + 一句理由:多入口路由逻辑由谁实现是产品设计决策,Neo 拍板后开 issue

**Wave 验证锚点**: chat.ts 的 onLoad / loadMessages 当前实现,检查参数读取与 chatId 派生

*反馈：chat页面还未集中调试与验收，但就这个问题，我选择选项 A，可以先调通API参数问题。*
---

### P1-12. 散客 memberId 取值约定(<=0?0?-1?NULL?)

**关联页面/接口**:
- `apps/miniprogram/miniprogram/pages/coach-service-records/coach-service-records.ts`(用 `memberId<=0` 判散客)
- 02a 矩阵 C18、§3.18
- 数据表:`dwd.dim_member` / `dws_*` 各表
- 后端契约:相关响应中的 `memberId` 字段

**业务背景**:
台球门店有"散客"概念(没有会员卡的临时客户),系统怎么表示散客没有统一约定。前端 coach-service-records 用 `memberId<=0` 判断散客并 toast"散客无详情可查看",但后端到底是把散客记为 `0` / `-1` / `NULL` / 还是别的特殊值,文档没明文约定。

**冲突逻辑**:
- 前端:`if (memberId <= 0) return scattered`
- 后端 / 数据库:实际可能是 `0` 或 `NULL` 或 `-1`,需要校验
- 影响:若后端返 `NULL`,前端 `null <= 0` 是 `true`,逻辑巧合对;若返其他正数表示散客,前端误判

**业务联系**:
- 上游:ETL 写入 dim_member / 结算单的散客记录
- 下游:小程序详情页"散客无详情"判断、看板统计等多处

**修改影响**:
- 若约定 `memberId IS NULL` 表示散客:前端改为 `!memberId || memberId <= 0`
- 若约定 `memberId = 0`:保持现状
- 若约定 `memberId = -1`:保持现状
- 文档同步 + 部分前端调整,工作量**小**

**推荐选项**:
1. **选项 A(约定 NULL = 散客)**: 优:数据库语义清晰 / 劣:JOIN 时需要 LEFT JOIN
2. **选项 B(约定 0 = 散客)**: 优:整数恒等好判断 / 劣:与"无 ID"语义混淆
3. **选项 C(约定 -1 = 散客)**: 优:清晰可识别 / 劣:负值不符常规
4. **选项 D(保持 <=0 兼容,任何<=0 都是散客)**: 优:零工作 / 劣:无单一真实值

**建议判定**: **C 待补** + 一句理由:Neo 决策散客 ID 取值,然后写到 ETL DWD-DOC 与后端契约

**Wave 验证锚点**: 跑 `SELECT DISTINCT member_id FROM dwd.dwd_settlement_head WHERE member_id <= 0 OR member_id IS NULL LIMIT 20` 看现状

*反馈：先调研 后端 / 数据库:实际可能是 `0` 或 `NULL` 或 `-1`,进行校验。并根据反馈结果，再决定Python处理层，API层，小程序层的约定，决定如何处理。*

---

### P1-13. P5.2-prerequisite-fixes.md 文件是否应存在但缺失

**关联页面/接口**:
- `docs/prd/specs/P5.1-mcp-server-ai-extension.md`(自述"批次 B 依赖 P5-A 完成")
- `docs/prd/specs/P5.2-prerequisite-fixes.md`(本调研未找到)
- 01 全景 §八-5

**业务背景**:
P5(AI 应用集成)拆为多批次实施,P5.1 是 MCP Server 扩展,P5.2 是用户原文里提及的"prerequisite-fixes"(P5.1 实施前的前置修复)。但本调研范围内 `docs/prd/specs/` 下只找到 `P5.1`,没找到 `P5.2-prerequisite-fixes.md`。

**冲突逻辑**:
- 用户原文:P5.2 标了 prerequisite-fixes,说明 P5.1 有前置问题
- 现状(文件系统):docs/prd/specs/ 下没有 P5.2-prerequisite-fixes.md
- 可能性 1:文件应该存在,但被误删
- 可能性 2:文件本来就没建,只是用户记忆中提过
- 可能性 3:文件路径不在 docs/prd/specs/,在别处

**业务联系**:
- 上游:P5.1 批次 B(MCP Server zqyy_app 扩展)
- 下游:P5.1 实施门槛 / 是否需要先解决前置问题

**修改影响**:
- 若需要补:新增一份 SPEC,工作量**中**(2-4 小时梳理前置问题)
- 若不需要:在 P5.1 中加一行说明"无前置修复",工作量**小**

**推荐选项**:
1. **选项 A(确认 P5.2 应该存在,补一份)**: 优:补齐文档 / 劣:工作量中
2. **选项 B(确认无需 P5.2,在 P5.1 中加注)**: 优:轻量 / 劣:用户记忆与现状不一致需澄清
3. **选项 C(P5.2 在别处,改名指向)**: 优:零新增 / 劣:需先找到原文件

**建议判定**: **C 待补** + 一句理由:文件存在性需要 Neo 确认,然后决定是补还是删除引用

**Wave 验证锚点**: 全仓库搜索 "prerequisite-fixes" 关键词,看是否有同名内容散落他处

*反馈：prerequisite-fixes这个文档是做什么的？有线索为我介绍么？是它么？\docs\specs\p4-prerequisite-fixes*

---

> 总计:13 条业务故事卡 / 全部建议判定标完整(2 条 A 过期-改文档 / 0 条 B / 9 条 C 待补 / 2 条 D Bug)
> 信息不足备注:
> - **P1-11 chat 多入口**:需要进一步看 chat.ts 当前 loadMessages 完整实现,以确认建议选项是否可行
> - **P1-13 P5.2 文件**:需要 Neo 直接确认是否记忆有误,本文档无法仅靠搜索定论


---
*额外的需求：我发现这个web-admin的dev-trace功能并没有用上，一次也没有使用过，而且还有占用性能的嫌疑，为我调研测试下这个模块日常接口调取和处理时，占用的性能消耗。如果过高我打算彻底drop移除掉。地址：http://localhost:5173/logs/dev-trace*

---