gaokao-volunteer-system/docs/FRONTEND_PRODUCTION_REMEDIATION_PLAN_2026-06-26.md

FRONTEND_PRODUCTION_REMEDIATION_PLAN_2026-06-26

For Hermes: 这不是普通视觉微调计划，而是“前端真实预览推翻旧乐观结论”后的生产级整改方案。后续执行必须以真实浏览器预览 + 真实用户链路验证为准，而不是仅以旧 TestClient / E2E 通过为准。

目标:

• 把 gaokao-volunteer-system 用户端从“系统说明书式页面 + 运营流程页 + 结构正确但产品语义错误”升级为“可上线的高信任付费教育服务前端”。
• 修复首页信息架构、复核结果页语义、表单输入方式、跨页信息复用、文档上传入口表达五类核心问题。

架构判断:

• 当前前端主问题不是单点 CSS bug，而是信息架构与用户路径设计错误。
• 旧结论“前端首轮产品化已完成”只证明了字符串级回归/局部链路通过，不等于真实预览体验符合生产要求。
• 后续整改必须同时覆盖：页面结构、交互语义、组件状态、真实浏览器验证、回归测试。

技术栈:

• FastAPI + Python f-string HTML
• shared CSS: admin/static/portal-ui.css
• 页面逻辑: admin/routes/web_public.py
• 测试: pytest + TestClient + browser 真预览

---

0. 新真相与旧结论冲突说明

本轮真实预览发现，旧的“前端已完成首轮产品化收口”结论不能直接继承到生产上线结论。

已确认的新问题：

1. 首页首屏说明卡过多，页面像系统说明书，而不是高信任付费服务首页。
2. 首页 CTA 获取复核与推荐 跳转到 /review/start?... 后，用户看到的是系统审核流程/内部 JSON，而不是方案评估状态与结论。
3. 首页省份字段仍是文本输入，不是下拉选择。
4. 用户在首页输入了省份/分数/目标信息后，后续流程语义上仍存在重复索取风险，缺乏明确的“已带入/可修改”产品表达。
5. 用户可上传其他供应商/老师给出的志愿方案文档的能力存在，但未被前台明确前置为核心入口能力。

结论:

• 旧 E2E 通过 = 技术链路局部可走通
• 不等于 = 用户端产品体验达到生产上线质量

因此，本计划将旧“已完成”状态重写为“结构可运行，但生产级 UX 仍未达标”。

---

1. 生产级前端验收标准（新的硬门禁）

1.1 页面级门禁

以下页面必须逐页达到“用户目标导向”而不是“系统说明导向”：

1. /
2. /review/start?...
3. /pricing
4. /checkout/standard
5. /portal/{token}/info
6. /portal/{token}/status

1.2 用户路径门禁

以下主链路必须以真实浏览器方式复核：

1. 首页填写最小信息
2. 点击 CTA 进入复核结果页（不是流程说明页）
3. 在结果页判断：继续免费复核 / 去上传现有方案 / 去看套餐 / 去完整规划
4. 下单后基础信息被自动带入后续流程
5. 资料页支持上传现有方案文档，并以用户可理解方式展示
6. 状态页能清楚告诉用户“现在到哪一步、下一步做什么”

1.3 真实验证门禁

任何“前端完成”声明前，必须同时满足：

• pytest 相关页面测试通过
• 浏览器真实预览通过
• 至少 1 条真实用户路径从首页走到后续页面，并确认语义正确
• 不出现内部 JSON / review_result_id / go_step1 / go_full_plan 这类内部结构暴露

---

2. 问题分级（以真实预览为准）

P0

P0-1 /review/start 产品语义错误

现象:

• 当前 /review/start?... 页面标题是“方案复核入口”
• 页面内容包含：
  • 审核输入
  • 最小约束
  • 审核输出摘要
  • 核心问题
  • 下一步分流
  • 原始 JSON 结果块
• 用户点击首页 CTA 后并没有得到“结论页”，而是看到系统中间态页面

影响:

• 直接破坏主转化链路
• 用户会认为这是内部系统页或调试页
• 高信任场景下属于严重产品语义错误

根因:

• 当前 review_start_page 仍沿用运营/审核流程视角
• 没有按用户预期包装成“复核结果页 / 初步判断页”

整改方向:

• 重命名为“复核结果页”或“初步评估结果”
• 删掉原始 JSON 暴露
• 把结果重构为：
  • 当前状态
  • 初步判断
  • 风险结论
  • 建议动作
  • 下一步 CTA

验证:

• 浏览器打开 /review/start?...
• 页面不可出现原始 JSON、review_result_id、go_step1 等内部术语
• 页面必须能一眼读懂“结果是什么、下一步是什么”

P0-2 首页 CTA 与结果页不匹配

现象:

• 首页 CTA 文案是“获取复核与推荐”
• 但落点不是“结果/评估页”而是“流程说明页”

影响:

• CTA 承诺与页面交付不一致
• 典型的转化欺骗感/体验断裂

整改方向:

• 要么改 CTA 文案
• 要么改落点
• 推荐：保持 CTA，改落点为真正结果页

---

P1

P1-1 首页首屏信息架构过重，说明卡压过主任务

现象:

• 首页首屏同时展示：
  • 左侧表单
  • 多组 article 说明卡
  • 右侧强调块“我们先把现有方案看明白”
  • 下方流程说明
• 视觉密度高，像系统说明书
• 真实用户难以判断主任务优先级

影响:

• 影响转化
• 用户无法快速理解“现在要做什么”
• 容易造成你反馈中的“右侧卡压住下面流程区”的观感

