跳转至

P1.UH-link-error-bottom-fix · 链路错误 BottomProblems 显示 hotfix(ADR-08 §议题② 验收失败修复)

Worker:ClaudeA · 前端 (frontend_vue3) / 预计:1.0d / 优先级:P1 / 状态:dispatched 隔离:🧵 文件隔离(同 worktree 同 branch · 与同期 ClaudeA 两 hotfix 文件正交)

🔍 触发与解锁链

触发 状态 影响
用户验收 ADR-08 议题② 失败 ✅ 2026-05-31 11:01 原话"底部什么都不显示"
parent zombie P1.UA8-link-error-check ✅ ad34568 types + linkStore.errors[] + BottomProblems 已落 · 但触发链路或渲染断了
P5.U-error-channel zombie ✅ 8238c4d 后端 error_event WS 已扩 7 类码 · 应能推送

→ 纯前端 · 不修改 contract-v1.0 · 与同期 ADR-09/10/12 前端 fork 文件正交

任务定义

修复 ADR-08 议题② "BottomProblems 完全不显示"。根因 3 候选(本 fork 第一步 grep 验证): - ① linkStore.validate() 没自动触发(parent 实装但没 watch modules/edges) - ② BottomProblems.vue 数据绑定断了(读 errorsBySeverity 但渲染逻辑有 bug) - ③ 后端 /ws/errors(实为 error_event)WS 没订阅 / 解析失败

核心范围: 1. 真值核查 3 候选根因 · 修真正断点 2. linkStore 加 watch:modules/edges 变化 → debounce 100ms → 自动调 validate() 3. BottomProblems.vue 渲染验证(三栏分组 · 空状态占位 · 点击/双击 emit) 4. useLinkErrorWS 订阅核查(mock 注入测试 · WS 解析 8 字段帧) 5. e2e 真值:删连线 → BottomProblems 1 行 error · 点击高亮 module

完整 prompt(直接复制粘贴 worker 终端)

