Neo-ZQYY/docs/_overview/04c-conflicts-P2-detail.md

# P2 文档冲突业务化详情(13 条)

> 生成日期:2026-05-04 / 来源:Wave 0 三个子代理产出 / 目的:把 P2 索引行展开为业务故事卡,供 Neo 拍板
> 配套索引见 `docs/_overview/04-doc-conflicts.md` § 一 P2 表格;P2-13 含 5 个子项,合并到一节呈现

---

## P2-1. tabBar 是 app.json 写死 3 项还是动态过滤

**关联**: 全部小程序页面;`apps/miniprogram/miniprogram/app.json` + `custom-tab-bar/` + `utils/auth-guard.ts`

**业务背景**: 不同角色看到的底栏不一样 — 助教/教练 3 项(任务/看板/我的),员工/管理人员只 2 项(看板/我的)。`app.json` 习惯写死 3 项,但实际渲染走 `custom-tab-bar` 按 `visibleTabs` 动态过滤。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| `app.json` | 写死 3 项("任务/看板/我的") |
| `auth-guard.ts` + storyboard | 按角色动态过滤,首登选第一个可见 tab |

**影响**: 文档一致性(轻)。代码已按动态实现,旧文档若仍写"3 项 tabBar"会误导新开发者。

**选项**:
- **A**: 旧文档同步为"动态过滤" — 优:与代码一致 劣:需扫一遍引用旧表述的文档
- **B**: 在 `app.json` 配置层加注释"实际由 custom-tab-bar 接管" — 优:零成本 劣:不解决根本

**建议判定**: A,旧文档过期一律改文档

*反馈：选项A*

---

## P2-2. 维客线索 tag 字段格式

**关联**: `task-detail` / `customer-detail` 维客线索区;`biz.member_retention_clue.tag`(应用 6/8 输出)

**业务背景**: 维客线索的 tag 作为客户分类标签展示(如"客户基础/消费习惯")。前端 mock 出现 `"客户\n基础"`(含换行符),类型定义却是单字符串,与 SPEC 中 6 大类枚举(客户基础/消费习惯/玩法偏好/促销接受/社交关系/重要反馈)又不一致。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| task-detail 内联 mock | `"客户\n基础"` 含换行 |
| `mock-data.ts` 类型定义 | 单字符串 |
| 契约 TASK-2 / SPEC | 6 大类枚举 key |

**影响**: 联调与展示(中)。如果 AI 真返回 `\n`,WXML 是否解析换行决定渲染样式;枚举/字符串不统一导致前端无法做颜色映射。

**选项**:
- **A**: 后端返回枚举 key + 中文 label 两字段,前端按 key 做色板映射 — 优:可扩展 劣:需改后端响应
- **B**: 后端返回中文长字符串(允许 `\n`),前端 white-space:pre-line 渲染 — 优:简单 劣:无法做样式区分

**建议判定**: A,与应用 6/8 的 JSON 输出对齐(分类 + Emoji + 摘要)

*反馈：选项A*
---

## P2-3. 维客线索 source 字段格式

**关联**: 同 P2-2;`biz.member_retention_clue.source`

**业务背景**: 客户线索来源用于在卡片底部展示"By:小燕"或区分人工/AI。当前前端 mock 用展示文案 `By:小燕`,类型定义用枚举 `manual | ai_consumption | ai_note`,两者语义层不同。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| 前端 mock | `'By:小燕' / 'By:系统'`(显示文案) |
| 类型定义 / SPEC | `manual / ai_consumption / ai_note`(枚举) |

**影响**: 前后端契约(中)。混用会导致后端返回枚举时前端无法直接展示,或反之。

**选项**:
- **A**: 后端返回 `source`(枚举) + `recorded_by_name`(可空),前端拼"By:xxx"或"AI" — 优:语义清晰 劣:前端要改拼接逻辑
- **B**: 后端直接返回成品文案 — 优:前端零改造 劣:失去枚举信息,后续做筛选/统计困难

**建议判定**: A,与 P10 SPEC 的 `member_retention_clue` 字段定义一致

*反馈：选项A*

---

## P2-4. 课程类型 class 前缀(tag- 前缀 vs 业务名)

**关联**: `performance-records` / `coach-service-records` 服务记录卡片

**业务背景**: 同样是课程类型徽章(基础课/包厢课/激励课),两个页面用了不同的 CSS class 命名约定,WXSS 选择器与 COURSE_TAG_MAP 也是双轨。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| performance-records | `tag-basic / tag-vip / tag-tip` |
| coach-service-records | `basic / room / incentive` |

**影响**: 体验(轻)。两个页面同色块来源不同样式表,改色板需要改两处。

