370 lines
13 KiB
Markdown
370 lines
13 KiB
Markdown
# 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
|
||
bash ./scripts/test/test_tksea_portal_assets.sh
|
||
```
|
||
|
||
最小浏览器级 smoke：
|
||
|
||
```bash
|
||
bash ./scripts/test/verify_frontend_smoke.sh
|
||
```
|
||
|
||
route 健康页 acceptance：
|
||
|
||
```bash
|
||
bash ./scripts/acceptance/verify_route_health_ui.sh
|
||
```
|
||
|
||
控制面 acceptance：
|
||
|
||
```bash
|
||
bash ./scripts/acceptance/verify_route_control_plane.sh
|
||
```
|
||
|
||
数据面 acceptance：
|
||
|
||
```bash
|
||
bash ./scripts/acceptance/verify_route_data_plane.sh
|
||
```
|
||
|
||
前端统一矩阵：
|
||
|
||
```bash
|
||
bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh
|
||
```
|
||
|
||
矩阵式 route acceptance：
|
||
|
||
```bash
|
||
bash ./scripts/acceptance/verify_route_acceptance_matrix.sh
|
||
```
|
||
|
||
Provider Admin 页面显式动作 acceptance：
|
||
|
||
```bash
|
||
bash ./scripts/acceptance/verify_provider_admin_actions.sh
|
||
```
|
||
|
||
## Review 结论模板
|
||
|
||
每次前端 review 完成后，至少输出以下字段：
|
||
|
||
- 审查日期
|
||
- 审查人
|
||
- 审查环境
|
||
- Nginx 反代是否正确
|
||
- 管理态登录是否可用
|
||
- 页面清单
|
||
- 每页状态：
|
||
- 静态存在 / 已接线 / 已闭环 / 有缺口
|
||
- 关键缺口列表
|
||
- 是否阻塞发布
|
||
- 证据链接或命令输出位置
|
||
|
||
## 当前建议结论
|
||
|
||
基于 2026-05-31 的仓库审查，当前最合理的统一口径是：
|
||
|
||
- 管理端前端**不是空白状态**，已经有多页真实静态资产和后端接口接线
|
||
- 但仓库**还没有形成前端专项验收体系**
|
||
- 因此当前不能只凭执行板就断言“已完成前端功能全部正常”
|
||
- 后续凡是声称“前端已完成”的条目，都应至少引用这份清单中的页面级闭环证据
|