320 lines
13 KiB
Markdown
320 lines
13 KiB
Markdown
# 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。
|
||
|
||
2026-06-01 已补一轮仓库级前端门禁收口：
|
||
|
||
1. 新增最小浏览器级 smoke：`bash ./scripts/test/verify_frontend_smoke.sh`
|
||
2. `providers.html` 页面内显式动作已有独立 acceptance：`bash ./scripts/acceptance/verify_provider_admin_actions.sh`
|
||
3. `portal / logical-groups / route-health / accounts / providers` 已新增统一矩阵入口：`bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh`
|
||
4. `portal` 已新增公网 / SSH 隧道可复跑的浏览器级验收入口：`bash ./scripts/acceptance/verify_public_portal_browser.sh`
|
||
5. `deploy/tksea-portal/` 的前端资产目录与质量门禁，已同步挂到 `PROJECT_STRUCTURE.md`、`AGENTS.md`、`DEPLOYMENT.md`、`scripts/README.md`
|
||
|
||
本轮实际完成的是：
|
||
|
||
1. 复核前端静态资产与导航一致性
|
||
2. 对照页面实际调用的 API 与后端路由注册
|
||
3. 复核 `EXECUTION_BOARD.md` 中已有的远端真验证据
|
||
4. 基于仓库证据把每页状态统一打标
|
||
|
||
原始审计轮次已实际执行并通过：
|
||
|
||
```bash
|
||
bash ./scripts/test/test_tksea_portal_assets.sh
|
||
```
|
||
|
||
结果：`PASS: tksea portal assets look consistent`
|
||
|
||
2026-06-01 追加门禁：
|
||
|
||
```bash
|
||
bash ./scripts/test/verify_frontend_smoke.sh
|
||
```
|
||
|
||
结果：前端关键页面在本机 stub CRM / portal proxy 环境下，已能通过 headless `chromium` 打开、完成管理员 session 检查，并回读关键标题 / 导航 / 主动作区。
|
||
|
||
## 状态定义
|
||
|
||
- `已接线`：页面存在，API 已注册，静态检查通过
|
||
- `历史已闭环`：仓库内存在明确远端真验证据，但本轮未重新在线复验
|
||
- `部分闭环`：核心链路有闭环证据，但不是整页所有动作都被充分证明
|
||
- `仅兼容入口`：页面本身不承载业务，只负责跳转或兼容旧地址
|
||
|
||
## 总结结论
|
||
|
||
### 1. 是否“前端功能都正常”
|
||
|
||
不能直接下这个结论。
|
||
|
||
当前更准确的说法是：
|
||
|
||
- 多数已交付页面具备**历史闭环证据**
|
||
- 本轮本地静态回归通过，说明页面资产、导航、关键 API 前缀当前未明显漂移
|
||
- 仓库现在已有“静态资产回归 + 最小浏览器级 smoke”两层前端门禁
|
||
- 但仍没有完整的前端工程化 E2E 套件，所以“现在全都正常”仍不能只靠仓库证明
|
||
|
||
### 2. 是否“功能闭环”
|
||
|
||
不是所有页面都处于同一成熟度。
|
||
|
||
- `logical-groups / route-health / accounts / portal` 有较强历史闭环证据
|
||
- `providers` 当前页面内显式动作已经有独立 acceptance 入口，草稿发布链闭环证据明确
|
||
- `admin/batch-import.html` 只是兼容跳转页，不算独立闭环页
|
||
|
||
### 3. 是否“与后端对齐”
|
||
|
||
核心已交付页面与后端接口整体对齐，且页面文案多数没有夸大后端尚未提供的能力。
|
||
|
||
### 4. 是否“UI 一致”
|
||
|
||
管理端 UI 基本一致，而且导航、session、API Base、状态栏这类高重复资产已经抽到
|
||
`admin-common.css` 与 `admin-common.js`。
|
||
所以现在可以说“当前视觉与导航大体一致，而且共享运行时已落地”，但仍不能夸大成“完整前端组件体系已经建立”。
|
||
|
||
## 页面级审计矩阵
|
||
|
||
### 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 -> draft save/update/delete -> publish” 当前已具备独立 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 依赖状态”，且现在已有 dedicated public-browser acceptance 入口；但最新一轮改动尚未在 remote43 / 公网重新补一份新的执行产物
|
||
4. 管理页虽然已经统一共享导航、session/runtime 与高频登录态提示，但完整前端 E2E 仍未建立，后续仍需要依赖 smoke 与页面级 acceptance 保持稳定
|
||
|
||
## 当前建议
|
||
|
||
如果下一步继续补强，优先级应该是：
|
||
|
||
1. 把 `providers.html` 新增 acceptance 入口真正跑到 remote43 / 公网最新环境，并补执行证据
|
||
2. 运行 `bash ./scripts/acceptance/verify_public_portal_browser.sh`，把 `portal` 这轮“申请 Key 依赖状态 / 宿主泄漏收口”补一次 remote43 / 公网浏览器级真验
|
||
3. 把 `accounts / logical-groups / route-health / portal` 的历史真验证据整理成可重复执行的统一脚本入口
|
||
|
||
## 审计口径结论
|
||
|
||
截至 2026-05-31，针对“没有看到前端 review 记录，前端功能是否正常、是否闭环、是否与后端对齐、UI 是否一致”这组问题，当前最准确的统一回答是：
|
||
|
||
- 仓库过去确实缺少前端专项 review 文档，这次已开始补齐
|
||
- 前端不是“没做”或“全靠静态页摆设”，多条核心运营链路已有历史真验证据
|
||
- 但也不能笼统说“前端都正常、全部闭环”
|
||
- 更准确的事实是：
|
||
- 多数关键页面历史上已闭环
|
||
- `providers.html` 只有部分闭环证据
|
||
- 当前轮没有做新的公网复验，因此不应把“历史已闭环”说成“本轮已重新证明正常”
|