From d3446290440fd442e534809f9a3f41f87d3e8f00 Mon Sep 17 00:00:00 2001 From: Flashduty AI-SRE Date: Thu, 8 Oct 2026 08:05:43 +0000 Subject: [PATCH] =?UTF-8?q?docs(api):=20daily=20audit=202026-10-08=20?= =?UTF-8?q?=E2=80=94=20document=20the=20incident=5Flist=20dashboard=20pane?= =?UTF-8?q?l=20kind?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Regenerated the public API specs for the 2026-10-07 → 2026-10-08 window. New public surface (source: monit-webapi origin/main 75bf6c5, PR #135, "feat(dashboard): 支持告警汇总面板类型 incident_list", commits b60e665 + 8fb2241): - adds the `incident_list` dashboard panel visualization kind. It is queryless (QuerylessVizKind() = text | incident_list in types/dashboard/contract.go, and the panel switch in validate.go groups it with `text`), so it carries exactly `{kind, options}` — the wire format asserted by types/dashboard/contract_test.go#TestIncidentListVizConfigWireFormat. Documented as `DashboardIncidentListViz`, wired into the `DashboardVizConfig` oneOf + discriminator, added to the `DashboardOutlineVizConfig.kind` enum, and noted in the `DashboardPanel.queries` description. Contract fix: - `IncidentFeedItem.deleted_at` said "(ms)" instead of "milliseconds". The field is a millisecond epoch (fc-event structs/feed.go:208, written via tsMilli at logic/feed/feed.go:85,141), and generate.md Step 3 requires the description to contain `milli` for the go-flashduty SDK to map it to TimestampMilli. It was the only such outlier among the 214 epoch int64 fields in the corpus; its two siblings in the same schema already say "milliseconds". No operations were added, removed, or re-versioned this round: the fc-pgy registry is unchanged at 366 `auth: "all"` rows and the committed path set is still 365, so `docs.json` and both `api-catalog.mdx` files are deliberately untouched. Files: 5 (+126/-18; identical counts under `git diff --minimal`, i.e. no reordering). --- api-reference/monitors.openapi.en.json | 35 +++++++++++++++++++++--- api-reference/monitors.openapi.zh.json | 35 +++++++++++++++++++++--- api-reference/on-call.openapi.en.json | 2 +- api-reference/openapi.en.json | 37 ++++++++++++++++++++++---- api-reference/openapi.zh.json | 35 +++++++++++++++++++++--- 5 files changed, 126 insertions(+), 18 deletions(-) diff --git a/api-reference/monitors.openapi.en.json b/api-reference/monitors.openapi.en.json index 55f3d01c..0dfd3e37 100644 --- a/api-reference/monitors.openapi.en.json +++ b/api-reference/monitors.openapi.en.json @@ -9351,7 +9351,7 @@ "$ref": "#/components/schemas/DashboardPanelQuery" }, "maxItems": 26, - "description": "Queries in the panel. `time_series` accepts 1–26, `text` accepts none, every other kind accepts exactly one." + "description": "Queries in the panel. `time_series` accepts 1–26, `text` and `incident_list` accept none, every other kind accepts exactly one." }, "viz_config": { "$ref": "#/components/schemas/DashboardVizConfig" @@ -9876,6 +9876,9 @@ }, { "$ref": "#/components/schemas/DashboardTextViz" + }, + { + "$ref": "#/components/schemas/DashboardIncidentListViz" } ], "discriminator": { @@ -9887,7 +9890,8 @@ "bar": "#/components/schemas/DashboardBarViz", "gauge": "#/components/schemas/DashboardGaugeViz", "logs": "#/components/schemas/DashboardLogsViz", - "text": "#/components/schemas/DashboardTextViz" + "text": "#/components/schemas/DashboardTextViz", + "incident_list": "#/components/schemas/DashboardIncidentListViz" } } }, @@ -10259,6 +10263,28 @@ "markdown" ] }, + "DashboardIncidentListViz": { + "type": "object", + "description": "Incident-list panel. The rows are filled by the client from the Flashduty incident API, so the panel runs no queries and needs no datasource.", + "properties": { + "kind": { + "type": "string", + "enum": [ + "incident_list" + ], + "description": "Visualization kind discriminator; always `incident_list`." + }, + "options": { + "type": "object", + "additionalProperties": true, + "description": "Open options object for the chosen visualization kind; the only part of the definition that round-trips losslessly. Missing or null normalizes to `{}`." + } + }, + "required": [ + "kind", + "options" + ] + }, "DashboardThreshold": { "type": "object", "description": "Colour threshold for a numeric value. At least one of `warning`/`critical` is required, and with both set the pair must be ordered according to `mode`.", @@ -11082,9 +11108,10 @@ "bar", "gauge", "logs", - "text" + "text", + "incident_list" ], - "description": "Visualization kind: `time_series` = time series; `table` = table; `stat` = single value; `bar` = bar chart; `gauge` = gauge; `logs` = log stream; `text` = Markdown text." + "description": "Visualization kind: `time_series` = time series; `table` = table; `stat` = single value; `bar` = bar chart; `gauge` = gauge; `logs` = log stream; `text` = Markdown text; `incident_list` = incident list." } }, "required": [ diff --git a/api-reference/monitors.openapi.zh.json b/api-reference/monitors.openapi.zh.json index cf6283df..e0b20df8 100644 --- a/api-reference/monitors.openapi.zh.json +++ b/api-reference/monitors.openapi.zh.json @@ -9351,7 +9351,7 @@ "$ref": "#/components/schemas/DashboardPanelQuery" }, "maxItems": 26, - "description": "面板内的查询。`time_series` 允许 1～26 条，`text` 不允许查询，其余类型必须恰好 1 条。" + "description": "面板内的查询。`time_series` 允许 1～26 条，`text`、`incident_list` 不允许查询，其余类型必须恰好 1 条。" }, "viz_config": { "$ref": "#/components/schemas/DashboardVizConfig" @@ -9876,6 +9876,9 @@ }, { "$ref": "#/components/schemas/DashboardTextViz" + }, + { + "$ref": "#/components/schemas/DashboardIncidentListViz" } ], "discriminator": { @@ -9887,7 +9890,8 @@ "bar": "#/components/schemas/DashboardBarViz", "gauge": "#/components/schemas/DashboardGaugeViz", "logs": "#/components/schemas/DashboardLogsViz", - "text": "#/components/schemas/DashboardTextViz" + "text": "#/components/schemas/DashboardTextViz", + "incident_list": "#/components/schemas/DashboardIncidentListViz" } } }, @@ -10259,6 +10263,28 @@ "markdown" ] }, + "DashboardIncidentListViz": { + "type": "object", + "description": "故障列表面板。数据由前端从 Flashduty 故障接口获取，因此面板不运行查询、也不需要数据源。", + "properties": { + "kind": { + "type": "string", + "enum": [ + "incident_list" + ], + "description": "可视化类型判别字段，固定为 `incident_list`。" + }, + "options": { + "type": "object", + "additionalProperties": true, + "description": "所选可视化类型的开放配置对象；也是定义中唯一无损 round-trip 的部分。缺失或 null 时规范化为 `{}`。" + } + }, + "required": [ + "kind", + "options" + ] + }, "DashboardThreshold": { "type": "object", "description": "数值的颜色阈值。`warning`/`critical` 至少设置一个；两者都设置时需按 `mode` 满足大小关系。", @@ -11082,9 +11108,10 @@ "bar", "gauge", "logs", - "text" + "text", + "incident_list" ], - "description": "可视化类型：`time_series` = 时序图；`table` = 表格；`stat` = 单值；`bar` = 柱状图；`gauge` = 仪表盘；`logs` = 日志流；`text` = Markdown 文本。" + "description": "可视化类型：`time_series` = 时序图；`table` = 表格；`stat` = 单值；`bar` = 柱状图；`gauge` = 仪表盘；`logs` = 日志流；`text` = Markdown 文本；`incident_list` = 故障列表。" } }, "required": [ diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index a886a8ca..312b543e 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -24010,7 +24010,7 @@ "deleted_at": { "type": "integer", "format": "int64", - "description": "Soft-delete timestamp (ms). Zero if not deleted." + "description": "Soft-delete timestamp in milliseconds. Zero if not deleted." }, "created_at": { "type": "integer", diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index d7d57a3c..d4c919c3 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -11387,7 +11387,7 @@ "type": "integer" }, "deleted_at": { - "description": "Soft-delete timestamp (ms). Zero if not deleted.", + "description": "Soft-delete timestamp in milliseconds. Zero if not deleted.", "format": "int64", "type": "integer" }, @@ -29665,7 +29665,7 @@ "$ref": "#/components/schemas/DashboardPanelQuery" }, "maxItems": 26, - "description": "Queries in the panel. `time_series` accepts 1–26, `text` accepts none, every other kind accepts exactly one." + "description": "Queries in the panel. `time_series` accepts 1–26, `text` and `incident_list` accept none, every other kind accepts exactly one." }, "viz_config": { "$ref": "#/components/schemas/DashboardVizConfig" @@ -30190,6 +30190,9 @@ }, { "$ref": "#/components/schemas/DashboardTextViz" + }, + { + "$ref": "#/components/schemas/DashboardIncidentListViz" } ], "discriminator": { @@ -30201,7 +30204,8 @@ "bar": "#/components/schemas/DashboardBarViz", "gauge": "#/components/schemas/DashboardGaugeViz", "logs": "#/components/schemas/DashboardLogsViz", - "text": "#/components/schemas/DashboardTextViz" + "text": "#/components/schemas/DashboardTextViz", + "incident_list": "#/components/schemas/DashboardIncidentListViz" } } }, @@ -30573,6 +30577,28 @@ "markdown" ] }, + "DashboardIncidentListViz": { + "type": "object", + "description": "Incident-list panel. The rows are filled by the client from the Flashduty incident API, so the panel runs no queries and needs no datasource.", + "properties": { + "kind": { + "type": "string", + "enum": [ + "incident_list" + ], + "description": "Visualization kind discriminator; always `incident_list`." + }, + "options": { + "type": "object", + "additionalProperties": true, + "description": "Open options object for the chosen visualization kind; the only part of the definition that round-trips losslessly. Missing or null normalizes to `{}`." + } + }, + "required": [ + "kind", + "options" + ] + }, "DashboardThreshold": { "type": "object", "description": "Colour threshold for a numeric value. At least one of `warning`/`critical` is required, and with both set the pair must be ordered according to `mode`.", @@ -31396,9 +31422,10 @@ "bar", "gauge", "logs", - "text" + "text", + "incident_list" ], - "description": "Visualization kind: `time_series` = time series; `table` = table; `stat` = single value; `bar` = bar chart; `gauge` = gauge; `logs` = log stream; `text` = Markdown text." + "description": "Visualization kind: `time_series` = time series; `table` = table; `stat` = single value; `bar` = bar chart; `gauge` = gauge; `logs` = log stream; `text` = Markdown text; `incident_list` = incident list." } }, "required": [ diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 576a5095..75f58d1e 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -29665,7 +29665,7 @@ "$ref": "#/components/schemas/DashboardPanelQuery" }, "maxItems": 26, - "description": "面板内的查询。`time_series` 允许 1～26 条，`text` 不允许查询，其余类型必须恰好 1 条。" + "description": "面板内的查询。`time_series` 允许 1～26 条，`text`、`incident_list` 不允许查询，其余类型必须恰好 1 条。" }, "viz_config": { "$ref": "#/components/schemas/DashboardVizConfig" @@ -30190,6 +30190,9 @@ }, { "$ref": "#/components/schemas/DashboardTextViz" + }, + { + "$ref": "#/components/schemas/DashboardIncidentListViz" } ], "discriminator": { @@ -30201,7 +30204,8 @@ "bar": "#/components/schemas/DashboardBarViz", "gauge": "#/components/schemas/DashboardGaugeViz", "logs": "#/components/schemas/DashboardLogsViz", - "text": "#/components/schemas/DashboardTextViz" + "text": "#/components/schemas/DashboardTextViz", + "incident_list": "#/components/schemas/DashboardIncidentListViz" } } }, @@ -30573,6 +30577,28 @@ "markdown" ] }, + "DashboardIncidentListViz": { + "type": "object", + "description": "故障列表面板。数据由前端从 Flashduty 故障接口获取，因此面板不运行查询、也不需要数据源。", + "properties": { + "kind": { + "type": "string", + "enum": [ + "incident_list" + ], + "description": "可视化类型判别字段，固定为 `incident_list`。" + }, + "options": { + "type": "object", + "additionalProperties": true, + "description": "所选可视化类型的开放配置对象；也是定义中唯一无损 round-trip 的部分。缺失或 null 时规范化为 `{}`。" + } + }, + "required": [ + "kind", + "options" + ] + }, "DashboardThreshold": { "type": "object", "description": "数值的颜色阈值。`warning`/`critical` 至少设置一个；两者都设置时需按 `mode` 满足大小关系。", @@ -31396,9 +31422,10 @@ "bar", "gauge", "logs", - "text" + "text", + "incident_list" ], - "description": "可视化类型：`time_series` = 时序图；`table` = 表格；`stat` = 单值；`bar` = 柱状图；`gauge` = 仪表盘；`logs` = 日志流；`text` = Markdown 文本。" + "description": "可视化类型：`time_series` = 时序图；`table` = 表格；`stat` = 单值；`bar` = 柱状图；`gauge` = 仪表盘；`logs` = 日志流；`text` = Markdown 文本；`incident_list` = 故障列表。" } }, "required": [