# sub2api-cn-relay-manager 前端系统性修复完善任务清单（2026-05-31）

日期：2026-05-31

## 输入依据

本任务清单基于以下审查结果整理：

- `docs/2026-05-31-FRONTEND_REVIEW_CHECKLIST.md`
- `docs/2026-05-31-FRONTEND_CLOSURE_AUDIT.md`
- `docs/2026-05-31-PROVIDERS_ACTION_ACCEPTANCE_MATRIX.md`

## 总体目标

把当前前端从“有多页真实资产和部分历史闭环证据，但缺统一前端验收与边界治理”的状态，收口成：

1. 页面范围清晰
2. 闭环证据可重复执行
3. 前后端边界不漂移
4. 管理端 UI 行为一致
5. 发布前有最小前端门禁

## 当前问题归纳

### P0 级问题

- 前端真实资产在 `deploy/tksea-portal/`，但仓库长期缺少前端专项 source of truth
- `PRD.md` 与实际交付范围存在明显漂移，导致“前端算不算已完成”口径不稳
- 多数页面只有历史真验证据，没有统一可重复的前端 acceptance 入口

### P1 级问题

- `providers.html` 页面边界不清，后端 provider 运维动作和当前页面能力容易被混为一谈
- 当前只有静态资产回归，没有浏览器级 smoke/E2E 门禁
- 管理页视觉和交互基本一致，但靠多份静态 HTML 手工复制维护，长期漂移风险高

### P2 级问题

- 用户 portal 仍有部分链路依赖宿主兼容线路，不是完全插件产品层闭环
- provider 运维动作还停留在 API / 脚本层，未进入正式前端运维视图

## 执行原则

- 先收口证据，再补 UI
- 先修边界，再扩能力
- 先补最小门禁，再谈重构
- 不做 SPA 重写，不引入无必要前端框架迁移

## 任务板

### F0. 前端范围与口径收口

#### F0-T1 建立前端 source of truth

- 问题：
  - 当前前端入口、页面范围、反代依赖、验收入口分散在执行板、脚本和静态资产里
- 目标：
  - 形成一个正式文档，明确：
    - 前端资产目录
    - 页面清单
    - 反代依赖
    - 页面与后端接口映射
    - 页面当前状态
- 主要文件：
  - `docs/2026-05-31-FRONTEND_REVIEW_CHECKLIST.md`
  - `docs/2026-05-31-FRONTEND_CLOSURE_AUDIT.md`
  - `docs/2026-05-31-PROVIDERS_ACTION_ACCEPTANCE_MATRIX.md`
  - `docs/PROJECT_STRUCTURE.md`
  - `docs/SOURCE_OF_TRUTH.md`
- 输出：
  - 在 `SOURCE_OF_TRUTH.md` 或独立 frontend source-of-truth 文档中挂出统一入口
- 验收：
  - 新人只读一份文档就能知道“前端在哪、有哪些页、哪些页已闭环、哪些只是兼容入口”
- 优先级：
  - `Must`

#### F0-T2 修正文档边界漂移

- 问题：
  - `PRD.md` 仍写“首版暂不做 Web 控制台”，与现状不符
- 目标：
  - 明确是：
    - `PRD` 保持历史事实，但补“后续范围已扩展”的说明
    - 还是显式新增“前端扩展边界”文档承接
- 主要文件：
  - `docs/PRD.md`
  - `docs/EXECUTION_BOARD.md`
  - `docs/PLUGIN_REQUIREMENTS_OVERVIEW_2026-05-28.md`
- 输出：
  - 不再出现“PRD 说没做，执行板说已完成”的冲突口径
- 验收：
  - 前端是否在交付范围内，有明确单一解释
- 优先级：
  - `Must`

#### F0-T3 把前端 review 纳入项目门禁

- 问题：
  - 当前 `AGENTS.md` 质量门禁偏 Go/后端，没有前端专项 gate
- 目标：
  - 把前端 review / acceptance 最小要求加入项目门禁
- 主要文件：
  - `AGENTS.md`
  - `docs/DEPLOYMENT.md`
  - `scripts/README.md`
- 输出：
  - 形成最小门槛，例如：
    - `test_tksea_portal_assets.sh`
    - 指定前端 acceptance 脚本
    - 页面级审计文档更新
- 验收：
  - 以后任何前端变更不能只跑 Go 门禁就宣称完成
- 优先级：
  - `Must`

### F1. 前端验收体系补齐

