feat(frontend): complete local UI remediation for web, portal, and dashboard

2026-06-16 15:02:01 +08:00
parent 9d239fe2c3
commit 40ee7f4dc0
10 changed files with 1572 additions and 238 deletions
--- a/docs/CURRENT_STATE.md
+++ b/docs/CURRENT_STATE.md
@@ -7,10 +7,12 @@
 1. 本文件
 2. docs/FINAL_COMPLETION_REPORT_2026-06-13.md
 3. docs/P0_P1_P2_REMEDIATION_PLAN_2026-06-14.md（当前整改板；2026-06-15 已做状态归一）
-4. docs/ACTIVE_REMEDIATION_2026-06-13.md
-5. product/PRD.md / product/ROADMAP.md / docs/IMPLEMENTATION_PLAN_v2.md
-6. docs/PRODUCTION_DEPLOYMENT_CHECKLIST_2026-06-15.md
-7. reports/PRODUCT_PLANNING_TECH_ALIGNMENT_REVIEW_2026-06-13.md（历史评审快照）
+4. docs/FRONTEND_UI_AUDIT_2026-06-16.md
+5. docs/FRONTEND_UI_EXECUTION_BOARD_2026-06-16.md
+6. docs/ACTIVE_REMEDIATION_2026-06-13.md
+7. product/PRD.md / product/ROADMAP.md / docs/IMPLEMENTATION_PLAN_v2.md
+8. docs/PRODUCTION_DEPLOYMENT_CHECKLIST_2026-06-15.md
+9. reports/PRODUCT_PLANNING_TECH_ALIGNMENT_REVIEW_2026-06-13.md（历史评审快照）

 ---

@@ -114,6 +116,9 @@
 - 用户端 Web 自助支付闭环缺失
 - 生产通知链已有底层 validated/delivered 状态机、portal 通知审计页、后台独立通知审计页、运维告警审计页与 watchdog alert sink；已支持 SMTP/IM webhook sink 代码接入，但仍缺线上真实通道配置后的生产联调
 - 前台入口已支持基础资料填写、最多 5 个附件上传与 5 步向导（基础信息 / 偏好与目标 / 已有方案与附件 / 协议确认 / 提交确认）；仍缺更完整文件类型策略与更细粒度错误提示
+- 2026-06-16 前端专项审计结论：用户端首页 / 定价页 / 结账页存在明显 AI 模板痕迹、开发术语外露与商业转化不足；后台 `/dashboard` 仍偏开发者自检页。当前执行板见 `docs/FRONTEND_UI_EXECUTION_BOARD_2026-06-16.md`
+- 2026-06-16 第二轮本地整改已完成：首页、定价页、结账页、portal 向导页 / 状态页、后台 `/dashboard` 已完成首轮产品化与去技术暴露重构；剩余前端工作聚焦 design token 基线与更强回归门禁
+- 2026-06-16 第三轮本地整改已完成：`admin/static/portal-ui.css` 已建立为共享样式基线，关键用户页面已接入 shared CSS，并补齐页面级回归断言；前端整改范围已本地收口，剩余仅为 Git 交付或后续更深层视觉迭代
 - 业务数据备份 / 恢复 / 密钥托管已有本地基线与验证，但异机备份和生产接入仍不足
 - 隐私政策 / 服务协议 / 监护人同意 / 数据保留与删除流程仍缺前台/客服自助工单与正式法务版本

