[flashduty]

api-review 每日审计（--mode generate --scope all --auto）

基线：flashduty-docs main cc51de68（2026-10-19 20:17 +08），实现仓均取 origin/main
（fc-pgy d416a2c1、fc-event c16eade92、fc-oncall c76999b、fc-rum c6f3e84、fc-statuspage edf9dad、
monit-webapi d287bf1、fc-datasource 55a1320、go-pkg 5028f42、fc-safari 077d7f1e、monit-edge fb7e4cb）。

本轮结论

• 接口增删：0（added 0 / removed 0，五个模块全部）。注册表 auth=all 且非 /event/push/ 的公开行 380 条，
  文档 operation 379 个，差集仍只有 1 条已知 unresolved（见下）。无接口增删，故未改 docs.json 与
  {en,zh}/openapi/api-catalog.mdx（按铁律 3）。
• 源码已改、文档未跟上：1 处（RUM），已在本 PR 修复。

各模块 operation 变化

模块	added	updated	removed
on-call	0	0	0
monitors	0	0	0
rum	0	1（schema RumFieldItem + /rum/field/list 响应示例）	0
platform	0	0	0
safari	0	0	0

本次修复（唯一一处，diff +24 / -0，4 个文件）

RumFieldItem.high_cardinality（boolean）缺失：

• 源码：fc-rum types/field.go 的 FieldItem.HighCardinality bool \json:"high_cardinality"`， 由 logic/transfer.go#FieldTableToItem 赋值，/rum/field/list 的 handler （cmd/server/controller/field/field.go#List）把它作为 items返回；该字段**无**apidoc:"omit"， 故属公开契约。引入提交 91194b9（2026-10-15，feat(dashboard): restrict grouping by high-cardinality fields`），
  已在主干，属窗口外历史遗留漂移（本轮窗口起点为 docs main HEAD 的 2026-10-19 12:17Z，故按「读源码定方向」单独修）。
• 文档：api-reference/rum.openapi.{en,zh}.json 与 api-reference/openapi.{en,zh}.json 的
  components.schemas.RumFieldItem 增加该属性，required 追加 high_cardinality（Go 中无 omitempty，
  故与非指针标量一致列入 required），并同步 /rum/field/list 的 200 响应示例。
• 键序：属性按该 schema 既有字母序插在 group 与 is_facet 之间；required 按 Go 结构体顺序插在
  is_facet 之后。落盘用「committed 内容 → json.loads → 插入 → json.dumps(indent=2)」，
  已逐文件验证无损往返（四个文件均为 ensure_ascii=False, indent=2 + 结尾换行），diff 只含上述新增。

本轮核查过、判定不改的项（每轮重算，不照抄上一轮）

1. POST /channel/incident/daily-counts（findings.unresolved，1 条）：注册表 auth=all 有行，
   但 fc-event 主干仍无 handler 与路由（cmd/server/controller/channel/daily_incident_counts.go 只在
   origin/dev），按 skill 记 unresolved、不写任何 spec。
2. fc-event e76de3a97（窗口内）：iFilter 删除 range_by / orderby / by_intersection，
   三者原本就带 apidoc:"omit"，文档 /incident/list 请求体从未包含它们，无需改。
3. fc-event 其他窗口内提交：channel/escalate/inhibit/silence/subscribe 等 access-hardening 只加权限过滤逻辑，
   无 schema 字段变化；structs/webhook.go 的新增 integration_id/data_source_id 是函数内匿名结构体，
   structs/alert.go 的 event_id 属 /event/push/ 入站面（非公开），均不动。
4. fc-statuspage c185199：account_domain.go 的 account_id/domain/in_use/dns01
   对应路由在注册表是 jwt/none，非公开面。
5. fc-datasource 907ad6d/c1561f0：im_setup.go（step/setup_checks/integration_id required）与
   plug_teams.go（user_id required）对应路由为 jwt（如 /datasource/im/setup/confirm），非公开面。