#### F1-T1 为 `providers.html` 补页面内显式动作 acceptance

- 当前状态：
  - `已完成（脚本与本地伪远端回归已落地）`
- 问题：
  - 当前 `providers.html` 只有动作级审计矩阵，没有页面内显式动作的统一验收脚本
- 目标：
  - 至少覆盖：
    - 目录加载
    - `preview-import`
    - `import`
    - draft `save`
    - draft `update`
    - draft `delete`
    - draft `publish`
- 主要文件：
  - `deploy/tksea-portal/admin/providers.html`
  - `scripts/acceptance/`
  - `scripts/test/`
  - `docs/2026-05-31-PROVIDERS_ACTION_ACCEPTANCE_MATRIX.md`
  - `docs/EXECUTION_BOARD.md`
- 输出：
  - 新增一条可重复执行的 provider-admin acceptance 入口
- 验收：
  - 能对每个页面内显式动作给出：
    - 请求
    - 回读
    - 页面证据或结果 JSON
- 优先级：
  - `Must`

#### F1-T2 把已有历史真验证据统一成可重跑入口

- 问题：
  - `logical-groups`、`route-health`、`accounts`、`portal` 的历史真验证据散落在 `EXECUTION_BOARD.md`
- 目标：
  - 为这些页面建立统一的 acceptance 入口或至少统一入口文档
- 主要文件：
  - `scripts/acceptance/verify_route_health_ui.sh`
  - `scripts/acceptance/verify_route_control_plane.sh`
  - `scripts/acceptance/verify_route_data_plane.sh`
  - `docs/2026-05-31-FRONTEND_CLOSURE_AUDIT.md`
  - `docs/ROUTE_ACCEPTANCE_MATRIX.md`
- 输出：
  - 页面级 acceptance 索引表
- 验收：
  - 不再只能从执行板里手工翻历史记录判断闭环
- 优先级：
  - `Must`

#### F1-T3 增加最小浏览器级 smoke

- 问题：
  - 当前只有静态字符串检查，没有浏览器级基础回归
- 目标：
  - 至少补一层最小 smoke，覆盖：
    - 页面可打开
    - 导航可跳
    - 管理员 session 可检查
    - 关键页面主标题 / 主动作 / 结果区存在
- 主要文件：
  - `scripts/test/`
  - `docs/DEPLOYMENT.md`
  - `docs/2026-05-31-FRONTEND_REVIEW_CHECKLIST.md`
- 输出：
  - 一个不依赖完整产品重构的轻量 smoke gate
- 验收：
  - 前端页面不再只靠 `grep` 文本检查就放行
- 优先级：
  - `Must`
- 说明：
  - 优先轻量方案，不先做大而全的 Playwright 套件

### F2. `providers.html` 边界与能力收口

#### F2-T1 正式声明 `providers.html` 的页面边界

- 问题：
  - 容易把 `rollback / reconcile / status / import-batches` 误认为这页已前端支持
- 目标：
  - 页面文案、文档、验收矩阵三处统一：
    - 页面内显式动作是什么
    - 页面外 provider 运维动作是什么
- 主要文件：
  - `deploy/tksea-portal/admin/providers.html`
  - `docs/2026-05-31-PROVIDERS_ACTION_ACCEPTANCE_MATRIX.md`
  - `docs/2026-05-31-FRONTEND_CLOSURE_AUDIT.md`
- 输出：
  - 页面边界不再靠口头解释
- 验收：
  - 任何 review 不会再把“后端有接口”误写成“页面已支持”
- 优先级：
  - `Must`

#### F2-T2 决策：provider 运维动作是否进入正式前端

- 问题：
  - `rollback / reconcile / status / access status / import-batches` 现在有后端能力，但没有正式前端承载
- 目标：
  - 做出明确产品决策：
    - 方案 A：继续停留在脚本/API 运维面
    - 方案 B：新增正式的 `Provider Operations` 视图
- 主要文件：
  - `docs/2026-05-31-PROVIDERS_ACTION_ACCEPTANCE_MATRIX.md`
  - `docs/PLUGIN_REQUIREMENTS_OVERVIEW_2026-05-28.md`
  - `docs/EXECUTION_BOARD.md`
- 输出：
  - 明确不再摇摆
- 验收：
  - 后续实现不会在 `providers.html` 上继续无边界堆动作
- 优先级：
  - `Must`

#### F2-T3 若选择进入前端，新增 `Provider Operations` 页面

