# T40 小程序全页面 UI 审查计划

> 日期: 2026-05-13 | 分支: feat/media-library-banner | 状态: 编写中

## 目录

1. **审查目标与范围** — 审查什么、达到什么标准
2. **设计体系速查** — Design Token / 变量 / mixin / 长者模式规范
3. **页面清单与分组** — 56 个页面按角色和功能分组，标注优先级
4. **审查方法与工具** — 逐页审查流程、MCP 自动化 vs 手动、检查清单
5. **审查记录模板** — 每个页面的标准记录格式
6. **已完成项与已知问题** — 前序修复记录、待复查项

---

## 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 每页标准输出

每个页面审查后按此格式记录：

```markdown
### P{编号} {页面名称}（{路由}）

**角色:** {访客/患者/Doctor/Nurse/HM}
**截图:** {有/无}
**结果:** {PASS | PASS_WITH_ISSUES | NEEDS_WORK}

| 维度 | 状态 | 备注 |
|------|------|------|
| 字号 Token | ✅/❌ | {如硬编码则列出具体行} |
| 颜色变量 | ✅/❌ | |
| 圆角变量 | ✅/❌ | |
| 触控区域 | ✅/❌ | |
| 空态 | ✅/❌/N/A | |
| 加载态 | ✅/❌/N/A | |
| 错误态 | ✅/❌/N/A | |
| 长者模式 | ✅/❌ | |
| 访客守卫 | ✅/❌/N/A | |

**问题清单：**
- [ ] {问题描述}（{严重级: HIGH/MEDIUM/LOW}）
```

### 5.2 汇总统计模板

全部审查完成后输出汇总：

```markdown
## 审查汇总

| 分组 | 页面数 | 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`。*