# HMS V1 发布 — 多领域专家评审报告 > 日期: 2026-05-17 | 分支: feat/media-library-banner | 评审基准: E2E 测试报告 v1-release > 评审团: 产品专家 / 技术架构专家 / 安全专家 / 测试质量专家 / 设计UX专家 --- ## 评审摘要 | 维度 | 评分 | 趋势 | 状态 | |------|------|------|------| | 功能完整性 | 8.5/10 | -- | 核心链路畅通，3 个字段不匹配需立即修复 | | 安全性 | 7.5/10 | 较5月审计提升 | 注入防护完善，CORS + 权限边界需收紧 | | 性能 | 8.5/10 | -- | 280ms 平均响应，满足当前规模 | | 跨平台一致性 | 7.0/10 | 需关注 | 路径/方法 100% 一致，DTO 字段名 3 处不匹配 | | 用户体验 | 8.0/10 | 显著提升 | Web 25 路由 + 小程序 66 页面全覆盖 | | **综合** | **7.9/10 (B+)** | **可发布** | 修复 3 CRITICAL + 2 HIGH 后达到 V1 发布标准 | **Go/No-Go 建议: 有条件 Go（详见第 4 节）** --- ## 1. 五位专家关键洞察 ### 1.1 产品专家视角 **洞察 1: 核心用户场景覆盖度满足 V1 预期** 48 个 API 端点 + 25 个 Web 路由 + 66 个小程序页面的覆盖范围，对于一个体检中心/血透中心的健康管理平台 V1 版本来说已属完整。患者管理、预约排班、咨询管理、随访任务、健康数据这五条核心业务链路全部畅通，能够支撑医护人员的日常工作流程。 **洞察 2: 3 个 CRITICAL 字段不匹配直接影响用户信任** 药物提醒（time_slots vs reminder_times）、化验报告（indicators vs items）、健康记录（content vs overall_assessment）的字段名不匹配，虽然不影响列表查看，但会导致用户创建/编辑操作静默失败。这种"看起来能操作但数据写不进去"的问题比完全不可用更危险——它会直接损害用户对系统的信任，且用户难以判断是操作失误还是系统问题。 **洞察 3: 小程序患者端体验已达到可交付水平** 66 页面 100% 覆盖、19 API 端点全通过、并发控制（MAX=8）、响应缓存（60s TTL）、安全定时器清理等优化措施表明小程序端已经具备了交付给患者使用的基础条件。积分商城、咨询、预约等患者高频场景的功能完备性值得肯定。 **洞察 4: 首次使用体验（FTUE）存在盲区** 测试中未覆盖新用户首次登录的引导流程：新患者建档后如何绑定微信、如何查看首条健康数据、如何完成首次预约。这些"从 0 到 1"的场景是用户留存的生死线，建议在发布后第一周优先收集这部分反馈。 **洞察 5: 用户反馈收集策略建议** - 在小程序"个人中心"页面增加"意见反馈"入口（已有积分体系可激励） - 管理后台增加"帮助中心"浮动按钮，收集医护人员操作困惑 - 第一周安排 2-3 名种子用户（1 医生 + 1 护士 + 5 患者）进行任务式测试 - 每日查看 `audit_logs` 和 API 400/500 错误日志，定位用户实际遇到的障碍 --- ### 1.2 技术架构专家视角 **洞察 1: 字段不匹配是缺乏契约测试的症状而非根因** 3 个 CRITICAL 问题本质上反映了一个架构短板：前后端之间没有强制性的接口契约层。后端 DTO 使用 Rust 的 `serde` 序列化字段名（snake_case），前端 TypeScript 接口独立定义字段名，两者之间没有自动化的同步校验机制。当前项目有 52 个 API 模块、189 个后端 DTO 文件，纯靠人工维护一致性不可持续——历史数据也证明了这一点（35 次 fix 源于前后端接口不一致）。 根因分析： - `medicationReminders.ts` 使用 `time_slots` 而后端 DTO 使用 `reminder_times` —— 两端独立命名，无交叉验证 - `healthData.ts` 的化验报告接口使用 `indicators` + `doctor_interpretation`，后端实际是 `items` + `doctor_notes` —— 后端 DTO 经历过重构但前端未同步 - 健康记录的 `content`/`attachment_urls` vs `overall_assessment`/`report_file_url` —— 同理 **洞察 2: 建议引入自动化契约检测** 短期（1 周内可落地）： - 利用后端已有的 utoipa OpenAPI 生成能力，从 `openapi.json` 自动提取所有 DTO schema - 编写脚本对比前端 TypeScript interface 与 OpenAPI schema 的字段名/类型一致性 - 集成到 CI pipeline，字段不匹配时构建失败 中期（1 个月内）： - 引入 `spectral` 或 `optic` 进行 API 契约测试 - 前端 API 层考虑从 OpenAPI spec 自动生成 TypeScript 类型（如 `openapi-typescript`） - 建立后端 DTO 变更时的"破坏性变更"自动检测 **洞察 3: API 版本管理现状评估** 当前所有端点使用 `/api/v1/` 前缀，这是正确的版本化起点。但需要注意： - 没有 API 版本弃用（deprecation）机制——未来字段变更时如何平滑过渡 - FHIR 端点（`/api/v1/fhir/R4/`）使用 OAuth 认证而非 JWT，与主 API 认证体系不一致 - 建议：V1 发布后冻结当前 DTO 结构，所有非向后兼容的变更走 v2 路径 **洞察 4: 权限模型的粒度问题** `stats_handler.rs` 中 `get_dashboard_stats` 使用 `health.patient.list` 权限而非专用的管理员权限。这意味着任何有"患者列表"查看权限的角色（医生、护士）都能访问管理统计仪表盘，这是 SEC-2 权限泄漏的根因。正确做法是引入 `health.admin.dashboard` 或 `health.statistics.view` 权限码，并在 seed 迁移中只分配给 admin 角色。 **洞察 5: 生产环境部署前技术检查清单** | 检查项 | 当前状态 | 要求 | |--------|---------|------| | CORS Origin 白名单 | 开发模式 wildcard | 必须配置具体域名（已有 release 模式 panic 保护） | | 数据库连接池 | 默认配置 | 建议根据并发量调整 pool_size | | 日志级别 | tracing warn+ | 生产环境建议 info + 结构化日志输出到文件 | | 健康检查端点 | 未明确 | 建议 `/health` 端点用于负载均衡探测 | | 优雅关闭 | 已实现（main.rs 优雅关闭） | 验证信号处理正确性 | | TLS | 未配置 | 生产环境必须启用 HTTPS | | 备份策略 | 未验证 | 数据库自动备份 + 恢复演练 | --- ### 1.3 安全专家视角 **洞察 1: CORS 配置已有双模式保护，但需确认生产配置** 代码审查显示 CORS 层已有合理的双模式实现（`build_cors_layer` 函数）： - `debug_assertions`（开发模式）：允许 wildcard，打印警告 - `release` 模式：wildcard 时直接 panic 拒绝启动 测试中观察到 `access-control-allow-credentials: true` 是因为在开发模式下运行。**生产环境只要确保 `ERP__CORS__ALLOWED_ORIGINS` 环境变量设置正确的域名，此问题自动解决。** 但建议： - 在部署文档中明确标注此环境变量为必填项 - 添加启动时日志输出当前 CORS 配置，便于排查 **洞察 2: 管理端点权限泄漏是权限设计缺陷** 如架构专家所述，`get_dashboard_stats` 使用了 `health.patient.list` 权限而非管理员专属权限。这不是 CORS 或中间件的问题，而是权限码粒度不够。修复方案： - 新增权限码 `health.admin.statistics` - 在 `stats_handler.rs` 中将 `health.patient.list` 替换为 `health.admin.statistics` - 在角色权限 seed 中只将此权限分配给 admin 角色 - 同理审查 `get_system_health`、`get_user_activity`、`get_module_status` 等管理端点（这些已使用 `health.dashboard.manage`，但 dashboard_stats 遗漏了） **洞察 3: 认证和注入防护已达到生产级水平** 测试结果表明： - SQL 注入防护：参数化查询生效，`OR '1'='1` 返回 0 条 - XSS 防护：`