[flashduty]

api-review 2026-10-22 (generate / scope all / auto)

基线：flashduty-docs main @ d53698a9（2026-10-20T14:26:40Z）。实现仓一律读 origin/main。

本轮 operation 变化

模块	added	updated	removed
on-call	4	0	0
monitors	0	0	0
rum	0	0	0
platform	0	0	0
safari	0	0	0

文档 operation 总数 379 → 383（consolidated 参考副本同）。

新增的 4 个公开接口（on-call）

Operation ID	Method + Path	来源
alert-read-email-preview	POST /alert/email/preview	fc-pgy 825186b7（2026-10-20T20:25:33-07:00）注册；fc-event cmd/server/controller/alert/email_preview.go，路由 routes.go:198
alert-read-pipeline-preview	POST /alert/pipeline/preview	fc-pgy 9f1b3d2d（2026-10-20T05:27:53-07:00）注册；fc-event cmd/server/controller/alert_pipeline/preview.go，路由 routes.go:439
enrichment-read-preview	POST /enrichment/preview	同上注册提交；fc-event cmd/server/controller/enrich/preview.go，路由 routes.go:411
enrichment-sample-read-list	POST /enrichment/sample/list	同上注册提交；fc-event cmd/server/controller/enrich/preview.go（SampleList），路由 routes.go:412

这四个 handler 由 fc-event PR #3346 的 merge fa08c381（2026-10-22T01:10:46-07:00）带上 main，注册行 Auth: "all"、非 /event/push/，属公开面。

同步补齐的 surface（只改 spec 不改这两处，新接口不会出现在文档站）：

• docs.json：EN / ZH 两个 On-call 分组各加 4 条 page —— Alerts（/alert/pipeline/preview）、Integrations（/alert/email/preview）、Alert enrichment（/enrichment/preview、/enrichment/sample/list）。
• en|zh/openapi/api-catalog.mdx：各加 4 行，On-call 计数 202 → 206，总计 379 → 383。

新增 19 个 schema：AlertEvent、EnrichStep、EnrichmentSample、EnrichmentPreviewEvent、PipelineStep、AlertPipelinePreviewEvent、AlertEmailPreviewSettings、AlertEmailRule、AlertEmailPreviewEmail、AlertEmailPreviewEvent、AlertEmailPreviewParsed 以及 8 个 Request/Response 包装。复用既有 EnrichRule、AlertPipeline、FilterCondition、AlertImage、SuccessEnvelope。

约束来源（仅 binding 标签与显式 handler 代码）：

• integration_id 的 binding:"gt=0" → minimum: 1；
• rules 的 binding:"lte=50" → maxItems: 50；
• AlertEvent.event_status 的 binding:"oneof=Critical Warning Info Ok" 与 SecondValidate() 的状态校验 → 该字段进 required；
• AlertEmailRule 的 filters 进 required，依据 PlugAlertEmail.Validate() 对 rule.Filters.Validate() 的调用（为 nil 直接报错）；
• 邮箱规则的 type / extract_from / mode / default 枚举全部来自 fc-datasource 的常量与 Validate() 分支。

两处「源码已改、文档未跟上」的字段漂移（同一提交内一并修复）

1. fc-datasource PR docs(on-call): add Monitive alert integration #659（merge 6db0165，2026-10-22T00:59:15-07:00）：structs/data_source.go 的 DataSourceItem 新增 last_source_time，cmd/datasource/controller/integration_contract.go 的 publicIntegrationDetail 同样新增，写入点 cmd/datasource/controller/info.go:343 与 :645。已在 IntegrationItem、IntegrationDetail 的 last_time 之后就地插入。语义取自 dsEventTimes 注释：上游最后一次送来事件的时间（含随后被丢弃的），Unix 秒。
2. fc-oncall PR docs(rum): add React Native SDK documentation #304（merge 7f256fb，2026-10-22T00:59:23-07:00）：models/schedule.go 的 ImNotifySettings 新增 disable_at（*bool）与 user_schema_id，校验在 models/notify.go。已在 ScheduleImNotifySettings 的 alias 之后就位插入（顺序与 Go 结构体一致），两者都带 omitempty，故不进 required。

窗口扫描的排除项（逐条核对过，不改文档）

