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

---