- 前提：
  - 仅在 `F2-T2` 选择方案 B 时执行
- 目标：
  - 用独立页面承载：
    - provider status
    - access status
    - resources
    - import-batches
    - reconcile
    - rollback
- 主要文件：
  - `deploy/tksea-portal/admin/`
  - `internal/app/http_api.go`
  - `docs/openapi.yaml`
  - `scripts/test/test_tksea_portal_assets.sh`
- 输出：
  - 不再把运维动作挤在 `providers.html`
- 验收：
  - 页面动作、结果区、host_id 查询维度、错误提示全部清晰
- 优先级：
  - `Should`

### F3. 管理端 UI 一致性与去重复

#### F3-T1 抽离共享 admin 资产

- 问题：
  - 多份静态 HTML 重复维护导航、session、API Base、状态栏、配色和局部脚本
- 目标：
  - 提取共享资产，例如：
    - `admin-common.css`
    - `admin-common.js`
    - 共享导航片段约定
- 主要文件：
  - `deploy/tksea-portal/admin/*.html`
  - `deploy/tksea-portal/`
  - `scripts/test/test_tksea_portal_assets.sh`
- 输出：
  - 减少重复代码和样式漂移
- 验收：
  - 修改一个公共导航或 session 行为，不需要在 4-6 个页面重复改
- 优先级：
  - `Should`

#### F3-T2 统一错误与状态提示语义

- 问题：
  - 目前各页虽大体一致，但错误提示和状态栏语气、字段名、回读行为仍有分散实现
- 目标：
  - 统一：
    - API 错误展示
    - 登录态提示
    - 成功后回读
    - “当前边界”提示文案
- 主要文件：
  - `deploy/tksea-portal/admin/*.html`
  - `docs/2026-05-31-FRONTEND_REVIEW_CHECKLIST.md`
- 输出：
  - 页面行为一致，不只视觉一致
- 验收：
  - 管理员切换页面时不会遇到完全不同的反馈模型
- 优先级：
  - `Should`

### F4. 用户 Portal 闭环补强

#### F4-T1 显式暴露“申请 Key”链路依赖状态

- 问题：
  - 当前用户 portal 的产品层已经较完整，但“申请测试 Key”仍依赖宿主兼容线路
- 目标：
  - 页面上明确区分：
    - 逻辑分组产品态
    - 宿主兼容线路依赖态
    - 无法申请时的具体原因
- 主要文件：
  - `deploy/tksea-portal/index.html`
  - `internal/app/portal_api.go`
  - `docs/2026-05-31-FRONTEND_CLOSURE_AUDIT.md`
- 输出：
  - 用户端不再只看到“失败”，而能看到失败类型
- 验收：
  - `目录可读但申请不可用` 的场景能被明确解释
- 优先级：
  - `Should`

#### F4-T2 评估是否继续保留宿主兼容泄漏

- 问题：
  - portal 已转到 logical-group 产品层，但仍残留部分宿主兼容实现细节
- 目标：
  - 明确哪些宿主字段必须保留，哪些应继续下沉
- 主要文件：
  - `deploy/tksea-portal/index.html`
  - `docs/PLUGIN_REQUIREMENTS_OVERVIEW_2026-05-28.md`
  - `docs/2026-05-31-FRONTEND_CLOSURE_AUDIT.md`
- 输出：
  - 用户端产品语言进一步收口
- 验收：
  - 普通用户主视角不再被宿主概念主导
- 优先级：
  - `Could`

### F5. 发布门禁与维护流程

#### F5-T1 前端发布前最小检查标准固化

- 问题：
  - 现在前端放行标准更多靠执行板记录，不够制度化
- 目标：
  - 形成一条最小前端 release checklist
- 主要文件：
  - `docs/DEPLOYMENT.md`
  - `docs/REAL_HOST_ACCEPTANCE_CHECKLIST.md`
  - `docs/2026-05-31-FRONTEND_REVIEW_CHECKLIST.md`
- 输出：
  - 发布前必须勾选：
    - 静态资产回归
    - 页面级 acceptance
    - 文档同步
- 验收：
  - 前端上线不再只凭“页面 200 + 人工看过”放行
- 优先级：
  - `Must`

#### F5-T2 执行板记录模板标准化

- 问题：
  - 当前 `EXECUTION_BOARD.md` 信息丰富，但对前端页面证据没有统一模板
