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 残留, 已修 commit17f045a) - P0-5 致命 2 (JWT aud 缺失, 已修 commit17f045a) - P0-6 clearAllTasks 守卫 (Wave 3) - P0-8 DBViewer 黑名单漏 (已修 commit17f045a) - 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:
515
docs/_overview/04b-conflicts-P1-detail.md
Normal file
515
docs/_overview/04b-conflicts-P1-detail.md
Normal file
@@ -0,0 +1,515 @@
|
||||
# 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*
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user