# 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 引用本票的时间语义结论。