Neo
2dfc926f96
Phase 2.3 chat 上下文捕获链路从未真正激活到完整工作: - 14 处 ai-float-button 补 sourcePage,chat.ts 三分支同步设 pageFilters.contextId - 后端 page_context 4 层 BUG 修(列名错位 + RLS site_id 未重设) - xcx_chat filters.pop 破坏 body.page_context 引用 — dict() 浅拷贝隔离 - chat 流式 markdown 实时解析(表格/标题/列表/加粗 + KPI 富卡) - reference_card KPI 富卡接入 SSE 路径,db 真写入 - 维客线索 source 显示规则:AI 来源用机器人 icon 替代长文字 数据库: - public.member_retention_clue 加 emoji + runtime_mode + sandbox_instance_id - biz.ai_run_logs 加 assistant_id + 复合索引 - chk_ai_cache_type CHECK 约束 8 类应用名 - cache_type / app_type 命名统一(app6_note / app7_customer / app8_consolidation) - 历史 emoji 抽取脚本 44/44 成功 后端 silent failure 修: - cleanup_service WHERE app_type → cache_type(90 天清理 + 20K 上限重新生效) - _build_ai_insight 字段错位修复(app4 → app7 + 字段对齐 prompt schema) - task_manager talkingPoints 改 app5_tactics + tactics 字段 - task_manager aiSuggestion 改取 one_line_summary - cache_service.CACHE_EXPIRY_DAYS 加 app2a_finance_area - WS /ws/ai-cache 加 token + JWT + site_id 校验(P0 信息泄露漏洞) - internal_ai token 改 hmac.compare_digest 工具/文档: - main.py 加 RotatingFileHandler logs/backend.log + uvicorn /health 过滤 - 新建 utils/clue_category.py(VI 6 类配色 + emoji fallback + source 显示规则) - 新建 utils/markdown.ts(轻量 md 转 rich-text 解析 + streaming 容错) - audit + 数据库变更说明 + backlog §七 #14 收口 + #15-#38 残余子任务 - backlog 追加 §十一 App1 参数/MCP/沙箱审计 + §十二 百炼/SQL MCP 主任务线 实地 MCP 走查:14 入口数据层 + 5 代表入口 sourcePage 注入 + customer-detail 全模块 + chat md 渲染 + reference_card 富卡 都已验证。9 项预先 BUG/UX 登记 §七 #29-#38 后续修复。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
24 KiB
24 KiB
架构演进 Backlog(长远)
创建日期:2026-05-06 状态:backlog,等优先级排期(不在当前 F1-6 范围) 记录人:Neo + Claude(F1-6 Sprint 2 #3 调研触发)
一、核心方向
DWD 层孤立 + Core 做连接器中间件,Core 之上的全部上游(DWS / 指数 / RLS 视图等)在所有连接器之间统一规范。
二、目标
- 后期可能接入多个连接器(与
feiqiu平行的其他平台,不同字段/不同设计) - DWD 层归属于各连接器自身(字段/口径可异),保留为各连接器原始数据落地层
- Core 层作为中间件:
- 下游对接各连接器的 DWD 层(吸收差异)
- 上游输出统一规范的字段/语义
- Core 之上的所有层(DWS、指数计算、RLS 视图、ETL 任务输出表等)结构、字段、设计、设置在所有连接器之间完全一致
- 后端 / 小程序 / admin-web / tenant-admin 仅依赖 Core 之上的统一层,不感知具体连接器
三、牵连(待逐一决断)
记录所有触发的牵连项,推进时逐一对齐:
| # | 牵连项 | 说明 | 当前状态 |
|---|---|---|---|
| 1 | 库结构重组(连接器粒度) | 当前每店铺一个 ETL 库(etl_feiqiu / test_etl_feiqiu),Neo 指示至少每连接器一个库,Core 后的全部上游应统一到一个共享库集中管理 |
待设计 |
| 2 | DWS 字段名 vs 实算口径不一致 | F1-6 Sprint 2 #3 调研发现 dws_member_consumption_summary.total_visit_count 字段名"累计到店次数",实算是 COUNT(settle_type IN (1,3)) 即结算单数(含商城订单);BD manual / dws_tasks.md 描述误导 |
待修订(随 #3 推到 Sprint 3) |
| 3 | F1-6 #3 累计交易笔数 | 按 Neo 业务语义"开台次数"(不含 settle_type=3 商城订单),需 ETL 在 DWS 新增 total_open_table_count = COUNT(settle_type=1) 字段 |
推迟 Sprint 3(ETL 配合) |
| 4 | DWD 不可被后端 / 应用层直读 | F1-6 Sprint 2 #3 调研发现 app7_customer AI prompt 当前直接读 app.v_dwd_settlement_head COUNT(*),违反"DWD 孤立"原则 |
待重构(随大架构演进) |
| 5 | 后端 fdw_queries.py 中所有 app.v_dwd_* 直读点 |
需要梳理全部,逐一改走 Core / DWS 统一接口 | 待清单化 |
| 6 | F1-7+ thin wrapper 收尾 sprint | F1-6 全部迁完后清理 fdw_queries 的 thin wrapper(详见 sandbox-replay-engine-spec.md §5.5) | 与本演进同步 |
四、不属于本 backlog
- F1-6 沙箱时光机阶段 B(Sprint 1-4)— 仍按现有 ETL 库结构推进,不等本演进。Sprint 推进过程中遇到本 backlog 第 2-5 项的具体问题,各自登记到对应 Sprint 任务清单。
- 架构设计细节(Core 层 schema 定义、库迁移策略、连接器适配 SDK 等)— 本文件仅做需求登记,详细设计待优先级到位时另起 spec。
五、关联
- F1-6 Sprint 3 任务清单:
docs/_overview/wave1-findings/F1-6-tasks.md§4 - 沙箱时光机模块 spec:
docs/_overview/sandbox-replay-engine-spec.md§5.5(thin wrapper)+ §11(远期目标) - DWD 强制规则:
apps/etl/connectors/feiqiu/CLAUDE.md§DWD 强制规则(12 条)
六、决策与变更记录
| 日期 | 决策 / 变更 | 触发 |
|---|---|---|
| 2026-05-06 | 创建本 backlog | F1-6 Sprint 2 #3 累计交易笔数调研发现 DWS 字段名与实算口径矛盾 + app7 直读 DWD 违规,Neo 决定将 DWD 孤立 + Core 中间件目标提上任务表 |
| 2026-05-06 | 追加 §七 全局收口洞口清单 + §八 文档规范化整理大工程 | Neo 反思项目全局控制度,5 问追溯调研后立项 |
| 2026-05-06 | §七 收口 #1 #2 完成 + 追加 #6~#13 + 新增 §九 全栈产品文档体系登记 | docs/roadmap/BACKLOG.md 60+ 项发现 + Wave 0 全栈文档体系实证 + 累积基线 33 项对账 |
| 2026-05-06 | §七 追加 #14 AI 9 APP 全链路未完成(P0)+ 新增 §十 专题登记 | Neo 提出 AI 9 APP(8 prompt + 1 chat 实时)在接口/入库/后端处理/前端展示 4 环节有未完成,优先级很高 |
| 2026-05-06 | §七 #14 主体收口(超级 Sprint)+ 追加 #15-#28 残余子任务 | 超级 Sprint 完成 49 文件改动,5 个 silent failure 修复 + chat sourcePage 全链路 + WS 鉴权;新发现 14 项独立子任务登记 |
七、全局收口洞口清单(2026-05-06 反思,逐项收口)
触发背景
Neo 发现"项目全局的控制度不够,有很多东西被漏了,到处都没有收口"。 经 5 问追溯调研(子代理 + Bash 实证),发现以下 5 个未收口洞口。
收口清单
| # | 洞口 | 来源证据 | 状态 | 优先级 | 处理方式 |
|---|---|---|---|---|---|
| 1 | 3 项迁移后功能验证 | docs/audit/changes/2026-05-02__claude_code_migration.md L111-113 |
✅ 2026-05-06 已收口 | P1 | 实测 PASS:5 slash 命令文件 + 8 subagent 文件 + 双测试库 SELECT 1 全通过;详见 2026-05-06__closure_p1_1_migration_post_verification.md |
| 2 | 2026-04-15 ~ 05-02 累积基线 33 项对账 | docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md |
✅ 2026-05-06 已对账 | P1 | 子代理对账:23 完成(70%)+ 5 部分 + 5 真正未收口(转登记 #9~#13);详见 2026-05-06__closure_p1_2_cumulative_baseline_reconciliation.md |
| 3 | F1-6 Sprint 3 范围描述误导 | F1-6-tasks.md §4 把 MP-2 单项 ETL 依赖错误暗示成 Sprint 3 整体不可做 | ✅ 2026-05-06 已修订 | P0 | F1-6-tasks.md §4 已修订:Sprint 3a(5 个 P1 可独立做)+ Sprint 3b(MP-2 + #11 等 ETL) |
| 4 | etl-coupon-detail 30+ "待调研"标注 4 个月未定 | docs/specs/etl-coupon-detail/ |
⏳ 灰色 | P2 | 待 Neo 评估是否 Wave 1 解决 |
| 5 | Sprint 3 / 4 衔接判断错误 | Claude 在 Sprint 2 收尾时推荐"跳过 Sprint 3"是错误判断 | ✅ 2026-05-06 已纠正 | P0 | Sprint 2 收尾后正确顺序 = Sprint 3 (5/6 项可做) → Sprint 4 |
| 6 | docs/roadmap/BACKLOG.md 60+ 项 P0-P2 待办 |
docs/roadmap/BACKLOG.md(2026-03-27 更新,258 行) |
⏳ 乍一看适用,但需细化对账 | P1 | Neo 指示:大多数任务"乍一看都适用",但很多逻辑细节值得再深入调研 — 有些已不适用 / 有些与现状冲突 / 有些被更好方式实现了。不能简单"批量标已完成"或"批量标待办"。需逐项做细化对账(可能与 Wave 1/F1 工作有大量交叠)。本身是一个独立的中等工作量任务(~ 2-3h),建议作为独立"BACKLOG.md 复核 sprint"启动 |
| 7 | docs/roadmap/2026-02-24__fdw-dwd-to-core-migration-plan.md FDW 迁移方案 |
docs/roadmap/2026-02-24__fdw-dwd-to-core-migration-plan.md |
⏳ 待对照 | P2 | 与 backlog §一 "DWD 孤立 + Core 中间件"目标完全一致,实际是同一目标的更早期 spec。需对照本 backlog §一确认是否仍代表当前方向,或已被本 backlog 取代 |
| 8 | Wave 0 全栈产品文档体系(已完成,但需登记并纳入 §八文档规范化范围) | docs/_overview/01-product-overview.md 等 5 篇 |
✅ Wave 0 完成 | — | 详见 §九新增登记;文档规范化大工程(§八)是其下一阶段,即"对完整体系进一步精化和重构,零信息损失" |
| 9 | (累积基线遗留)缓存分桶 + EventBus 生产观察 | 累积基线 3.1.3 | ⏳ 未收口 | P2 | F1-6 sprint 3 完成后补 audit |
| 10 | (累积基线遗留)WebSocket 消费稳定性 | 累积基线 3.1.7 | ⏳ 未收口 | P2 | 上线灰度期(5-7 ~ 5-15)长期观察 |
| 11 | (累积基线遗留)ETL 库完整 GUC 传递 26 视图 | 累积基线 3.5.5 | ⏳ 未收口 | P1 | 推迟 F1-5b Wave C(已规划) |
| 12 | (累积基线遗留)finance_area_daily 会员分桶 vs DWS 规范 | 累积基线 3.7.2 | ⏳ 未收口 | P1 | 数据质量 Review,上线灰度期 |
| 13 | (累积基线遗留)RLS 视图 pg_get_viewdef 全量重建 | 累积基线 3.7.3 | ⏳ 未收口 | P1 | 数据质量 Review + 视图清单专题 audit |
| 14 | AI 9 APP 全链路未完成(接口/入库/后端处理/前端展示) | Neo 2026-05-06 提出 | ✅ 2026-05-06 主体收口(超级 Sprint) | P0 | 详见 2026-05-06__w1_ai_closure_super_sprint.md — 49 文件改动 + 1 数据库迁移 + 5 个 silent failure 修复 + chat sourcePage 全链路接通 + WS 鉴权;残余 14 项独立子任务登记为 #15-#28 |
| 15 | /api/retention-clue POST/DELETE 三端点无认证(P0-3 安全洞) |
超级 Sprint 调研发现 | ⏳ 未收口 | 🔴 P0 | Sprint 后立即独立修 — 加 Depends(require_approved) + site_id 从 JWT |
| 16 | 时光机日期切换 AI 数据初始化机制 | Neo 2026-05-06 提出 | ⏳ 未收口 | P1 | F1-6 阶段 B 必做 — 切日期时该实例 cache 空触发批量初始化 + 预算保护 |
| 17 | App8 落库静默吞排查(67 cache → 44 入库,差 23 条) | 超级 Sprint 调研发现 | ⏳ 未收口 | P1 | 独立 audit 数据质量 review |
| 18 | App3 daily budget 超限 45% 失败率 | 超级 Sprint 调研发现 | ⏳ 未收口 | P2 | 生产灰度前复核 daily 预算上限 |
| 19 | tenant-admin 新增"创建维客线索"功能(POST 端点 + UI) | 超级 Sprint 调研:source='manual' 字段已设计但 UI 录入入口缺失 | ⏳ 未收口 | P2 | 独立 M sprint(~ 2h):POST 端点 + 前端表单 + 用户校验 |
| 20 | MCP 沙箱场景 B 走查(切沙箱模式只读验证) | 超级 Sprint 跳过(避免污染 prod) | ⏳ 未收口 | P2 | F1-6 阶段 B 必做 |
| 21 | RLS 迁移(P1-1 public → biz schema + app.v_*) | Neo 已批选 A 但未执行 | ⏳ 未收口 | P1 | F1-6 阶段 B 收尾后 |
| 22 | chat-history 新建/删除按钮 | 超级 Sprint UX 增量 | ⏳ 未收口 | P2 | 独立小 sprint |
| 23 | ai_conversations.source_page/source_context 冗余孤儿列(已建未用) |
超级 Sprint 调研发现 | ⏳ 未收口 | P2 | 决策弃用还是启用 |
| 24 | admin-web 全 snake_case → camelCase 大改造 | 超级 Sprint 调研:admin 与 xcx 端命名风格分裂 | ⏳ 未收口 | P2 | 影响面巨大,独立 sprint |
| 25 | admin-web WS 客户端补 ?token= query 参数 |
超级 Sprint P0-9 仅修后端 | ⏳ 未收口 | 🔴 P0 安全 | 与 #15 一起立即修 — 否则 admin 监控页 WS 全部 close 4401 |
| 26 | prompt/Pydantic/前端类型四端单一权威源 spec | 超级 Sprint 调研发现 | ⏳ 未收口 | P2 | 架构级,需 spec |
| 27 | cache_service._row_to_dict datetime 强转 ISO 字符串丢 tz |
超级 Sprint 调研登记 P1 但未做(怕破坏现有调用方) | ⏳ 未收口 | P2 | 改保留 datetime 对象,由 Pydantic 序列化 |
| 28 | ai_run_logs.assistant_id 列已加,历史回填仍未做(不阻塞功能,定位用) |
超级 Sprint 仅加列 | ⏳ 未收口 | P2 | 独立回填脚本(可选) |
| 29 | _text_coach_detail SQL hire_date 列不存在 |
复盘 chat 上下文走查实证 | ⏳ 未收口 | P1 | 看 dim_assistant 实际列名,改 SQL — 影响 coach-detail 入口 chat 上下文 |
| 30 | _text_board_finance SQL items_sum 列不存在(应用 DWD-DOC #1 合成表达式) |
复盘 chat 上下文走查实证 | ⏳ 未收口 | P1 | 改用 (table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money) 或对应 v_dws 视图字段 — 影响 board-finance 入口 chat 上下文 |
| 31 | _text_board_customer SQL sh.items_sum 同 #30 |
复盘 chat 上下文走查实证 | ⏳ 未收口 | P1 | 同 #30 解法 — 影响 board-customer 入口 chat 上下文 |
| 32 | _text_performance SQL sc.performance_tier 列不存在 |
复盘 chat 上下文走查实证 | ⏳ 未收口 | P1 | 看 dws_assistant_task_monthly 等表实际列,改 SQL — 影响 performance 入口 chat 上下文 |
| 33 | App1 chat 调用全链路审计 — 拉起参数完整性 / 本地 MCP 查询 / 沙箱边界收口 | Neo 2026-05-06 提出 | ⏳ 未收口 | P1 | 详见 §十一(独立专题登记)— 独立 sprint 评估 |
| 34 | 百炼调取 + 本地 SQL MCP 任务 全部接入主任务线追踪 | Neo 2026-05-06 提出 | ⏳ 未收口 | P1 | 详见 §十二(独立专题登记)— 独立 sprint 评估 |
| 35 | chat md 渲染:--- 水平分割线未特殊处理(被当作普通段落) |
复盘 chat md 走查发现 | ⏳ 未收口 | P2 | mdToRichHtml 加 <hr> 处理(rich-text 支持 hr) |
| 36 | _text_task_detail SQL coach_tasks_member_view / coach_tasks_assistant_view 视图不存在 |
14 入口走查实证 | ⏳ 未收口 | P1 | 看实际 dim_member / dim_assistant FDW 视图,改 SQL — 影响 task-detail 入口 chat 上下文 |
| 37 | 4 个入口缺 _text_* 实现 → chat 拿不到页面上下文(coach-service-records / performance-records / notes / chat-history) |
14 入口走查实证 | ⏳ 未收口 | P2 | 加到 SUPPORTED_PAGE_TYPES + 实现各自 _text_* 函数;或者把 wxml sourcePage 映射到已支持 page(coach-service-records → coach-detail 等) |
| 38 | customer-detail 频繁 navigate 切换时偶发 pageState='error' |
14 入口走查实证(loadDetail 手动调可重现成功,onLoad 触发时偶发失败) | ⏳ 未收口 | P2 | 看 onShow auth-guard 与 onLoad loadDetail 的并发竞争,加 lock 或重试 |
收口原则
- 每项洞口完成后,出对应 audit 文档(
docs/audit/changes/2026-05-XX__closure_*.md) - 完成后标 ✅ 并补 commit 引用
- 不再让"待验证 / 待调研"在文档中无限期挂着
八、文档规范化整理(大工程,长期立项)
触发背景
Neo:"项目中的文档又多又零碎,分支理不清,只能逐一处理并全部文档按类型和作用 重构合并去重等。但我不想损失任何的信息精度。这是一个很重很大的工程。"
调研背景(子代理 2 实证 2026-05-06):没有找到明确的"2026-01-01 至今文档整理" 任务记录,只有零散的局部整理痕迹(2026-02-13 BD manual 整理 / 2026-02-15 docs/database 合并 / 2026-04-06 v1 整理 1155 文件)。本立项即明确该任务正式登记。
工程目标(Neo 定义)
- 规范化:项目内所有文档按类型和作用归类
- 归档:过期内容统一归档(不删除)
- 对账:不符合项目实时状态的文档,逐一对比分析原因
- 去重 + 合并:多文档同主题/重叠内容,合并去重
- 重构:目录结构按"类型 + 作用"重新组织
- 零信息损失 (关键约束):不损失任何精度,即使整理过程也保留原文留底
范围估算(初步,详细 spec 待立)
docs/_overview/(产品全景索引)docs/audit/(审计记录,200+ 篇 audit 文档)docs/prd/(PRD + 决策卡 + 反馈)docs/database/(BD manual + DDL)docs/specs/(spec 文档,含 etl-coupon-detail 等)docs/ai/(AI prompt 体系)docs/contracts/(OpenAPI 契约)docs/guides/(开发指南)docs/miniprogram-dev/(小程序开发)docs/architecture/(架构总览)docs/ai-env-history/(迁移历史)- 各模块内
docs/(模块本地文档)
工程量初判
- 大概率 L+ 工作量(数十小时,需要分多个 sprint)
- 必须有明确 spec 设计(类型分类标准 / 归档约定 / 去重原则 / 信息损失防护)
- 不在 F1-6 阶段 B 做,作为独立任务在 F1-6 完成后或并行启动
执行原则
- 先 spec 后施工(不做无规划重构)
- 每次提交 1 个目录或 1 个主题,不批量乱动
- 整理前留下 git 备份点(全文档 tar 归档 _DEL/ )
- 整理后做信息精度核对(diff 比对关键内容)
状态
- ⏳ 立项(2026-05-06 由 Neo 在反思时正式登记)
- 详细 spec 待 Neo 调度时立(可能与 F1-6 阶段 B 收尾后启动)
九、Wave 0 全栈产品文档体系(已完成,登记并纳入 §八后续重构范围)
触发背景
Neo 反思时问:"WEB 小程序 数据库 后端等项目全局的一个文档的任务,是否也规划了, 还是已经完成了?"经子代理调研:已完成 Wave 0(2026-05-04),但当时缺乏明确登记, 本次正式登记并标注后续与 §八 文档规范化大工程的关系。
Wave 0 完成清单
| 文档 | 完整度 | 内容 | 引用方 |
|---|---|---|---|
docs/_overview/01-product-overview.md |
95% | 380 行产品全景脑图,角色到 4 端映射,8 大章节 | F1-* sprint 引为标杆 |
docs/_overview/02a-miniprogram-page-matrix.md |
90% | 21 页小程序业务指纹矩阵(498 行) | W1-T1 / F1-5b MP-3/4/5 |
docs/_overview/02b-adminweb-page-matrix.md |
85% | 19 路由 admin-web 业务指纹矩阵(280 行) | F1-5b UI-1/2/3/4/5 |
docs/_overview/admin-api-prd/00-overview.md |
90% | 151 端点 API 全景(拆 5 批 PRD,W1-T7 批 1 完成) | W1-T7 P1-7 |
docs/_overview/04-doc-conflicts.md |
90% | 39 条文档冲突清单(已拍板) | W1 P0/P1/P2 反馈调研 |
docs/_overview/00-index.md |
— | 主索引 + 维护协议 | 全 W1/F1 sprint |
完整覆盖范围
- WEB 端(admin-web 19 路由 + tenant-admin)
- 小程序端(21 页业务指纹)
- 数据库端(
docs/_overview/01-product-overview.md §四 数据流+docs/database/BD manual) - 后端端(
admin-api-prd 151 端点+ 后端架构) - AI 应用矩阵(8 个千问 APP 汇总)
当前状态
- ✅ 已规划 + 已完成(Wave 0,2026-05-04)
- 🔄 持续优化中(W1/F1 sprint 推进时持续引用 + 增量更新)
- ⏳ 待精细化(§八 文档规范化大工程是其下一阶段,目标"对完整体系进一步规范化、去重、零信息损失重构")
与 §八 的关系
Wave 0 文档体系是 §八 文档规范化大工程的起点(已有的全景索引体系),不是 §八 的目标产物。§八 的目标是把整个 docs/ 目录(11+ 子目录,200+ 篇 audit + N 篇 spec/PRD)按 统一的"类型 + 作用"分类标准重构,Wave 0 已建立的全景索引体系是其规范的"骨架", 具体规则、归档约定、信息精度防护待 §八 详细 spec 时立。
十、AI 9 APP 全链路未完成(P0 高优先级)
触发背景
Neo 2026-05-06 反思时提出:"AI 方面 9 个 APP 的处理还没有完成,在接口、入库、后端处理、 前端小程序展示等环节还没有完成。这个也记录下,而且优先级很高。"
9 APP 全景
| # | APP | 类型 | prompt 文件 | dispatcher 调度 |
|---|---|---|---|---|
| 1 | app1_chat |
实时对话 | (无独立 prompt 文件,走 chat_service) | 不走 dispatcher |
| 2 | app2_finance |
财务洞察(全域) | app2_finance_prompt.py |
✓ 已对接 |
| 2a | app2a_finance_area |
财务洞察(区域派生) | app2a_finance_area_prompt.py |
✓ 已对接 |
| 3 | app3_clue |
维客线索 | app3_clue_prompt.py |
✓ 已对接 |
| 4 | app4_analysis |
助教分析 | app4_analysis_prompt.py |
✓ 已对接 |
| 5 | app5_tactics |
助教策略 | app5_tactics_prompt.py |
✓ 已对接 |
| 6 | app6_note |
备注分析 | app6_note_prompt.py |
✓ 已对接 |
| 7 | app7_customer |
客户分析 | app7_customer_prompt.py |
✓ 已对接 |
| 8 | app8_consolidate |
消费链整合 | app8_consolidation_prompt.py |
✓ 已对接 |
合计:8 prompt + 1 chat 实时 = 9 APP(Neo 表述准确)。
4 环节未完成现状(初步实证)
| 环节 | 现状 | 缺口举例 |
|---|---|---|
| 接口 | 部分就位 | 后端 8 prompt + dispatcher 调度链路存在;但每个 APP 的 OpenAPI 端点是否完整(8 个独立 GET / POST?)、是否有调用文档对接前端,需逐一对账 |
| 入库 | 表结构就位 | biz.ai_run_logs + biz.ai_app_cache 等表存在;但每个 APP 的实际入库行为(成功率、缓存命中率、字段完整性)、是否所有 APP 字段都正确写入,需逐一对账 |
| 后端处理 | 主体就位 | dispatcher 9 路调用链路存在;但 trace_service 装饰、熔断/限流/预算追踪、ctx_snapshot 防漂移、F1-5a runtime_context 注入是否所有 APP 都覆盖,需逐一对账 |
| 前端小程序展示 | 不全 | 实证小程序仅 4 个文件涉及 AI(board-finance / customer-detail / services/api / ai-title-badge 组件)。理论上 9 APP 至少应有更多展示点(board-overview / coach-detail / coach-service-records / customer-records 等是否对接 AI 洞察 ?)。展示完整性需重点对账 |
关键不确定性
- 9 APP 中实际"已完整运行"的有几个?
- 9 APP 中实际"已被前端展示"的有几个?
- 是否有 APP 已写代码但实际"沉默不调用"(僵尸 APP)?
- 是否有 APP 在小程序展示但缺少入库/审计?
- 是否有数据库 schema 与实际入库行为不一致?
工程量估算(初步,详细 spec 待立)
- 单 APP 全链路对账(接口 + 入库 + 后端 + 前端 4 环节实证)≈ 30-45 min
- 9 APP × 30-45min = 4.5 - 7h 全链路对账
- 加发现问题后修复 + 测试 + audit ≈ 总 L 工作量(8-12h)
状态
- ⏳ P0 高优先级未收口(2026-05-06 由 Neo 正式登记)
- 暂未启动专门 sprint
- 与 F1-6 沙箱时光机的关系:沙箱时光机(F1-5a/F1-5b/F1-6)涉及 ctx_snapshot 注入到 9 APP, 已部分覆盖"后端处理"环节;但其他 3 环节(接口/入库/前端展示)需独立对账
建议执行路径
新增独立"AI 9 APP 全链路收口 wave"(可命名为 W1-AI-CLOSURE):
- Step 1 调研(~ 1h):对每个 APP 的 4 环节做初步实证扫描,出"全链路现状矩阵"
- Step 2 拆 sprint(~ 0.5h):按发现问题严重度拆 N 个独立 sprint(每 sprint 收 1-3 个 APP)
- Step 3-N 实施:每个 sprint 走 §3 五步流程 + 双口径走查(若涉及 sandbox)+ audit + commit
与现有 backlog 关系
本项与 §一 DWD 孤立 + Core 中间件、§八 文档规范化大工程并列为"L 级长期工程", 但优先级 P0 高于其他(Neo 强调"优先级很高")。F1-6 阶段 B 收尾后,优先启动本项。
十一、App1 chat 调用全链路审计(P1,独立 sprint)
触发背景
Neo 2026-05-06 W1-AI-CLOSURE 复盘时提出:"App1 要传入的参数是否已经传入?对于拉起、访问本地 MCP 查询,如果有沙箱的设置,如何收口查询边界?相关联的措施整理需求并记录。"
审计维度
- 拉起参数完整性 — App1 chat 触发链路对接百炼应用 ID (
DASHSCOPE_APP_ID_1_CHAT) 时,所有期望参数(biz_params: User_ID/Role/Nickname,session_id,prompt 拼装的 page_context + 历史消息)是否在 dispatcher / xcx_chat 中真实传入? - 本地 MCP 查询 — chat 路径上百炼应用是否真正用到本地 MCP server(
apps/mcp-server/)?MCP server 在.mcp.json注册的 PostgreSQL 只读连接,App1 拉起时是否调用?调用频率 / 失败回退? - 沙箱边界收口 — 当门店进入 sandbox 模式(
biz.site_runtime_context.mode='sandbox'),chat 应用的查询边界:- prompt 注入的
current_time是否走as_runtime_business_now_str(site_id)?✅(W1-AI-CLOSURE 已实证) - page_context 注入的客户消费数据是否过滤
business_date上界?(F1-6 阶段 B 范围) - 本地 MCP 查询是否传入 sandbox_instance_id 隔离?
- 百炼应用拉取的工具调用结果是否带沙箱上下文?
- prompt 注入的
工作量
- 链路全审 ~ 2-3h
- 修复缺口 ~ 1-2 个 sprint
状态
⏳ 未启动 — 待 W1-AI-CLOSURE 主体收口后独立调研
十二、百炼 + 本地 SQL MCP 任务追踪(P1,主任务线)
触发背景
Neo 2026-05-06 W1-AI-CLOSURE 复盘时提出:"百炼调取,本地跑的 SQL MCP 任务也要记录在主任务线中。"
当前缺口
- 百炼 API 调用记录 —
biz.ai_run_logs表已记录 dispatcher 调用(8 个 prompt 应用),但 App1 chat 的百炼调用(call_app_stream)目前未写入 ai_run_logs(只写ai_messages)。chat 调用的成功率 / latency / token / 失败原因没有统一观测面板。 - 本地 MCP server 调用记录 —
apps/mcp-server/提供 PostgreSQL 只读 MCP 工具,百炼应用通过 MCP 协议调用本地 SQL 时,调用日志没有持久化(MCP server 可能只在 stdout 输出)。无法追踪:- 百炼实际调了哪些 SQL?
- 调用成功率 / 错误率?
- 单次调用 token 消耗 / 时间?
- 沙箱 site_id 是否正确隔离?
- 任务线统一面板 — admin-web 的 AIRunLogs 当前只看 dispatcher 8 个 prompt 应用的日志,chat + MCP 调用没纳入面板,运维盲点。
收口动作建议
chat_service在每次 SSE 完成后写一条ai_run_logs记录(app_type=app1_chat,记 prompt/response/token/duration/status)- mcp-server 加调用日志中间件(可写到
biz.mcp_call_logs新表 / 或复用ai_run_logs+ app_type='mcp_xxx') - admin-web AIRunLogs 面板加
app_type IN ('app1_chat', 'mcp_*')筛选项 - 关联到 dashboard:百炼应用 + chat + MCP 三类调用的统一观测视图
工作量
- 后端写入 ~ 1h
- mcp-server 拦截器 ~ 1h
- admin-web 面板补 ~ 1h
- 总:~ 3h(单 sprint 范围)
状态
⏳ 未启动 — 与 §十一 配套,作为独立"AI 调用观测性"sprint 推进