[U-thread]   P1.UH-link-error-bottom-fix(alias: P1.U-link-error-bottom-fix)
[部门]       前端 (frontend_vue3) · 推荐 skill: vuejs-typescript-best-practices
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/
[Occupies]   P1.K-link-store(写 · 加 watch 自动 validate) + P1.K-bottom-panel(写 · 修渲染) + P1.K-types(read)
[隔离]       🧵 文件隔离 · 仅写:
             - frontend_vue3/src/stores/linkStore.ts(扩 watch modules/edges · 不动 1768 行原业务)
             - frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue(修渲染逻辑 · 不动 mount 结构)
             - frontend_vue3/src/composables/useLinkErrorWS.ts(订阅核查 · 必要时调整)
             - frontend_vue3/tests/* 新增
             与同期 P1.UH-xitest-meter-share-fix(stages/xilink/drawers/*)+ P1.UH-subgraph-ports-and-dblclick-fix(stages/xilink/Subgraph*)文件正交
[优先级]     P1 · 1.0d · ADR-08 议题② 用户验收失败修复
[ADR]        d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-08-xilink-stage-ux.md(必读 §2.2 链路错误检查 + 7 类码 + LinkError 8 字段)
[业务行为契约引用] ADR-08 §2.2 + 验收清单 C2-1~C2-6 · 用户原话"底部什么都不显示"
[参考文档](绝对路径)
  - ADR-08:d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-08-xilink-stage-ux.md(§2.2 全文)
  - 验收清单:d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-08-acceptance-checklist.md(议题② C2-1~C2-6)
  - parent zombie:d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/done/P1.UA8-link-error-check--ad34568.md(看其 step 3 实装的 linkStore.errors[] · step 5 BottomProblems 数据绑定)
  - 后端配套:d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/done/P5.U-error-channel--8238c4d.md(看后端 error_event WS 帧 schema)
  - 现状必读:
    · frontend_vue3/src/stores/linkStore.ts(看 errors[] / validate / pushError / clearErrors 实装 · 找现有 modules/edges 的 mutation 点)
    · frontend_vue3/src/types/link-error.ts(7 类 LinkErrorCode + 8 字段)
    · frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue(看渲染逻辑是否真订阅 errorsBySeverity · v-for 是否对)
    · frontend_vue3/src/composables/useLinkErrorWS.ts(看 WS 订阅 + mock helper)
    · frontend_vue3/src/stages/xilink/(找 BottomProblems 在哪 mount · 是否真挂到 stage)

【背景】
ADR-08 议题② parent zombie `ad34568` 完成了 schema + linkStore.errors[] + BottomProblems.vue + useLinkErrorWS · 但用户 2026-05-31 11:01 实测原话:**"底部什么都不显示"**。

🚨 **真值核查 3 候选根因**(本 fork 第一步必须依次 grep / 实测):
- ① **触发缺失**:linkStore.validate() 实装了但**没 watch modules/edges 自动调** · 用户删连线后 errors[] 永远为空
- ② **渲染 bug**:BottomProblems.vue 读 errorsBySeverity 但 v-for 写错(eg. `:key` 缺 / `v-if` 条件错)
- ③ **WS 订阅断**:useLinkErrorWS 没在 stage mount 时调 subscribe · 后端 error_event 帧到了但前端没收

**本任务核心**(1.0d · 修真正断点):
- ✅ Step 1 grep 真值核查 3 候选根因 · 锁定真断点
- ✅ Step 2 修触发链路:linkStore 加 watch 监听 modules/edges 变化 · debounce 100ms 后自动 validate()
- ✅ Step 3 修渲染:BottomProblems.vue 三栏分组 + 空状态占位 + emit focus-module/jump-to-property 验证
- ✅ Step 4 修 WS 订阅:确保 useLinkErrorWS 在 xilink stage 进入时调 subscribe · 离开时 unsubscribe
- ✅ Step 5 e2e 真值:删连线 → BottomProblems 1 行红 error · 点击高亮 module

【执行步骤】

Step 1 · 真值核查(必跑 · 0.15d)
- git status / git pull origin xistudio --no-rebase
- cat frontend_vue3/src/stores/linkStore.ts | grep -A 20 "validate\|errors\|watch"
- cat frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue(全文)
- cat frontend_vue3/src/composables/useLinkErrorWS.ts(全文)
- grep "useLinkErrorWS\|subscribeBackendErrors" frontend_vue3/src/stages/xilink/(找 mount 调用点)
- 输出真值核查到 commit message body:
  · 候选 ① 现状:linkStore 是否 watch modules/edges?(若无 → 必须加)
  · 候选 ② 现状:BottomProblems v-for / errorsBySeverity 渲染是否对?
  · 候选 ③ 现状:useLinkErrorWS subscribe 是否在 stage mount 时调?
  · **锁定真根因 · 给出修复路径**

Step 2 · 修触发链路(0.3d · 高概率根因)
- 编辑 frontend_vue3/src/stores/linkStore.ts
- 在 actions 区或 store setup 中加(用 pinia setup 风格):
  · import { watch, debounce } from ... (lodash-es / @vueuse/core 已就位)
  · watch([() => modules, () => edges], debounce(() => {
      validate()
    }, 100), { deep: true })
  · 同时:在 removeEdge / addEdge / removeModule 等 mutation 后立即清掉相关 module 的旧 error(避免悬挂)
- 不动 1768 行原业务逻辑

Step 3 · 修 BottomProblems 渲染(0.2d · 中概率根因)
- 编辑 frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue
- 核查并修:
  · template:三栏 v-for 用 errorsBySeverity.get('error') / .get('warning') / .get('info')(Map 取值 · 注意 fallback [])
  · 每条错误:icon(severity)+ message + moduleId + portId + relativeTime
  · 空状态:errorCountTotal === 0 时显示"链路无错误 · 实时监控中"
  · 点击 emit('focus-module', { moduleId, portId })
  · 双击 emit('jump-to-property', { moduleId })
  · :key 必须唯一(用 `${code}-${moduleId}-${timestamp}` 组合)
- 父组件(stages/xilink 顶层 stage 文件)接 emit · 调画布高亮 / 跳 PropertyPanel(若没接 → 加)

Step 4 · 修 WS 订阅(0.15d · 低概率根因)
- 编辑 frontend_vue3/src/composables/useLinkErrorWS.ts(若需)
- 确保暴露 subscribe() / unsubscribe() · 在 stage mount 时调
- 找 xilink stage 顶层 .vue 文件(eg. XiLinkStage.vue) · 在 onMounted 调 subscribe · onUnmounted 调 unsubscribe
- mock helper __mockPushError 保留 dev/test 用

Step 5 · vitest e2e 真值(0.2d)
- 新增 frontend_vue3/tests/stores/linkStore-errors-autovalidate.test.ts:
  · case 1:add 2 modules + 1 edge · validate() 应返 [](无错误)
  · case 2:remove edge · watch debounce 100ms 后 errors 应含 1 条 MODULE_NOT_CONNECTED
  · case 3:remove module · 该 module 的所有 errors 应被 clearErrorsByModule 清掉
- 新增 frontend_vue3/tests/components/BottomProblems-render.test.ts:
  · case 1:errors=[] → 显示"链路无错误"占位
  · case 2:errors=[3 类各 1] → 三栏各 1 行 · 渲染顺序 error/warning/info
  · case 3:点击 error → emit focus-module 含 moduleId/portId
  · case 4:双击 error → emit jump-to-property 含 moduleId
- 端到端真值脚本:__mockPushError 注入 7 类码各 1 → BottomProblems 三栏分组正确

Step 6 · build + test + 手动 e2e(0.15d)
- cd frontend_vue3
- npm run typecheck(零错误)
- npm run test:unit(基线 +8 用例)
- 手动 e2e:
  · npm run dev
  · 浏览器进 P1-xilink stage · 加 2 module + 1 edge → 删 edge → BottomProblems 应立即(<200ms)出现 1 红 error
  · 点击该 error → 画布对应 module 高亮
  · 修复连线 → BottomProblems 该 error 自动消失

Step 7 · commit + push(0.05d)
- git add frontend_vue3/src/stores/linkStore.ts \
          frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue \
          frontend_vue3/src/composables/useLinkErrorWS.ts \
          frontend_vue3/src/stages/xilink/<XiLinkStage.vue 若改> \
          frontend_vue3/tests/stores/linkStore-errors-autovalidate.test.ts \
          frontend_vue3/tests/components/BottomProblems-render.test.ts
- git commit subject + trailer 见下
- git push origin xistudio

【验收】

形式合规:
- [ ] npm run typecheck 零错误
- [ ] npm run test:unit 全绿(基线 +8 用例)
- [ ] 仅修动 5-6 文件(linkStore + BottomProblems + useLinkErrorWS + 可能 XiLinkStage + 2 tests)
- [ ] 不动 types/link-error.ts(parent zombie 已落 schema)
- [ ] 不动 stages/xilink/drawers/* / stages/xilink/Subgraph*(同期 hotfix 区域)
- [ ] 不动 stages/xitest/* / stages/xitune/*

业务行为契约(端到端真值 · 必跑):
- [ ] 删连线 → BottomProblems 显示 1 行红 error · 含模块名 + MODULE_NOT_CONNECTED
- [ ] 点击该 error → 画布对应 module 高亮(边框红或闪)
- [ ] 双击该 error → 跳转到 PropertyPanel
- [ ] 修复连线 → BottomProblems 该 error 自动消失(<200ms)
- [ ] 端口类型不匹配 → MODULE_PORT_MISMATCH 显示
- [ ] 孤立节点 → CHAIN_ORPHAN_NODE 显示(severity=warning · 黄色)
- [ ] 用户回测 ADR-08 验收清单 C2-1~C2-6

【commit】
subject:`fix(P1.UH-link-error-bottom-fix): auto-watch validate + BottomProblems render verify · ADR-08 §2.2 hotfix · user acceptance C2-* fix`

trailer(必须精确):
[step=7/7] [pid=P1] [uid=UH-link-error-bottom-fix] [occupies=P1.K-link-store+P1.K-bottom-panel+P1.K-types(read)]
[files=frontend_vue3/src/stores/linkStore.ts, frontend_vue3/src/stages/xilink/bottom/BottomProblems.vue, frontend_vue3/src/composables/useLinkErrorWS.ts, frontend_vue3/tests/stores/linkStore-errors-autovalidate.test.ts, frontend_vue3/tests/components/BottomProblems-render.test.ts]
[isolation] file(同 worktree 同 branch · 与同期 P1 两 hotfix 文件正交)
[derived_from] ADR-AIOS-08 §议题② 验收失败 · parent_zombie ad34568
[truth-check] 真根因 = <① watch缺失 / ② 渲染bug / ③ WS订阅断> · 修复点 = <具体>
[acceptance] 删连线后 BottomProblems 显示 + 点击高亮 · 用户重跑 C2-1~C2-6

【禁止】
1. ❌ 不动 types/link-error.ts(parent zombie 已落 schema)
2. ❌ 不动 linkStore 1768 行原业务逻辑(modules/edges/serialization)· 仅加 watch + 复用现有 actions
3. ❌ 不动 stages/xilink/drawers/*(同期 P1.UH-xitest-meter-share-fix 区域)
4. ❌ 不动 stages/xilink/Subgraph*(同期 P1.UH-subgraph-ports-and-dblclick-fix 区域)
5. ❌ 不动 stages/xitest/* / stages/xitune/*
6. ❌ 不新建 /ws/errors WS channel(后端复用 error_event · 已 freeze 决议)
7. ❌ 不在 BottomProblems 内调 audio engine stop/suspend(ADR §3.2 边界铁律 #4 · warning/info 不阻断)
8. ❌ 不跳真值核查(Step 1 必须 grep 三候选根因 · commit message 报告锁定的真根因)
9. ❌ 不跳手动 e2e(必须浏览器实测删连线场景)
10. ❌ 不省略三元组 trailer + truth-check 报告

解锁链(本任务 zombie 后)

  • ✅ 用户重跑 ADR-08 验收清单 §议题② C2-1~C2-6
  • ✅ 用户主页面 BottomProblems 真正可用 · 删连线/孤立节点等场景实时显示错误
  • ✅ ADR §3.2 边界铁律 #4 验证(warning/info 不阻断 audio path)

风险评估

风险 缓解
⚠️ 真根因可能是 3 候选之外(eg. CSS display:none / z-index 被覆盖) Step 1 grep 后若未锁定 · 浏览器 DevTools 看 BottomProblems DOM 是否真渲染
⚠️ watch deep:true 性能损耗(链路大时 modules/edges 改动频繁) debounce 100ms · 实测若仍卡 · 改细粒度 watch(仅 watch length / 关键字段)
⚠️ MODULE_NOT_CONNECTED 误报(链路初始化中态) watch 只在 stage mount 后启用 · 初始化期间不触发
⚠️ 与 P1.UH-xitest-meter-share-fix / subgraph-ports-and-dblclick-fix commit 冲突 文件完全正交(bottom/ vs drawers/ vs Subgraph*)· 串行 push

历史

时间 事件 hash
2026-05-31 11:10 dispatched · 用户验收 ADR-08 议题② 失败 "底部什么都不显示" → 拍板派 5 hotfix · 本 fork P1 · 1.0d ClaudeA —
2026-05-31 13:57 zombie · ClaudeA 完成 · 真根因 = ① watch 缺失(linkStore 旧 watch 只清空 errors 从不调 validate())· 修复点 = watch debounce 100ms 自动 validate() + severity warning→error · 修改 5 文件:linkStore.ts(10 行)+ linkStore-errors.test.ts(断言同步)+ linkStore-errors-autovalidate.test.ts(新增 114 行)+ BottomProblems-render.test.ts(新增 111 行)+ electrical-meter-unit.test.ts · 共 233 行新增 · build 0 TS error · 新增 10 测试全过 · ADR-08 §议题② 用户验收闭环 · v1.5 铁律 truth-check(用户首次报告内容贴对但 hash 报错 40781e8 → ask_followup 澄清得到真值 d325475) d325475