sub2api-cn-relay-manager/docs/2026-05-31-PROVIDERS_ACTION_ACCEPTANCE_MATRIX.md

# providers.html 动作级 Acceptance 矩阵（2026-05-31）

日期：2026-05-31

## 目的

这份矩阵专门回答一个此前被混在一起的问题：

- `providers.html` 当前到底承载了哪些动作
- 这些动作里哪些已经有历史真验证据
- 哪些只是后端有接口，但页面并没有显式做成 UI
- 哪些还缺独立页面级 acceptance

本矩阵只针对 `deploy/tksea-portal/admin/providers.html`。

## 先给结论

`providers.html` 当前真正显式承载的动作只有两类：

1. provider 目录 + `preview-import` / `import`
2. provider draft 的 `save / update / delete / publish`

**它并没有显式承载 `rollback` 或 `reconcile` 按钮。**

所以：

- 不能把后端存在 `POST /api/providers/{providerID}/rollback` / `POST /api/providers/{providerID}/reconcile`，直接说成“providers.html 已完成这两个前端动作闭环”
- 更准确的说法是：
  - `preview-import / import`：页面显式承载
  - `rollback / reconcile`：后端已提供，real-host acceptance 也有证据，但当前**不属于这页的显式 UI 能力**

## 页面实际承载范围

从 `providers.html` 当前实现看，页面明确包含：

- 管理员 session 登录
- pack / host / provider 目录加载
- `preview-import`
- `import`
- manifest draft 生成
- 草稿保存到服务端
- 草稿更新
- 草稿删除
- 草稿发布到仓库

页面未显式提供：

- `rollback`
- `reconcile`
- `provider status`
- `provider resources`
- `access status`
- `import-batches` 历史列表

这些能力虽然在后端存在，但不是当前 `providers.html` 的显式按钮或结果区。

## 动作级矩阵

| 动作 | 后端接口 | 当前是否在 `providers.html` 显式承载 | 当前证据强度 | 审计结论 |
| --- | --- | --- | --- | --- |
| 加载 pack / host / provider 目录 | `GET /api/packs` `GET /api/hosts` `GET /api/packs/{pack_id}/providers` | 是 | 代码接线 + 静态回归 | 已接线，缺独立远端页面级矩阵 |
| preview-import | `POST /api/providers/{provider_id}/preview-import` | 是 | 页面接线 + real-host acceptance API 证据 | 部分闭环 |
| import | `POST /api/providers/{provider_id}/import` | 是 | 页面接线 + real-host acceptance 强证据 | 部分闭环 |
| draft save | `POST /api/provider-drafts` | 是 | 执行板 + 页面接线 | 历史已闭环 |
| draft update | `PUT /api/provider-drafts/{draft_id}` | 是 | 执行板 + 页面接线 | 历史已闭环 |
| draft delete | `DELETE /api/provider-drafts/{draft_id}` | 是 | 执行板 + 页面接线 | 历史已闭环 |
| draft publish | `POST /api/provider-drafts/{draft_id}/publish` | 是 | 执行板远端真验强证据 | 历史已闭环 |
| rollback | `POST /api/providers/{provider_id}/rollback` | 否 | 后端路由 + 单测 | 不属于当前页面显式能力 |
| reconcile | `POST /api/providers/{provider_id}/reconcile` | 否 | 后端路由 + real-host acceptance API 证据 | 不属于当前页面显式能力 |
| provider status | `GET /api/providers/{provider_id}/status` | 否 | 后端路由 + acceptance 证据 | 不属于当前页面显式能力 |
| access status | `GET /api/providers/{provider_id}/access/status` | 否 | 后端路由 + acceptance 证据 | 不属于当前页面显式能力 |
| import-batches | `GET /api/providers/{provider_id}/import-batches` | 否 | 后端路由 + OpenAPI | 不属于当前页面显式能力 |

## 逐项审计

### 1. 目录加载

- 页面证据：
  - `GET /api/packs`
  - `GET /api/hosts`
  - `GET /api/packs/{pack_id}/providers`
- 当前结论：
  - 页面层面接线明确
  - `test_tksea_portal_assets.sh` 只证明页面引用了这些入口，不证明远端目录加载全过程持续可用
- 状态：
  - `已接线`

### 2. `preview-import`

- 页面证据：
  - 页面有“预检导入”按钮
  - 直接调用 `POST /api/providers/{provider_id}/preview-import`
  - preview 结果区直接展示原始 JSON
- 后端证据：
  - 路由已注册
  - OpenAPI 已声明
  - `real_host_acceptance.sh` 会固定落盘 `04-preview-import.json`
- 当前结论：
  - 这条动作在 API 层有真实宿主证据
  - 但仓库里没有一份专门说明“通过 `providers.html` 点击预检导入完成远端验证”的独立页面级证据
- 状态：
  - `部分闭环`

### 3. `import`

- 页面证据：
  - 页面有“执行导入”按钮
  - 直接调用 `POST /api/providers/{provider_id}/import`
  - import 结果区直接展示原始 JSON
- 后端证据：
  - 路由已注册
  - OpenAPI 已声明
  - `real_host_acceptance.sh` 固定落盘 `05-import.json`
  - `import_remote43_provider.sh` 有 remote43 定向验收链