**选项**:
- **A**: 统一为 `tag-basic / tag-vip / tag-tip`(显式语义前缀) — 优:与 design-system 一致 劣:改 coach-service-records 的 WXSS
- **B**: 统一为业务名 `basic / room / incentive`(更贴近后端 course_type) — 优:与后端一致 劣:与已有 design-system 命名冲突

**建议判定**: A,与 `design-system/DISPLAY-STANDARDS.md` 标注一致

*反馈：这个你再调研下，从数据库真实数据到后端处理再到前端，我记得是两套课程体系，或者有2级课程体系，要确认好所有信息，再做最终决定。*

---

## P2-5. ChatMessage timestamp vs 契约 created_at

**关联**: `pages/chat/chat`;`biz.ai_messages.created_at`

**业务背景**: AI 对话页消息列表展示发送时间。前端类型用 `timestamp`,后端契约表是 `created_at`。这是命名风格(camel/snake)与含义层级(时间戳/创建时间)的双重不一致。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| 前端 ChatMessage type | `timestamp` |
| 契约 / 数据库 | `created_at` |

**影响**: 联调(中)。后端按 CamelModel 转 camelCase 时会变 `createdAt`,前端访问 `msg.timestamp` 会拿到 undefined。

**选项**:
- **A**: 前端类型改为 `createdAt` — 优:与后端 CamelModel 自动序列化对齐 劣:WXML/TS 多处改名
- **B**: 后端 alias 输出 `timestamp`(对前端) — 优:前端零改造 劣:与全站 camelCase 规范背离

**建议判定**: A,沿用 CamelModel 默认行为

*反馈：选项A*
---

## P2-6. ChatHistoryItem title 是后端返回还是前端截断

**关联**: `pages/chat-history`;`biz.ai_conversations`

**业务背景**: 对话记录列表每条要展示一个"标题"(如"关于客户王昕的咨询")。当前契约 CHAT-1 没有 title 字段,前端 mock 是写死的。可选方案:让 AI 摘要、取首条用户消息截断、用客户名拼接。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| 契约 CHAT-1 | 无 title 字段 |
| 前端展示 | 必须有标题 |

**影响**: 体验(中)。无标题时列表只有"最后消息摘要 + 时间",辨识度低。

**选项**:
- **A**: 后端在 `ai_conversations` 加 `title`(由应用 1 首轮自动摘要生成 ≤16 字) — 优:语义最佳 劣:增加一次 AI 调用成本
- **B**: 后端取首条 user 消息前 20 字截断 — 优:零额外成本 劣:可读性差
- **C**: 前端按客户名/时间拼接(如"王昕的对话 03-10") — 优:零后端改造 劣:无业务语义

**建议判定**: A,与应用 1 SSE 流式输出兼容,首轮结束时落库

*反馈：选项A，是不是要修改百炼APP1的系统Prompt?*
---

## P2-7. board-coach time=last_6m + sort=sv_desc 是否后端拒绝

**关联**: `pages/board-coach`;契约 BOARD-1

**业务背景**: 助教看板支持时间筛选(month/quarter/last_6m)与排序(perf/salary/sv/task)。前端 TIME_OPTIONS 注释"last_6m + sv_desc 不兼容",但未说明是后端会 400 拒绝、还是返回空数据、还是允许但语义无效。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| 前端注释 | 该组合不兼容 |
| 后端契约 | 未明示约束 |

**影响**: 体验(轻)。用户先选 sort=sv_desc 再切 time=last_6m 时不报错但结果可能为空。

**选项**:
- **A**: 后端校验该组合,返回 422 + 错误文案"近 6 月不支持储值排序" — 优:体验明确 劣:前端要捕获 422
- **B**: 前端 disable 该组合(切 last_6m 时把 sv_desc 选项变灰) — 优:UI 提前拦截 劣:前端规则要硬编码
- **C**: 后端允许返回空,前端显示空态 — 优:零约束 劣:用户不知道为何为空

**建议判定**: B,前端拦截最不易引发歧义
*反馈：选项B,但要双向禁止/变灰，即切 last_6m 时把 sv_desc 选项变灰，切 sv_desc 时把 last_6m 选项变灰。再看下还有没有类型的切换限制的问题，一同修复？*

---

## P2-8. dev-tools 角色列表缺 site_admin / tenant_admin

**关联**: `pages/dev-tools`;`auth-guard.ts` ROLE_LIST

**业务背景**: dev-tools 是 manager 调试用的"切角色"页。当前 ROLE_LIST 只列了 `[coach, staff, head_coach, manager]` 4 个,小程序的实际角色枚举还有 `site_admin / tenant_admin`(虽然这两个角色主战场在 tenant-admin 后台,小程序只查阅看板)。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| dev-tools ROLE_LIST | 4 角色 |
| auth-guard 全角色枚举 | 6 角色(含 site_admin / tenant_admin) |