• fc-oncall 9476701 / 4f6d6a3：mapping/resolve-users 的 channel 枚举扩到 oneof=feishu wecom zoom，但该路由挂在 localG（/-/ 内部组），非公开面；mapping_schema.go 的改动只是引用列表，无 json/binding 变化。
• fc-event f2c459f0 / a3d4d3b3：oncall_reference.go 与 user_mapping.go 的新结构体只服务于内部路由。
• fc-rum eb72ac3：删除的 ErrorStats（error_count / session_count / is_crash）是内部聚合结构，不在响应；df7a938 / 3398292 只加 Doris 列类型标签，json 标签未变。
• fc-safari e47b0a9f / 4ebb98db / 6f34135a：im_settings、chat_settings 相关字段都在 runtime / 内置工具结构体上，不属于 /safari/* 公开响应。
• monit-webapi（ab4d5dc、f09964d、5750e0d）与 monit-edge（e50d091、ed5e64b）：只改查询校验与 HTTP/2 探活，无字段变化。
• fc-datasource 9c4a482（webhook endpoint / 自定义 body 脱敏）是读取逻辑，无 schema 变化。

unresolved（1 条，沿用上一轮结论）

• POST /channel/incident/daily-counts（channel:read:incidentDailyCounts，Auth: "all"）：注册表有行，但 fc-event origin/main 上既没有 handler 也没有路由，实现只在 origin/dev。按 skill 记 findings.unresolved，不写入任何 spec，由人判断是补 handler 还是改注册行的 Auth。

注册表公开行 384 条 vs 文档 383 个 operation，差集只有这一条。

示例说明（必读）

每轮每个 operation 的 requestBody 与 responses.200 示例：本环境不能直接引用凭据环境变量（也无法调用 dev 环境 API），因此 本轮 4 个新增 operation 的示例全部按 schema 与 handler 行为构造，值用真实风格的集成 ID（6113996590131）、ObjectID/哈希、真实标签集合与时间戳，未使用 "string" 占位符。构造依据：preprocess.EmailToEvent / judgeEmail（key_source、key_fallback、alert_key = md5(key_source)、alwaysTrigger 的随机键）、preprocess.PreviewEvent（事件时间由服务端盖章）、enrich.RecordSourceEvent（样本保留 20 条 / 7 天 / 描述 8 KiB / 事件 64 KiB）。

内部漂移：记录不改

• consolidated 的 DutyError.reason 带 x-flashduty-preserve-absence: true，是既有的手改标记（split 侧刻意没有该字段），本轮不动。
• split 与 consolidated 的其余共享 schema（on-call 429 个、monitors 190、rum 153、platform 59、safari 86）深比较（忽略 key 序）后无差异；operation 级 0 差异。
• 四个模块的 EN/ZH 结构 0 差异（仅 ErrorCode.x-enumDescriptions 为翻译文本，属设计）。

diff 纪律与验证

• 4 个 spec 文件全部从 git show HEAD:<path> 的 committed 基线重建，新 path / schema 追加、修补字段就位插入；git diff --diff-algorithm=patience 显示每个 spec 文件均为纯新增（+1215 / −0），0 删除行、无 key 重排。review 时请带 patience：默认 Myers 会把整块新增错配成大量删除（on-call.openapi.* 显示 2775 行变更）。
• docs.json 只按需改了 8 条 page（无页面增删时不动的规则本轮正好被新增接口触发），无导航顺序规范化。
• python3 scripts/lint_openapi.py → OK: 12 spec files, no violations。
• 4 个输出文件 python3 -c "import json; json.load(open(path))" 全部通过；docs.json 同样通过。
• 全路径覆盖检查：5 个模块的 spec path 在 docs.json、EN 与 ZH api-catalog.mdx 中缺失数均为 none。
• 本环境未安装 mint，mint broken-links 未跑；本轮只新增既有分组下的路径，未改动任何被引用的页面 slug。

---

追加：CI 的第三个门面（docs.json 的 API path redirects）

首轮 CI 的 lint job 在 python3 scripts/api_path_redirects.py --check 上失败。这是本轮此前漏掉的一步：
docs.json 里还有一组「裸 API 路径 → zh 参考页」的 redirect，新增 operation 后必须重新生成，
否则爬虫解析到页面里内嵌的裸路径会 404。已补：

• 提交 91d3b251：为 4 个新 path 生成 redirect（/alert/email/preview、/alert/pipeline/preview、/enrichment/preview、/enrichment/sample/list）。

追加：origin/main 自身在该检查上是红的（与本轮改动无关）

第二次 CI 仍失败，查下来 origin/main（9b6eeba3）本身就跑不过 api_path_redirects.py --check：
doc-review 的两次合并把两条 RUM 纠错 redirect（/zh|/en/rum/error-tracking/erro-reporting/web）
追加到了托管列表末尾，而脚本按 source 排序，于是 --check 判定 stale。复现方式（与本 PR 无关）：

git worktree add /tmp/wt-main origin/main
cd /tmp/wt-main && python3 scripts/api_path_redirects.py --check   # exit 1
python3 scripts/api_path_redirects.py                              # 8 插入 / 8 删除，纯重排

处理：把 origin/main 合入本分支（53ba4cf6），再用仓内脚本重排（d23d4198，8 插入 / 8 删除，无语义变化，
diff 里只有那两条 RUM redirect 的位置）。这条不属于 api-review 的改动范围，如果维护人希望它单独成一个 PR，
可以把 d23d4198 单独 cherry-pick 到新分支，本 PR 只保留 42e34f22 + 91d3b251。

CI 现状：lint pass（run 39749480241），Mintlify Deployment 在 PR 上为 skipping。

追加后的 diff 口径（对 origin/main）

git diff --diff-algorithm=patience origin/main HEAD：4 个 spec 文件各 +1215 / −0；
docs.json +34 / −10；两份 api-catalog 各 +6 / −2；合计 +4906 / −14。
默认 Myers 仍会把整块新增显示成大量删除（+6466 / −1574），review 时请带 --diff-algorithm=patience。