# Route Acceptance Matrix

日期：2026-05-29

## 目标

把 Phase 2 已经验证过的三类能力，收敛成固定入口和固定证据格式：

1. 控制面
2. 运行态 / 健康视图
3. 数据面

当前统一入口：

- `scripts/acceptance/verify_route_control_plane.sh`
- `scripts/acceptance/verify_route_health_ui.sh`
- `scripts/acceptance/verify_route_data_plane.sh`
- `scripts/acceptance/verify_route_acceptance_matrix.sh`

其中 `verify_route_acceptance_matrix.sh` 是总入口，会按顺序执行前三个脚本并汇总 `summary.json`。

## 验收矩阵

### 1. 控制面

脚本：

- `scripts/acceptance/verify_route_control_plane.sh`

验证范围：

- 创建 `logical_group`
- 创建 `logical_group_model`
- 创建 `route`
- 创建 `route_model`
- `GET /api/logical-groups/{group_id}`
- `PUT /api/logical-groups/{group_id}`
- `PUT /api/logical-groups/{group_id}/routes/{route_id}`
- `GET /api/logical-groups/{group_id}/routes`
- `GET /api/logical-groups/{group_id}/routes/{route_id}/models`

最小输入：

- `CRM_BASE`
- `CRM_ADMIN_TOKEN`

主要产物：

- `01-create-group.json`
- `03-create-route.json`
- `06-update-group.json`
- `07-update-route.json`
- `10-summary.json`

### 2. 健康视图 / 运行态

脚本：

- `scripts/acceptance/verify_route_health_ui.sh`

验证范围：

- 公网 `route-health.html` 页面可达
- `POST /api/routing/sticky/cooldowns`
- `POST /api/routing/sticky/route-failures`
- `GET /api/routing/routes/health`
- `POST /api/routing/resolve`
- `GET /api/routing/logs/failovers`

最小输入：

- `CRM_BASE`
- `CRM_ADMIN_TOKEN`
- 可选 `ROUTE_HEALTH_PAGE_URL`

主要产物：

- `00-route-health.html`
- `08-health-before.json`
- `09-resolve.json`
- `10-health-after.json`
- `11-failovers.json`
- `12-summary.json`

### 3. 数据面

脚本：

- `scripts/acceptance/verify_route_data_plane.sh`

验证范围：

- 创建临时 `logical_group / route / route_model`
- `POST /api/routing/chat/completions`
- `GET /api/routing/logs/decisions`

最小输入：

- `CRM_BASE`
- `CRM_ADMIN_TOKEN`
- `SHADOW_HOST_ID`
- `SHADOW_GROUP_ID`
- 二选一：
  - `SUBSCRIPTION_USER_ID`
  - `GATEWAY_API_KEY`

补充说明：

- 若传 `SUBSCRIPTION_USER_ID`，期望 `effective_gateway_key_source=managed_subscription`
- 若传 `GATEWAY_API_KEY`，脚本仍可跑通，但这不覆盖“自动供给 managed key”场景

主要产物：

- `05-route-chat.json`
- `06-decision-logs.json`
- `07-summary.json`

## 总入口

脚本：

- `scripts/acceptance/verify_route_acceptance_matrix.sh`

它会创建：

```text
artifacts/phase2-routing-matrix/<timestamp>_route_matrix/
  control_plane/
  health_ui/
  data_plane/
  summary.json
```

`summary.json` 只保留最核心的摘要字段：

- `control_plane_group_id`
- `health_ui_group_id`
- `data_plane_group_id`
- `data_plane_request_id`
- `data_plane_upstream_status`
- `health_ui_resolve_route_id`

## remote43 推荐执行方式

如果要避免把真实 `CRM_ADMIN_TOKEN` 带回本地，推荐直接在 `remote43` 上执行：

```bash
cd /home/ubuntu/sub2api-kimi-patched-auto2-20260525_18169
set -a
. ./.env.crm
set +a

cd /home/ubuntu/sub2api-cn-relay-manager-git-current
CRM_BASE="https://sub.tksea.top/portal-admin-api" \
SHADOW_HOST_ID="<real-shadow-host-id>" \
SHADOW_GROUP_ID="<real-shadow-group-id>" \
SUBSCRIPTION_USER_ID="<managed-user-id>" \
bash ./scripts/acceptance/verify_route_acceptance_matrix.sh
```

## 当前边界

- 脚本只负责留证据和判断通过/失败，不负责清理临时 `logical_group`
- 数据面脚本当前仍依赖调用方提供真实 `shadow_host_id / shadow_group_id`
- 尚未覆盖“同公开模型双线路主备”的未来策略矩阵