- 目标：
  - 固定每个前端条目的记录结构：
    - 页面
    - 动作
    - 接口
    - 真实回读
    - 是否留测试垃圾
- 主要文件：
  - `docs/EXECUTION_BOARD.md`
- 输出：
  - 后续前端条目结构统一，利于审计
- 验收：
  - 不再需要从长篇执行板里手工提炼页面闭环
- 优先级：
  - `Should`

## 建议实施顺序

### 第一批：立即做

1. `F0-T1` 建立前端 source of truth
2. `F0-T2` 修正文档边界漂移
3. `F0-T3` 把前端 review 纳入门禁
4. `F1-T1` 为 `providers.html` 补页面内显式动作 acceptance
5. `F1-T3` 增加最小浏览器级 smoke
6. `F2-T1` 正式声明 `providers.html` 页面边界
7. `F5-T1` 固化前端发布前最小检查标准

### 第二批：紧随其后

1. `F1-T2` 把已有历史真验证据统一成可重跑入口
2. `F2-T2` 决策 provider 运维动作是否进入正式前端
3. `F3-T1` 抽离共享 admin 资产
4. `F3-T2` 统一错误与状态提示语义
5. `F5-T2` 标准化执行板记录模板

### 第三批：按产品需要推进

1. `F2-T3` 新增 `Provider Operations` 页面
2. `F4-T1` portal 的“申请 Key”依赖状态显式化
3. `F4-T2` 继续下沉宿主兼容泄漏

## 按迭代排期

这部分不是重复任务板，而是把上面的任务压成真正可执行的排期顺序。

### 本周必须做

#### 1. `F0-T1` 建立前端 source of truth

- 原因：
  - 现在已经有 review/checklist/audit/matrix 四份前端文档，但还没有正式挂到项目统一 truth 入口
- 目标产物：
  - 在 `docs/SOURCE_OF_TRUTH.md` 或等价入口中正式引用前端文档
  - 在 `docs/PROJECT_STRUCTURE.md` 明确 `deploy/tksea-portal/` 是前端真实资产目录
- 本周完成标准：
  - 新人进入仓库后，不会再先去 `web/` 找前端

#### 2. `F0-T2` 修正文档边界漂移

- 原因：
  - 这是前端范围所有争议的根源
- 目标产物：
  - `PRD / EXECUTION_BOARD / PLUGIN_REQUIREMENTS_OVERVIEW` 对前端交付范围给出单一解释
- 本周完成标准：
  - 不再出现“PRD 说不做 Web 控制台，但执行板写多页前端已完成”的冲突表述

#### 3. `F0-T3` 把前端 review 纳入项目门禁

- 原因：
  - 现在最大风险不是“没有页面”，而是前端变更没有正式 gate
- 目标产物：
  - `AGENTS.md`、`docs/DEPLOYMENT.md`、`scripts/README.md` 明确前端最小门禁
- 本周完成标准：
  - 任何涉及 `deploy/tksea-portal/` 的改动，不能只跑 Go 门禁就算完成

#### 4. `F2-T1` 正式声明 `providers.html` 页面边界

- 原因：
  - 这是当前 review 里最容易被误解的页面
- 目标产物：
  - 页面文案、总审计文档、动作级矩阵三处口径完全一致
- 本周完成标准：
  - `rollback / reconcile / status / import-batches` 不再被误写成这页已支持的前端动作

#### 5. `F1-T1` 为 `providers.html` 补页面内显式动作 acceptance

- 原因：
  - 这是当前最关键的实质性验收缺口
- 目标产物：
  - 至少覆盖：
    - 目录加载
    - `preview-import`
    - `import`
    - draft `save / update / delete / publish`
- 本周完成标准：
  - `providers.html` 从“部分闭环但口径模糊”升级到“页面内显式动作有独立 acceptance”

#### 6. `F1-T3` 增加最小浏览器级 smoke

- 原因：
  - 现在只有静态字符串检查，防不了页面级退化
- 目标产物：
  - 一个轻量 smoke，至少覆盖页面可开、导航可跳、主标题/主动作/结果区存在
- 本周完成标准：
  - 发布前不再只靠 `test_tksea_portal_assets.sh`

#### 7. `F5-T1` 固化前端发布前最小检查标准

- 原因：
  - 没有 release checklist，就算补了验收也容易再次失效
- 目标产物：
  - 前端 release checklist
- 本周完成标准：
  - 发布前必须显式勾选前端检查项

