技能介绍

解决 HTML 看板迁移的“数据幻觉”

在 HTML 看板迁移或独立开发时，开发者常面临“数据不显示”、“白屏”或“数据与 Console 不一致”的诡异问题。这并非单纯的代码 bug，而是底层数据链路差异导致的：HTML 页面查询的是延迟最高 4 小时的 Parquet 快照，执行引擎为 DuckDB；而 Console 端直接查询 PostgreSQL 原表。此外，SDK 命名空间变更、ECharts 实例更新规范以及容器时区差异，都让数据对齐和页面渲染变得异常脆弱。

六步自动化验证流水线

该技能将迁移验证拆解为严密的 6 步流水线，确保每层数据与代码逻辑均可追溯：

静态扫描与 JS 语法检验：执行 lint 检查并强制验证 <script> 内的 JS 语法。语法错误会直接导致线上白屏且无报错，必须在此步拦截。
列真实性与 SQL 检查：通过 probe 验证字段存在性，用 check-sql 确保 DuckDB 语法（如 INTERVAL '7 days'）正确执行，并覆盖 D 变量。
数据一致性对比：执行 compare 时强制 sync 快照。若 COUNT 差异巨大，优先排查 LEFT JOIN 导致的行重复膨胀问题；若存在时区或嵌套 API 问题，则引入 PostgreSQL 进行三级仲裁。
功能对齐检查：统计 HTML 中 querySql() 调用次数与 Console 后端查询数对齐，防止数据正确但功能缺失的盲区。

适用边界与排障原则

验证的核心基准是 Console API 返回值（用户实际看到的数据），而 PostgreSQL 仅作为当 Parquet 快照与 API 不一致时的排障工具。此外，图表渲染必须严格遵循 ECharts 规范，使用 setOption 增量更新，禁止 dispose+init 或 Canvas/SVG 手绘。同步至空间前，务必确保已通过 lint 与 JS 语法检验，避免无提示白屏事故。