Deprecation Notice: /v1/orders

Deprecation Notice: /v1/orders

Status: Deprecated as of <公告日> Replacement: /v2/orders（迁移指南见下文） Removal date: Advisory — no hard deadline yet； 受最大消费者合同约束，任何破坏性变更提前 90 天通知 Reason: （由团队按实际情况填写）

Migration Guide

1. 将请求路径由 /v1/orders 迁移到 /v2/orders
2. 更新鉴权/配置（按实际差异补充）
3. 用现有遥测核对迁移后行为一致

同时针对清单的最后一项缺口——"v1 目前没有响应弃用头"——在响应中加入弃用标记（如 `Deprecation` / `Sunset` 类头信息）是公告动作的自然组成，让 48,000 请求/天的每一次 v1 调用都在向消费者自我宣告弃用状态。

### Step 3：逐个增量迁移，并执行 Churn Rule

技能要求"逐个迁移消费者，而不是一次性切换"，每个消费者走五步：识别所有触点 → 切换到替代实现 → 验证行为一致 → 移除旧引用 → 确认无回归。

清单里的触达结构决定了外联计划的形状：

- **188 个可直接联系的消费者**：由支持团队按流量排序（遥测里有 API key 与 route，可以按 key 聚合出日请求量），先迁头部消费者——头部 key 迁移后，剩余流量曲线会明显下坠，为"零流量"判据提供提前信号；
- **12 个经销商托管账户**：不能直接触达终端用户，需要经销商作为中转；计划里必须给经销商留出独立的沟通与排期通道，这是很多"日历式"计划漏掉的长尾。

技能中的 **Churn Rule**（流失责任规则）在本场景尤其重要：既然平台拥有 v1 基础设施，就有责任把用户迁走，或者提供"无需迁移"的向后兼容更新——"发个公告就让用户自己搞定"被明确列为常见合理化借口之一（"Users will migrate on their own" → "They won't."）。

### Step 4：确认零流量后移除

清单第 5 条（遥测记录 API key、route、status、response latency）正是"验证零活跃使用"的现成数据源：按 route 过滤 v1 路径、按 API key 聚合剩余调用量，当 173 个活跃 key 全部归零、且持续观察窗口内无回升时，才进入移除步骤（删代码、删关联测试/文档/配置、删弃用公告本身）。这与评测期望第 3 条"Removal is gated on measured migration, not a calendar date alone"一一对应。

## 6. 流量迁移模式：绞杀者（Strangler）最贴合本场景

技能给出了四种迁移模式，对本清单而言优先级如下。

**绞杀者模式（Strangler）**：新旧并行，把流量从 v1 逐步切到 v2，旧系统降到 0% 流量后移除。技能给出的阶段划分可直接套用到 48,000 请求/天的订单流量上：

Phase 1: New system handles 0%, old handles 100% Phase 2: New system handles 10% (canary) Phase 3: New system handles 50% Phase 4: New system handles 100%, old system idle Phase 5: Remove old system

**适配器模式（Adapter）**：保留旧接口签名、内部委托给新实现，适合那些"暂时动不了请求路径"的消费者。技能中的示例：

```typescript
// Adapter: old interface, new implementation
class LegacyTaskService implements OldTaskAPI {
  constructor(private newService: NewTaskService) {}

  // Old method signature, delegates to new implementation
  getTask(id: number): OldTask {
    const task = this.newService.findById(String(id));
    return this.toOldFormat(task);
  }
}

特性开关（Feature Flag）：按消费者维度逐个切换实现：

function getTaskService(userId: string): TaskService {
  if (featureFlags.isEnabled('new-task-service', { userId })) {
    return new NewTaskService();
  }
  return new LegacyTaskService();
}

从本清单的结构看，按 API key 作为开关维度是自然的粒度：遥测本来就以 key 为记录单位，开关、监控、回滚全部可以落在同一个键空间里。（这是基于清单"按 key 记录遥测"这一事实的规划推断，而非仓库中的既有实现。）

7. 移除前的红旗对照与验证清单

把技能的 Red Flags 逐项对照本清单，可以快速确认计划的完备性：

• "Deprecated systems with no replacement available" → 已排除（/v2/orders 存在）；
• "Deprecation announcements with no migration tooling or documentation" → 当前真实风险：清单承认没有迁移指南，计划必须先补；
• "Deprecation without measuring current usage" → 已排除：遥测记录 key/route/status/latency；
• "Removing code without verifying zero active consumers" → 用第 5 步的零流量判据约束。

完成退役后，用技能的验证清单收口：

• 替代方案已在生产验证、覆盖全部关键用例；
• 迁移指南存在且含具体步骤与示例；
• 所有活跃消费者已迁移（以遥测/日志为证据，而非口头确认）；
• 旧代码、测试、文档、配置全部移除；
• 代码库中不再残留对弃用系统的引用；
• 弃用公告本身也被移除（它已完成使命）。

8. 在仓库中复现这个评测场景

该场景由 CI 之外的行为评测层驱动。在本地克隆本仓库后（需要 Node 环境与 claude CLI，行为评测会消耗 token）：

# Tier 2：确定性的触发/路由检查，免费，可先跑
node scripts/run-evals.js

# Tier 3：行为评测，把 evals/fixtures/deprecation-and-migration/ 下的清单
# 物化进一次性 git 工作区，由无头 Agent 产出退役计划，再按 expectations[] 评分
node scripts/run-evals.js --behavioral deprecation-and-migration
node scripts/run-evals.js --behavioral deprecation-and-migration --dry-run  # 只打印执行计划