付费开发者 API 参考

允许值

• 省略：接受（最新行为）。
• 若填写，须恰好为 "2026-04-01"（PUBLIC_SCHEDULE_API_VERSION）。
• 其他字符串拒绝（TYPE_ERROR）。

行为

• 在 sanitizeApiVersion 中等同 trim 的处理后比较。

常见错误

• TYPE_ERROR不支持的 apiVersion 值。

允许值

• 线上格式为单个字符串。API 不以封闭枚举列出全部时区：由服务器动态校验。
• 校验与 `isValidIanaTimeZone` 一致：Luxon `DateTime.now().setZone(zone).isValid` 须为 true。
• 请使用规范 IANA 标识符，例如 `Asia/Tokyo`、`America/New_York`、`Europe/Berlin`、`UTC`。
• 勿仅依赖缩写（`EST`、`JST`、`GMT`）— 不是稳定的 IANA ID，可能被拒绝。
• 列表参考：IANA 发布包（https://www.iana.org/time-zones）或您平台的时区 API。

行为

• 用于下游规范化中的日期与槽时间。
• 若客户端需要固定列表，请用相同规则（IANA ID）自行推导，勿指望 JSON 模式中的服务端枚举。

常见错误

• INVALID_TIME_ZONE缺失、空或无效 IANA 时区。

允许值

• 须匹配 /^\d{4}-\d{2}-\d{2}$/（trim 后）。
• 真实日历日期；含端范围须通过 enumerateDates 至少产生一天。
• 范围内天数不得超过 maxScheduleDays（付费 API 通常两周规划最多 14 天；精确上限 = 租户权益）。

行为

• scheduleStartDate 须早于或等于 scheduleEndDate。

常见错误

• INVALID_DATE_RANGE格式错误、无效日期或空范围。
• SCHEDULE_SPAN_TOO_LONG超过 maxScheduleDays 的天数。

允许值

• 非空字符串（trim），与 UI 相同的槽枚举（`enumerateSlotsByGranularity`）。
• 二者须至少生成一个槽，否则校验失败。

行为

• 与 slotGranularityMinutes 一起决定 cellKey 所用的 slotId。

常见错误

• INVALID_TIME_RANGE缺失或该范围下槽数为 0。

允许值

• 须恰好为 60 或 15（非字符串）。
• 还须出现在 allowedGranularities 中。付费 API 通常两者均开；若租户关闭 15 则返回 INVALID_GRANULARITY。

行为

• 与时间范围一起决定槽数量。

常见错误

• INVALID_GRANULARITY非 60/15 或方案不允许。

允许值

• 须为普通 JSON 对象（非数组）。
• 每个键须为预期网格（日期×slotId）上的 cellKey。未知键 → UNKNOWN_CELL_KEY。
• 每个值须为 JSON 整数，0–15（含）。
• 省略的格视为需求 0（仅需求≥1 的格参与 SHORTFALL）。

行为

• 键在 sanitizeCellKey trim 后比较。

常见错误

• INVALID_REQUIREMENTS不是对象或某键数值无效。
• UNKNOWN_CELL_KEY键不在计算的日期×槽网格内。

允许值

• 长度在 1 与 maxStaffPerSchedule 之间（POST /v1/schedule 默认 500；与 POST /v1/staff 名册上限分开）。
• 每项须为普通对象，且仅含允许键：staffId、displayName、availableCells（严格模式）。
• staffId 与 displayName 须通过清理（见「清理」一节）。
• staffId 在数组内须唯一（DUPLICATE_STAFF_ID）。

行为

• 保留顺序用于可用性计数。

常见错误

• INVALID_STAFF空数组、过多行、对象无效或清理失败。
• UNKNOWN_FIELD严格模式下 staff 对象出现额外键。
• DUPLICATE_STAFF_ID重复的 staffId。

允许值

• 省略：该员工视为在整个网格上可用（内部 null 表示「全部格」）。
• 若提供：须为 JSON 字符串数组；每个非空字符串须为预期网格上的 cellKey。
• 数组中不允许空字符串（INVALID_AVAILABLE_CELL）。

SHORTFALL 检查

• 对每个需求≥1 的格，计为可用的员工数须≥需求，否则 SHORTFALL_CELLS。

常见错误

• INVALID_AVAILABLE_CELL未知 cellKey 或空项。
• SHORTFALL_CELLS相对需求人数不足。

API 在父行上存储的内容

• 公开 API 仅在顶层接受 ROOT_KEYS，每行 staff 仅接受 STAFF_KEYS。请勿发送 laborLawJurisdiction、usLaborStateCode、laborModelVersion 或 paidOptimization。
• 提交时，服务器用共享默认值填充父 SCHEDULE_CONDITION：paidOptimization = DEFAULT_PAID_OPTIMIZATION — laborLawCompliance 为 false；balanceStaffLoad、honorShiftWishes、preferConsecutiveShifts 为 true（见 schedule-defaults-shared.ts 与 build-schedule-transact-items.ts）。laborLawJurisdiction 为 JP，usLaborStateCode 为 GENERIC，laborModelVersion 为 v1。
• 优化器中成文法风格的劳动约束需父级与每人员工合规标志同时开启；本路径默认关闭，勿仅凭此 JSON 期望法定上限生效。
• 劳动模型为排班近似，不构成法律意见。目录：optimizer/config/labor_models.json。

文档

• 完整说明：docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §2.1.1 与 §3.1。

若发送不允许的键

• UNKNOWN_FIELD严格模式拒绝未知的根或 staff 属性。