整改方向:

• 首屏只保留：
  • 核心价值主张
  • 最小信息表单
  • 1 条 trust-proof strip
  • 1 个简短辅助说明区
• 把多余说明卡下沉到首屏以下
• 服务流程改成更短、更克制的时间线表达

P1-2 省份字段应从 textbox 改为下拉选择

现象:

• 当前首页省份字段仍是 textbox，placeholder 为“例如：湖南”

影响:

• 易输错
• 支持省份边界无法自然表达
• 在高信任教育产品中不专业

整改方向:

• 改为 31 省级行政区下拉
• 若部分功能有地域差异，以下拉提示或二级说明处理

P1-3 “上传现有方案文档”能力未被前置成用户能力

现象:

• 代码已支持附件上传与 portal_attachment
• 但首页和复核链路没有把“可上传其他供应商/老师方案文档”前置表达为主能力

影响:

• 核心卖点埋没
• 用户不知道系统能做“先复核他人给出的方案”

整改方向:

• 首页首屏 / 复核结果页 / 资料页都要明确：
  • 可以上传已有方案文档
  • 系统可先做免费复核

P1-4 已填基础信息需要跨页明确复用

现象:

• 技术链路上 candidate_province 等已可进入后续链路
• 但产品表达上没有清楚告诉用户“这些信息已带入后续步骤，可继续修改，不必重复填写”

影响:

• 用户会担心重复填表
• 破坏顺滑感

整改方向:

• 结果页 / 下单页 / portal info 页增加“已带入的基础信息”摘要与可修改提示
• 不在支付页重复要求输入同样基础信息

---

P2

P2-1 视觉节奏与卡片层级收缩

• 减少首屏卡片数量
• 收窄右侧强调块高度
• 流程区与信任区做层级重排

P2-2 shared CSS / design token 继续收紧

• 避免继续在 web_public.py 里堆新样式
• 将新增结果页样式优先落到 shared CSS

---

3. 系统性整改方案（执行顺序）

Phase A — 结果页语义重构（最高优先级）

目标:

• 把 /review/start 从“运营入口页”改成“复核结果页”

文件:

• admin/routes/web_public.py
• admin/tests/test_web_public_review_flow.py

必须完成:

1. 页面标题改为用户语义
2. 隐藏原始 JSON
3. 将风险等级/核心问题/下一步动作产品化
4. CTA 主次分层：
   • 主推荐动作
   • 备选动作
5. 不再使用内部动作名直接暴露给用户

验证:

• 浏览器真实打开 /review/start?...
• 用户一眼能看懂：当前结论 + 下一步

Phase B — 首页首屏重构

目标:

• 让首页从说明书变成高信任服务首页

文件:

• admin/routes/web_public.py
• admin/tests/test_web_public.py
• admin/tests/test_web_public_content_pages.py

必须完成:

1. 省份改下拉
2. 首屏说明卡减量
3. trust-proof strip 前置
4. 明确“可上传已有方案文档”
5. CTA 与后续落点一致

验证:

• 浏览器真实预览首页
• 首屏主任务清楚，说明卡不再压迫流程区

Phase C — 跨页信息复用与上传能力前置

目标:

• 把首页最小输入贯穿到结果页/下单页/资料页
• 前置上传现有方案文档能力

文件:

• admin/routes/web_public.py
• admin/tests/test_web_public_alipay_sim_e2e.py
• admin/tests/test_web_public_portal_info.py

必须完成:

1. 首页基础信息进入后续流程摘要
2. 不在支付页重复索取
3. portal info 明确支持上传其他供应商方案文档
4. 结果页给出“上传现有方案文档”入口

验证:

• 真实浏览器走：首页 → 结果页 → 下单/资料页
• 确认基础信息被带入且不重复索取

Phase D — 生产级前端验收

目标:

• 用真实浏览器验证，而不是只靠旧字符串断言

必须完成:

1. 真实打开首页
2. 填写省份/分数/目标
3. 点击 CTA
4. 验证结果页不是说明书页
5. 验证可进入套餐/资料/上传链路
6. 验证页面无内部 JSON、内部动作名暴露

输出产物:

• 新前端验收报告
• 新执行板状态更新

---

4. 真实验证策略（取代旧乐观 E2E 结论）

L1 测试验证

• pytest admin/tests/test_web_public.py admin/tests/test_web_public_review_flow.py admin/tests/test_web_public_content_pages.py admin/tests/test_web_public_portal_info.py

L2 页面结构验证

• 浏览器 snapshot + browser_vision 审查首页与结果页

L3 用户链路验证

• 首页输入 → 结果页
• 结果页 → 套餐页 / 上传入口 / 下一步动作

L4 语义验证

必须人工确认：

• 页面是在“给用户结果”
• 不是“解释系统流程”
• 不是“暴露内部 JSON / review_result_id / action slug”

---

5. 本轮结论与范围边界

当前状态:

• 旧的“前端首轮产品化完成”结论已不适合作为生产上线结论
• 真实预览已证明：首页与结果页仍存在产品语义错误

本计划不做的事:

• 不扩大到后台 /dashboard 的深度改版
• 不在本轮先做支付真实接入
• 不先做视觉装饰优化而跳过主链路语义修正

---

6. 立即执行建议

推荐按下面顺序直接推进：

1. Phase A /review/start 结果页语义重构
2. Phase B 首页首屏重构 + 省份下拉
3. Phase C 上传入口前置 + 跨页信息复用
4. Phase D 浏览器真实验收 + 文档同步

这是当前最短、最真实、最符合生产上线要求的前端整改路径。