chore(docs): Wave 0 调研产出 + P0/P1/P2 反馈调研

建立项目级标杆文档 docs/_overview/ 作为产品全景索引,
解决"PRD 零碎、文档膨胀、跨子系统调研无入口"的问题。

主要内容:
- 00-index 总索引 + 维护协议 + 与 CLAUDE.md 关系
- 01-product-overview 产品全景脑图(6 角色 / 6 子系统 / 数据流 /
  7 业务概念 / 8+1 AI 矩阵 / 22 术语)
- 02a-miniprogram-page-matrix 小程序 21 页业务指纹
- 02b-adminweb-page-matrix admin-web 19 路由业务指纹
- 03-test-spec 测试规范 (L1-L5 分层 + 走查模板 + 75-95 case 估算)
- 04-doc-conflicts 39 条冲突索引(P0×8 / P1×13 / P2×13 + 5 子项)
- 04a/b/c-conflicts-*-detail 业务故事卡(7 字段:关联/逻辑/影响/选项/判定)
- 05-orphan-pages-cleanup admin-web 6 孤儿页面处置(1 归档 + 4 保留)
- WAVES-MASTER-PLAN.md 全 Wave 主计划(0-5,共 22-32 工作日)
- WAVE-1-KICKOFF.md Wave 1 实施 kickoff
- GLOBAL-DECISION-DASHBOARD.md 全局决策仪表板

反馈调研产物:
- 04a-feedback/ P0 两轮反馈(8+8 项决策 + D-1/2/3 + F-1/2 子代理产出)
- 04b-feedback/ P1 两轮反馈(13+1+5 项 + E-1/2/3/4 + G-1/2 子代理产出)
- 04c-feedback/ P2 反馈(13 项 + 5 子项 + H-1/2/3 子代理产出)
- NEO-DECISIONS-LOG 累积决策记录

关键追加发现 8 处 D Bug(原蓝本 0):
- P0-3 看板沙箱接入(Wave 1 W1-T1)
- P0-5 致命 1 (4 处 fdw_etl 残留, 已修 commit 17f045a)
- P0-5 致命 2 (JWT aud 缺失, 已修 commit 17f045a)
- P0-6 clearAllTasks 守卫 (Wave 3)
- P0-8 DBViewer 黑名单漏 (已修 commit 17f045a)
- P1-3 task-detail 跳转传 task_id 而非 customer_id
- P2-7 board-finance 隐式 null
- 2 个独立 Bug (page_context.created_at + ClueCategory 字典)

参考: docs/_overview/00-index.md
This commit is contained in:
Neo
2026-05-04 07:38:28 +08:00
parent c6453829a6
commit 509cf43284
44 changed files with 10789 additions and 0 deletions

View File

