# Oncall-v2 API 规范整改方案（第一版）

目标
- 统一前后端对 /api1/schedule/window 的参数规范（数组优先）
- 修复 swagger 与后端实现漂移，保证 SDK 可生成、可对齐
- 保持向后兼容（不立即破坏历史 CSV 传参）

本次已落地
1) 后端（已改）
- 文件: services/oncall/api/router.go
- 路由: GET /api1/schedule/window
- 变更:
  - 支持标准数组 query: category_ids=1&category_ids=2（QueryArray）
  - 兼容 CSV alias: category_ids_csv=1,2,3
  - 兼容 category_ids 单项里带逗号（逐项 split）
  - 对 category_ids 去重

2) OpenAPI（已改）
- 文件: services/oncall/swagger.yaml
- 新增完整 path:
  - GET /api1/schedule/window
  - 参数定义:
    - category_ids: array<int>, style=form, explode=true
    - category_ids_csv: string（兼容）
    - past/future/current_only/include_empty/respect_hour_window

3) 前端（已改）
- 先重新生成 SDK:
  - apps/oncall-web/src/api/services/DefaultService.ts
  - 新签名:
    getApi1ScheduleWindow(categoryIds?: number[], categoryIdsCsv?: string, past?: number, ...)
- 调用改造:
  - 文件: apps/oncall-web/src/pages/CategoryDetail.js
  - 由 String(categoryId) 改为 [Number(categoryId)]（数组）

验证结果
- go test ./api ./service -run TestDoesNotExist 通过
- 前端 npm run build 通过

当前遗留（下一批建议）
1) CategoryConfig 直连遗留接口
- 文件: apps/oncall-web/src/pages/CategoryConfig.js
- 仍调用 /api1/config/round（后端/文档无此接口）
- 建议：
  - 要么补后端 + swagger
  - 要么删除该页面入口并迁移到现有 category 配置接口

2) 路由命名风格不统一（RPC 动词风格）
- 例如 /add /remove /change /generate
- 建议分阶段：
  - Phase A: 先补 swagger，保持现状
  - Phase B: 增加 REST 别名接口（新）
  - Phase C: 前端切换后下线旧接口

3) period_type 语义多套（week/day + weekly/daily）
- 建议统一 canonical 枚举，保留别名兼容层

迁移策略建议
- 兼容窗口: 2~4 周
- 兼容期内：同时支持数组与 CSV
- 日志埋点：统计 category_ids_csv 使用量
- 使用量归零后移除 CSV 分支

回滚点
- 后端: router.go 单文件回滚
- 文档: swagger.yaml path 删除即可
- 前端: CategoryDetail getApi1ScheduleWindow 参数恢复旧签名（不建议）