长表、频率与时区

本页说明 series 长表的写法、默认清洗路径接受的时间戳格式、freq 频率字符串，以及时区如何换算，末尾附数据格式速查。raw 预设的要求更严格，见 raw 预设。

1. 长表记录

series 是一个扁平数组，每行一条观测：

[
{"unique_id": "grid_01", "ds": "2026-09-01T00:00:00Z", "y": 120.5},
{"unique_id": "grid_01", "ds": "2026-09-01T01:00:00Z", "y": null},
{"unique_id": "grid_02", "ds": "2026-09-01T00:00:00Z", "y": 88.0}
]

• 行的顺序不限，也不必按实体分组；默认清洗会按时间排序，并在报告中记录。
• 同一行上的其他数值字段是历史协变量，会被对齐并逐列报告；目前没有模型使用它们，见协变量支持现状。
• 预测结果按实体返回，时间戳一律为 UTC，以 Z 结尾。

2. 时间戳格式

default 与 strict 预设下，ds 可以是以下任一格式。同一实体内格式应保持一致；非 ISO 格式会在清洗报告中记为 timestamp_format 问题。

D/M/YYYY 与 M/D/YYYY 只有在数据能证明日月顺序时才会被接受（例如出现 13/09/2026）；否则返回 AMBIGUOUS_DATE_FORMAT，这时请传 options.ds_format（dmy 或 mdy），或直接改用 ISO 8601。

3. 频率字符串

freq 是可选的。省略时服务会从数据推断，并在清洗报告的 series[].freq 中给出推断结果与置信度；推断失败返回 FREQ_INFERENCE_FAILED，多个实体推断出不同频率或存在多个候选时返回 FREQ_AMBIGUOUS。数据不规则时，建议总是显式传入。

• 除 B 外，所有写法都可以带整数倍数前缀，例如 15min、2h、3MS、3M@15。
• 大小写敏感：M 是月末，m 是分钟。
• freq 字段会原样回显你传入的写法；省略时回显推断出的规范写法，例如 min、h、d、w、MS、QE、M@15，带倍数时如 15min。
• 月、季、年等日历频率按本地时钟推进（时区见下一节），会自动处理大小月、闰年与夏令时。
• raw 预设只接受固定步长的频率（秒、分钟、小时、天、周），日历频率返回 RAW_INPUT_INVALID。

4. 时区处理

• 带偏移的时间戳（Z 或 ±HH:MM）按自身偏移解析，options.timezone 不会覆盖它。
• 不带偏移的时间戳按 options.timezone（IANA 时区名，例如 Asia/Shanghai）解析；未提供时按 UTC 解析，并在报告中记一条 naive_timestamps_assumed_utc（info 级别）。
• 无效的时区名返回 VALIDATION_ERROR。
• 输出：model_input 与 forecast 中的时间戳一律换算为 UTC，客户端需要时再换回本地时间。

清洗报告的 series[].timezone 记录每个实体实际使用的时区：

下例把北京时间的月度数据按月初频率处理。每个月初是本地的 00:00，换算为 UTC 后落在前一天 16:00：

// 请求
{"series": [{"unique_id": "sales", "ds": "2025-01-01", "y": 101}, ...],
"h": 2, "freq": "MS", "options": {"timezone": "Asia/Shanghai"}}

// model_input[0].ds 为 "2024-12-31T16:00:00Z"
// forecast 的两个时间戳为 "2026-08-31T16:00:00Z" 与 "2026-09-30T16:00:00Z"
// cleaning_report.series[0].timezone
{"used": "Asia/Shanghai", "source": "option", "naive_rows": 20,
"explicit_rows": 0, "explicit_offsets": []}

5. 数据格式速查

/v1/forecast 请求中与数据格式相关的字段一览。完整字段、默认值与校验顺序见 POST /v1/forecast。