# 开发维护记录

## 2026-07-12｜需求分析

- 研读 `spec-数据管理.md` v1.2、`spec-历史数据.md` v1.1、`code-standards.md` v1.2 和一致性决策基线 v1.0。
- 确认采用单进程 Go 服务、Handler → Service → Repository、每设备独立协议连接、同设备读写串行、PostgreSQL 当前元数据权威、TDengine 子表由 UUID 派生。
- 历史查询边界统一为最多 20 点、31 天；曲线默认 2000 样本；表格使用精确半间隔最近邻；CSV 最大 50,000 行。

## 技术与视觉决策

- 前端使用 Vue 3 + TypeScript + Pinia + Vue Router + Axios + ECharts。
- 视觉采用深石墨底、荧光绿主色、青色辅助数据序列；避免卡片堆叠，保持工业数据表和图表的高信息密度。
- 非线性分段轴算法位于 `web/src/components/charts/`，API 和导出只使用原始值。
- PostgreSQL 使用 pgx 连接池；TDengine 使用官方 Go REST 驱动，连接信息全部来自环境变量。

## 已识别问题与处理

- 现场给出的读取地址 `DB2.DB2.1186.0` 与规格 `DB{db}.{byte}.{bit}` 冲突。实现严格接受 `DB2.1186.0`；现场测试前需由用户/PLC 工程师确认前一形式是否只是录入笔误。
- PLC `192.168.107.10:102` 在 2026-07-12 的 TCP 探测未在 30 秒窗口内完成；未执行任何写入。
- 用户提供的数据库凭据仅用于本次环境验证，不写入代码、示例或日志。

## 变更摘要

- 新增 PostgreSQL/TDengine 幂等迁移。
- 新增设备、采集点、写入点、历史数据四个桌面工作区。
- 新增设备 API、点位/日志列表、历史树、曲线、表格和 CSV 导出。
- 新增协议注册表、S7/Modbus 地址与配置校验骨架。

## 测试记录

- PostgreSQL `101.35.54.96:5432`：TCP 可达；目标库最初不存在，已通过受控标识符创建 `aquacontrolai` 并成功执行迁移。
- TDengine `101.35.54.96:6041`：TCP 可达；已创建/确认数据库及两个超级表，REST 驱动健康检查通过。
- PLC `192.168.107.10:102`：早期 TCP 探测超时，后续通过 S7 客户端成功连接并完成受控读写联调，详见下方补充记录。
- `go test ./...`：通过。
- `npm run build`：通过；Vite 提示 ECharts 主包超过 500 kB，后续可拆为异步图表 chunk。
- `GET /api/v1/health`：真实数据库配置下返回 `code=0`。
- Playwright Chromium 1600×1000：历史页可渲染，无框架错误覆盖层；空库状态正确显示 0/20 和空图表。应用内浏览器缺少必需控制入口，按规范使用 Playwright 回退。
- 视觉比对：应用壳、色板、导航、紧凑工具栏、开放式图表/表格容器与概念一致；空库无法验证多序列曲线、点位树密度和游标数据态。

## 2026-07-12｜现场 S7 联调补充

