niuniu/sub2api-cn-relay-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
13b88ba2e7ede1e6ff2acb65b2966ea6d7dae40c
sub2api-cn-relay-manager/docs/2026-05-31-FRONTEND_REVIEW_CHECKLIST.md
phamnazage-jpg 7ce72cbc35 docs: sync truth docs, frontend audits, and runbooks
2026-06-04 20:00:03 +08:00

13 KiB
Raw Blame History

sub2api-cn-relay-manager 前端 Review 清单（2026-05-31）

日期：2026-05-31

目的

这份清单用于补齐当前仓库缺失的前端专项 review 基线，避免继续出现：

  • 页面已经上线，但没有独立前端验收口径
  • 执行板写“已完成”，但无法快速判断是否真正闭环
  • 前端页面、反代配置、后端接口三者存在漂移却没人显式检查

这份文档不是 UI 设计稿，也不是测试报告；它是前端审查与验收入口。

审查范围

当前仓库内实际存在的前端资产不在 web/，而在 deploy/tksea-portal/：

  • 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

当前事实

已有

  • 有静态资产一致性检查：scripts/test/test_tksea_portal_assets.sh
  • 有最小浏览器级 smoke：scripts/test/verify_frontend_smoke.sh
  • 有部分远端 acceptance 脚本：
    • scripts/acceptance/verify_frontend_acceptance_matrix.sh
    • scripts/acceptance/verify_portal_catalog_ui.sh
    • scripts/acceptance/verify_accounts_admin_ui.sh
    • scripts/acceptance/verify_route_health_ui.sh
    • scripts/acceptance/verify_route_control_plane.sh
    • scripts/acceptance/verify_route_data_plane.sh
    • scripts/acceptance/verify_route_acceptance_matrix.sh
  • 管理端页面普遍采用相同入口：
    • /portal-admin-api/ 访问 CRM 管理接口
    • /api/admin/session 登录态

当前缺口

  • 没有完整前端工程化的 lint / build / Playwright 级 E2E 门禁
  • 逐页“页面 -> API -> 闭环结果 -> 证据”台账已开始收口，但不是每页都有统一可重跑入口
  • 用户 portal 与 admin portal 共享部署资产，但不共享组件体系，后续 UI 漂移风险高

闭环判定标准

每个页面都按同一口径判定，不允许只因为“页面能打开”就标记完成。

A. 静态存在

  • HTML 文件存在
  • 入口链接可达
  • 页面内引用的核心 API 前缀存在

B. 接口对齐

  • 页面实际调用的 API 在服务端已注册
  • 关键写操作不是伪按钮或本地假数据
  • 页面文案没有夸大后端尚未提供的能力

C. 运行闭环

  • 登录 / 鉴权通过
  • 请求可从浏览器发到反代入口
  • 关键读操作有真实返回
  • 关键写操作有真实落库或真实副作用
  • 写后可回读

D. UI 一致性

  • 管理页导航一致
  • 登录态交互一致
  • 状态栏、错误提示、主按钮语义一致
  • 页面不是孤立“拼装页”而能回到统一管理入口

只有 A+B 成立，最多算“前后端已接线”。 只有 A+B+C 成立，才算“功能闭环”。 A+B+C+D 成立，才算“可认为产品化完成”。

跨页面公共检查项

每次前端 review 必查以下 10 项：

  1. nginx.sub.tksea.top.conf.example 中是否同时保留 /portal/、/portal-proxy/、/portal-admin-api/
  2. 管理页是否都优先支持管理员 session，而不是只靠手填 token
  3. 页面中 API Base 默认值是否仍然指向同域前缀，而不是硬编码远端机器地址
  4. 页面报错时是否给出可读错误，而不是只在控制台抛异常
  5. 页面写操作后是否自动回读，而不是只提示“成功”
  6. 页面是否显式说明当前边界，避免前端能力大于后端真实能力
  7. 页面导航是否能互相到达，不出现孤岛页
  8. 页面是否保留旧地址兼容策略
  9. 页面是否把“只改插件状态”与“会改宿主资源”区分清楚
  10. 页面依赖的后端 action 是否允许为空；如果允许，是否有清晰降级提示

页面级审查矩阵

