docs(api): daily audit 2026-09-25 — document the new /integration API family

[flashduty]

api-review daily audit — 2026-09-25

--mode generate --scope all --auto. Registry baseline: fc-pgy/logic/api/api_test.go @ 6e4013f0 (default branch main, fetched 2026-09-25T08:06Z).

Operations changed

Module	Added	Updated	Removed
on-call	9	0	0
monitors / rum / safari / platform	0	0	0

Added — a new public family, POST /integration/* (9 operations, 13 new schemas).
These rows landed in the fc-pgy registry after the last regeneration, via 3caa6d8d ("Merge pull request #1025 from flashcatcloud/feat/integration-api-sync-20260915", merged 2026-09-22 15:16 +0800), and the handlers are live on fc-datasource main (cmd/datasource/routes.go:70 integrationG := restSrv.Engine.Group("/integration/", BackAuth())):

• POST /integration/type/list → integration-api-read-type-list
• POST /integration/list → integration-api-read-list
• POST /integration/info → integration-api-read-info
• POST /integration/create → integration-api-write-create
• POST /integration/update → integration-api-write-update
• POST /integration/delete → integration-api-write-delete
• POST /integration/enable → integration-api-write-enable
• POST /integration/disable → integration-api-write-disable
• POST /integration/key/rotate → integration-api-write-rotate-key

Evidence and constraints come from fc-datasource/cmd/datasource/controller/integration_{contract,query,mutation,lifecycle,settings}.go; permission names (Integrations Read / Integrations Manage, scope on-call) from fc-pgy logic/permission/permission_test.go ids 1400/1401 (b4a9a396); per-op rate limits from the registry rows (AQps 20 / AQpm 300 on the six writes, 50 / 1000 on the three reads). Notable behaviors documented: plugin_type must carry supports_api_create: true; integration_key is returned only by create and key/rotate; update is a partial update whose settings object replaces the stored one except that entries left out or sent back as the masked ****** keep their stored value; delete returns HTTP 400 ReferenceExist with data.refs when something still references the integration.

Updated — on-call template schemas (3 schemas, 2 new properties each).
TemplateCreateRequest, TemplateUpdateRequest, TemplateItem now carry dingtalk_app_war_room_enabled and slack_app_war_room_enabled, alongside the already-documented Feishu sibling. Source: fc-event/cmd/server/controller/template/template.go:38-40 (create input, plain bool), :256-258 (update input, *bool → nullable, not required), structs/func.go:106-108 (item, always serialized → required); button visibility rule from cmd/engine/controller/notify/app_war_room.go:46-53 (hidden when the incident is closed or has no responders).

Nav / catalog reconciliation (required, operations were added)

• docs.json: +9 "POST /integration/..." entries under the on-call Integrations sub-group, in both the EN and the ZH navigation.
• {en,zh}/openapi/api-catalog.mdx: +9 rows each; <Accordion title="On-call (193 endpoints)"> → 202 endpoints; intro total 338 → 347.

Verified with the Step 5.5 check: every path in every split spec is present in docs.json and in both catalogs (nav_missing=none, catalog_missing=none for all five modules).

Diff discipline

git diff --numstat --minimal — purely additive, no deletions anywhere:

1359  0  api-reference/on-call.openapi.en.json
1359  0  api-reference/on-call.openapi.zh.json
1359  0  api-reference/openapi.en.json
1359  0  api-reference/openapi.zh.json
  20  2  docs.json
  11  2  en/openapi/api-catalog.mdx
  11  2  zh/openapi/api-catalog.mdx

Purely additive with no key reordering: every pre-existing key in paths / components.schemas / each touched schema's properties and required keeps its exact relative order (checked mechanically against git show HEAD:<path>). The 2-line deletions in docs.json and the catalogs are the two anchor lines that gained a trailing comma / were re-headed.

One placement note: the 9 new operations are inserted near the head of the split specs' paths map rather than appended at the tail. That map has no ordering convention (it is a merge artifact — the first entries are /channel/inhibit/rule/delete, /enrichment/mapping/data/truncate, /status-page/migration/status), and inserting at the tail made git's default diff heuristic pair ~411 added lines with pre-existing ones in the repetitive schema tail, so the GitHub diff showed deletions that do not exist in the content. With this placement all four spec files are 1359/0 under git diff --numstat without --minimal, i.e. what the review page renders. Path order in the spec does not affect what Mintlify renders (the nav pages allow-list does). EN and ZH are structurally identical for all new content (same paths, operationIds, schema keys, required, types, enums) — differences limited to summary/description/sidebar title/tag label/rendered body — and request/response examples use the same values in both files. All new examples were validated against their schemas (every example key resolves to a schema property). python3 -c "import json; json.load(...)" passes on all four spec files. mint broken-links was not run — mint is not installed in this environment.

Unresolved

1. POST /channel/incident/daily-counts (registry row channel:read:incidentDailyCounts, auth=all, provider event, added in fefd8eac 2026-09-14) has no handler on fc-event main. The implementation exists only on unmerged branches (origin/codex/aliyun-dataworks-op, origin/codex/checkly-alert-integration-dev: cmd/server/controller/channel/daily_incident_counts.go). Not documented — it needs the fc-event route on main first. No route path was invented.
2. monit-webapi / monit-edge are not on GitHub (as in previous rounds), so the monitors module was left at its committed HEAD content and not re-audited.
3. mapping.yaml claims neither /integration (no path_prefix) nor, at module level, /monit/query, /route, /rum/data|field|resource, /oncall/license/list, /member/notify, /calendar/*, /status-page/* (the last four fail the providers filter: the mapping says pgy/event/statuspage while the registry rows say pgy/event/status-page). 17 auth=all rows are unclaimed. The new /integration/* family is in that set, so it was written directly into the spec; the next generator run needs mapping.yaml updated or guard_no_path_drop() will abort on these 9 paths.
4. Audited this window and found not public (no spec change needed): fc-event/cmd/server/controller/incident/inter.go (InterSimilarAmong, internal no-app_key route), logic/ai_sre/* (runtime internals), structs/channel.go AssignedTo.EffectivePersonIDs (push-event payload type, not in any public schema), fc-datasource/logic/data_source/plug_jira.go status_mapping (the Jira settings schema is not part of the public surface — every /datasource/jira/* row is auth=jwt), fc-rum/model/event/view.go FirstViewTime (json:"-").

Open finding, not changed in this PR (needs a decision)

147 public operations document a rate limit that does not match their registry row (AQps/AQpm): 136 of them document the account default 1,000/minute; 50/second while the row declares 20/second, 300/minute (on-call 115 of them: platform 13, monitors 7, safari 7, rum 5). The other 11 are tuned in both directions — e.g. /status-page/subscriber/import documents 20/minute; 2/second against a registry 3/second, 60/minute, and /safari/artifact/stream documents 100/minute; 10/second against 50/second, 1000/minute. Because 43 of the 45 operations that do carry a per-op cell are audited writes, the convention looks like "mirror the registry row", but the 11 non-20/300 rows show the module data was also hand-tuned, so which side is authoritative is a product call. Not touched here — it is a 147-endpoint change and would bury the new-API diff.

Examples are constructed, not captured

The dev API (https://api-dev.flashcat.cloud) was not called: this environment cannot reference $FLASHDUTY_APP_KEY, so no real responses were captured. Every request and 200-response example for the 9 new operations is constructed from the Go types with realistic values (integration 6113996590131, team 1467226103121, 24-hex a_… ref IDs, a 32-hex + 3-digit integration key, ISO-free Unix-second stamps). No "string" placeholders. Values are consistent between the request and response example of the same operation.

Environment prerequisite is missing (same blocker as the last six rounds)

This skill's mandated per-round pre-step — apply runbooks/api-review-apply-patches.py (mapping.yaml alignment + generator baseline-fidelity patches) and follow runbooks/api-review-daily.md — could not run: neither file exists in the team knowledge pack. Checked against the platform this session (fduty safari knowledge-file-list --data '{"pack_id":"kpk_csftf5pZZ7tim6R8843eyL"}'): 26 files, none matching api-review. The reason it matters: scripts/generate_openapi.py reads its module inputs from .api-review/modules/*.json, which are gitignored and absent from a fresh checkout, while guard_no_path_drop() refuses to write a spec that would lose committed paths — so the generator cannot be re-run here without the missing prerequisite, and running it "with one hand tied" would silently drop ~330 endpoints. The changes above were therefore made as targeted edits to the split + consolidated specs, with the additive-only, key-order-preserving diff verified mechanically, which is the same shape as the previously merged daily audits (#400, #405). Restoring the two knowledge files (or changing the Automation prompt to drop the patch pre-step) unblocks the generator path for future rounds.