OK

2026-07-13 11:13:00 +08:00
parent ef96af7f21
commit dac7457c60
9 changed files with 297 additions and 28 deletions
@@ -158,3 +158,41 @@
 - 根因：采集读失败后 `Manager` 将设备状态置为 `disconnected`；缓存连接后续读取成功时此前只更新点位最新数据，没有恢复设备状态，因此设备管理页持续显示离线。
 - 修复：采集成功后调用 `Manager.MarkConnected` 恢复在线状态；`MarkConnected` 与 `MarkDisconnected` 仅在状态发生变化时更新时间戳，避免每个采集周期反复刷新最近在线/离线时间。
 - 验证：真实环境中 PLC1、PLC2、PLC3 均显示 `connected`，40 个采集点的 `latest_value.ts` 持续更新；新增设备状态恢复及时间戳稳定性单元测试。
+
+## 2026-07-13 · 启停流程文档与历史曲线断档修复
+
+- 维护约定：从本次起，后续每次代码、配置、部署流程或验证方式调整，都必须同步记录到 `docs/development-log.md`。
+- README 启停流程补充：明确项目按前后端分离运行；后端默认 `8080`，前端 Vite 默认 `5173`；应用不会自动读取 `.env`，启动后端前必须先在 PowerShell 中注入环境变量；补充后端、前端启动命令、健康检查命令和按端口停止服务命令。
+- pnpm 构建脚本审批：将 `pnpm-workspace.yaml` 中 `allowBuilds.esbuild` 从占位值修正为 `true`，解决 `esbuild@0.25.12` postinstall 被拦截导致前端无法构建的问题。
+- 启动验证：`.env` 已指向云端数据库，PostgreSQL `101.35.54.96:5432` 与 TDengine REST `101.35.54.96:6041` TCP 连通；`GET http://127.0.0.1:8080/api/v1/health` 与 `GET http://127.0.0.1:5173/api/v1/health` 均返回 `code=0`。
+- 服务停止验证：停止后端 Go 进程与前端 Vite 进程后，`8080` 和 `5173` 均无监听进程。
+- 历史曲线断档根因：曲线查询只返回真实采样点，停机或未采集时段没有显式空值断点；ECharts 在相邻有效点之间会直接连线，因此会把 2026-07-13 02:00 到 08:00 这类无数据时段渲染成连续曲线。
+- 历史曲线修复：后端 `history/query` 按点位 `history_interval` 判断断档，相邻样本间隔超过 `3 × history_interval` 时插入 `value=null, quality=none` 断点；前端游标插值遇到空值或非 good 质量断点时不再跨断档估算，避免提示表显示伪造的连续值。
+- 新增测试：`internal/service/platform/history_test.go` 覆盖长时间无数据插入断点、短时间采集抖动不误判断档。
+- 验证：`go test ./...` 通过；`pnpm build` 通过，仅保留既有 ECharts chunk 体积提示；`pnpm lint` 未通过，原因为项目当前缺少 ESLint 9 所需的 `eslint.config.js`，不是本次变更引入。
+
+## 2026-07-13 · TDengine 时间戳时区修复
+
+- 现象：TDengine 工具中最新历史数据时间显示为 `2026-07-13 17:50:53.026`，比现场当前时间快 8 小时；页面实时数据时间显示正常。
+- 根因：历史写入使用 `2006-01-02 15:04:05.000` 无时区格式，TDengine REST 链路按 UTC instant 存储；数据库工具按本地时区显示后形成 `+8h` 偏移。历史查询代码此前又把读回时间按上海墙上时间重建，导致页面显示正常但库内物理时间不一致。
+- 验证：临时 TDengine 探测表写入同一时间的两种格式，`plain` 无时区读回为 `2026-07-13T10:10:10.123Z`，`rfc3339` 带 `+08:00` 读回为 `2026-07-13T02:10:10.123Z`，证明无时区写入会偏移 8 小时。
+- 修复：TDengine 写入和查询时间字面量统一改为 RFC3339 样式 `yyyy-MM-ddTHH:mm:ss.SSS+08:00`；读回时间按真实 instant 转换为 `Asia/Shanghai`，不再重建墙上时间。
+- 测试：新增 `TestTDTimeLiteralUsesShanghaiOffset`，锁定 TDengine 时间字面量必须带 `+08:00`。
+- 验证：`go test ./...` 通过；`pnpm build` 通过，仅保留既有 ECharts chunk 体积提示。
+- 运行验证：重启后端后，`8080` 后端健康检查与 `5173` 前端代理健康检查均返回 `code=0`；对点位 `1dd3c3c4-bb27-4b57-bd10-039a6e2a81d9` 查询 `2026-07-13T10:00:00+08:00` 到 `10:30:00+08:00` 区间，TDengine 返回新记录 `2026-07-13 10:05:41.002 +08:00`，证明新写入时间已按本地真实时间入库。
+- 注意：修复只保证后续新写入数据时间正确；已经写入 TDengine 的旧历史行物理时间戳已偏移到未来，如需修正，需要在停采后执行一次受控数据回拨/重写操作，不能自动盲改。
+
+## 2026-07-13 · TDengine 旧历史数据时间回拨
+
+- 操作前先停止后端采集进程，确认 `8080` 无监听，避免迁移期间继续写入历史数据。
+- 迁移范围：枚举 TDengine `collection_data` 下 40 张 `p_*` 点位子表，共 1562 行历史数据；dry-run 统计 1526 行为旧无时区写入数据，需要整体回拨 8 小时，36 行位于 `2026-07-13 10:00~10:30 +08:00` 修复后新写入窗口，保留原时间不动。
+- 备份：执行前导出 JSONL 本地备份 `C:\Users\ADMINI~1\AppData\Local\Temp\aquacontrolai-tdengine-history-backup-20260713-101548.jsonl`，记录原始时间、修正后时间、点位、设备、质量和值。
+- 修复方式：因时间戳为 TDengine 时序主键，不直接执行盲目 `UPDATE`；脚本逐表读取全量行、计算修正时间、检查修正后同表时间戳冲突，然后 `DROP TABLE` 子表并按原稳定表 `collection_data`、原标签和原数据列重建写回。
+- 结果：实际执行后 `repair_complete rows=1562`，迁移前后总行数一致。
+- 验证：全库最新时间由未来 `18:00` 左右恢复为 `2026-07-13 10:05:46.506 +08:00`；示例点位 `1dd3c3c4-bb27-4b57-bd10-039a6e2a81d9` 最新 5 条为 `10:05:41`、`10:00:53`、`09:50:53`、`09:48:52`、`09:43:55`；该点位 `2026-07-13 02:00~08:00 +08:00` 区间查询结果为 0 条。
+
+## 2026-07-13 · 历史数据 CSV 导出列调整
+
+- 需求：历史数据表格导出 CSV 时，每个测点只导出一列实际值，不再为每个测点额外导出“质量”列。
+- 修复：`POST /api/v1/history/export` 表头从“时间 + 点位值列 + 点位质量列”改为“时间 + 每个点位一个值列”；行数据仅写入 `value`，无值时留空，不再输出 `good/bad/—` 质量文本。
+- 验证：`go test ./...` 通过；重启后端后调用 `POST /api/v1/history/export` 导出点位 `1dd3c3c4-bb27-4b57-bd10-039a6e2a81d9` 的 `2026-07-13 09:40~10:10 +08:00` 数据，CSV 表头为 `时间,2区PAC投加流量[L/h]`，列数为 2，无质量列。