**影响**: 调试覆盖(轻)。开发期无法在小程序模拟门店管理员视角。

**选项**:
- **A**: ROLE_LIST 补齐 6 个 — 优:全角色调试 劣:dev-switch-role 后端要支持这两个 aud 在小程序 token 内
- **B**: 文档明确 dev-tools 只调试 4 个 C 端角色,site_admin/tenant_admin 在 tenant-admin Web 调试 — 优:边界清晰 劣:小程序看板的角色显示无法覆盖测试

**建议判定**: A,与小程序 tabBar 角色映射表(全 6 角色)对齐

*反馈：选项B,因为site_admin/tenant_admin在小程序端没有相应的配置信息可以读取。两套角色相互平行，不能混用。*
---

## P2-9. no-permission 管理员姓名"厉超"硬编码

**关联**: `pages/no-permission`

**业务背景**: 申请被拒/账号禁用页底部显示"如有疑问请联系管理员 厉超"。当前是 WXML 硬编码,`_hardcode-summary.md` 第 6 项决策"保持硬编码(只有一个管理员)"。但多门店上线后每个门店可能有不同的 site_admin。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| `_hardcode-summary.md` | 决策硬编码"厉超" |
| 多门店现实 | 不同店应有不同管理员 |

**影响**: 体验(中)。新门店上线后用户被拒看到的还是"厉超",找不到本店管理员。

**选项**:
- **A**: 后端 `/me` 返回时附带 `siteAdminContact:{ name, phone? }`,无值回落"管理员" — 优:多门店可用 劣:后端要 JOIN auth.tenant_admins
- **B**: 改为不出现具体姓名("请联系门店管理员") — 优:零改造 劣:用户不知道找谁
- **C**: 在 `apply` 表单时记录 `site_id`,被拒时按该 site 查管理员 — 优:精准 劣:实现成本与 A 接近

**建议判定**: A,与 P10 tenant-admin 账号体系联动

*反馈：选项A,但不能直接显示管理员的用户名，应该在tenant-admin中，加入一个管理入口，专门编辑no-permission的显示信息，这个功能你帮我设计下，并进行实现且按照我们的约定方式，进行测试。*

---

## P2-10. customer-records 字段 consumption60D 大写 D Pydantic alias 规范

**关联**: `pages/customer-records`;后端 `/customer/{id}/profile`

**业务背景**: 该字段后端命名 `consumption_60d`(snake),前端类型却是 `consumption60D`(大写 D),代码注释里标"踩坑"。这是 Pydantic alias 转 camelCase 时数字+字母的处理差异(`60d` → `60D` vs `60d` 不同库不同行为)。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| 后端 snake | `consumption_60d` |
| Pydantic CamelModel 输出 | `consumption60D`(踩坑) |
| 业界惯例 | `consumption60d` 全小写 |

**影响**: 全站类型一致性(中)。同类字段(如 `visits_30d`)如果在另一个接口被序列化为 `visits30D` 会产生连锁不一致。

**选项**:
- **A**: 后端字段名改 `consumption60`(去掉单位 d),保留单位在文档说明 — 优:绕开 alias 边界 劣:语义不清
- **B**: 给该类字段显式写 alias `Field(..., alias='consumption60d')` — 优:可控 劣:每个字段都要手写
- **C**: 接受 `60D` 大写,在全站规范里写明"数字+字母时字母大写" — 优:规则清晰 劣:不直观

**建议判定**: B,与 CamelModel 默认行为脱钩,每个 60d/30d/90d 字段显式 alias

*反馈：选项B。*

---

## P2-11. AI 需求 2 表头标 6 个实际 8 个(笔误)

**关联**: `docs/prd/AI需求2.md`(产品脑图 §六 引用)

**业务背景**: AI 需求文档第 26 行表头写"6 个 AI 应用的详细需求",实际表格列出应用 1-8 共 8 个。SPEC 总览 P5 也是 8 个。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| AI需求2.md 表头 | 6 个 |
| AI需求2.md 表格内容 | 8 个(应用 1-8) |
| SPEC 总览 P5 | 8 个 |

**影响**: 文档一致性(轻)。仅文字笔误,不影响实现。

**选项**:
- **A**: 改表头为"8 个" — 优:1 行修复 劣:无
- **B**: 保留并注释"含 7/8 整合应用" — 优:解释来源 劣:啰嗦

**建议判定**: A,直接改表头

*反馈：选项A。*

---

## P2-12. admin-web /admin/tenant-admins 与 tenant-admin 职责边界

**关联**: `apps/admin-web` `/tenant-admins` 路由 vs `apps/tenant-admin` 整个后台

**业务背景**: 两个 Web 应用看似都涉及"租户管理":
- admin-web `/admin/tenant-admins` 操作 `auth.tenant_admins` 表(账号 CRUD)
- apps/tenant-admin 整个应用是这些账号登录后用的工作台

