# sub2api-cn-relay-manager 前端闭环审计（2026-05-31）

日期：2026-05-31

## 审计范围

本次审计只覆盖仓库中实际存在的前端资产与其证据链：

- `deploy/tksea-portal/index.html`
- `deploy/tksea-portal/admin/index.html`
- `deploy/tksea-portal/admin/logical-groups.html`
- `deploy/tksea-portal/admin/route-health.html`
- `deploy/tksea-portal/admin/accounts.html`
- `deploy/tksea-portal/admin/providers.html`
- `deploy/tksea-portal/admin-batch-import.html`
- `deploy/tksea-portal/admin/batch-import.html`
- `deploy/tksea-portal/nginx.sub.tksea.top.conf.example`

## 审计方法

本轮没有做新的公网浏览器操作，也没有重跑依赖 remote43 的在线 acceptance。

本轮实际完成的是：

1. 复核前端静态资产与导航一致性
2. 对照页面实际调用的 API 与后端路由注册
3. 复核 `EXECUTION_BOARD.md` 中已有的远端真验证据
4. 基于仓库证据把每页状态统一打标

本轮已实际执行并通过：

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

结果：`PASS: tksea portal assets look consistent`

## 状态定义

- `已接线`：页面存在，API 已注册，静态检查通过
- `历史已闭环`：仓库内存在明确远端真验证据，但本轮未重新在线复验
- `部分闭环`：核心链路有闭环证据，但不是整页所有动作都被充分证明
- `仅兼容入口`：页面本身不承载业务，只负责跳转或兼容旧地址

## 总结结论

### 1. 是否“前端功能都正常”

不能直接下这个结论。

当前更准确的说法是：

- 多数已交付页面具备**历史闭环证据**
- 本轮本地静态回归通过，说明页面资产、导航、关键 API 前缀当前未明显漂移
- 但仓库没有形成持续的前端 E2E 门禁，所以“现在全都正常”仍不能只靠仓库证明

### 2. 是否“功能闭环”

不是所有页面都处于同一成熟度。

- `logical-groups / route-health / accounts / portal` 有较强历史闭环证据
- `providers` 的草稿发布链闭环证据明确，但整页所有导入变体没有同等强度的统一证明
- `admin/batch-import.html` 只是兼容跳转页，不算独立闭环页

### 3. 是否“与后端对齐”

核心已交付页面与后端接口整体对齐，且页面文案多数没有夸大后端尚未提供的能力。

### 4. 是否“UI 一致”

管理端 UI 基本一致，但实现方式是多份静态 HTML 手工维护，不是共享组件体系。
所以可以说“当前视觉与导航大体一致”，不能说“工程上已稳定一致”。

## 页面级审计矩阵

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

- 资产：`deploy/tksea-portal/index.html`
- 当前状态：`历史已闭环`
- 前后端对齐：`是`
- UI 一致性：`与用户态目标一致，但不与 admin 共用组件`
- 证据：
  - 页面实际读取：
    - `/portal-proxy/api/v1`
    - `/portal-admin-api/api/portal`
  - `PORTAL_CATALOG_PREFIX = "/portal-admin-api/api/portal"`，见 `index.html`
  - `EXECUTION_BOARD` 已记录：
    - P4-T1：portal catalog API 远端真验通过
    - P4-T2：`/portal/` 已切到 logical group catalog
    - P4-T3：权限、订阅、Key 已投影回 logical group
    - P4-T4：使用建议与模型说明已接到公开聚合 API
- 审计判断：
  - “目录、权限、订阅、历史 key 投影”这条链路有历史闭环证据
  - 但“申请测试 Key”仍依赖宿主兼容线路，不是完全独立产品闭环

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

- 资产：`deploy/tksea-portal/admin/index.html`
- 当前状态：`已接线`
- 前后端对齐：`基本成立`
- UI 一致性：`好`
- 证据：
  - 提供到 logical groups / route health / accounts / providers / batch import 的统一入口
  - 静态资产回归脚本持续检查这些导航项存在
- 审计判断：
  - 这是入口页，不是业务闭环页
  - 它的价值在于导航与边界表达，不在于独立业务闭环

### 3. Logical Group Admin

