[flashduty]

api-review 每日审计 · 2026-10-21（--mode generate --scope all --auto）

结论： 本轮无接口增删，修复 1 处「源码已改、文档未跟上」的 schema 漂移（safari 模块 /safari/artifact/sign）。

各模块 operation 变化

模块	added	updated	removed	说明
on-call	0	0	0	无漂移
monitors	0	0	0	无漂移
rum	0	0	0	无漂移
platform	0	0	0	无漂移
safari	0	1	0	SignedURLs 补 3 个字段（见下）

已注册公开 operation 数未变：on-call 202 / monitors 46 / rum 50 / platform 28 / safari 53 = 379（consolidated 参考副本同为 379）。无接口增删，故 docs.json 与 {en,zh}/openapi/api-catalog.mdx 未改动（逐 path 覆盖检查均为 none）。

修复内容：safari SignedURLs 缺 3 个 frame 字段

一手证据（fc-safari origin/main）：

• logic/artifact/file.go → SignedURLs 结构体含 frame_url、frame_base（omitempty）、frame_expires_in；由 signForFileWith() 在每次 /safari/artifact/sign 调用中无条件填充，FrameURL / FrameExpiresIn 无 omitempty，即必然出现在响应中。
• 引入提交：56a491d6（2026-10-17，feat(artifact): multi-file versions served through a sandboxed frame route），晚于 safari 规格最初写入，故文档一直缺这三个字段。
• 语义取自 logic/artifact/frame.go：frame_url = /safari/artifact/f/<token>/<escaped name>（token 为唯一凭据，有效期 12 小时）；frame_base = 版本目录地址，仅目录型（多文件）记录非空、单文件为空并被省略；frame_expires_in 恒为 43200。
• 因无 omitempty，frame_url / frame_expires_in 同时加进 SignedURLs.required；frame_base 保持可选。

改动文件（EN/ZH × split/consolidated 共 4 个）：属性就地插在 expires_in 之后（与 Go 结构体顺序一致，非重排），并同步扩展 /safari/artifact/sign 的 200 响应示例。

示例来源说明

本环境无法引用凭据类环境变量，因此调不通 dev API（api-dev.flashcat.cloud）抓真实响应。本次新增的 frame_url 与 frame_expires_in 两个示例值按 schema 与代码常量构造（token 沿用该 operation 既有示例的同一串，frame_expires_in 取代码常量 43200），非线上抓包；既有示例未改动。

本轮排除的候选（逐条附证，均判定为不应改）

1. monitors DSMongoDBConfig 缺 tls_cert / tls_key：Go 结构体确实通过内嵌 TLSClientConfig 携带这两个字段，但 model/datasource_diagnostic.go 的 validateDiagnosticTLS(..., mongo=true, ...) 里 if mongo && (TLSCert != "" || TLSKey != "") 直接返回错误 does not support client certificates。MongoDB 诊断配置不支持客户端证书，文档省略是正确的（Kafka 同类配置传 mongo=false，文档有这两个字段）。
2. safari A2AAgentItem.description：结构体注释写明「kept temporarily for pre-GA API clients … OpenAPI/SDK/CLI no longer expose description」，属刻意不公开。
3. on-call AssignedTo 的 layer_person_* / layer_webhook_*：来自 push event / servicenow 场景，push 路由不走公开面，属刻意不公开（与既有记录一致）。
4. on-call EscalateRuleItem.channel_name：仅 ListEscalateRuleBySchedule（注册表 Auth: jwt，非公开）填充；公开的 /channel/escalate/rule/info|list 不填。
5. on-call EscalateTarget.by / webhooks：Go 为 required_without=（互斥约束），非普通 required；文档已在 description 说明「Required unless webhooks is set」，无需改动。
6. fc-event a46ac82e（cmd/server/controller/incident/info.go）：iFilter 删除了 range_by / orderby / by_intersection，但它们原本就是 apidoc:"omit"，从未进入文档；start_time / end_time 的 binding:"required" 保持不变。
7. 窗口内其余提交：fc-pgy dff799e3（etc/kv.yml 白名单，kv 模块 hidden）、fc-rum f955e51 / e51144a（引擎解析逻辑与注释，无 wire 字段变化）、monit-webapi f09964d（check_nodata.end_mode 在未启用时补默认值，属业务分支默认、非 binding 约束）、monit-webapi 5750e0d / ab4d5dc、monit-edge e50d091（查询校验）、fc-datasource f2bc808（IM 插件重试）——均不触及公开 schema。

findings.unresolved（1 条，与前几轮一致，未写入任何 spec）

• POST /channel/incident/daily-counts（注册名 channel:read:incidentDailyCounts，Auth: "all"）：handler cmd/server/controller/channel/daily_incident_counts.go 仍只存在于 fc-event 的 origin/dev，不在 origin/main。注册表公开行 380 条 vs 文档 379 个 operation，差集仅此一条。需人判断是补 handler 还是把该行 Auth 改掉。

内部漂移（记录不改，本轮重算）

• DutyError.reason：consolidated 有、split 无，带 x-flashduty-preserve-absence: true 手改标记 → 不动。
• safari split 的 components.responses：BadRequest 示例带 safari 专有 skill_id、Forbidden 示例名 accessDenied、NotFound / ServiceUnavailable 仅 consolidated 有（split 未引用，无悬空 $ref）→ 判定为有意定制。
• safari split 的 components.securitySchemes.AutomationTriggerBearerAuth：两侧均无 operation 引用，属未引用定义 → 仅记录。
• 各 split 未定义 ServiceUnavailable（仅 monitors 引用它，monitors split 已定义）：其余 split 不引用，属正常裁剪。

校验清单

• 4 个改动文件 JSON 全部可解析；python3 scripts/lint_openapi.py → OK: 12 spec files, no violations。
• 最小 diff：4 files changed, 64 insertions(+)，0 deletions；patience 与默认算法结果一致（无重排 / 纯排序 diff）。
• 基线与落盘方式：全部从 git show HEAD:<path> 读取；逐个文件验证 json.dumps(..., indent=2) + "\n" 与原字节完全一致后才落盘，故 diff 只含本轮语义新增。
• EN/ZH 结构对齐：去掉本地化文本后 5 个模块 path/schema 结构差异均为 0。
• 悬空 $ref：5 个 split 与 consolidated 均无。
• nav 与目录覆盖：379 个 path 在 docs.json、en/zh api-catalog.mdx 中覆盖均为 none（无增删，故未改）。
• Unix 毫秒约定：全部 epoch 字段（77 个按毫秒、160 个按秒）描述均含 Unix/epoch/timestamp 或 milli 字样，无缺口。
• mint broken-links 未执行：本环境未安装 mint；本轮只改既有 path 的属性与示例，不新增链接。