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_REMEDIATION_TASK_BOARD.md
phamnazage-jpg 7ce72cbc35 docs: sync truth docs, frontend audits, and runbooks
2026-06-04 20:00:03 +08:00

22 KiB
Raw Blame History

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

  • 当前状态：

    • 已完成（truth 入口、docs 导航与目录口径已统一挂出）

  • 问题：

    • 当前前端入口、页面范围、反代依赖、验收入口分散在执行板、脚本和静态资产里

  • 目标：

    • 形成一个正式文档，明确：
      • 前端资产目录
      • 页面清单
      • 反代依赖
      • 页面与后端接口映射
      • 页面当前状态

  • 主要文件：

    • 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 已补历史语义与 deployment-facing 前端资产说明）

  • 问题：

    • 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 / DEPLOYMENT / scripts/README / verify_quality_gates 已补前端 gate）

  • 问题：

    • 当前 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 把已有历史真验证据统一成可重跑入口

  • 当前状态：

    • 已完成（portal / logical-groups / route-health / accounts / providers 已有统一矩阵入口）

  • 问题：

    • 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

  • 当前状态：

    • 已完成（headless chromium + 本机 stub CRM / portal proxy 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、状态栏、配色和局部脚本
  • 当前状态：
    • 已完成（2026-06-01）
  • 目标：
    • 提取共享资产，例如：
      • admin-common.css
      • admin-common.js
      • 共享导航片段约定
  • 主要文件：
    • deploy/tksea-portal/admin/*.html
    • deploy/tksea-portal/
    • scripts/test/test_tksea_portal_assets.sh
  • 输出：
    • 减少重复代码和样式漂移
  • 验收：
    • 修改一个公共导航或 session 行为，不需要在 4-6 个页面重复改
  • 实际落地：
    • 已新增 deploy/tksea-portal/admin-common.css
    • 已新增 deploy/tksea-portal/admin-common.js
    • admin/index.html、admin/logical-groups.html、admin/route-health.html、admin/accounts.html、admin/providers.html、admin-batch-import.html 已切到共享导航与共享 session/API Base/status runtime
    • scripts/test/test_tksea_portal_assets.sh 已增加共享资产引用断言
    • scripts/test/verify_frontend_smoke.sh 已验证抽取后页面仍可真实加载
  • 优先级：
    • Should

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

  • 问题：
    • 目前各页虽大体一致，但错误提示和状态栏语气、字段名、回读行为仍有分散实现
  • 当前状态：
    • 已完成（2026-06-01）
  • 目标：
    • 统一：
      • API 错误展示
      • 登录态提示
      • 成功后回读
      • “当前边界”提示文案
  • 主要文件：
    • deploy/tksea-portal/admin/*.html
    • docs/2026-05-31-FRONTEND_REVIEW_CHECKLIST.md
  • 输出：
    • 页面行为一致，不只视觉一致
  • 验收：
    • 管理员切换页面时不会遇到完全不同的反馈模型
  • 实际落地：
    • admin-common.js 已统一 note / warn / warning / error / danger tone 归一化
    • 管理员 会话检查 / 登录成功 / 登录失败 / 退出成功 / 退出失败 / 缺少凭证 已收口到共享 runtime
    • accounts / logical-groups / route-health / providers / admin-batch-import 已移除重复或相互冲突的 session 文案
    • 页面登录按钮现在统一由 session status 区反馈，不再一页写详情区、一页写状态栏、一页直接透传原始错误
  • 优先级：
    • Should

F4. 用户 Portal 闭环补强

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

  • 问题：
    • 当前用户 portal 的产品层已经较完整，但“申请测试 Key”仍依赖宿主兼容线路
  • 当前状态：
    • 已完成（2026-06-01）
  • 目标：
    • 页面上明确区分：
      • 逻辑分组产品态
      • 宿主兼容线路依赖态
      • 无法申请时的具体原因
  • 主要文件：
    • deploy/tksea-portal/index.html
    • internal/app/portal_api.go
    • docs/2026-05-31-FRONTEND_CLOSURE_AUDIT.md
  • 输出：
    • 用户端不再只看到“失败”，而能看到失败类型
  • 验收：
    • 目录可读但申请不可用 的场景能被明确解释
  • 实际落地：
    • portal 已新增独立“申请 Key 依赖状态”说明区
    • 页面现在显式区分：
      • 可直接申请
      • 可申请，调用前需确认状态
      • 待补开通
      • 待人工整理
      • 仅目录可见
    • selection-summary / entitlement / usage guides / session summary 已统一引用这一状态模型
  • 优先级：
    • Should

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

  • 问题：
    • portal 已转到 logical-group 产品层，但仍残留部分宿主兼容实现细节
  • 当前状态：
    • 已完成（2026-06-01）
  • 目标：
    • 明确哪些宿主字段必须保留，哪些应继续下沉
  • 主要文件：
    • deploy/tksea-portal/index.html
    • docs/PLUGIN_REQUIREMENTS_OVERVIEW_2026-05-28.md
    • docs/2026-05-31-FRONTEND_CLOSURE_AUDIT.md
  • 输出：
    • 用户端产品语言进一步收口
  • 验收：
    • 普通用户主视角不再被宿主概念主导
  • 实际落地：
    • portal 主文案已从“兼容宿主线路 / allowed_groups / group_id”收口为“申请 Key 依赖 / 申请资格 / 申请来源”
    • 用户态主视角不再把宿主分组数字作为核心展示
    • 宿主兼容分组仍保留在后端发放流程中，但不再主导普通用户页面叙事
  • 优先级：
    • 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 信息丰富，但对前端页面证据没有统一模板
  • 当前状态：
    • 已完成（2026-06-01）
  • 目标：
    • 固定每个前端条目的记录结构：
      • 页面
      • 动作
      • 接口
      • 真实回读
      • 是否留测试垃圾
  • 主要文件：
    • docs/EXECUTION_BOARD.md
  • 输出：
    • 后续前端条目结构统一，利于审计
  • 验收：
    • 不再需要从长篇执行板里手工提炼页面闭环
  • 实际落地：
    • EXECUTION_BOARD.md 顶部已新增“前端记录模板”
    • 同文件已新增“前端页面统一索引”，统一覆盖：
      • /portal/
      • /portal/admin/logical-groups.html
      • /portal/admin/route-health.html
      • /portal/admin/accounts.html
      • /portal/admin/providers.html
      • /portal/admin-batch-import.html
      • /portal/admin/batch-import.html
    • 每个条目现已固定记录：
      • 页面
      • 动作
      • 接口
      • 最近真实回读
      • 测试垃圾
      • 当前结论
  • 优先级：
    • 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 资产（已完成，2026-06-01）
  4. F3-T2 统一错误与状态提示语义（已完成，2026-06-01）
  5. F5-T2 标准化执行板记录模板（已完成，2026-06-01）

第三批：按产品需要推进

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

按迭代排期

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

本周必须做

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 资产（已完成，2026-06-01）

  • 完成结果：
    • 已提取共享 admin-common.css / admin-common.js
    • 主要管理页已接入共享导航、session、API Base 与状态栏逻辑

4. F3-T2 统一错误与状态提示语义（已完成，2026-06-01）

  • 完成结果：
    • 管理页的 session 错误/成功提示已统一收口到共享 runtime
    • 页面局部状态栏不再混用不同口径的登录反馈

5. F5-T2 标准化执行板记录模板（已完成，2026-06-01）

  • 完成结果：
    • EXECUTION_BOARD.md 已提供统一前端模板与页面索引
    • 后续不需要再从历史长段中手工拼装页面闭环结论

6. F4-T1 显式暴露用户 portal 的“申请 Key”依赖状态（已完成，2026-06-01）

  • 完成结果：
    • 目录可读但申请不可用 的场景已经能在用户页被明确解释

暂缓

1. F2-T3 新增 Provider Operations 页面

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

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

  • 暂缓原因：
    • 当前主要问题是门禁、边界、闭环证据，不是技术栈本身
  • 重启条件：
    • 完成前端最小门禁和 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 运维能力
  • 一旦这页边界与验收收口，整套前端审查口径会立刻稳定很多
Reference in New Issue View Git Blame Copy Permalink