hms/docs/superpowers/specs/2026-05-21-miniprogram-production-ready-design.md

小程序上线前全面改进设计规格

日期: 2026-05-21 | 状态: Draft | 分支: feat/media-library-banner 方法: MCP 实操审查 + 3 专家组并行分析（UX/前端工程/产品安全）

背景

通过 MCP 连接微信开发者工具实际操作 59 个页面，配合 3 个专家组（UX/前端工程/产品安全）并行源码级审查，发现 8 CRITICAL / 11 HIGH / 22 MEDIUM 问题。本规格定义 5 个 Phase 的改进方案，目标 1-2 周内达到可公开测试标准。

审查方法

• MCP 实操: 连接微信 DevTools（iPhone 12 Pro 模拟器），注入 admin 认证，逐页检查加载/交互/错误
• 自动化审计: audit_all 批量检测 59 页面健康状态（35 OK / 1 CRASH / 23 路径不匹配）
• 3 专家组并行: 每组阅读 13-20 个核心源文件，按 CRITICAL/HIGH/MEDIUM/LOW 分级输出

发现汇总（去重后 TOP 问题）

CRITICAL（8 项）

#	问题	文件	影响
C1	secureGet 解密逻辑失效	secure-storage.ts:60	用户关闭小程序后重开必须重新登录
C2	Storage key 前缀不一致	request.ts:149, health.ts:20	current_patient_id 写加密读明文，X-Patient-Id header 缺失
C3	analytics_queue 前缀不一致	analytics.ts:38 vs auth.ts:266	logout 无法清除分析队列，PII 泄漏风险
C4	咨询创建无症状描述输入	consultation/create/index.tsx	医生收到空咨询请求
C5	缺少紧急求助/SOS 入口	index.tsx HomeDashboard	患者突发状况无法快速求助
C6	Token 存储弱加密（XOR + 硬编码 fallback）	secure-storage.ts:3	越狱设备可直接恢复 JWT token
C7	开发快速登录可能泄露到生产	login/index.tsx:8-9	攻击者获取 dev 凭证
C8	AI 聊天持久化需验证	messages/index.tsx	wiki 标记已修复（后端消息加载 API 已添加），需验证实际效果

HIGH（11 项）

#	问题	文件
H1	积分任务按钮无 onClick	mall/index.tsx:187
H2	告警无微信推送能力	alerts/index.tsx
H3	体征录入校验不一致	health/index.tsx:112 vs input/index.tsx:33
H4	医生端工作台 API 失败无重试	pkg-doctor-core/index.tsx
H5	家属代理操作无权限模型	family/index.tsx:47, auth.ts:226
H6	首页医护人员 reLaunch 状态丢失	index.tsx:319-329
H7	PII 明文绕过 secure storage	family/index.tsx:63
H8	化验报告缺少指标解读	reports/index.tsx:57
H9	趋势图缺少交互和 AI 解读	trend/index.tsx
H10	预约无防恶意占用机制	appointment/create/index.tsx
H11	API 无请求签名	request.ts:154

---

Phase 0（Day 1）：基础设施修复

P0-1. 修复 secureGet 解密逻辑

文件: src/utils/secure-storage.ts