1. 用户 portal

  • 页面：deploy/tksea-portal/index.html
  • 主要用途：普通用户查看产品目录、权限、订阅、历史 key，并申请兼容 key
  • 关键前缀：
    • /portal-proxy/api/v1
    • /portal-admin-api/api/portal
  • 关键读接口：
    • /api/portal/logical-groups
    • /api/portal/logical-groups/{group_id}
    • /api/portal/logical-groups/{group_id}/models
    • 宿主侧 /auth/me
    • 宿主侧 /groups/available
    • 宿主侧 /subscriptions
    • 宿主侧 /keys
  • 必查项：
    • 未登录时是否能明确看到“目录可读 / 权限不可读”的状态差异
    • 登录后是否能同时拉到逻辑分组目录和用户自身订阅
    • “新创建 key 对应哪个逻辑分组 / 模型”是否在页面上可见
    • 目录为空时是否降级到清晰提示，而不是空白页
  • 闭环判定：
    • 目录可读
    • 用户态接口可读
    • 创建或展示 key 后能回读
  • 当前仓库级判断：
    • 已接线
    • 是否闭环依赖 portal-proxy、portal-admin-api 和宿主用户态 API 联动，必须在线真验

2. 管理首页

  • 页面：deploy/tksea-portal/admin/index.html
  • 主要用途：统一入口，不承载复杂写操作
  • 关键检查：
    • 导航是否覆盖逻辑分组、route health、accounts、providers、batch import
    • 页面文案是否仍准确反映当前安全边界
    • 旧入口是否仍可跳到新入口
  • 闭环判定：
    • 导航全可达
    • 管理态登录可用
  • 当前仓库级判断：
    • 结构存在
    • 更像入口页，不是单独业务闭环页

3. Logical Group Admin

  • 页面：deploy/tksea-portal/admin/logical-groups.html
  • 关键接口：
    • POST /api/admin/session/login
    • GET /api/admin/session
    • POST /api/logical-groups
    • GET /api/logical-groups
    • PUT /api/logical-groups/{group_id}
    • DELETE /api/logical-groups/{group_id}
    • POST /api/logical-groups/{group_id}/models
    • GET /api/logical-groups/{group_id}/models
    • DELETE /api/logical-groups/{group_id}/models/{model}
    • POST /api/logical-groups/{group_id}/routes
    • GET /api/logical-groups/{group_id}/routes
    • PUT /api/logical-groups/{group_id}/routes/{route_id}
    • DELETE /api/logical-groups/{group_id}/routes/{route_id}
    • POST /api/logical-groups/{group_id}/routes/{route_id}/models
    • GET /api/logical-groups/{group_id}/routes/{route_id}/models
  • 必查项：
    • 页面是否仍明确声明“route model 首版只支持新增与查看”
    • group / route / route model 三层数据能否顺序创建并回读
    • 删除 group 前是否对关联 route 有清晰反馈
    • 编辑 route 后 shadow_group_id / shadow_host_id 是否立即反映
  • 闭环判定：
    • logical_group -> route -> route_model 至少完成一轮 create + read back
  • 当前仓库级判断：
    • 前后端接口对齐较好
    • 需要远端真验确认删改流程和错误态

4. Route Health Admin

  • 页面：deploy/tksea-portal/admin/route-health.html
  • 关键接口：
    • GET /api/admin/session
    • POST /api/admin/session/login
    • GET /api/routing/routes/health
  • 必查项：
    • 筛选参数是否真正影响后端查询
    • healthy / cooldown / failing / disabled 汇总是否和返回数据一致
    • route 详情是否反映 sticky / failover / cooldown 的真实字段
    • 空结果、鉴权失败、后端超时是否都有页面级提示
  • 闭环判定：
    • 能登录
    • 能过滤
    • 能稳定看到 route 健康列表和详情
  • 当前仓库级判断：
    • 有脚本化验收入口
    • 是当前最接近“可独立验收”的前端页之一

5. Provider Accounts Admin

  • 页面：deploy/tksea-portal/admin/accounts.html
  • 关键接口：
    • GET /api/provider-accounts
    • GET /api/provider-accounts/{account_id}/binding-candidates
    • POST /api/provider-accounts/{account_id}/binding
    • POST /api/provider-accounts/{account_id}/enable
    • POST /api/provider-accounts/{account_id}/disable
    • POST /api/provider-accounts/{account_id}/retire
  • 必查项：
    • 页面是否持续明确“只修改插件 provider_accounts 库存状态”
    • 列表过滤是否真的作用于后端而不是前端本地过滤
    • 选中帐号后，binding 候选与详情是否一致
    • enable / disable / retire 后，状态是否能立即回读
    • clear binding 与 assign binding 是否都能真实落库
  • 闭环判定：
    • 一条帐号完成 disable -> enable 或 assign -> clear -> read back
  • 当前仓库级判断：
    • 页面边界表达相对诚实
    • 是运营闭环重要页面，必须补真实在线回归

