docs(api): daily audit 2026-10-14 — schedule cycles, release_limited, work-item status enums

[flashduty]

What this is

Daily api-review --mode generate --scope all --auto audit of the public OpenAPI 3.1 specs.

• Source registry: fc-pgy@9a12713a (logic/api/api_test.go, 1,212 rows, 366 with Auth: all).
• Source handlers: fc-event@03b3d09b1, fc-oncall@366de55, fc-rum@c9d1923, fc-statuspage@69ca45f, monit-webapi@87308c1, fc-datasource@c4c17f9, go-pkg@e56c64e (origin/main, fetched this run).
• Docs baseline: flashduty-docs@e92b8695 (main).
• unresolved handler lookups: 1 (listed below). No module failed to generate.

Operation changes

Module	added	updated	removed
on-call	0	3 schema groups	0
monitors	0	0	0
rum	0	0	0
platform	0	0	0
safari	0	0	0

No path was added or removed, so docs.json and {en,zh}/openapi/api-catalog.mdx are deliberately untouched (no nav or catalog edit is due this round).

Fixes (each one read from the Go source, not inferred)

1. ScheduleFixedTimeNotifyInfo — week/month fixed-time cycles.
fc-oncall commit d581345 ("feat(schedule): support week/month cycles for fixed-time duty notification", merged 2026-10-14), models/schedule.go:

const (
    FixedTimeCycleDay   = "day"
    FixedTimeCycleWeek  = "week"
    FixedTimeCycleMonth = "month"
)
type FixedTimeNotifyInfo struct {
    Cycle string `json:"cycle"`
    Start string `json:"start"`
    Days  []int  `json:"days,omitempty"`
}

Validate() requires a non-empty days for week (each 0-6) and for month (each 1-31); a short month without that date is skipped. The docs still said cycle was a single-value enum ["day"] with "only day is supported" and no days at all — so a documented-valid request is the only thing the docs allowed, while week/month were unrepresentable.

• cycle enum ["day"] -> ["day","week","month"], description rewritten.
• new days property (array of integer). Not added to required, because it is only required for week/month; the condition is stated in the description.

2. /oncall/license/list — release_limited.
fc-event commit eebe84b61 ("feat(license): cap license releases per billing window"), cmd/server/controller/license/info.go: all three success branches of LicenseList now return gin.H{"total": ..., "items": ..., "release_limited": ...}. An account may release at most license_cnt x 10 seats per 30-day window; once the quota is used, releasing a seat is rejected with NoLicense (reason release limited in the Flashcat-No-License header).

• LicenseListResponse: new release_limited (boolean), added to required (the handler always sets it), plus the field in the operation's 200 example.

3. Work-item statuses.
fc-event commit df07bf805 ("fix(work-item): accept only the four work-item statuses"), logic/post_incident/work_item.go + structs/work_item.go: WorkItemStatusOpen|InProgress|Done|Cancelled. Create rejects anything outside the four (blank defaults to open), update rejects anything outside the four (including empty), complete's target_status must be exactly done, convert accepts the four.

The docs described all four fields as free-form ("client-defined status", "There is no fixed state machine") — actively wrong for complete, where any other value is a 400.

• CreateWorkItemRequest.status: enum [open, in_progress, done, cancelled] + default note.
• UpdateWorkItemRequest.status: same enum.
• CompleteWorkItemRequest.target_status: enum [done], "There is no fixed state machine" removed.
• ConvertWorkItemRequest.target_status: same four-value enum (stays nullable).

Note: the two nullable status/target_status fields keep their existing ["string","null"] type union and get an enum without null, which is the convention already used by the 20 other nullable-enum properties in this repo (e.g. CreateStatusPageChangeRequest.updates[].status). No new convention introduced.

Diff discipline

• 178 insertions / 30 deletions across 4 files (api-reference/on-call.openapi.{en,zh}.json, api-reference/openapi.{en,zh}.json) — larger than the usual 100-line budget because this round carries three independent schema fixes; no file rewrite, no reformatting.
• No reordering: every file round-trips byte-identically through json.dumps(..., indent=2, ensure_ascii=False) before editing, and each new key was inserted at the position the file's own local ordering calls for (Go order in the split specs, alphabetical in the consolidated copies).
• Verified by an order-sensitive walk of git show HEAD:<path> against the working tree: exactly the 14 intended nodes change per file, zero KEY_ORDER diffs, no unintended key-set or type change.
• EN/ZH structural parity re-checked after the edit: 0 differences across all 5 split pairs.
• Every one of the 4 files loads with python3 -c "import json; json.load(open(path))".
• mint is not installed in this environment, so mint broken-links was not run; only existing paths were edited, so no link can have changed.

Constructed examples

No new operation and no new operation-level example this round. The one example edit is adding the literal "release_limited": false to the /oncall/license/list 200 example so it matches the field the handler now always returns. The dev API (api-dev.flashcat.cloud) is not callable from this environment, so examples remain schema-derived; nothing else was touched.

unresolved (recorded, not written into any spec)

• /channel/incident/daily-counts (channel:read:incidentDailyCounts, Auth: all) is in the fc-pgy registry but has no route and no handler anywhere on fc-event origin/main (git grep -n 'daily-counts' origin/main is empty); the controller exists only on origin/dev and feature branches. Same finding as the 2026-10-12 round. Needs a human: add the handler to main, or drop the registry row.

Recorded but not fixed (needs a human decision on direction)

• Work-item 200 examples: the on-call split specs omit assignees from the 7 /incident/work-item/* response examples while the consolidated copy includes it, even though WorkItemItem.required contains assignees. Aligning either way is ~200 lines and the two existing conventions disagree ("split is the rendering truth" vs "a field in the backend struct belongs in both"), so it stays out of a daily-audit diff. Unchanged by this PR.
• DutyError.reason: the consolidated copies carry an extra reason property marked x-flashduty-preserve-absence: true; the split specs do not. That marker is the established hand-edit convention, so the hand-edit was left alone and only recorded here. Unchanged by this PR.
• Safari shared responses: api-reference/safari.openapi.*.json diverges from the consolidated copy (and from the other four split specs) in 4 places inside components.responses — an extra summary on the BadRequest example, a skill_id-specific BadRequest message, accessDenied vs noEditPermission on Forbidden, and a shorter TooManyRequests description. The skill_id in the message looks deliberate (safari-specific), so this was not "fixed". Unchanged by this PR.
• Stale open PR: flashcatcloud/flashduty-docs#1051 documents App Key leak handling, but the fc-pgy feature it documents was merged and then reverted the same day (35130657 then 9f39515c/9a12713a), so its subject is no longer on fc-pgy main. Not touched here — it is someone else's open PR. A maintainer should close or rework it.