frontend: 五轮首页与复核页结构减法，逼近高信任付费服务页标准
改版主线： - /review/start: 从系统运营页改成用户结果页（不再暴露 JSON/go_step1） - 首页：省份改下拉，表单压缩为 3 字段并移出 hero 核心区 - hero: 副文案压缩为一句，去掉三张说明卡与了解流程链接 - trust strip: 4→3，右侧判断块压缩为一句风险+上传能力 - browser_vision 复验确认：说明书感已显著下降，结构已从功能堆叠过渡到决策引导 测试基线同步： - test_web_public.py: 首页副文案/流程编号/说明卡断言更新 - test_web_public_review_flow.py: 复核页断言改为用户视角文案 文档： - docs/FRONTEND_PRODUCTION_REMEDIATION_PLAN_2026-06-26.md 记录整改真相源
This commit is contained in:
Hermes Agent
395
docs/FRONTEND_PRODUCTION_REMEDIATION_PLAN_2026-06-26.md
Normal file
395
docs/FRONTEND_PRODUCTION_REMEDIATION_PLAN_2026-06-26.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# 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 浏览器真实验收 + 文档同步
|
||||
|
||||
这是当前最短、最真实、最符合生产上线要求的前端整改路径。
|
||||
Reference in New Issue
Block a user