6. Provider Admin

  • 页面：deploy/tksea-portal/admin/providers.html
  • 页面内显式接口：
    • GET /api/packs
    • GET /api/hosts
    • GET /api/packs/{pack_id}/providers
    • POST /api/providers/{provider_id}/preview-import
    • POST /api/providers/{provider_id}/import
    • GET /api/provider-drafts
    • POST /api/provider-drafts
    • PUT /api/provider-drafts/{draft_id}
    • DELETE /api/provider-drafts/{draft_id}
    • POST /api/provider-drafts/{draft_id}/publish
  • 后端相邻能力，但当前不属于页面显式动作：
    • POST /api/providers/{provider_id}/rollback
    • POST /api/providers/{provider_id}/reconcile
    • GET /api/providers/{provider_id}/status
    • GET /api/providers/{provider_id}/access/status
    • GET /api/providers/{provider_id}/import-batches
  • 必查项：
    • pack / host / provider 目录能否顺序加载
    • preview-import 与 import 的前置校验是否一致
    • 草稿 save / update / delete / publish 是否都可回读
    • publish 后 commit 结果是否展示给操作者
    • 当前页面是否仍清楚区分“新增 provider”与“导入 provider account”
  • 闭环判定：
    • 至少完成一次 draft save -> update -> publish -> 回读结果
  • 当前仓库级判断：
    • 页面内显式动作现已存在独立 acceptance 入口：scripts/acceptance/verify_provider_admin_actions.sh
    • 后端 provider 运维能力仍需单独决策是否进入正式前端

7. Batch Import Admin

  • 页面：
    • deploy/tksea-portal/admin-batch-import.html
    • deploy/tksea-portal/admin/batch-import.html
  • 页面语义：
    • admin/batch-import.html 当前只是跳转兼容页
    • 真正承载功能的是 admin-batch-import.html
  • 关键接口：
    • POST /api/admin/session/login
    • GET /api/admin/session
    • POST /api/batch-import/runs
    • GET /api/batch-import/runs/{run_id}
    • GET /api/batch-import/runs/{run_id}/items
  • 必查项：
    • 新旧入口跳转是否稳定
    • 发起 run 后，run 状态、items 列表、matched_account_state / account_resolution / provision_reused 是否都能回读
    • 失败 run 是否有可读错误，而不是只显示空结果
  • 闭环判定：
    • 发起一次 batch run，并能回读 run 与 item 结果
  • 当前仓库级判断：
    • 闭环目标清楚
    • 新旧地址并存，回归时必须同时检查

建议的 review 顺序

按风险和闭环价值排序，建议每次 review 按这个顺序执行：

  1. Nginx 反代配置检查
  2. 管理员 session 登录检查
  3. 管理首页导航检查
  4. Logical Group Admin
  5. Route Health Admin
  6. Provider Accounts Admin
  7. Provider Admin
  8. Batch Import Admin
  9. 用户 portal

原因：

  • 先检查反代和 session，后面的页面才有审查价值
  • 先看控制面最基础的 group / route，再看观测页、库存页、导入页
  • 用户 portal 依赖最多，放到最后最省排障时间

最小执行命令集

本地静态一致性：

bash ./scripts/test/test_tksea_portal_assets.sh

最小浏览器级 smoke：

bash ./scripts/test/verify_frontend_smoke.sh

route 健康页 acceptance：

bash ./scripts/acceptance/verify_route_health_ui.sh

控制面 acceptance：

bash ./scripts/acceptance/verify_route_control_plane.sh

数据面 acceptance：

bash ./scripts/acceptance/verify_route_data_plane.sh

前端统一矩阵：

bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh

矩阵式 route acceptance：

bash ./scripts/acceptance/verify_route_acceptance_matrix.sh

Provider Admin 页面显式动作 acceptance：

bash ./scripts/acceptance/verify_provider_admin_actions.sh

Review 结论模板

每次前端 review 完成后，至少输出以下字段：

  • 审查日期
  • 审查人
  • 审查环境
  • Nginx 反代是否正确
  • 管理态登录是否可用
  • 页面清单
  • 每页状态：
    • 静态存在 / 已接线 / 已闭环 / 有缺口
  • 关键缺口列表
  • 是否阻塞发布
  • 证据链接或命令输出位置

当前建议结论

基于 2026-05-31 的仓库审查，当前最合理的统一口径是：

  • 管理端前端不是空白状态，已经有多页真实静态资产和后端接口接线
  • 但仓库还没有形成前端专项验收体系
  • 因此当前不能只凭执行板就断言“已完成前端功能全部正常”
  • 后续凡是声称“前端已完成”的条目，都应至少引用这份清单中的页面级闭环证据
Reference in New Issue View Git Blame Copy Permalink