- 资产：`deploy/tksea-portal/admin/logical-groups.html`
- 当前状态：`历史已闭环`
- 前后端对齐：`强`
- UI 一致性：`好`
- 证据：
  - 页面直接消费 `/api/logical-groups` 及 group / route / route-model 相关接口
  - 页面明确声明 route-model 首版只支持新增与查看，不假装已支持 delete / update
  - `EXECUTION_BOARD` P2-T1 已记录：
    - 管理员登录成功
    - `POST /api/logical-groups` 成功
    - `POST /api/logical-groups/{group_id}/routes` 成功
    - `GET /api/logical-groups/{group_id}` 已回读到 `shadow_group_id / shadow_host_id / upstream_base_url_hint`
- 审计判断：
  - 从仓库证据看，这页已经不只是“页面存在”，而是确实完成了 `logical_group -> route -> shadow_group` 最小闭环

### 4. Route Health Admin

- 资产：`deploy/tksea-portal/admin/route-health.html`
- 当前状态：`历史已闭环`
- 前后端对齐：`强`
- UI 一致性：`好`
- 证据：
  - 页面直接消费 `GET /api/routing/routes/health`
  - acceptance 脚本 `verify_route_health_ui.sh` 明确验证：
    - 页面返回 `Route Health Admin`
    - route cooldown / failure 状态能被写入并回读
    - `resolve` 会自动切到 fallback route
    - failover 日志与健康视图一致
  - `EXECUTION_BOARD` P2-T3 已记录：
    - 公网健康页 `HTTP 200`
    - `primary=cooldown`
    - `failing=failing`
    - `resolve.route_id=fallback-*`
    - `recent_failover_count=1`
- 审计判断：
  - 这是目前证据最强的前端页之一
  - 不只是“看状态”，而是和真实路由运行态对齐过

### 5. Provider Accounts Admin

- 资产：`deploy/tksea-portal/admin/accounts.html`
- 当前状态：`历史已闭环`
- 前后端对齐：`强`
- UI 一致性：`好`
- 证据：
  - 页面直接消费：
    - `GET /api/provider-accounts`
    - `POST /enable`
    - `POST /disable`
    - `POST /retire`
    - `GET /binding-candidates`
    - `POST /binding`
  - 页面文案明确限制：
    - 当前动作只改插件 `provider_accounts` 状态，不假装联动宿主 account
  - `EXECUTION_BOARD` P3-T2 / P3-T3 已记录：
    - 真实样本可完成 `disable -> list -> enable -> list -> retire -> list`
    - conflict binding 可读
    - `binding-candidates` 可读
    - `POST /binding` 可 assign
    - `POST /binding {"clear":true}` 可恢复 conflict
- 审计判断：
  - 帐号库存、启停、显式整理 route 归属三条链都已有远端真验
  - 这页不是“展示页”，而是实操页

### 6. Provider Admin

- 资产：`deploy/tksea-portal/admin/providers.html`
- 当前状态：`部分闭环`
- 前后端对齐：`强`
- UI 一致性：`好`
- 证据：
  - 页面直接消费：
    - `/api/packs`
    - `/api/hosts`
    - `/api/packs/{pack_id}/providers`
    - `/api/providers/{provider_id}/preview-import`
    - `/api/providers/{provider_id}/import`
    - `/api/provider-drafts*`
    - `/api/provider-drafts/{draft_id}/publish`
  - `EXECUTION_BOARD` 已记录：
    - `providers.html` 可保存/更新/删除服务端草稿
    - `publish` 会真正写 provider 文件、bump pack version、更新 checksums、`git add` + `git commit`
    - remote43 真验已确认 `create -> publish -> git commit` 闭环，且 `HEAD` 与 API 返回的 `commit_sha` 一致
  - 动作级拆分已单独沉淀到：
    - `docs/2026-05-31-PROVIDERS_ACTION_ACCEPTANCE_MATRIX.md`
- 审计判断：
  - “草稿保存 -> 发布到仓库”这条链闭环证据明确
  - `preview-import / import` 有真实宿主 API 证据，但仍缺单页动作级 acceptance
  - `rollback / reconcile` 当前并不是这页的显式 UI 动作，不应混入这页的闭环结论
  - 所以整页应标记为 `部分闭环`，而不是笼统地说“全部已闭环”

