sub2api-cn-relay-manager/docs/2026-05-31-FRONTEND_REMEDIATION_TASK_BOARD.md

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 运维能力
• 一旦这页边界与验收收口，整套前端审查口径会立刻稳定很多