03: 监测数据时间字段与异构设备来源

Type: grilling Status: resolved Labels: wayfinder:grilling Blocked by: 01

Question

锁定运行监测真实数据的统一时间契约：数据库字段 create_time，Java 实体属性 createTime，API 字段 createdAt，前端展示为“数据时间”。

Answer

一、`createdAt` 语义与取数（Q2/Q4/Q13/Q15）

createdAt＝记录创建时间（create_time），不是采样/上报时刻。
监测概览 /monitoring/overview：按聚合源各表真实记录 create_time 跨类型取 max；执行票逐表核验 create_time 存在性，某表无则如实标缺口并说明取数范围。不与 /overview/monitoring 的 metricFreshness 跨端点借用（筛选域不同）。

二、三端点字段落点（Q1/Q3/Q7/Q8/Q16）

/monitoring/overview：分区级 createdAt（信封，一个读数）。
/monitoring/distribution：信封级 createdAt + 台账逐对象级 createdAt（点位 marker 用 monitor_point.create_time、设备 marker 用 equipment_base.create_time）。后端需把 create_time 加进 Marker 响应（现状把 statusTime 丢弃在响应外）。
/monitoring/situation：信封级 createdAt + 异常设备逐对象级 createdAt（用其来源表 create_time）。趋势桶沿用既有窗口时间（bucketStart），不加 create_time。
map-snapshot 不加 createdAt（空间摘要，时间展示归面板/台账/详情）。

三、`sampledAt` 与 `createdAt` 分工（Q14）

两字段并存、语义分离：
- createdAt＝记录创建时间（新增，本次范围）；
- sampledAt＝设备采样/上报时刻（既有，设备级，复合语义：GAS report_time 优先、WATER timestamp_since 优先、create_time 兜底——保持现状不改）。
status_update_time（设备状态更新时刻）是第三套时间，设备级承载，不与 createdAt 混。

四、空态与不冒充（Q5）

无 create_time 或集合为空 → createdAt 显式返回 null/未知，前端显示“—”或“数据时间未知”；绝不用响应时间/envelope updatedAt/serverUpdatedAt 冒充。

五、前端措辞（Q6/Q17）

两套标签各归其位：
- “数据时间”＝createdAt（create_time 语义），用于监测概览、台账卡、设备详情的时间标签；
- “采样时间”＝sampledAt/installTime/status_update_time 按其语义，用于设备级指标/详情。
METRIC_FRESHNESS_GAP 措辞改为“数据时间＝记录创建时间，不是设备采样时刻”。
票 18 旧验收文字“最近采集时间”统一替换为“数据时间”（已按此交付，本票固化）。

六、契约新增清单（供后端执行票）

monitoring/overview：响应加分区级 createdAt（跨类型 max create_time）。
monitoring/distribution：响应加信封 createdAt + Marker（点位/设备）逐对象 createdAt。
monitoring/situation：响应加信封 createdAt + 异常设备逐对象 createdAt。
三端点 mapFilter/信封不新增其它时间字段；updatedAt（快照加载时刻）与 serverUpdatedAt（响应生成时刻）保留原语义。
archive 端点不加 createTime（现状有 installTime/productionDate，详情时间按“采样时间/安装时间”展示，不改契约）。

七、边界（Q12）

#03 只定数据时间语义与契约字段；刷新/重新取数时机归 #04（real 生命周期），#03 引用即可。
与 #02 无关（#02 管筛选与命中设备子集，不含时间字段）。

八、事实更正（后端只读核实，2026-09-28）

/overview/monitoring 的 metricFreshness 已从空适配器变为真实接线（BusinessCockpitOverviewMonitoringAdapter @Primary，从 gas/water 最新 create_time 算 metricUpdatedAt；无采样数据时 null，固定 CURRENT 无 STALE 逻辑）。
distribution 现状把快照 statusTime 丢弃在响应外（本次要带上 create_time）。
archive 有 installTime、无 createTime。

状态

已解决。 数据时间语义（createdAt＝create_time）、三端点字段落点、sampledAt/createdAt 分工、空态、前端“数据时间/采样时间”措辞与契约新增清单均已确认。后端契约改动清单待进入执行票；#04 引用本票的时间语义结论。