6. fc-rum 868f512（rc_wait）：只进 model/session 与 datadog 入站结构，公开的 /rum/session-replay/*
   用的是回放表；types/field.go 除 high_cardinality 外只是 gofmt 对齐。
7. monit-webapi c273b73：model/edge_instance.go 的 heartbeat_age_seconds/online，
   /monit/edge/* 不在公开注册表；model/active_alerts.go 的改动是 json:"-"。
8. fc-oncall 8fa80ba：account_id 只加在 callee/pgy.go 的 pgy 客户端类型上。
9. fc-safari 窗口内提交：logic/environment/redis_bus.go 的 A2AFramePayload（task_id/source_instance_id/
   replay_count）是跨实例 Redis 中继帧，不在公开 spec；logic/tool/builtin/*.go 的 jsonschema: 文本是
   Agent 工具入参 schema，不进 OpenAPI。
10. 内部漂移 A —— DutyError：consolidated 有 reason（x-flashduty-preserve-absence: true 的手改标记），
    split 没有；按既定约定不动，仅记录。
11. 内部漂移 B —— safari 的 components.responses：BadRequest / Forbidden 示例与其他 4 个 split 不一致
    （含 safari 专有字段），判定为有意定制，不动。
12. 双语契约偏差 —— 示例取值本地化：monitors 的 /monit/rule/move、safari 的
    /safari/artifact/gallery/{list,get,update} 在 ZH 规格里用了中文示例值（如「移动成功」「支付接口延迟复盘报告」），
    与 skill「双语示例取值必须一致」相悖。这批中文示例由 4eaf43df（2026-10-17，docs(api-reference): align every operation with server behavior）一次性写入，属近期有意为之；改回去要动 4 个 operation 的用户可见示例，
    方向需人定，故本轮只记录不改（默认以 split 为准的原则在此不适用——两侧都是「有意为之」）。
13. ScheduleNotify.advance_in_time 描述不含 Unix/epoch：该字段是「提前多少秒」的时长而非时间点，
    按 skill 的判据本就应该保持 integer，不是缺口（其余 0 处 Unix/epoch 缺口）。

一致性校验结果

• EN/ZH 结构一致性（本地化文本除外）：5 个模块 params / schemas / required / enum / type 全一致；
  唯一差异是 ErrorCode.x-enumDescriptions（人类文本，应当本地化）与上述第 12 条示例取值。
• $ref 悬空：0。
• Unix/epoch 毫秒字段描述：0 缺口（advance_in_time 见上，属时长）。
• docs.json 导航与两份 api-catalog.mdx 覆盖：5 个模块的 path 全部命中，none 缺失。
• operation 数：on-call 202 / monitors 46 / rum 50 / platform 28 / safari 53，consolidated 379（EN=ZH）。

构造示例说明

本环境无法调用 api-dev.flashcat.cloud（拿不到 FLASHDUTY_APP_KEY），因此本轮没有回填真实响应示例；
所有示例均按 schema 构造。本轮新增内容只有 schema 属性 high_cardinality 与其在
/rum/field/list 既有示例里的一个布尔值，未构造新的业务取值。

未覆盖项 / 限制

• 本环境未安装 mint，mint broken-links 未运行；本轮只改既有 schema 属性、无新增路径，不可能产生新链接。
• 窗口法（实现仓 origin/main 中提交时间晚于 docs main HEAD 的提交 + 其与第一父的 diff）只覆盖窗口内变化；
  本轮据 21 天 json:/binding: 增量的补充扫描，找出第 1 条那处窗口外遗留。更早的历史漂移仍需
  全量源码 vs 文档对照，未在本轮展开。
• skill mapping.yaml 把 on-call/calendar 的 provider 指为 event（实际 handler 自 2023 年起在 fc-pgy），
  属已知配置缺陷，按既定政策只报告不改 skill 本体。