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 ./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 已支持的前端闭环能力