- 用户确认采集地址为 `DB2.1186.0`、类型 REAL。考虑现场工程记法，校验器仅对 DB 数值地址兼容末尾 `.0`；驱动实际按 DB2、字节偏移 1186 连续读取 4 字节。
- 写入地址 `MD540` 按 M 区字节偏移 540 连续读写 4 字节 IEEE-754 REAL。
- PLC 建立连接成功；`DB2.1186.0` 实际读值 `724.0000610351562`，质量 `good`。
- 写入测试成功：`MD540=10.0`，回读 `10.0`，日志 ID `36d173ec-a496-495b-ba6a-d7048e616afa`。
- 强制恢复成功：`MD540=0.0`，回读 `0.0`，日志 ID `88c0d3dc-3988-46b9-9e98-d03819f6dbbc`。
- TDengine REST 驱动不支持在 `USING ... TAGS` 中绑定参数；动态表名仍只由 UUID 派生，标签/字符串采用单引号倍增转义，数值使用 `strconv.FormatFloat`，并增加表名和转义单元测试。
- 修复 TDengine REST 时间语义：API 的 ISO 8601 时间统一换算为 `Asia/Shanghai` 后生成 TDengine 查询字面量，现场最近一小时查询返回 28 条记录并成功绘制曲线。
- 修复 `vue-tsc -b` 在 `src/` 旁生成陈旧 `.js` 并覆盖 TypeScript 模块解析的问题：启用 `noEmit`、删除生成物；Playwright 验证控制台无 warning/error。
- Playwright 1600×1000 验证：历史树 1 个可选现场点位、默认勾选、ECharts canvas 正常、曲线显示真实 TDengine 数据；切换表格模式后渲染 7 行最近邻数据。

## 2026-07-12｜剩余功能收尾

- 补齐设备、采集点、写入点详情 API，采集分组 API，以及三类配置 CSV 导入/导出。
- CSV 真实回灌验证：三类各 1 行，均为 `created=0, updated=1, failed=0`，名称幂等规则有效且没有产生重复记录。
- 补齐采集点和写入点新增、编辑、删除弹窗；三类页面导入文件选择与导出下载按钮已接入真实 API。
- 新增历史保留策略 GET/PUT；更新顺序为 TDengine `ALTER DATABASE KEEP` 成功后再提交 PostgreSQL 生效值。真实环境以 365 天原值回写验证成功。
- Playwright 逐页验证：设备、采集点、写入点三个新增弹窗均可打开并取消；历史保留配置可见；表格模式渲染 7 行；控制台无 warning/error。
- 补齐设备列表的协议/启用筛选，采集点和写入点的设备/分组/类型/启用/写入开关筛选，以及统一 `page/page_size`（最大 100）分页；写入日志支持点位、设备、结果和关键词筛选。
- 历史页新增精确到秒的自定义起止时间输入；快捷时间与自定义时间共用查询缓存键。
- 最终浏览器回归：三类页面导入/导出入口均可见，三个新增弹窗均可打开；历史页 2 个时间输入、保留策略控件和 7 行表格数据正常；控制台无 warning/error。

## 2026-07-12｜设备状态展示调整

- 设备管理表头由“运行状态”改为“设备状态”。
- 后端状态映射为：`connected → 在线`、`disconnected → 离线`、`disabled → 禁用`。
- 前端使用无圆点的文字卡片：在线绿色、离线红色、禁用灰色。
- 1600×1000 Playwright 回归：设备状态列标题与“离线”红色文字卡片正常显示，控制台无错误。
- 设备管理表格进一步调整：连接地址拆为“地址”和“端口”；移除“启用”列；新增“最近在线”和“最近离线”。时间由采集引擎连接状态事件维护，接口字段为 `last_online_at`、`last_offline_at`。
- 真实接口回归返回在线设备时间戳，页面列顺序为：名称、协议、地址、端口、设备状态、最近在线、最近离线、操作。

## 2026-07-12｜数据采集分组与 REAL 解析调整

- 新增 `collection_groups` 表及幂等迁移；启动时同步历史 `group_name` 并删除 `collection_points.valid_min/valid_max`。
- 新增分组 GET/POST/PUT/DELETE API。删除分组前端二次提示，后端事务内逻辑删除该分组全部采集点；`default` 分组禁止删除。
- 数据采集页新增左侧分组栏、分组添加/改名/删除操作，新建采集点改为分组下拉选择。
- 采集列表将“地址 / 类型”拆成“地址”和“类型”；新建/编辑表单移除有效最小值和有效最大值。
- S7 REAL 解析统一四舍五入到小数点后最多 3 位；采集质量不再执行有效范围判断。
- 真实数据库验证：分组新增、改名、删除级联均通过；删除后采集点查询总数为 0；现场 REAL 值示例 `1411.719`。