### 7. Batch Import Admin 真实页

- 资产：`deploy/tksea-portal/admin-batch-import.html`
- 当前状态：`历史已闭环`
- 前后端对齐：`强`
- UI 一致性：`与 admin 体系一致`
- 证据：
  - 页面直接消费：
    - `POST /api/batch-import/runs`
    - `GET /api/batch-import/runs/{run_id}`
    - `GET /api/batch-import/runs/{run_id}/items`
  - 页面直接展示：
    - `matched_account_state`
    - `account_resolution`
    - `provision_reused`
  - `EXECUTION_BOARD` 已记录：
    - 用 `/portal/admin-batch-import.html` 做过真实页面操作验证
    - 曾抓到 live reuse 缺口并已修正
    - 修正后二次复验确认 `account_resolution=created -> reused` 收敛，且 `provision_reused=true`、`access_status=active`
- 审计判断：
  - 这页的核心价值就是验证 batch-import 运行结果投影
  - 对这条主链来说，仓库证据支持“历史已闭环”

### 8. Batch Import 兼容入口

- 资产：`deploy/tksea-portal/admin/batch-import.html`
- 当前状态：`仅兼容入口`
- 前后端对齐：`不适用`
- UI 一致性：`有`
- 证据：
  - 页面本身只做 `meta refresh` 到 `/portal/admin-batch-import.html`
- 审计判断：
  - 这不是独立业务页
  - 它的目标只是保留统一 `/portal/admin/` 地址空间与旧入口兼容

## 交叉结论

### 功能是否闭环

按页面拆开看：

- 已有较强闭环证据：
  - 用户 Portal 的 logical-group 产品层展示
  - Logical Group Admin
  - Route Health Admin
  - Provider Accounts Admin
  - Legacy Batch Import Admin
- 只有部分闭环证据：
  - Provider Admin
- 不应被当作独立闭环页：
  - 管理首页
  - `/portal/admin/batch-import.html` 兼容跳转页

### 与后端是否对齐

整体是对齐的，理由有三点：

1. 页面调用的关键接口在 `internal/app/http_api.go` 中都能找到注册
2. 页面文案多数明确说明当前边界，不伪装后端没有的能力
3. 多个关键页面在 `EXECUTION_BOARD` 中已有写后回读或真实 API 验证记录

### UI 是否一致

可给出的审计结论是：

- 管理端导航、登录态、API Base、状态提示的产品语义基本一致
- `test_tksea_portal_assets.sh` 也在持续检查这些静态一致性
- 但这些一致性来自手工维护的多份静态 HTML，不是共享组件系统

所以：

- `当前 UI 一致性：基本成立`
- `长期稳定一致性：风险仍高`

## 当前缺口

1. 没有真正的前端专项 CI 门禁，只有静态资产检查
2. `providers.html` 虽然已经有页面内显式动作 acceptance 入口，但最新 remote43 / 公网执行证据还没有在本轮重新补齐
3. 用户 portal 的“申请 Key”链仍依赖宿主兼容线路，不是完全插件内聚
4. 多份静态 HTML 并行维护，后续最容易在 UI 细节和错误处理上产生漂移

## 当前建议

如果下一步继续补强，优先级应该是：

1. 把 `providers.html` 新增 acceptance 入口真正跑到 remote43 / 公网最新环境，并补执行证据
2. 把 `accounts / logical-groups / route-health / portal` 的历史真验证据整理成可重复执行的统一脚本入口
3. 为前端补最小浏览器回归，而不是只做静态字符串检查

## 审计口径结论

截至 2026-05-31，针对“没有看到前端 review 记录，前端功能是否正常、是否闭环、是否与后端对齐、UI 是否一致”这组问题，当前最准确的统一回答是：

- 仓库过去确实缺少前端专项 review 文档，这次已开始补齐
- 前端不是“没做”或“全靠静态页摆设”，多条核心运营链路已有历史真验证据
- 但也不能笼统说“前端都正常、全部闭环”
- 更准确的事实是：
  - 多数关键页面历史上已闭环
  - `providers.html` 只有部分闭环证据
  - 当前轮没有做新的公网复验，因此不应把“历史已闭环”说成“本轮已重新证明正常”