niuniu/sub2api-cn-relay-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cf7dd35e1df19e891dadd5e64de0fbc2df99c2cc
sub2api-cn-relay-manager/docs/2026-05-31-FRONTEND_CLOSURE_AUDIT.md
phamnazage-jpg 5fbac6ef0b test(frontend): add provider admin acceptance coverage 
Add a dedicated acceptance script for providers.html, cover it in the local real-host script regression suite, and document the current frontend review baseline, closure audit, providers action matrix, and remediation task board.

This keeps the frontend acceptance boundary explicit: providers.html now has a repeatable verification entry point for its page-level actions, while non-UI provider operations remain documented as backend-only capabilities.
2026-06-01 09:58:20 +08:00

12 KiB
Raw Blame History

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 ./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 只有部分闭环证据
    • 当前轮没有做新的公网复验，因此不应把“历史已闭环”说成“本轮已重新证明正常”
Reference in New Issue View Git Blame Copy Permalink