# sub2api-cn-relay-manager 前端 Acceptance Matrix（2026-06-01）

日期：2026-06-01

## 目的

把前端相关的可重跑入口从 `EXECUTION_BOARD.md` 的历史记录里剥出来，形成统一矩阵：

- 哪个页面对应哪个脚本
- 哪些脚本是本地门禁
- 哪些脚本是 live CRM / live portal 读写验收
- 哪些页面当前只有只读验收，哪些已经有动作级验收

## 总入口

统一矩阵脚本：

```bash
bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh
```

默认行为：

- 总是执行：
  - `scripts/test/verify_frontend_smoke.sh`
  - `scripts/acceptance/verify_portal_catalog_ui.sh`
- 显式开启 `RUN_PUBLIC_PORTAL_BROWSER=1` 时执行：
  - `scripts/acceptance/verify_public_portal_browser.sh`
- 当提供 CRM 鉴权时执行：
  - `scripts/acceptance/verify_accounts_admin_ui.sh`
- 当同时提供 route data-plane 依赖时执行：
  - `scripts/acceptance/verify_route_acceptance_matrix.sh`
- 当同时提供 provider import 依赖时执行：
  - `scripts/acceptance/verify_provider_admin_actions.sh`

产物目录：

```text
artifacts/frontend-acceptance-matrix/<timestamp>_frontend_matrix/
  browser_smoke/
  portal_catalog/
  portal_public_browser/
  accounts_admin/
  route_matrix/
  provider_admin/
  summary.json
```

若某一步缺少环境变量，会被标记为 `skipped`，并把原因写进 `summary.json`。

## 页面到脚本映射

### 1. 用户 Portal `/portal/`

脚本：

- `bash ./scripts/test/verify_frontend_smoke.sh`
- `bash ./scripts/acceptance/verify_portal_catalog_ui.sh`
- `RUN_PUBLIC_PORTAL_BROWSER=1 bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh`
- `bash ./scripts/acceptance/verify_public_portal_browser.sh`

验证范围：

- 页面可打开
- `逻辑分组目录` 标题存在
- `申请 Key 依赖状态` 与五种产品语义存在：
  - `可直接申请`
  - `可申请，调用前需确认状态`
  - `待补开通`
  - `待人工整理`
  - `仅目录可见`
- `GET /api/portal/logical-groups`
- `GET /api/portal/logical-groups/{group_id}/models`
- 可选：当提供 `PORTAL_ACCESS_TOKEN` 时，继续验证：
  - `/auth/me`
  - `/groups/available`
  - `/subscriptions`
  - `/keys?page=1&page_size=20`

说明：

- 这是只读验收，不会创建临时用户或改写宿主状态
- `verify_public_portal_browser.sh` 额外用 headless `chromium` 对公网或 SSH 隧道页面做 DOM 回读
- 若要重跑历史的 entitlement 真验，仍需要回看 `EXECUTION_BOARD.md` 中的 remote43 记录

### 2. 管理首页 `/portal/admin/`

脚本：

- `bash ./scripts/test/verify_frontend_smoke.sh`

验证范围：

- 页面可打开
- 管理导航存在
- 管理员 session 视图可渲染

说明：

- 这是入口页，不单独承载 CRM 写操作

### 3. Logical Group Admin

脚本：

- `bash ./scripts/test/verify_frontend_smoke.sh`
- `bash ./scripts/acceptance/verify_route_control_plane.sh`
- `bash ./scripts/acceptance/verify_route_acceptance_matrix.sh`

验证范围：

- 页面可打开
- `logical_group / route / route_model` 创建与回读
- `GET /api/logical-groups/{group_id}`
- `GET /api/logical-groups/{group_id}/routes`
- `GET /api/logical-groups/{group_id}/routes/{route_id}/models`

说明：

- `verify_route_control_plane.sh` 是这页最核心的 live acceptance

### 4. Route Health Admin

脚本：

- `bash ./scripts/test/verify_frontend_smoke.sh`
- `bash ./scripts/acceptance/verify_route_health_ui.sh`
- `bash ./scripts/acceptance/verify_route_acceptance_matrix.sh`

验证范围：

- 页面可打开
- route health 页面标题存在
- cooldown / failure 注入
- `GET /api/routing/routes/health`
- `POST /api/routing/resolve`
- `GET /api/routing/logs/failovers`

### 5. Provider Accounts Admin

脚本：

- `bash ./scripts/test/verify_frontend_smoke.sh`
- `bash ./scripts/acceptance/verify_accounts_admin_ui.sh`
- 可选：结合历史 remote43 证据回看 `EXECUTION_BOARD.md`

验证范围：

- 页面可打开
- `GET /api/provider-accounts`
- `GET /api/provider-accounts/{account_id}/binding-candidates`

当前边界：

- 当前脚本默认是只读验收
- `enable / disable / retire / binding / clear-binding` 的历史真验证据已存在，但还没有独立的“默认无副作用可重跑脚本”覆盖整条动作链

### 6. Provider Admin

脚本：

- `bash ./scripts/test/verify_frontend_smoke.sh`
- `bash ./scripts/acceptance/verify_provider_admin_actions.sh`
- `bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh`

验证范围：

- 页面可打开
- 目录加载
- `preview-import`
- `import`
- draft `save / update / delete / publish`

### 7. Batch Import Admin

脚本：

- `bash ./scripts/test/verify_frontend_smoke.sh`

说明：

- 当前矩阵中它先由浏览器级 smoke 挂住页面可达、会话、主动作区
- 更深的 batch-import 行为仍主要通过已有历史真验证据与执行板记录解释

## 推荐执行顺序

### 最小本地门禁

```bash
bash ./scripts/test/test_tksea_portal_assets.sh
bash ./scripts/test/verify_frontend_smoke.sh
```

### 前端统一矩阵

```bash
bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh
```

### route / provider 深验

```bash
bash ./scripts/acceptance/verify_route_acceptance_matrix.sh
bash ./scripts/acceptance/verify_provider_admin_actions.sh
```

## 环境变量

### 仅跑 portal + browser smoke

- 无必填 CRM 变量

可选：

- `PORTAL_PAGE_URL`
- `PORTAL_CATALOG_BASE`
- `PORTAL_PROXY_BASE`
- `PORTAL_ACCESS_TOKEN`
- `RUN_PUBLIC_PORTAL_BROWSER=1`
- `PUBLIC_PORTAL_PAGE_URL`
- `PUBLIC_PORTAL_CATALOG_BASE`
- `PUBLIC_PORTAL_PROXY_BASE`

### 加跑 accounts

必填：

- `CRM_BASE`
- `CRM_ADMIN_TOKEN`

或：

- `CRM_BASE`
- `CRM_ADMIN_USERNAME`
- `CRM_ADMIN_PASSWORD`

### 加跑 route matrix

除 CRM 鉴权外，还需要：

- `SHADOW_HOST_ID`
- `SHADOW_GROUP_ID`
- `SUBSCRIPTION_USER_ID`

或：

- `GATEWAY_API_KEY`

### 加跑 provider admin actions

除 CRM 鉴权外，还需要：

- `ACCESS_API_KEY`
- `PROVIDER_KEYS`

## 当前结论

截至 2026-06-01：

- `portal / logical-groups / route-health / accounts / providers` 已经都有统一入口可追
- 入口强度不完全相同：
  - `logical-groups / route-health / providers` 的动作级验收更完整
  - `portal / accounts` 当前统一入口先以只读回读为主
- 后续如果继续收口，最值得补的是：
  - `accounts` 的启停/归属动作无副作用可重跑验收
  - `batch-import` 的页面级独立 acceptance