PRD NS4/NS4.1 主要描述 tenant-admin,未明文边界。

**冲突**:
| 来源 | 说法 |
| --- | --- |
| admin-web | 创建/编辑/重置密码租户管理员账号 + 简写 ID 管理 |
| tenant-admin | 用户审核 / Excel 上传 / 维客线索管理 |

**影响**: 文档边界(中)。两个团队/角色读不同 PRD 容易认为对方负责创建账号。

**选项**:
- **A**: 文档加边界声明 — admin-web 操作"账号本身"(创建/启停/重置),tenant-admin 操作"门店运营"(用户/Excel/线索) — 优:零代码改 劣:仅文档
- **B**: tenant-admin 内部加自助"重置密码"入口 — 优:用户体验好 劣:超出 NS4 范围
- **C**: 把 `/admin/tenant-admins` 从 admin-web 移到独立超管页 — 优:权责清 劣:大重构

**建议判定**: A,在 NS4 加一节"职责边界",admin-web 侧也加 README 说明

*反馈：同意你的建议。*

---

## P2-13. AIPrewarm + 事件枚举 + 侧边栏 ?tab + Login 路径 + ai-group 展开(5 子项)

**关联**: `apps/admin-web` 多个页面;NS3 PRD

**业务背景**: 这 5 个小冲突共同指向"NS3 PRD 与 admin-web 现状对照不足"。统一处理。

### P2-13.1 AIPrewarm 72 组合二分逻辑未在 NS3 写明

**冲突**: 注释"72 组合"实际是 `area=all 走 app2_finance 8 组合 + 8 区域走 app2a_finance_area 64 组合`,NS3 / API-REFERENCE 是否同步该二分?

**选项**:
- **A**: NS3 加一节"72 组合二分逻辑" — 优:文档清晰 劣:维护新章节
- **B**: 仅在 AIPrewarm.tsx 顶部注释扩写 — 优:就近 劣:非前端开发者读不到

**建议**: A
*反馈：A。*

### P2-13.2 event_type 枚举完整表缺失

**冲突**: AIOperations.EVENT_TYPE_OPTIONS 列 4 项(consumption / dws_completed / note_created / task_assigned),AIPrewarm 用 dws_completed,AITriggerJobs 不限制。NS3 是否有完整枚举表?

**选项**:
- **A**: NS3 加 `event_type` 枚举完整表(含触发条件 + 后置应用链) — 优:全局一致 劣:工作量
- **B**: 在 `biz/cfg_event_types.py` 维护源,文档自动生成 — 优:不漂移 劣:需要工具

**建议**: A 起步,长期 B
*反馈：B。*

### P2-13.3 侧边栏 ?tab= 双入口 UX

**冲突**: "AI 管理 → 触发器设置"与"系统设置 → 触发器配置"都跳到 `/triggers?tab=ai|biz`,两个菜单 entry 共用一个页面。

**选项**:
- **A**: 接受现状(两入口不同语境) — 优:零改造 劣:用户疑惑"为何两处都有"
- **B**: 合并为一个入口,在 `/triggers` 顶部加面包屑显示来源 — 优:UX 清晰 劣:菜单收窄

**建议**: A,在 PRD 解释保留双入口的理由(操作语境不同)
*反馈：A。*


### P2-13.4 Login 路径前缀

**冲突**: `useAuthStore.login` 调 `/api/auth/login`,401 拦截器引用 `/auth/refresh`。是否含 `/admin` 前缀?本调研未读 `apps/backend/app/routers/auth.py`。

**选项**:
- **A**: 校对 auth.py 实际路径并同步 NS1 文档 — 优:无猜测 劣:需要读代码
- **B**: 在 admin-web README 写明前缀来源 — 优:就近 劣:其他端读不到

**建议**: A,补 NS1 后端 API 章节
*反馈：同意你的建议。*

### P2-13.5 ai-group 默认展开

**冲突**: 从 ai 子菜单跳到 `/triggers?tab=ai` 时,侧边栏 `ai-group` 不会自动展开(`getDefaultOpenKeys` 注释"无法判断 tab")。

**选项**:
- **A**: `getSelectedKeys` 改造,根据 `pathname + search` 同时展开多个 group — 优:UX 一致 劣:需要测多种入口组合
- **B**: 接受现状 — 优:零改造 劣:用户跳转后菜单状态丢失

**建议**: A
*反馈：A。*

**P2-13 整体建议判定**: 全部走 A,集中在 NS3 同步 + admin-web 侧边栏小重构

---

> 完成日期:2026-05-04 / 用途:为 Neo 提供 P2 13 条的紧凑业务化判定材料,确认后批量进入 Wave 5 文档收尾或对应模块小工单