- 当前结论：
  - import 主链路本身证据很强
  - 但 `providers.html` 页面级 acceptance 仍与 API acceptance 混在一起，未形成动作级单页矩阵
- 状态：
  - `部分闭环`

### 4. draft save / update / delete

- 页面证据：
  - 页面提供按钮并直接调用：
    - `POST /api/provider-drafts`
    - `PUT /api/provider-drafts/{draft_id}`
    - `DELETE /api/provider-drafts/{draft_id}`
- 执行板证据：
  - 已明确记录：
    - 草稿落到 CRM SQLite
    - `providers.html` 可保存、回看、更新、删除服务端草稿
- 当前结论：
  - 这些动作已经属于页面显式能力，且历史上已被写成真实交付范围
- 状态：
  - `历史已闭环`

### 5. draft publish

- 页面证据：
  - 页面提供“发布到仓库”按钮
  - 调用 `POST /api/provider-drafts/{draft_id}/publish`
- 执行板证据：
  - remote43 公网真验已记录：
    - `draft_id`
    - `provider_id`
    - `provider_path`
    - `pack_version` bump
    - `commit_sha`
    - 远端 repo `HEAD` 与 API 返回 `commit_sha` 一致
- 当前结论：
  - 这是 `providers.html` 当前证据最强的动作之一
  - 可认为历史上已形成页面驱动的完整闭环
- 状态：
  - `历史已闭环`

### 6. `rollback`

- 页面证据：
  - 当前 `providers.html` 没有 `rollback` 按钮，也没有结果区对应 `rollback`
- 后端证据：
  - 路由已注册：`POST /api/providers/{provider_id}/rollback`
  - OpenAPI 已声明
  - `app_test.go` 有 API handler 测试
- 注意：
  - 当前 real-host 主脚本真实验证的是 `POST /api/import-batches/{batch_id}/rollback`
  - 这证明“回滚链路存在”，但不是“`providers.html` 已显式支持 provider rollback”
- 当前结论：
  - 不能把它算作 `providers.html` 已闭环动作
  - 它属于“后端存在，但页面未显式承载”
- 状态：
  - `不属于当前页面显式能力`

### 7. `reconcile`

- 页面证据：
  - 当前 `providers.html` 没有 `reconcile` 按钮，也没有结果区对应 `reconcile`
- 后端证据：
  - 路由已注册：`POST /api/providers/{provider_id}/reconcile`
  - OpenAPI 已声明
  - `real_host_acceptance.sh` 固定落盘 `09-reconcile.json`
  - runbook 明确把 `reconcile` 视为真实宿主验收链一环
- 当前结论：
  - API 层与 real-host 层证据都存在
  - 但这仍然不能推导出“当前 `providers.html` 已做 reconcile 前端闭环”
- 状态：
  - `不属于当前页面显式能力`

## 为什么 `providers.html` 当前只能判为“部分闭环”

因为这页混合了承担两类完全不同的事情：

1. provider 引导与导入前置动作
2. provider draft 的仓库发布动作

其中：

- draft 发布链已经有很强的远端真验证据
- `preview-import / import` 有真实宿主 API 证据，但缺单页动作级 acceptance
- `rollback / reconcile` 根本不是当前页面显式 UI

因此把整页粗暴标成“已闭环”会夸大页面能力；标成“未闭环”又会抹掉 draft publish 这条已经很扎实的链。

最准确的结论只能是：

- `providers.html`：`部分闭环`

当前仓库已新增专用脚本入口：

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

它的职责是把页面内显式动作收成可重复执行的 acceptance；是否在某个具体环境真正跑成“全部通过”，仍取决于该环境的 host、provider key、repo root 与发布权限配置。

## 建议的下一步验收拆法

如果要把 `providers.html` 继续收口成真正的动作级 acceptance，建议拆成两组：

### A. 页面内显式动作

必须补页面级 acceptance 的动作：

1. 加载目录
2. `preview-import`
3. `import`
4. draft `save`
5. draft `update`
6. draft `delete`
7. draft `publish`

这组动作可以直接定义为“`providers.html` 页面 acceptance”。

### B. 后端 provider 运维动作

当前不应强行算到 `providers.html` 的动作：

1. `rollback`
2. `reconcile`
3. `provider status`
4. `access status`
5. `import-batches`

这组动作有两条路：

- 要么新增一个 “Provider Operations” 视图
- 要么明确归到脚本/API 运维面，而不是当前前端页

## 推荐的补强顺序

如果继续做，优先级建议是：

1. 先给 `providers.html` 补页面内显式动作的 acceptance 记录
2. 再决定要不要把 `rollback / reconcile / status / import-batches` 真正做进一个可视化运维页

原因很简单：

- 现在的主要问题不是后端没有能力
- 而是“这页到底承载什么”没有被正式写清楚
- 先把边界写清，再补页面级 acceptance，性价比最高

## 审计口径结论

截至 2026-05-31，针对 `providers.html` 最准确的口径是：

- 页面内显式动作：
  - `preview-import / import`：已接线，且有真实宿主 API 证据，但仍缺单页动作级 acceptance
  - `draft save / update / delete / publish`：历史闭环证据充分，其中 `publish` 证据最强
- 页面外后端动作：
  - `rollback / reconcile / status / access / import-batches`：后端已提供，但当前不应宣称为 `providers.html` 已支持的前端闭环能力