### 下一迭代

#### 1. `F1-T2` 把已有历史真验证据统一成可重跑入口

- 为什么放下一迭代：
  - 这项收益很高，但需要先把本周的门禁和边界收口，否则入口会继续漂移
- 交付目标：
  - `logical-groups / route-health / accounts / portal` 不再主要依赖执行板历史记录判断闭环

#### 2. `F2-T2` 决策 provider 运维动作是否进入正式前端

- 为什么放下一迭代：
  - 这是产品/运维边界决策，不该阻塞本周基础收口
- 交付目标：
  - 明确选择：
    - 继续留在脚本/API 面
    - 或新增 `Provider Operations` 视图

#### 3. `F3-T1` 抽离共享 admin 资产

- 为什么放下一迭代：
  - 这是减少重复和长期漂移的工程优化，不是当前最急 gate 问题
- 交付目标：
  - 提取共享 `admin-common.css` / `admin-common.js` 或等价方案

#### 4. `F3-T2` 统一错误与状态提示语义

- 为什么放下一迭代：
  - 先把 acceptance 和边界固定，再统一交互反馈更稳
- 交付目标：
  - 管理页统一错误提示、登录态反馈、成功后回读提示和边界说明

#### 5. `F5-T2` 标准化执行板记录模板

- 为什么放下一迭代：
  - 这项会显著提升后续审计效率，但不阻塞本周修复
- 交付目标：
  - 前端条目在 `EXECUTION_BOARD.md` 中采用统一结构记录

#### 6. `F4-T1` 显式暴露用户 portal 的“申请 Key”依赖状态

- 为什么放下一迭代：
  - 用户 portal 当前已有较强历史闭环证据，优先级低于管理端门禁和 provider 页
- 交付目标：
  - `目录可读但申请不可用` 的场景能在用户页明确解释

### 暂缓

#### 1. `F2-T3` 新增 `Provider Operations` 页面

- 暂缓原因：
  - 在 `F2-T2` 做出正式产品决策前，不应直接开做
- 重启条件：
  - 明确决定把 `rollback / reconcile / status / access / import-batches` 做成正式前端能力

#### 2. `F4-T2` 继续下沉宿主兼容泄漏

- 暂缓原因：
  - 这是产品化质量提升项，不是当前最核心的稳定性或验收缺口
- 重启条件：
  - 用户 portal 的依赖状态已显式化，且团队确认要继续推进普通用户产品层收口

#### 3. 管理端整体重构或前端框架迁移

- 暂缓原因：
  - 当前主要问题是门禁、边界、闭环证据，不是技术栈本身
- 重启条件：
  - 完成前端最小门禁和 acceptance 体系后，再评估是否值得重构

## 排期建议摘要

如果按一个正常迭代节奏推进，最合理的执行顺序是：

### 本周

1. 收口文档口径
2. 收口 `providers.html` 页面边界
3. 补 `providers.html` 页面内显式动作 acceptance
4. 加最小浏览器 smoke
5. 固化发布前 front-end checklist

### 下一迭代

1. 把已有历史闭环页收成统一 acceptance 入口
2. 决策 provider 运维动作是否进入正式前端
3. 做管理端共享资产和交互一致性整理
4. 规范执行板记录模板

### 后续

1. 再决定要不要新增 `Provider Operations`
2. 再推进用户 portal 更彻底的产品层收口

## 不建议现在做的事

- 不建议现在把整套静态页面重写成 SPA
- 不建议先做大而全的前端框架迁移
- 不建议先做纯视觉重设计
- 不建议在页面边界未定之前，把 provider 运维动作继续堆进 `providers.html`

## 完成标准

可认为“前端系统性修复完成”的最小标准是：

1. 前端范围与页面状态有单一 source of truth
2. 项目门禁里正式出现前端 review / acceptance
3. `providers.html` 的页面内显式动作有独立 acceptance
4. 管理端至少有一层最小浏览器级 smoke
5. `PRD / EXECUTION_BOARD / 审计文档` 对前端范围不再互相冲突

## 当前最关键的判断

如果只能先做一件事，优先做：

- `F1-T1` 为 `providers.html` 补页面内显式动作 acceptance

原因：

- 这是当前审查里边界最模糊、最容易被误判为“全闭环”的页面
- 它同时连接导入主链、草稿发布链和后端 provider 运维能力
- 一旦这页边界与验收收口，整套前端审查口径会立刻稳定很多