--- a/docs/FRONTEND_UI_AUDIT_2026-06-16.md
+++ b/docs/FRONTEND_UI_AUDIT_2026-06-16.md
@@ -0,0 +1,245 @@
+# FRONTEND_UI_AUDIT_2026-06-16
+
+状态词: 本地审计完成（代码审计 + 浏览器视觉审计 + 基础门禁验证）
+真相源: `docs/CURRENT_STATE.md`
+适用范围: T12 用户端 Web 自助 MVP + `/dashboard` 管理后台 UI
+
+---
+
+## 1. 审计目标
+
+本次审计聚焦以下问题：
+
+- UI 设计是否专业
+- 是否存在明显 AI 模板痕迹
+- 是否达到大厂级产品设计能力
+- 前端是否遵循行业最佳实践
+- 用户体验是否足以支持真实付费转化
+
+---
+
+## 2. 审计方法与证据
+
+### 2.1 代码审计
+
+关键文件：
+
+- `admin/routes/web_public.py`
+- `admin/routes/ui.py`
+- `admin/routes/notifications.py`
+- `admin/static/dashboard.html`
+- `admin/static/dashboard.js`
+
+代码结构证据：
+
+- `admin/routes/web_public.py`：11 处 `<!doctype html>`、43 处 `style=`、3 处 `<script>`
+- `admin/routes/notifications.py`：3 处 `<!doctype html>`、17 处 `style=`
+- 前端页面主要由 Python 内联 HTML + inline style/script 拼接生成，缺少 design system / 组件层 / token 层。
+
+### 2.2 实测页面
+
+已在本地服务 `http://127.0.0.1:18081` 实际打开并审查：
+
+- `/`
+- `/pricing`
+- `/checkout/standard`
+- `/dashboard`
+
+### 2.3 测试证据
+
+命令：
+`. .venv/bin/activate && python -m pytest admin/tests/test_web_public.py admin/tests/test_admin_ui_pages.py -q`
+
+结果：
+`13 passed, 2 warnings in 1.59s`
+
+### 2.4 真实运行缺口证据
+
+`POST /api/public/orders` 在本地真实运行返回 500。
+
+根因日志：
+
+- `MissingEncryptionKey`
+- `GAOKAO_ORDERS_FERNET_KEY 未设置`
+
+结论：测试通过 ≠ 用户真实下单可用。
+
+---
+
+## 3. 总体结论
+
+### 3.1 用户端 Web 自助前端
+
+结论: 未达到上线质量
+
+判断：
+
+- UI 专业度: 未达到
+- 去 AI 痕迹: 未达到
+- 大厂级产品化: 未达到
+- 前端最佳实践: 条件达到
+- 用户体验: 未达到
+
+### 3.2 管理后台前端
+
+结论: 未达到专业后台标准
+
+判断：
+
+- 仍偏开发者自检页 / 最小仪表盘
+- 技术细节暴露严重
+- 数据可视化与空状态设计不足
+- 不符合大厂后台的导航、权限、状态、信息层级标准
+
+---
+
+## 4. 关键问题清单
+
+### P0 / Blocker
+
+1. 用户端页面暴露工程/开发术语
+
+- 证据:
+  - `Mock 支付沙箱`
+  - `支付接入建设中`
+  - `最小 Web 自助闭环`
+- 影响:
+  - 直接破坏真实用户信任，尤其在高考付费场景下属于转化阻断。
+
+2. 真实下单闭环在当前运行环境中失败
+
+- 证据:
+  - `POST /api/public/orders` → 500
+  - 根因: `GAOKAO_ORDERS_FERNET_KEY` 缺失
+- 影响:
+  - 前端结账页无法完成真实主链路验收。
+
+3. 首页 / 定价页缺少付费教育产品必需的信任构建模块
+
+- 缺失:
+  - 品牌识别
+  - 专家背书
+  - 服务保障
+  - 用户案例/社会证明
+  - FAQ / 联系方式 / 转化引导
+- 影响:
+  - 用户愿意付费的信任链不成立。
+
+### P1 / High
+
+4. 首页结构明显模板化，AI 痕迹重
+
+- 深色 hero + 三卡 + 白底圆角 section，是高度通用 SaaS 模板。
+- “当前自助流程建设重点”像内部研发 TODO，不像用户价值说明。
+
+5. 定价页商业信息密度严重不足
+
+- 三档卡片只有标题+价格+按钮
+- 无功能对比、无推荐档、无适用人群、无交付说明
+- 99 元主推档没有视觉强调
+
+6. 结账页是开发表单，不是商业结账页
+
+- 无订单摘要
+- 无支付方式选择
+- 无信任锚点/保障信息
+- 无更完整状态反馈（loading / success / recoverable error）
+
+7. 管理后台暴露技术细节
+
+- 证据:
+  - `最小仪表盘`
+  - `接口: /api/stats/dashboard`
+  - `admin_users 总数`
+- 影响:
+  - 页面像开发者工具，不像业务后台。
+
+### P2 / Medium
+
+8. 前端缺少统一 design system
+
+- 无共享 token / 组件库 / 统一交互模式
+- inline style 多，后续一致性难以保证
+
+9. Portal 向导页与状态页仍偏系统页
+
+- 虽然功能路径存在，但视觉和产品语义仍缺少打磨
+- 更像“内部系统流程页”，不是付费服务体验页
+
+10. 可维护性不足
+
+- 内联 HTML / style / script 导致页面迭代成本高
+- 不利于后续去 AI 痕迹与大厂化设计统一落地
+
+---
+
+## 5. 页面级判定
+
+### `/` 首页
+
+结论: 粗糙待重构
+
+主要问题：
+
+- AI 模板感强
+- C 端/B 端入口混线
+- 缺少商业化首页必备信任模块
+- 信息架构像介绍一个开发项目，而不是销售一个教育服务
+
+### `/pricing` 定价页
+
+结论: 粗糙待重构
+
+主要问题：
+
+- 直接暴露 `Mock 支付沙箱` / `支付接入建设中`
+- 套餐卡没有功能清单与推荐策略
+- 商业转化设计不足
+
+### `/checkout/standard` 结账页
+
+结论: 条件达标（仅表单可用），不具备商业结账页质量
+
+主要问题：
+
+- 可提交最小表单，但产品化/支付转化设计不足
+- 无订单摘要、无信任设计、无支付认知引导
+- 真实接口当前还被配置缺口阻断
+
+### `/dashboard` 管理后台
+
+结论: 粗糙待重构
+
+主要问题：
+
+- 技术细节直出
+- 登录与业务看板混在一起
+- 图表空状态设计和数据语义都不专业
+
+---
+
+## 6. 建议的整改策略
+
+优先顺序：
+
+1. 先修 P0（去开发文案 + 真实下单闭环约束 + 用户信任链）
+2. 再修 P1（首页/定价/结账三页产品化重构）
+3. 最后修 P2（统一 design system + dashboard 专业化）
+
+首批必须先动的 3 个页面：
+
+1. `/pricing`
+2. `/checkout/standard`
+3. `/`
+
+后台 `/dashboard` 排在第二批，因为当前商业转化损失主要发生在用户端链路。
+
+---
+
+## 7. 关联执行板
+
+执行真相请看：
+
+- `docs/FRONTEND_UI_EXECUTION_BOARD_2026-06-16.md`
+
+本报告负责解释问题；执行板负责推动整改。
--- a/docs/FRONTEND_UI_EXECUTION_BOARD_2026-06-16.md
+++ b/docs/FRONTEND_UI_EXECUTION_BOARD_2026-06-16.md
@@ -0,0 +1,369 @@
+# FRONTEND_UI_EXECUTION_BOARD_2026-06-16
+
+状态词: 当前有效前端整改执行板
+真相源: `docs/CURRENT_STATE.md`
+审计来源: `docs/FRONTEND_UI_AUDIT_2026-06-16.md`
+
+---
+
+## 1. 当前门禁结论
+
+结论: 用户端前端未达到上线质量；后台前端未达到专业后台标准。
+
+进展更新（2026-06-16 本轮本地实现）:
+进展更新（2026-06-16 本轮本地实现）:
+
+- B-UI-01 已完成：去除用户可见开发术语，并把缺少加密密钥时的下单失败改为友好 503 提示
+- B-UI-02 已完成：`/pricing` 已完成首轮商业化重构
+- B-UI-03 已完成：`/checkout/standard` 已完成首轮转化链重构
+- H-UI-01 已完成：首页已完成首轮品牌/信任/信息架构重构
+- H-UI-02 已完成：Portal 资料向导与状态页已完成首轮产品化重构
+- H-UI-03 已完成：后台 `/dashboard` 已完成首轮去技术暴露与专业化重构
+- M-UI-01 已完成：已建立共享 `portal-ui.css` 作为前端样式基线
+- M-UI-02 已完成：已补关键页面 shared CSS 链接与页面级回归断言
+- 当前剩余仅为 Git 交付（commit / 三仓推送）或下一轮更深层视觉迭代
+
+禁止事项:
+
+- 不得在用户可见页面继续保留 `Mock 支付沙箱`、`支付接入建设中`、`最小 Web 自助闭环` 等开发文案
+- 不得把“测试通过”误报成“用户真实可用”
+- 不得先做装饰性美化，跳过信任链、信息架构和关键路径设计
+- 不得把后台 `/dashboard` 的技术暴露问题当成纯文案小问题忽略
+
+---
+
+## 2. 最短闭环主线
+
+推荐执行顺序:
+
+1. B-UI-01 用户端去开发术语与真实运行前置约束收口
+2. B-UI-02 定价页商业化重构
+3. B-UI-03 结账页转化链重构
+4. H-UI-01 首页品牌/信任/信息架构重构
+5. H-UI-02 Portal 向导页与状态页产品化
+6. H-UI-03 后台仪表盘去技术暴露与专业化重构
+7. M-UI-01 建立前端 design token / 共享样式基线
+8. M-UI-02 补前端真实验收门禁与回归样例
+
+说明:
+
+- 第一批先改 `/pricing`、`/checkout/standard`、`/`，因为这三页直接影响付费转化。
+- `/dashboard` 放第二批，但必须纳入本轮执行板，不再拖延为“以后再美化”。
+
+---
+
+## 3. 执行任务清单
+
+### B-UI-01 用户端去开发术语与真实运行前置约束收口
+
+Owner: engineer / PM
+优先级: P0
+状态: completed（本地验证完成）
+
+目标:
+
+- 去掉所有用户可见开发术语，补齐真实运行前置约束说明，避免假可用界面。
+
+文件:
+
+- 修改: `admin/routes/web_public.py`
+- 修改: `admin/tests/test_web_public.py`
+- 参考: `docs/FRONTEND_UI_AUDIT_2026-06-16.md`
+
+完成标准:
+
+- 页面不再出现以下文案：
+  - `Mock 支付沙箱`
+  - `支付接入建设中`
+  - `最小 Web 自助闭环`
+- 若真实支付/下单前置仍未满足，必须改成用户可理解的非技术提示或仅在内部环境显示
+- 重新跑相关页面测试并更新断言
+
+验证方法:
+
+- `grep -R "Mock 支付沙箱\|支付接入建设中\|最小 Web 自助闭环" -n admin/routes admin/static`
+- 浏览器重新打开 `/` `/pricing` `/checkout/standard`
+
+依赖:
+
+- 无
+
+---
+
+### B-UI-02 定价页商业化重构
+
+Owner: frontend-ui-expert / engineer
+优先级: P0
+状态: completed（本地验证完成）
+
+目标:
+
+- 把 `/pricing` 从模板定价卡改成真正可转化的商业化套餐页。
+
+文件:
+
+- 修改: `admin/routes/web_public.py::_render_pricing_page`
+- 测试: `admin/tests/test_web_public.py`
+
+完成标准:
+
+- 每个套餐卡至少包含：
+  - 标题
+  - 价格
+  - 适用人群
+  - 3-5 条功能清单
+  - CTA
+- `99元 完整志愿方案` 作为主推档，需视觉高亮
+- 页面增加至少一个信任模块：服务保障 / FAQ / 联系方式 / 专家背书占位
+- 移除任何开发状态横幅
+
+验证方法:
+
+- 浏览器审查 `/pricing`
+- 断言测试补齐新文案/结构
+
+依赖:
+
+- B-UI-01
+
+---
+
+### B-UI-03 结账页转化链重构
+
+Owner: frontend-ui-expert / engineer
+优先级: P0
+状态: completed（本地验证完成）
+
+目标:
+
+- 把 `/checkout/standard` 从表单页升级为可付费的结账页。
+
+文件:
+
+- 修改: `admin/routes/web_public.py::_render_checkout_page`
+- 测试: `admin/tests/test_web_public.py`
+
+完成标准:
+
+- 增加订单摘要区
+- 增加服务说明/交付说明/隐私与保障提示
+- 优化字段分组：联系人 / 考生 / 备注
+- 增加更专业的 submit 状态反馈（loading / error / success）
+- 不再出现内部术语，如“最小下单”
+
+验证方法:
+
+- 浏览器审查 `/checkout/standard`
+- 真实 `POST /api/public/orders` 至少在具备必需 env 时可成功
+- 若 env 缺失，错误提示必须专业且可诊断，不暴露堆栈
+
+依赖:
+
+- B-UI-01
+
+---
+
+### H-UI-01 首页品牌/信任/信息架构重构
+
+Owner: PM / frontend-ui-expert / engineer
+优先级: P1
+状态: completed（本地验证完成）
+
+目标:
+
+- 让首页从“项目介绍页”变成“高考付费服务落地页”。
+
+文件:
+
+- 修改: `admin/routes/web_public.py::_render_landing_page`
+- 测试: `admin/tests/test_web_public.py`
+
+完成标准:
+
+- 去掉 C 端首页中的后台入口并弱化内部链接
+- 增加品牌/服务价值主张
+- 增加至少一个信任模块（专家、案例、保障、流程）
+- “当前自助流程建设重点”改成用户视角表达
+
+验证方法:
+
+- 浏览器审查 `/`
+- 页面不再像内部开发首页
+
+依赖:
+
+- B-UI-01
+
+---
+
+### H-UI-02 Portal 向导页与状态页产品化
+
+Owner: frontend-ui-expert / engineer
+优先级: P1
+状态: completed（本地验证完成）
+
+目标:
+
+- 提升 `/portal/{token}/info` 与 `/portal/{token}/status` 的产品体验与用户理解成本控制。
+
+文件:
+
+- 修改: `admin/routes/web_public.py::_render_info_page`
+- 修改: `admin/routes/web_public.py::_render_status_page`
+- 测试: `admin/tests/test_web_public.py`
+
+完成标准:
+
+- 5 步向导有更清晰层级、状态、帮助文案
+- 状态页有更明确的下一步引导、通知状态、交付状态表达
+- 不再只是系统数据回显页
+
+验证方法:
+
+- 浏览器打开 portal 页面（有 token 时）
+- 检查步骤/状态表达是否面向家长用户，而不是内部系统
+
+依赖:
+
+- B-UI-03
+
+---
+
+### H-UI-03 后台仪表盘去技术暴露与专业化重构
+
+Owner: frontend-design-reviewer / engineer
+优先级: P1
+状态: completed（本地验证完成）
+
+目标:
+
+- 把 `/dashboard` 从开发者自检页提升为专业运营后台。
+
+文件:
+
+- 修改: `admin/static/dashboard.html`
+- 修改: `admin/static/dashboard.js`
+- 测试: `admin/tests/test_admin_ui_pages.py`
+
+完成标准:
+
+- 去掉以下用户可见技术暴露：
+  - `最小仪表盘`
+  - `接口: /api/stats/dashboard`
+  - `admin_users 总数`
+- 登录区与业务区分层更清晰
+- 指标/图表补齐 loading/empty/error 语义
+- 关键快捷入口不再使用廉价裸链接样式
+
+验证方法:
+
+- 浏览器审查 `/dashboard`
+- 文案与结构不再像开发自检页
+
+依赖:
+
+- 无
+
+---
+
+### M-UI-01 建立前端 design token / 共享样式基线
+
+Owner: tech-lead / engineer
+优先级: P2
+状态: completed（本地验证完成）
+
+目标:
+
+- 逐步摆脱大段 inline style，建立共享样式基线。
+
+文件:
+
+- 新建或重构: `admin/static/*.css`（待设计落点）
+- 修改: `admin/routes/web_public.py`
+- 修改: `admin/routes/notifications.py`
+
+完成标准:
+
+- 抽出颜色、圆角、间距、按钮、卡片、表单等通用规则
+- 新改页面优先复用共享样式
+- 为后续统一去 AI 痕迹提供基础设施
+
+验证方法:
+
+- inline style 数量下降
+- 新旧页面视觉一致性提升
+
+依赖:
+
+- B-UI-02
+- B-UI-03
+- H-UI-01
+
+---
+
+### M-UI-02 补前端真实验收门禁与回归样例
+
+Owner: QA / engineer
+优先级: P2
+状态: completed（本地验证完成）
+
+目标:
+
+- 让前端页面不只是测试字符串存在，而是有更贴近体验的回归门禁。
+
+文件:
+
+- 修改: `admin/tests/test_web_public.py`
+- 修改: `admin/tests/test_admin_ui_pages.py`
+- 可新增: 浏览器/HTTP smoke 用例
+
+完成标准:
+
+- 补充对关键文案、分组、按钮、信任模块的断言
+- 对真实下单闭环至少补环境前置或 fail-closed 断言
+- 对后台去技术暴露的文案补回归保护
+
+验证方法:
+
+- pytest 全绿
+- 新增断言能覆盖本轮整改目标
+
+依赖:
+
+- B-UI-02
+- B-UI-03
+- H-UI-03
+
+---
+
+## 4. 首批改造页面建议
+
+第一批（必须先做）:
+
+1. `/pricing`
+2. `/checkout/standard`
+3. `/`
+
+第二批: 4. `/dashboard` 5. `/portal/{token}/info` 6. `/portal/{token}/status`
+
+原因:
+
+- 第一批直接影响“能不能让家长愿意下单”
+- 第二批解决后台专业度和购买后的持续体验
+
+---
+
+## 5. 推荐提交边界
+
+建议按任务单独提交：
+
+- `B-UI-01: ...`
+- `B-UI-02: ...`
+- `B-UI-03: ...`
+- `H-UI-01: ...`
+
+每项整改后同步更新：
+
+- `docs/CURRENT_STATE.md`
+- 本执行板状态
+- 相关测试断言