问题: secureGet 第 60 行 if (raw.startsWith('{') || raw.startsWith('eyJ')) 条件判断错误。secureSet 存储的 XOR 加密 + base64 编码数据通常以 A-Za-z0-9 开头，不以 { 或 eyJ 开头，导致解密分支永远不执行。

修复:

export function secureGet(key: string): string {
  const prefixedKey = STORAGE_PREFIX + key;
  const raw = Taro.getStorageSync(prefixedKey);
  if (!raw || typeof raw !== 'string') return '';

  // 始终尝试 base64 解码 + XOR 解密（secureSet 的写入格式）
  try {
    const decoded = fromBase64(raw);
    if (decoded) {
      return xorEncrypt(decoded, ENCRYPTION_KEY);
    }
  } catch {
    // fallthrough — 可能是未加密的旧数据
  }

  // fallback: 兼容未加密的旧数据（明文 JSON/JWT 或其他值）
  return raw;
}

验证: 登录 → 完全关闭小程序 → 重新打开 → 确认自动恢复登录态（非访客页面）

P0-2. 修复 Storage Key 前缀不一致

文件:

• src/services/request.ts 第 149 行: Taro.getStorageSync('current_patient_id') → secureGet('current_patient_id')（先修此处，确保内存缓存正确填充）
• src/services/request.ts 第 218 行: Taro.removeStorageSync('current_patient_id') → secureRemove('current_patient_id')
• src/services/health.ts 第 20 行: 改用 getCachedPatientId()（依赖 request.ts 的内存缓存）
• src/stores/auth.ts 第 264-265 行: secureRemove('current_patient') / secureRemove('current_patient_id') 需同步确认写入路径一致
• src/stores/auth.ts 第 266 行: secureRemove('analytics_queue') → Taro.removeStorageSync('analytics_queue')（analytics 使用明文存储，清理也必须用明文）
• src/services/analytics.ts: 确认 analytics_queue 包含 userId/patientId，logout 时必须清除（PII 泄漏风险）

P0-3. 验证

• 注入认证 → reLaunch → 首页正确显示登录态
• 医生端工作台数据正常加载
• 请求头 X-Patient-Id 正确携带

---

Phase 1（Day 2-4）：核心体验修复

P1-1. 咨询创建添加症状描述

文件:

• src/pages/consultation/create/index.tsx — 添加 UI 字段
• src/services/consultation.ts — createSession 函数类型签名添加 description 参数

改动:

• 添加多行 <Input type='textarea'> 字段（placeholder: "请描述您的症状或问题"）
• 标记为建议填写（非必填），但未填写时 Toast 提醒"建议描述症状以便医生更快响应"
• services/consultation.ts 的 createSession 参数类型扩展，添加 description?: string
• 提交时将描述传递给后端 API（后端 DTO 已支持 description 字段）

P1-2. 体征录入统一范围校验

文件: src/pages/health/index.tsx, src/pages/pkg-health/input/index.tsx

改动:

• 复用 input/index.tsx 中已有的 num() 校验函数（非创建新文件），提取到 src/utils/vital-validation.ts
• health/index.tsx 第 112-115 行，调用提取后的 num() 替代简单的非空检查
• 保留 input/index.tsx 中的动态阈值警告逻辑（getWarnForIndicator），不降级为静态范围

P1-3. 积分任务入口修复

文件: src/pages/mall/index.tsx 第 187-192 行

方案: 暂时隐藏未实现的"积分任务"入口，仅保留"签到打卡"和"兑换记录"。后续实现后恢复显示。

- <View className='mall-action'>
-   <View className='mall-action-icon mall-action-icon--task'>
-     <Text className='mall-action-icon-text'>★</Text>
-   </View>
-   <Text className='mall-action-label'>积分任务</Text>
- </View>
+ {/* TODO: 积分任务功能待实现后恢复 */}

P1-4. 医生端首页加载优化

文件: src/pages/pkg-doctor-core/index.tsx

改动:

• loadDashboard catch 中 setDashboard({}) 确保组件不卡在永久 Loading
• loading 为 false 且 dashboard 为空对象时，统计卡片显示 -（当前已实现）
• 添加错误状态提示和重试按钮（当前缺少）

P1-5. 首页医护人员跳转优化

文件: src/pages/index/index.tsx

改动: 将 shouldRedirect 计算提前到组件顶层（useMemo），在 useDidShow 之前就确定跳转。注意：首页是 TabBar 页面，redirectTo 替换 TabBar 页面可能导致 TabBar 消失，需改为在 useDidShow 中使用 reLaunch（保留现有方式），但提前判断避免先渲染 Loading 再跳转。

---

Phase 2（Day 5-8）：功能补全

P2-1. 紧急求助入口

文件: src/pages/index/index.tsx HomeDashboard 组件

改动:

• 添加固定悬浮 SOS 按钮（右下角，红色圆形，直径 56px）
• 点击弹出确认弹窗："是否拨打机构急救电话 xxx-xxxx？"
• 电话号码从后端配置 API 获取，fallback 为租户配置的电话
• 仅在患者登录状态显示（admin/doctor 不显示）

P2-2. 告警微信推送订阅

文件: src/pages/pkg-health/alerts/index.tsx

改动:

• 页面加载时调用 Taro.requestSubscribeMessage({ tmplIds: [CRITICAL_ALERT_TEMPLATE_ID] })
• 复用 process.env.TARO_APP_WX_TEMPLATE_CRITICAL_ALERT 模板 ID
• 用户拒绝时不阻塞页面使用，仅在 subscribeStatus 中记录
• critical 级别告警列表项显示"已开启推送"或"点击开启推送"标识

P2-3. 趋势图交互增强

文件: src/pages/pkg-health/trend/index.tsx

改动:

• ECharts 配置添加 tooltip 组件（trigger: 'axis'），点击/长按显示具体日期和数值
• 血压趋势图添加收缩压+舒张压双线（series 两条线）
• 阈值区间以阴影区域显示（markArea）

P2-4. 个人中心菜单优化

文件: src/pages/profile/index.tsx

改动:

• 17 项菜单分为 4 组，每组有分组标题：

健康档案: 健康记录 / 我的报告 / AI 分析 / 诊断记录 / 用药记录
就诊服务: 我的预约 / 我的随访 / 在线咨询
透析管理: 透析记录 / 透析处方 / 知情同意
账号设置: 积分商城 / 线下活动 / 就诊人管理 / 长辈模式 / 设备同步 / 设置

• 图标：汉字替换为 <Text className='iconfont icon-xxx'> 或用 antd-mini 图标
• 每组之间添加 12px 间距和分割线

P2-5. 家属管理安全修复

文件: src/pages/pkg-profile/family/index.tsx

改动:

• edit_patient 数据改用 secureSet('edit_patient', JSON.stringify(patient)) 存储
• 编辑页从 API 获取最新患者数据（GET /health/patients/{id}），不完全依赖 Storage 中的旧数据
• Storage 数据添加 5 分钟过期检查

---

Phase 3（Day 9-12）：品质打磨

P3-1. 老年模式交互增强

• 所有可点击元素最小尺寸 56px（通过 elder-mode CSS 变量覆盖）
• 体征录入页：数值输入区增加 +/- 按钮辅助（每次步进 1）
• TabBar 图标字号 elder-mode 下放大 120%
• 考虑 P2 迭代添加语音输入（本次不实现，仅预留接口）

P3-2. 安全加固

开发快速登录保护:

• login/index.tsx 第 8-9 行: IS_DEV 和 IS_SIMULATOR 已有保护
• 实际风险：体验版（envVersion === 'trial'）也会显示开发登录按钮（IS_SIMULATOR 为 true）
• 修复：第 9 行改为 typeof __wxConfig !== 'undefined' && (__wxConfig as any).envVersion === 'develop'（仅开发版显示）
• config/index.ts 中 TARO_APP_DEV_USER/PASS 已有空字符串 fallback，无需额外修改 prod.ts

Tenant ID 安全:

• request.ts 第 161 行: X-Tenant-Id 改为从 JWT payload 的 tid 字段提取
• 不再从 Storage 读取 tenant_id

密码输入框:

• login/index.tsx 第 160 行: type="text" 改为 type="safe-password"

预约防恶意占用:

• appointment/create/index.tsx: 备注字段 maxlength=200
• 提交按钮添加 loading 态防重复点击

P3-3. 空状态和错误处理统一

• 所有列表页空状态统一使用 EmptyState 组件
• Loading 组件拆分：<Loading /> 仅用于加载中，新增 <ListEnd text="没有更多了" /> 组件（无旋转动画）
• API 失败统一显示 <ErrorRetry message="加载失败" onRetry={loadData} />

P3-4. ErrorBoundary 增强

• App 级 ErrorBoundary 添加最大重试次数（3 次），超限显示"请重启小程序"
• 咨询详情、健康数据、AI 聊天 3 个高频页面添加独立 ErrorBoundary
• componentDidCatch 调用 trackEvent('error_boundary', { error: String(error) })

P3-5. 访客首页优化

• "查看全部"改为跳转 /pages/article/index（文章列表页）
• "健康资讯"区域调用公开 API（/api/v1/health/public/articles）展示真实文章
• 3 个静态卡片（健康数据管理/积分商城/专业科普）改为动态文章数据

---

Phase 4（Day 13-14）：全量回归测试

验证清单

• MCP audit_all 59 页面全部 OK（0 CRASH / 0 ERROR）
• 4 角色测试：admin / doctor / patient / family
• 长者模式全页面验证（58/58 页面可操作）
• 并发测试：快速 Tab 切换 10 次 + 长轮询运行 + 5 个并发 API
• 生产构建：pnpm build 通过 + 主包 < 2MB + 分包各 < 2MB
• secureGet 往返测试：登录 → 关闭 → 重开 → 确认自动恢复
• 紧急求助功能端到端测试
• 告警推送订阅流程测试

---

预期交付物

Phase	天数	交付物
Phase 0	1	secureGet 修复 + Storage key 一致性
Phase 1	3	核心体验修复（咨询/体征/商城/医生端/跳转）
Phase 2	4	功能补全（SOS/推送/趋势图/菜单/家属）
Phase 3	4	品质打磨（老年模式/安全/空状态/ErrorBoundary）
Phase 4	2	全量回归测试报告
合计	14	可公开测试版本

风险和缓解

风险	概率	缓解措施
secureGet 修复影响旧版本用户	中	migrateLegacyStorage 兼容两种格式
后端缺少部分 API（告警推送模板、紧急电话）	中	Phase 2 后端同步开发，前端先 mock
ECharts 双线血压趋势性能问题	低	限制数据点数量（最多 30 天）
微信审核拒绝（SOS 按钮、订阅消息）	低	SOS 改为"联系机构"文案，订阅消息仅 critical 级别