sub2api-cn-relay-manager/docs/ROUTE_ACCEPTANCE_MATRIX.md

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

它会创建：

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 上执行：

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
• 尚未覆盖“同公开模型双线路主备”的未来策略矩阵