@@ -0,0 +1,107 @@
# P1-10 customer-detail 跳转入口实证调研
> 调研时间:2026-05-04
> 调研范围:`apps/miniprogram/miniprogram/pages/`
> Neo 反馈:"customer-detail 页面上,我没有找到 customer-service-records 的跳转入口"
## 一、customer-detail 页面作用
文件:`apps/miniprogram/miniprogram/pages/customer-detail/customer-detail.ts` + `.wxml`
定位:**单个客户的 360 度全景管理页**,服务于店长 / 助教视角下"管理某位会员"。
页面分块(从 wxml 顺序):
1. **Banner**:头像 + 姓名 + 手机号(查看/复制) + 4 项核心指标(储值余额 / 60 天消费 / 理想间隔 / 距今到店)
2. **AI 智能洞察**(`aiInsight`):AI 摘要 + 推荐策略,接 `app7_customer_analysis`
3. **维客线索**(`clues`):AI 生成的客户挽留/转化线索
4. **助教任务分配**(`coachTasks`):该客户被分配给哪些助教,任务进行中
5. **最喜欢的助教**(`favoriteCoaches`):近 60 天关系指数排名,前 3 默认展示,折叠展开
6. **消费记录**(`consumptionRecords`):台桌结账 / 商城订单卡片(已是详细消费明细)
7. **备注记录**(`sortedNotes`):增删备注(走 `createNote` / `deleteNote` 后端 API)
8. **底部操作栏**:`问问助手`(跳 chat) + `备注`(打开 noteModal)
数据来源:`fetchCustomerDetail(id)` 一次性返回所有结构化字段。
## 二、customer-detail 实际有的跳转入口
`customer-detail.ts` 中所有 `wx.navigateTo` 与外部跳转事件:
| 触发位置 | 方法 | 目标页面 | 备注 |
|---------|------|---------|------|
| `<view class="card-header" bindtap="onViewServiceRecords">` (消费记录区块右上 chevron-right) | `onViewServiceRecords` (line 182-188) | `pages/customer-records/customer-records?customerId=${id}` | 客户消费记录(月度切换) |
| 底部"问问助手"按钮 | `onStartChat` (line 190-196) | `pages/chat/chat?customerId=${id}` | AI 对话 |
| 备注弹窗内部确认 | `onNoteConfirm` (line 203-230) | 不跳转,仅创建备注 | 调 createNote API |
**结论:customer-detail 总共只有 2 个外跳入口**:
- `customer-records`(消费记录页)
- `chat`(AI 对话页)
**没有 `customer-service-records` 跳转**(注意!`customer-records``customer-service-records` 是两个不同的页面)。
## 三、customer-service-records 的全部上游入口
> `customer-service-records`(客户**服务**记录,服务于"助教视角")
grep `customer-service-records` 在整个 `apps/miniprogram/miniprogram/pages/`:
| 引用位置 | 性质 | 是否上游入口 |
|---------|------|------------|
| `app.json:17` | 页面注册 | 否 |
| `pages/task-detail/task-detail.ts:440` | `wx.navigateTo` `/pages/customer-service-records/...` | **是,唯一上游入口** |
| `components/service-record-card/service-record-card.ts:3` | 注释,说明组件被该页和 task-detail 复用 | 否 |
| `utils/auth-guard.ts:35` | 路由权限映射(`view_board_customer`) | 否 |
| `pages/customer-records/customer-records.wxss:135` 等 | 注释中"复用月份切换交互" | 否 |
| `pages/dev-tools/dev-tools.ts:21` | 调试页面跳转列表(开发用) | 不算业务上游 |
| `pages/customer-service-records/customer-service-records.ts:109` | 自身权限守卫 | 否 |
**结论:customer-service-records 业务上游入口**:**仅 task-detail 一处**(`onViewAllRecords` 方法,line 436-443)。
```ts
// task-detail.ts:436-442
onViewAllRecords() {
const customerId = (this.data.detail as any)?.customerId || this.data.detail?.id || ''
wx.navigateTo({
url: `/pages/customer-service-records/customer-service-records?customerId=${customerId}`,
...
})
}
```
## 四、customer-records 的全部上游入口
> `customer-records`(客户**消费**记录,服务于"店长 / 客户管理视角")
grep `customer-records`(注意排除 `customer-service-records` 子串误匹配):
| 引用位置 | 性质 | 是否上游入口 |
|---------|------|------------|
| `app.json:18` | 页面注册 | 否 |
| `pages/customer-detail/customer-detail.ts:185` | `wx.navigateTo` `/pages/customer-records/...` | **是,唯一上游入口** |
| `utils/runtime-clock.ts:3` | 注释说明 sandbox 模式涉及该页 | 否 |
| `pages/customer-records/customer-records.ts:59` | 自身权限守卫 | 否 |
**结论:customer-records 业务上游入口**:**仅 customer-detail 一处**(`onViewServiceRecords` 方法,line 182-188)。
## 五、修正 P1-10 原结论
P1-10 conflict 矩阵原假设:"customer-detail 页面有跳转到 customer-service-records 的入口"。
**实证修正**:
- customer-detail **没有**跳 customer-service-records 的入口
- customer-detail **只有**跳 customer-records 的入口(消费记录区右上 chevron-right)
- customer-service-records 的**唯一**业务上游是 task-detail(助教任务详情页)
- 两个页面用户角色和数据语义不同:
- **customer-records**(消费):面向门店/店长,展示客户每月消费金额、储值
- **customer-service-records**(服务):面向助教,展示助教对该客户的服务次数、时长、到手收入
## 六、推荐处理
P1-10 应该**关闭/重新定义**,因为原命题(customer-detail 双跳问题)不存在:
1. **现状是单跳,无冲突**:customer-detail → customer-records,task-detail → customer-service-records,各走各路。
2. **若 P1-10 想表达的是"两个 records 页是否应合并"**,这属于产品决策(消费视角 vs 服务视角是否要做同一页),不属于代码冲突。
3. **若想表达"页面命名重叠容易混淆"**,可考虑改名(如 `customer-consumption` / `customer-service`),属于命名规范优化,无紧迫性。
**建议操作**:
- P1-10 在 `04-doc-conflicts.md` 表格中标注"已实证,原结论不成立",从冲突清单移除;
- 或者升级为"命名规范建议",降级到 P3。