docs(api): daily audit 2026-10-08 — document the incident_list dashboard panel kind

[flashduty]

Daily API-reference audit — 2026-10-08

Scope: --mode generate --scope all --auto. Round drawn against flashduty-docs main = fa6e962a.

Window analysis

Window start = the 2026-10-06 round's analysis point (docs main merge of #1022 at 2026-10-06T08:37:15Z). Base-diffed each source repo from the last commit before that instant to origin/main, so commits merged in-window with older author dates are not missed:

repo	window base	origin/main	changed files
monit-webapi	41b236a	75bf6c5	8 (types/dashboard/* + runtime + tests + plan docs)
fc-pgy	ac1e2bc8	ac1e2bc8	none (the 知识 rename merged 2026-10-06 was already handled by #1022)
fc-event / fc-oncall / fc-rum / fc-statuspage / fc-datasource / go-pkg	—	unchanged	none

monit-webapi 75bf6c5 = merge of PR #135 feat/dashboard-incident-list-panel (commits b60e665, 8fb2241).

Operation changes per module

module	added	updated	removed
on-call	0	0	0
monitors	0	0	0
rum	0	0	0
platform	0	0	0
safari	0	0	0

No operation was added, removed, or re-versioned. The fc-pgy registry is unchanged at 366 auth: "all" rows, and the committed public path set is still 365; the only registered public path with no module handler remains /channel/incident/daily-counts (see unresolved, below). Because there is no page add/delete, docs.json and both {en,zh}/openapi/api-catalog.mdx are deliberately untouched (no nav or catalog edit is needed, and a no-op edit would only produce a large diff).

What changed

1. New dashboard panel visualization kind incident_list — monitors split + both consolidated files, EN and ZH.

Source of truth in monit-webapi main:

• types/dashboard/variants.go — VizConfig.UnmarshalJSON gains case "incident_list", decoding only vizCommon and rejecting unknown fields, so the wire shape is exactly {kind, options}.
• types/dashboard/contract.go — new QuerylessVizKind(kind) bool = text | incident_list.
• types/dashboard/validate.go — the panel switch groups case "text", "incident_list" (no queries, no datasource_ref) and runs datasourceRef validation only when !QuerylessVizKind(kind).
• logic/logic_dashboard_runtime.go — PanelRun / PanelPreview / resolvePanelQueryPlan now reject any queryless kind, with the message built from the kind.
• types/dashboard/contract_test.go#TestIncidentListVizConfigWireFormat — asserts {"kind":"incident_list"} and {"kind":"incident_list","options":{...}} decode, that markdown / value_fields / unknown fields are rejected, and that marshal emits {"kind":"incident_list","options":{...}}.
• misc/plan/dashboard/implementation/contracts.md — the intended enum is time_series | table | stat | bar | gauge | logs | text | incident_list, with incident_list carrying no typed fields (settings live in options, rows are filled by the client from the Flashduty incident API).

Spec edits, mirroring the existing per-kind style (DashboardTextViz minus markdown):

• new DashboardIncidentListViz (kind enum ["incident_list"], open options, required: [kind, options]), inserted directly after DashboardTextViz to match the Go variant order;
• DashboardVizConfig.oneOf gains the arm and discriminator.mapping gains "incident_list";
• DashboardOutlineVizConfig.kind enum + description gain the value;
• DashboardPanel.queries description now reads "text and incident_list accept none" (「text、incident_list 不允许查询」).

2. IncidentFeedItem.deleted_at millisecond wording — on-call split EN + consolidated EN (1 leaf each).

It read "Soft-delete timestamp (ms). Zero if not deleted.". The field is a millisecond epoch — fc-event structs/feed.go:208 (DeletedAt int64) is written via tsMilli at logic/feed/feed.go:85,141 — and generate.md Step 3 requires a millisecond field's description to contain milli so the go-flashduty SDK maps it to TimestampMilli rather than a bare int64. It was the only such outlier among the 214 epoch int64 fields in the corpus; its two siblings in the same schema (created_at, updated_at) already say "milliseconds". Now "Soft-delete timestamp in milliseconds. Zero if not deleted." The ZH side already said 毫秒 and is unchanged.

Verification performed

• Every written file parses: python3 -c "import json; json.load(open(path))" — monitors 41 paths / 185 schemas, on-call 202 / 410, consolidated 365 / 826.
• Leaf-level deep compare against git show HEAD:<path> (committed baseline only, never the worktree): exactly the intended leaves changed — 1 in on-call.openapi.en.json, 15 in each of the four dashboard-bearing files. Every hunk is listed above; none is a reorder.
• git diff --numstat equals git diff --numstat --minimal for all five files, i.e. no phantom delete/re-add.
• Byte round-trip: each file is reproduced exactly by json.dumps(obj, ensure_ascii=False, indent=2) + "\n" (trailing newline probed per file) — so no incidental formatting churn.
• EN/ZH structural parity with human-text keys masked (summary, description, title, x-mint, tags, name, x-enumDescriptions, examples): 0 differences across all five modules.
• Request/response example values byte-identical between EN and ZH: 0 differences across all five modules.
• Split vs consolidated agree for every shared schema, except the pre-existing items listed below (identical before and after this round).
• openapi.legacy.zh.json untouched.
• Nav + catalog reachability: every path of every module is present in docs.json and in both api-catalog.mdx (nothing new to add — no operation changed).

Constructed examples

No operation was added, so no new request/response example was required and no example was touched this round. All pre-existing examples are unchanged. This environment cannot read the credential env var, so the dev API (https://api-dev.flashcat.cloud) was not called and no example was re-captured.

Unresolved

• POST /channel/incident/daily-counts — registry row auth: "all", but no module claims the path and no handler exists in any backend repo. Fifth consecutive round unresolved; not emitted rather than fabricated.
• 9 /integration/* rows have no mapping.yaml prefix. They are already present in the committed specs; the skill's working copy of mapping.yaml is behind. Not a documentation gap.
• mint broken-links could not run (no node/npx in this environment); the skill's Step 5.5 reachability check was used instead and reports no gap.

Known pre-existing split/consolidated inconsistencies (recorded, not touched)

Identical at HEAD before this round, so not drift introduced here; both were already adjudicated in earlier rounds and remain human decisions:

• DutyError.reason — present in the consolidated specs plus the monitors/rum splits (carrying the deliberate x-flashduty-preserve-absence: true marker, 76 occurrences corpus-wide) but absent from the on-call/platform/safari splits. go-pkg main srv/error.go has only code/message, and monit-webapi's envelope error is {Code, Message} (the Reason field lives on the unrelated types/dashboard/runtime.go RuntimeError). Per the standing decision not to erase human-marked content, it is left as-is.
• on-call WorkItemItem / ListWorkItemRequest — the split and the consolidated side disagree on assignees / agent_session_id / agent_session_venue / assignee_type. fc-event main structs/work_item.go:47 has neither (AssigneeIDs []int64 json:"assignee_ids" only) — the supporting commit 7eff20f30 is on origin/feat/work-item-ai-sre and origin/dev. Neither side can be aligned from main, so no change was made.

Round note (known environment gaps)

The knowledge pack's runbooks/api-review-daily.md and runbooks/api-review-apply-patches.py are still absent, so the "apply baseline-preservation patches, then run scripts/generate_openapi.py" pipeline could not be used — this is the fifth round affected. .api-review/modules/*.json is gitignored and absent, so the generator cannot run. This round therefore used the established fallback: committed-baseline (git show HEAD:<path>) reconstruction plus a targeted, dry-run-first minimal-diff patch script, verified by the leaf-level deep compare above.