从 API v1 迁移到 v2

对照认证、请求字段、幂等、错误和响应变化，把现有 Darkroom API v1 订单集成安全迁移到 v2。

迁移目标是让 Darkroom API v2 成为唯一的新写入入口，同时保留 v1 集成作为可回滚路径，直到真实订单验证完成。

主要差异

关注点	Darkroom API v1	Darkroom API v2
base URL	`https://api.darkroom.net/v1`	`https://api.darkroom.net/v2`（沙盒 `https://sandbox-api.darkroom.net/v2`）
认证	query/form 的 `api_key` + PHP-compatible HMAC `api_sig`	OAuth 2.0 client_credentials → `Authorization: Bearer <token>`
签名	参数排序后 `json_encode` 再 HMAC，签名结果对编码字节敏感	无请求签名；长期 `client_secret` 仅用于获取访问令牌
防重放	无	`order_code` 提供自然幂等，可安全处理相同请求的重试
输入来源	query/form 同名字段按 v1 兼容规则合并	业务字段只接受 JSON body；query 参数返回 400
body	form/query；`order_plans` 是 JSON string	结构化 UTF-8 JSON
幂等	重复编号返回数字错误 153	相同内容 replay 200；不同内容 conflict 409
错误	通常 HTTP 200 + 数字 `error_code`	真实 HTTP 状态码 + 字符串 `error.code` + `request_id`
顾客更新	严格保持 Laravel 4.2 全字段更新和空值覆盖	省略不更新；nullable 字段传 `null` 才清空；空字符串校验失败
顾客免登	响应含永久 `auto_login_url`	永不返回
限流	`20 requests/min/key`，超限 HTTP 429	双层：20/min 配额 + 2/s 突发整形，两类 429 的 error.code 与退避不同
沙盒	无	有，与生产完全隔离且不发任何真实通知

核心字段映射

Darkroom API v1	Darkroom API v2	说明
`order_id` / `order_code`	`order_code`	3–40 位外部订单编号，也是自然幂等键
`order_date`	`scheduled_date`	`YYYY-MM-DD`
`order_hour`	`scheduled_start_time`	`HH:MM:SS`
`created_at`	`source_created_at`	外部系统最初建单时间；不传时由 Darkroom 记录接收时间
`store_id`	`store_code`	Darkroom API v2 要求显式传门店 code
`order_plans` JSON string	`services` JSON array	`id` → `service_code`，`price` → `unit_price_amount`，`num` → `quantity`
`customer_name`	`customer.name`	只更新明确出现的字段
`customer_area_code`	`customer.country_calling_code`	例如 `+86`
`customer_mobile`	`customer.mobile`	不含国家区号
`customer_email`	`customer.email`	可选
`customer_gender`	`customer.gender`	`female`、`male`、`unspecified`
`kid_` / `customer_baby`	`customer.child.*`	可选儿童资料
`prepay_amount`	`prepayment.amount`	两位小数字符串
`prepay_method`	`prepayment.method`	可用值由商家配置决定
`order_coupon`	`coupon_code`	可选
`customer_remark`	`customer_remark`	可选
`order_remark` + `team_remark`	`team_remark`	迁移前先确认两字段拼接顺序

推荐迁移流程

盘点 v1 调用

记录当前版本、端点、调用频率、来源服务、订单编号规则、签名实现和错误处理，并以生产配置和运行记录为准。

建立字段转换层

在调用方内部生成明确的 v2 request object，再交给 HTTP client 发送。避免在网络请求层同时处理 v1 和 v2 字段映射。

接入新凭据

分别保存 v1 和 v2 凭据。v2 凭据仅授予所需的 orders:read 或 orders:write scope；write 不包含 read。请先使用 dr_test_ 前缀的沙盒凭据完成验证，再切换生产环境。

使用隔离数据进行对比验证

使用同一组脱敏测试数据分别验证响应和 Darkroom 后台订单结果。重点覆盖幂等重放、订单编号冲突、顾客字段部分更新、优惠码和订金。

小流量切换

选择可识别的一小部分订单仅写入 v2，并按 order_code 核对结果。迁移期间不对同一订单执行双写。

保留可回滚窗口

出现问题时停止新 v2 请求并恢复 v1 单写。已经由 v2 创建的订单不会因流量回滚自动删除。

上线前检查

Darkroom 已确认启用 v2 接口和相关凭据，scope 覆盖实际使用的端点；write 不包含 read。
访问令牌已缓存，不会在每个业务请求前调用 /oauth/token。该端点限制为 10 次/分钟/client_id。
收到 401 invalid_token 时，仅在获取新令牌后重试一次，避免循环重试。
两类 429 分别退避：burst_limit_exceeded 约 1 秒，rate_limit_exceeded 到下一分钟。
收到 409 order_code_conflict 时，不会自动更改订单编号并重试。
5xx 使用有上限的指数退避，避免产生大量重复请求。
日志仅保存 request_id、HTTP 状态码、error code 和脱敏订单标识，不记录 client_secret 或完整访问令牌。
调用方不依赖 auto_login_url。
v1 回滚配置仍可用，但不会和 v2 同时写同一订单。