df1d85bfde
- T40 UI 审计计划和结果文档（docs/qa/） - wiki 更新：miniprogram 设计系统合规审计记录 + index 关键数字更新 - 审计 V2 完整报告（docs/audits/v2/） - 讨论记录文档（docs/discussions/） - 设计规格和实施计划（docs/superpowers/） - 角色测试计划和结果（docs/qa/role-test-*） - Docker 生产部署配置
18 KiB
18 KiB
T40 小程序全页面 UI 审查计划
日期: 2026-05-13 | 分支: feat/media-library-banner | 状态: 编写中
目录
- 审查目标与范围 — 审查什么、达到什么标准
- 设计体系速查 — Design Token / 变量 / mixin / 长者模式规范
- 页面清单与分组 — 56 个页面按角色和功能分组，标注优先级
- 审查方法与工具 — 逐页审查流程、MCP 自动化 vs 手动、检查清单
- 审查记录模板 — 每个页面的标准记录格式
- 已完成项与已知问题 — 前序修复记录、待复查项
1. 审查目标与范围
1.1 目标
对小程序 全部 56 个页面 进行逐页 UI 审查，确保：
- 视觉一致性 — 所有页面遵循「温润东方风」设计体系（Design Token + SCSS 变量）
- 交互可用性 — 触控区域 ≥ 48px、按钮/Tab 响应正常、空态/加载态/错误态完整
- 长者模式适配 — 字号 ≥ 22px、间距放大、信息层级清晰
- 角色适配正确 — 患者/医护(Doctor/Nurse/HM)/访客 各看到正确的 UI
1.2 通过标准
每个页面的审查结果分为三级：
| 等级 | 含义 |
|---|---|
| PASS | 无问题，设计体系完全遵循 |
| PASS_WITH_ISSUES | 可用但有轻微不一致（低优先级修复） |
| NEEDS_WORK | 存在明显问题需修复后才可通过 |
1.3 范围
| 维度 | 包含 | 不包含 |
|---|---|---|
| 页面 | 主包 16 页 + 6 个子包 40 页 = 56 页 | — |
| 角色 | 访客、登录患者、Doctor、Nurse、Health Manager | Operator（后台为主，小程序体验有限） |
| 状态 | 正常态、空态、加载中、错误态 | 极端边界（如 10k+ 列表项） |
| 设备 | iPhone SE ~ iPhone 15 Pro Max 宽度 | iPad / 横屏模式 |
| 模式 | 标准模式 + 长者模式 | 深色模式（未实现） |
2. 设计体系速查
审查时的参考基准。所有页面必须遵循这些规范，偏离即为问题。
2.1 色彩系统（styles/variables.scss）
| Token | 值 | 用途 |
|---|---|---|
$pri |
#C4623A |
赤土橙，主强调色（按钮/活跃Tab/图标） |
$pri-l |
#F0DDD4 |
赤土浅，背景高亮 |
$pri-d |
#8B3E1F |
赤土深，渐变终点 |
$acc |
#5B7A5E |
鼠尾草绿，成功/完成状态 |
$acc-l |
#E8F0E8 |
成功浅背景 |
$bg |
#F5F0EB |
页面主背景（温润米底） |
$card |
#FFFFFF |
卡片白色 |
$surface-alt |
#EDE8E2 |
辅助底色（Tab 未选中/输入框背景） |
$tx |
#2D2A26 |
主文字（warm black） |
$tx2 |
#5A554F |
次文字（AA 正文 ~5.5:1） |
$tx3 |
#78716C |
淡文字（AA 大字 ~4.6:1，仅 ≥24px） |
$bd |
#E8E2DC |
边框 |
$dan |
#B54A4A |
危险红 |
$dan-l |
#FDEAEA |
危险浅背景 |
$wrn |
#C4873A |
警告琥珀 |
$wrn-l |
#FFF3E0 |
警告浅背景 |
2.2 字号 Token（styles/tokens.scss）
正常模式 10 级字号：
| Token | 正常 | 长者模式 | 用途 |
|---|---|---|---|
--tk-font-hero |
48px | 56px | 装饰图标、空状态字符 |
--tk-font-h1 |
26px | 30px | 页面/区块标题 |
--tk-font-h2 |
24px | 28px | 副标题、日期 |
--tk-font-body-lg |
28px | 34px | 大正文、按钮 |
--tk-font-body |
22px | 30px | 正文、标签 |
--tk-font-body-sm |
16px | 22px | 中等正文、列表项 |
--tk-font-num |
30px | 34px | 数值 |
--tk-font-num-lg |
34px | 40px | 大数值、统计 |
--tk-font-cap |
13px | 18px | 说明文字、时间戳 |
--tk-font-micro |
11px | 17px | 角标、标签 |
规则： 页面样式必须用 var(--tk-font-*) 而非硬编码 px 值，否则长者模式不生效。
2.3 圆角与阴影
| Token | 值 | 用途 |
|---|---|---|
$r |
16px | 卡片、输入框 |
$r-sm |
12px | 小型标签、内部元素 |
$r-xs |
8px | 微型圆角 |
$r-lg |
20px | 大卡片、头部区域 |
$r-pill |
999px | 胶囊按钮、角标 |
$shadow-sm |
0 1px 4px rgba(45,42,38,0.04) |
列表项 |
$shadow-md |
0 2px 12px rgba(45,42,38,0.08) |
卡片 |
$shadow-lg |
0 8px 32px rgba(45,42,38,0.12) |
浮层 |
2.4 常用 Mixin（styles/mixins.scss）
| Mixin | 用途 | 使用场景 |
|---|---|---|
@include flex-center |
水平垂直居中 | 图标容器、按钮文字 |
@include serif-number |
Georgia 字体 + 等宽数字 | 数值显示、首字图标 |
@include section-title |
区块标题样式 | 各页 section 标题 |
@include tag($bg, $color) |
标签胶囊 | 状态标签 |
@include touch-target |
最小触控区域 48×48 | 可点击元素 |
@include btn-primary |
主按钮 | 确认/提交 |
@include btn-outline |
描边按钮 | 次要操作 |
@include safe-bottom |
底部安全区 | 列表页底部留白 |
2.5 长者模式机制
原理： tokens.scss 中 .elder-mode 选择器覆写所有 --tk-* 变量，elder-mode.scss 做结构性布局调整（触控放大、间距放大、网格降列）。
审查要点：
- 字号引用
var(--tk-font-*)→ 长者模式自动放大 - 字号硬编码 px → 长者模式 不生效，需修复
- 触控区域 ≥ 48px（正常）/ ≥ 56px（长者）
- 体征网格 2 列 → 1 列（长者模式避免溢出）
3. 页面清单与分组
56 个页面按角色和功能分 7 组。优先级：P0 = 核心流程必审，P1 = 次要功能，P2 = 低频页面。
3.1 患者端 — TabBar 页面（P0）
| # | 路由 | 页面 | 访客守卫 | 说明 |
|---|---|---|---|---|
| 1 | pages/index/index |
首页 | 内置 GuestHome | 登录前轮播图+文章+登录引导；登录后体征进度+快捷操作 |
| 2 | pages/health/index |
健康数据 | GuestGuard 组件 | 体征录入 Tab、趋势柱状图、AI 建议卡片 |
| 3 | pages/messages/index |
消息 | GuestGuard 组件 | 咨询/通知分段控件、消息卡片列表 |
| 4 | pages/profile/index |
我的 | 内置 isGuest | 用户卡片+积分统计+分组菜单+退出登录 |
3.2 患者端 — 核心功能页面（P0）
| # | 路由 | 页面 | 说明 |
|---|---|---|---|
| 5 | pages/consultation/index |
咨询列表 | 发起咨询按钮+会话卡片列表 |
| 6 | pages/consultation/detail/index |
咨询详情 | 聊天气泡+日期分割+输入栏+长轮询 |
| 7 | pages/appointment/index |
预约列表 | 预约卡片+状态标签+悬浮新建按钮 |
| 8 | pages/appointment/create/index |
创建预约 | 多步骤表单（科室→医生→日期时间） |
| 9 | pages/appointment/detail/index |
预约详情 | 单个预约详情+取消操作 |
| 10 | pages/mall/index |
积分商城 | 积分余额卡+签到+商品网格 |
| 11 | pages/login/index |
登录 | 微信登录+手机绑定 |
3.3 患者端 — 子包功能页面（P1）
| # | 路由 | 页面 | 说明 |
|---|---|---|---|
| 12 | pages/pkg-health/trend/index |
健康趋势 | 趋势图+时间范围切换 |
| 13 | pages/pkg-health/input/index |
体征录入 | Zod 校验的录入表单 |
| 14 | pages/pkg-health/daily-monitoring/index |
日常监测 | 血压/体重/血糖/出入量录入 |
| 15 | pages/pkg-health/alerts/index |
健康告警 | 患者端告警列表 |
| 16 | pages/pkg-mall/exchange/index |
积分兑换 | 确认兑换流程 |
| 17 | pages/pkg-mall/orders/index |
兑换订单 | 订单列表+状态 Tab |
| 18 | pages/pkg-mall/detail/index |
商品详情 | 积分商品详情 |
| 19 | pages/article/index |
文章列表 | 文章分类筛选+列表 |
| 20 | pages/article/detail/index |
文章详情 | 富文本+分享 |
| 21 | pages/events/index |
线下活动 | 活动列表+报名 |
| 22 | pages/device-sync/index |
设备同步 | BLE 扫描+连接+数据同步 |
3.4 患者端 — 个人中心子页面（P1）
| # | 路由 | 页面 | 说明 |
|---|---|---|---|
| 23 | pages/pkg-profile/health-records/index |
健康记录 | 分页记录列表 |
| 24 | pages/pkg-profile/reports/index |
我的报告 | 化验报告列表 |
| 25 | pages/pkg-profile/followups/index |
我的随访 | 随访任务+状态 Tab |
| 26 | pages/pkg-profile/family/index |
就诊人管理 | 家庭成员列表+切换 |
| 27 | pages/pkg-profile/family-add/index |
添加就诊人 | 表单（姓名/关系/性别/生日） |
| 28 | pages/pkg-profile/medication/index |
用药记录 | 药物 CRUD |
| 29 | pages/pkg-profile/diagnoses/index |
诊断记录 | 诊断列表+类型/状态标签 |
| 30 | pages/pkg-profile/consents/index |
知情同意 | 同意记录列表+撤销 |
| 31 | pages/pkg-profile/dialysis-records/index |
透析记录 | 患者端透析记录列表 |
| 32 | pages/pkg-profile/dialysis-records/detail/index |
透析记录详情 | 单次透析详情 |
| 33 | pages/pkg-profile/dialysis-prescriptions/index |
透析处方 | 处方列表 |
| 34 | pages/pkg-profile/dialysis-prescriptions/detail/index |
处方详情 | 单个处方详情 |
| 35 | pages/pkg-profile/elder-mode/index |
长者模式 | 模式切换开关 |
| 36 | pages/pkg-profile/settings/index |
设置 | 清缓存+退出登录 |
| 37 | pages/ai-report/list/index |
AI 分析列表 | 分析报告列表+状态标签 |
| 38 | pages/ai-report/detail/index |
AI 分析详情 | 报告渲染 |
| 39 | pages/report/detail/index |
化验报告详情 | 指标列表+参考范围 |
| 40 | pages/followup/detail/index |
随访详情 | 患者端随访提交 |
3.5 医护端 — 工作站（P0）
| # | 路由 | 页面 | 角色可见 | 说明 |
|---|---|---|---|---|
| 41 | pages/doctor/index |
医护工作台 | D/N/HM | 工作概览卡片+健康审核+快捷操作网格 |
| 42 | pages/doctor/patients/index |
患者列表 | D/N | 搜索+患者卡片+分页 |
| 43 | pages/doctor/patients/detail/index |
患者详情 | D/N | 患者信息+健康摘要 |
| 44 | pages/doctor/consultation/index |
咨询管理 | D/N | 4 个状态 Tab+会话卡片 |
| 45 | pages/doctor/consultation/detail/index |
咨询详情(医护) | D/N | 医护端聊天界面 |
| 46 | pages/doctor/followup/index |
随访管理 | D/N/HM | 5 个状态 Tab+任务列表 |
| 47 | pages/doctor/followup/detail/index |
随访详情(医护) | D/N | 任务详情+提交记录 |
| 48 | pages/doctor/alerts/index |
告警中心 | D/N/HM | 严重级别+状态 Tab |
| 49 | pages/doctor/alerts/detail/index |
告警详情 | D/N/HM | 单条告警+确认/解除 |
| 50 | pages/doctor/report/index |
化验审核 | D | 搜索+报告列表 |
| 51 | pages/doctor/report/detail/index |
化验详情(医护) | D | 报告详情+医生备注 |
| 52 | pages/doctor/action-inbox/index |
待办事项 | D/N/HM | 行动收件箱 |
3.6 医护端 — 透析管理（P2）
| # | 路由 | 页面 | 说明 |
|---|---|---|---|
| 53 | pages/doctor/dialysis/index |
透析记录(医护) | 透析记录列表+状态 Tab |
| 54 | pages/doctor/dialysis/detail/index |
透析详情(医护) | 单次透析详情 |
| 55 | pages/doctor/dialysis/create/index |
新建透析 | 透析参数表单 |
| 56 | pages/doctor/prescription/index |
透析处方(医护) | 处方列表 |
| 57 | pages/doctor/prescription/detail/index |
处方详情(医护) | 单个处方详情 |
| 58 | pages/doctor/prescription/create/index |
新建处方 | 透析器/透析液/抗凝参数 |
3.7 法律页面（P2）
| # | 路由 | 页面 | 说明 |
|---|---|---|---|
| 59 | pages/legal/user-agreement |
用户协议 | 静态富文本 |
| 60 | pages/legal/privacy-policy |
隐私政策 | 静态富文本 |
注意： 实际页面数 56（主包 16 + 子包 40），上表含部分共享路由（如
pages/article/index同时服务访客和登录患者），总计 60 条目。
4. 审查方法与工具
4.1 审查流程（每个页面）
Step 1 静态代码审查 — 读 .tsx + .scss，对照 §2 设计体系检查
Step 2 截图/自动化 — 通过 MCP 注入对应角色身份 → navigate → screenshot
Step 3 对照检查清单 — 逐项判定 PASS / ISSUE
Step 4 记录结果 — 按 §5 模板填入审查记录
4.2 静态代码审查要点
逐文件检查以下维度：
| 维度 | 检查项 | 怎么查 |
|---|---|---|
| 字号 | 是否全部使用 var(--tk-font-*) |
Grep 硬编码 font-size: [0-9]+px |
| 颜色 | 是否使用 SCSS 变量 $pri/$tx/... |
Grep 硬编码 #xxxxxx（rgba 除外） |
| 圆角 | 是否使用 $r/$r-sm/... |
Grep 硬编码 border-radius: [0-9]+px |
| 触控 | 可点击元素 min-height ≥ 48px | 检查 &:active 或 onClick 所在元素 |
| 间距 | 页面内边距是否统一 20-24px | 读 padding 值 |
| 空态 | 空列表是否有提示 UI | 搜索 length === 0 分支 |
| 加载态 | 是否有 Loading 组件或状态 | 搜索 loading / Loading |
| 错误态 | API 失败是否有用户友好提示 | 搜索 catch / error |
| 长者模式 | 上述字号/触控/间距是否适配 | 切换 elder-mode 验证 |
4.3 自动化截图流程（MCP）
使用 @hms/weapp-local MCP 工具：
1. connect() — 连接 DevTools
2. inject_auth({ username }) — 注入角色身份
3. evaluate('__hms.restoreAuth()') — 恢复 zustand 状态
4. reLaunch('/pages/index/index') — 跳转到目标页
5. screenshot() — 截图
6. page_data() — 获取页面文本内容
角色注入参数：
| 角色 | username | 说明 |
|---|---|---|
| 患者 | admin | 默认注入 patient_id，进入患者首页 |
| Doctor | doctor_test | 医护工作站 |
| Nurse | nurse_test | 医护工作站 |
| Health Manager | hm_test | 医护工作站 |
| 访客 | 不注入 | 直接 reLaunch 到目标页 |
4.4 手动验证场景
MCP 无法覆盖的场景需手动在 DevTools 中验证：
- 下拉刷新动画
- 列表无限滚动加载
- 输入框聚焦/键盘弹出
- 长者模式切换效果
- 分包页面首次加载 loading
- 图片预览、分享菜单
4.5 审查分组建议
按优先级分批执行：
| 批次 | 范围 | 页面数 | 预计耗时 |
|---|---|---|---|
| Batch 1 | §3.1 TabBar 页面 | 4 | 30 min |
| Batch 2 | §3.5 医护工作站（Doctor 视角） | 12 | 60 min |
| Batch 3 | §3.2 患者端核心功能 | 7 | 45 min |
| Batch 4 | §3.3 患者端子包功能 | 11 | 60 min |
| Batch 5 | §3.4 个人中心子页面 | 18 | 90 min |
| Batch 6 | §3.6 透析管理 + §3.7 法律 | 8 | 30 min |
5. 审查记录模板
5.1 每页标准输出
每个页面审查后按此格式记录：
### P{编号} {页面名称}（{路由}）
**角色:** {访客/患者/Doctor/Nurse/HM}
**截图:** {有/无}
**结果:** {PASS | PASS_WITH_ISSUES | NEEDS_WORK}
| 维度 | 状态 | 备注 |
|------|------|------|
| 字号 Token | ✅/❌ | {如硬编码则列出具体行} |
| 颜色变量 | ✅/❌ | |
| 圆角变量 | ✅/❌ | |
| 触控区域 | ✅/❌ | |
| 空态 | ✅/❌/N/A | |
| 加载态 | ✅/❌/N/A | |
| 错误态 | ✅/❌/N/A | |
| 长者模式 | ✅/❌ | |
| 访客守卫 | ✅/❌/N/A | |
**问题清单：**
- [ ] {问题描述}（{严重级: HIGH/MEDIUM/LOW}）
5.2 汇总统计模板
全部审查完成后输出汇总：
## 审查汇总
| 分组 | 页面数 | PASS | PASS_WITH_ISSUES | NEEDS_WORK |
|------|--------|------|-----------------|------------|
| TabBar 页面 | 4 | | | |
| 患者端核心 | 7 | | | |
| 患者端子包 | 11 | | | |
| 个人中心 | 18 | | | |
| 医护工作站 | 12 | | | |
| 透析+法律 | 8 | | | |
| **合计** | **60** | | | |
**问题统计：**
- HIGH: {n} 个
- MEDIUM: {n} 个
- LOW: {n} 个
6. 已完成项与已知问题
6.1 前序验证中已修复的问题
来源: T30 完整业务链路验证（2026-05-13）
| # | 问题 | 修复文件 | 状态 |
|---|---|---|---|
| FIX-1 | 登录后首页/个人中心名称显示"访客" | pages/index/index.tsx、pages/profile/index.tsx — fallback 链改为 display_name → patient.name → username → phone后4位 → "用户" |
✅ 已修复 |
| FIX-2 | 护士工作站快捷操作布局混乱（flex → 一行挤 4-7 个按钮） | pages/doctor/index.scss — display: flex → display: grid; grid-template-columns: repeat(4, 1fr) |
✅ 已修复 |
| FIX-3 | 咨询页面访客无守卫，触发 401 API 调用 | pages/consultation/index.tsx — 添加 user 检查，未登录显示登录引导 |
✅ 已修复 |
| FIX-4 | 首屏 mount 时 zustand 状态不恢复 | app.tsx — 添加 useEffect(() => { restoreAuth(); restoreUI(); }, []) + globalThis.__hms bridge |
✅ 已修复（前序会话） |
6.2 T30 遗留问题（本审查需覆盖）
| # | 问题 | 级别 | 备注 |
|---|---|---|---|
| BUG-1 | /health/dashboard/stats 返回 404（Doctor 角色） |
MEDIUM | 可能是路由路径与测试不一致，需验证实际端点 |
| BUG-2 | /health/offline-events 返回 404（Operator 角色） |
LOW | 路由注册问题，需确认 |
| LIMIT-1 | MCP auth injection 无法触发 zustand re-render | INFO | 已通过 __hms bridge 修复，需重新编译验证 |
| LIMIT-2 | 分包页面通过 MCP navigateTo 导航失败 | INFO | DevTools 限制，需手动测试或 reLaunch |
6.3 审查执行前的准备
新会话开始审查前，需确认：
- 小程序已重新编译（
pnpm dev:weapp），包含 FIX-1~4 - 微信开发者工具已打开并扫码登录
- MCP 连接可用（
ws://localhost:9420） - 后端服务运行中（
localhost:3000） - 测试用户密码均为
Admin@2026
6.4 新会话启动指令
新会话可直接使用以下 prompt 启动审查：
执行 T40 小程序 UI 审查。计划文档在 docs/qa/T40-miniprogram-ui-audit-plan.md，
先读 §2 设计体系速查和 §3 页面清单，然后从 §3.1 TabBar 页面开始按 Batch 顺序审查。
每批完成后输出该批汇总，最后输出全量汇总。
文档结束。开始审查后，结果将记录在 docs/qa/role-test-results/T40-ui-audit-results.md。