AI-Health/docs/HANDOFF-2026-07-16.md

小脉健康项目交接文档

更新时间：2026-07-16
工作目录：D:\health_project
当前分支：main

1. 项目当前阶段

项目主体已经完成，包括 Flutter App 和 .NET 后端。目前处于：

Android 本地真机测试、功能稳定优化、前端 UI 统一、合规准备，以及等待正式环境和资质流程。

当前不是“马上提交应用商店审核”的状态。

• Android 一直以本地真机为主要测试平台。
• iOS 代码已经合入并做过基础适配，但尚未完成本地真实 iPhone 的完整回归。
• 后端及 H5 合规页面仍以本地环境为主，正式服务器、域名和 HTTPS 尚未最终切换。
• 正式 API、数据库、JWT、短信、文件存储和 CORS 要在服务器及域名确定后统一配置。
• 正式 Android keystore、发布签名、APK/AAB 仍取决于外部资质和正式配置交付。
• 苹果开发者账号、证书、Bundle ID、签名和 TestFlight 权限仍取决于外部流程。
• ICP、公安备案、软著、安全评估和应用市场账号等由外部继续推进。
• 项目明确不使用 Docker，不要围绕 Docker 增加工作。

2. Git 与代码状态

• 当前分支：main，不要创建额外分支。
• 当前提交：5288596 merge: integrate sccsbc release preparation safely。
• origin/main 当前为 fade61a，本地 main 比远端多 6 个提交。
• sccsbc 的 Apple 登录、上线准备和 Android 签名相关提交已经通过合并提交进入本地 main。
• 合并采用“保留当前新版业务和 UI、吸收对方上线准备”的方式，没有用对方旧快照覆盖现有代码。
• 当前工作区有大量未提交修改。这些包含用户现阶段 UI、iOS 适配和交互调整，不能执行 git reset --hard、git checkout -- 或用旧分支覆盖。
• 开始新修改前必须先查看 git status 和相关文件差异，只改当前任务涉及的代码。

当前主要未跟踪正式资源：

• health_app/assets/branding/login_background_v2.png
• health_app/assets/branding/drawer_background_v2.png
• health_app/assets/branding/health_login_character_transparent.png
• health_app/test/native_navigation_test.dart

3. 用户的协作习惯

• 先用用户视角解释，不要堆技术术语。
• 一次讨论一个明确问题，说明表现、原因和修改结果。
• 用户说“先讨论”时不能直接修改。
• 用户说“开始改”“动手”“去做”后直接实现，不要反复确认。
• 不要擅自扩大范围，不要增加与当前目标无关的工作量。
• 用户可能同时修改其他文件，必须保留并兼容用户改动。
• 用户通常自己构建和安装；除非明确要求，不要运行耗时构建或安装。
• 简单改动只做快速格式或静态检查，不要反复跑长测试。
• 数据删除、注销、历史对话等操作必须对应真实后端结果，不能只改前端显示。
• 修改聊天相关代码时，必须保证恢复历史对话后仍可继续聊天。

4. 已确认的 UI 方向

整体基调

• 首页现有品牌化紫色背景和整体结构基本保留。
• 普通二级页面以白色内容区为主，使用极浅中性灰建立页面与内容组边界。
• 不允许把模块颜色铺满整个页面、标题栏或大卡片。
• 风格要求干净、克制、专业、柔和，避免大面积紫色、重橙色和过亮颜色。

列表

• 同一内容组内连续排列，不要每行单独套白卡片。
• 分隔线只从文字区域开始，不贯穿左侧图标区域。
• 删除背景默认完全隐藏，左滑后才显示。
• 删除失败时不能提前从前端移除真实数据。

图标

• 全 App 图标样式必须统一，颜色可以按模块变化。
• 优先使用同一套线性、圆润图标。
• 同类列表的图标底座尺寸、圆角、图标尺寸和对齐保持一致。
• 运动模块已统一使用更合适的跑步图标，修改时要同步首页今日健康、胶囊和运动页面等所有入口。

色彩

• 通用输入焦点、选中和品牌操作继续使用 App 紫色体系。
• 模块色只用于模块识别、图标、状态和少量关键数字。
• 成功、警告、错误和信息颜色必须按语义使用，不能与模块色混用。
• 当前页面背景为 #F3F5F8，白色内容区用于建立层次。
• 当前健康模块为克制青绿色体系；运动模块为蓝靛体系；用药模块保持原有蓝青色体系。
• 今日健康异常状态已从偏黑的棕红色改为鲜明红橙色 #E8562A。

圆角、阴影和字体

• 所有圆角优先使用项目已有的 AppRadius，不要随手写不同圆角。
• 卡片不能层层嵌套，也不能同时堆重描边和重阴影。
• 不要随意缩小字体；列表紧凑但必须清楚可读。
• 选中状态不能改变文字大小、字重或位置。
• 为避免 Android 跟随系统楷书时粗体失控，项目已减少 w800/w900 的使用，主要层级使用 w600/w700。

完整基础规范见：docs/ui-design-system.md。实际逐页精修仍以真机截图和用户确认优先。

5. 最近完成的界面与交互修改

登录页

• 登录页使用新背景：login_background_v2.png。
• 新背景去掉旧版气泡、玻璃方块和心电线，改为低饱和蓝紫柔光，中央保持安静。
• App 图标继续使用原来的白底人物版本，没有继续使用错误生成的紫色底图标。
• 登录页单独使用透明人物资源：health_login_character_transparent.png。
• 登录键盘掉帧已针对性优化：
  • 背景使用独立重绘边界，键盘弹出时背景不重复重绘。
  • 删除原来每次键盘高度变化都会重启的 AnimatedPadding。
  • 表单改为轻量 Transform.translate 位移，最大抬升 150 px。
  • 下滑表单可以关闭键盘。
• 这项键盘优化只做了格式和差异检查，尚未经过用户重新安装后的真机确认。
• 透明人物由原人物参考生成并去除背景。用户非常重视人物不变形；需要真机确认其造型是否与原人物完全一致。如果仍有偏差，应使用确定性的抠图方式处理原图，不能再次重新设计人物。

App 图标与启动页

• Android 和 iOS 已恢复原来的白底人物图标及周围小元素。
• 已撤销错误的紫色底图标和重新生成的人物衍生图。
• Flutter 启动页恢复使用 health_splash_master.png。
• Android 原生启动图恢复使用原 launch_brand.png。
• iOS AppIcon 和 LaunchImage 配置恢复引用原文件。

侧边栏

• 使用新背景：drawer_background_v2.png。
• 背景改为顶部淡蓝紫、向下过渡白色，遮罩同步调轻。
• 对话记录区域继续保留当前结构，不要因为“区域转换突然”擅自重排；用户认为类似蚂蚁阿福的结构可以接受。
• 当前侧边栏仍是：系统整页拖拽关闭，只在中间对话流区域使用自定义右滑触发；智能体胶囊和输入区不应触发侧边栏。
• 顶部菜单按钮仍可打开侧边栏。
• 不要再次擅自改成推页式侧栏或另一套 Drawer 手势，除非用户重新明确要求。

首页和今日健康

• 首页整体结构用户基本满意，不要进行大面积重构。
• 今日健康加载策略已调整，避免返回首页时先显示两行再闪成三行。
• 健康概览图标已统一为“记数据”中使用的图标风格。
• 跑步、用药等入口图标需与智能体胶囊保持同样样式。
• 今日健康异常文字和右侧警告图标当前统一为 #E8562A。
• 首页键盘布局保持原来的结构；上一轮误加的首页键盘悬浮布局已经撤回。

通知中心

• 通知列表重新压缩并调整信息布局。
• 用户指定单行最低高度约 82 px，不要再次压到 68 px。
• 标签和时间已重新安排，时间位于右侧区域，减少不必要的独立行。
• 列表内容要保持视觉垂直居中。
• 未读提醒区域不能使用大面积强紫色。

用药、运动、报告和设备

• 用药与运动列表的红色删除背景“提前露出”问题已处理过；后续修改需继续检查右侧红底不能浮出。
• 运动计划列表已向用药、报告的连续列表形式统一，并补充前置运动图标。
• 报告页面以靛紫色为模块识别，但“查看原始报告”不能使用突兀的大紫色实心按钮。
• 蓝牙设备管理仅允许修改 UI，不得改变扫描、连接、自动读取、上传和解绑逻辑。
• 蓝牙页右下角自动扫描动画必须保留，用于表达页面正在持续检测设备。

6. 功能与平台适配状态

已合并/已处理

• sccsbc 分支的 Apple 登录和部分上线准备代码已经合并。
• Apple 登录前端按钮、服务端身份映射和相关迁移已进入当前代码历史。
• Android 签名相关配置结构已合入，但真实 keystore、密码和正式证书不应写入 Git。
• iOS 页面导航已加入原生风格返回适配相关测试文件，但尚未在真实 iPhone 全量验证。
• iOS 与 Android 共用同一套 Flutter 业务页面；平台差异主要在权限、签名、Apple 登录和系统交互。
• Android 本地电脑与手机同 Wi-Fi 的开发 API 地址方式继续保留；iPhone 真机调试时需要配置为电脑局域网 IP，而不是 localhost。

暂不投入的功能

• 医生端尚未正式完成。
• 医患实时交流、问诊和随访目前不是近期上线重点。
• 未启用的医生端、问诊和随访页面不需要继续做 UI 精修，也不要为它们扩大工作量。
• 但已有页面和入口不能伪装成已经可用的正式医疗服务。

7. Apple 审核与医疗合规风险

苹果反馈涉及 Guideline 1.4.1 和 2.1，要求：

• 外接医疗硬件的监管批准材料。
• 能证明 App 与硬件按描述工作的硬件测试报告或同行评议研究。
• 在真实 Apple 设备上完成硬件首次配对和完整流程的演示视频。
• 涉及医疗数据、诊断或治疗建议时提供相应监管批准文件。

当前本地测试主要使用欧姆龙 J735 血压计，但代码定位为通用 BLE 设备。后续必须在产品表述和审核材料之间作出一致选择：

• 如果继续声明支持医疗硬件，需要设备授权、监管文件、测试材料和真实 iPhone 演示。
• 如果定位为个人健康记录工具，需要削弱“医疗服务、诊断、治疗建议、恢复健康”等可能触发医疗器械审查的表述，并明确 AI 仅提供一般健康信息，不替代医生。
• 不要在没有材料时直接回复苹果称已经满足要求。

8. 正式环境前仍需完成

• 正式服务器、域名、HTTPS。
• 正式数据库与备份方案。
• 正式 JWT 密钥和密钥轮换。
• 正式短信服务。
• 正式文件/对象存储及删除策略。
• 正式 CORS 白名单。
• Android 正式 keystore、release 签名、APK/AAB。
• Apple 开发者证书、Bundle ID、签名、TestFlight 真机流程。
• 隐私政策、服务协议、个人信息清单、第三方 SDK 清单和关于我们的最终定稿。
• ICP、公安备案、软著、安全评估及各应用市场账号。
• Apple 医疗硬件与医疗建议相关审核材料或产品定位调整。

9. 当前验证情况

• 最近图片和 UI 修改只做了 dart format、git diff --check、资源引用和配置文件检查。
• 用户明确要求不要反复运行耗时测试，因此最近没有执行完整 Flutter build、安装或全量回归。
• Android 和 iOS 图标恢复后尚需用户重新构建查看系统桌面实际裁切。
• 登录页透明人物、新背景和键盘流畅度尚需 Android 真机确认。
• iOS 尚需真实 iPhone 验证 Apple 登录、蓝牙权限、页面侧滑返回、键盘和 TestFlight 包。

10. 下一窗口建议的第一步

1. 先运行 git status --short，确认用户是否又修改了文件。
2. 不要回退当前工作区，不要重新合并 sccsbc。
3. 让用户先安装当前 Android 包，优先确认：
   • 登录页透明人物是否仍保持原人物造型。
   • 登录键盘弹出是否明显更流畅，输入框是否始终可见。
   • App 图标是否恢复白底且人物显示完整。
   • 新登录背景和侧边栏背景在真机上的亮度与边界。
   • 今日健康异常红橙色是否清楚但不过重。
4. 根据用户真机截图逐项微调，每次只改明确页面。
5. 用户确认当前视觉效果后，再整理未使用的项目图片并提交代码；删除前必须确认没有 Android、iOS 或 Flutter 配置引用。

11. 禁止事项

• 不使用 Docker。
• 不创建其他分支。
• 不覆盖或回退用户正在修改的文件。
• 不用旧快照替换当前 main。
• 不在用户说“先讨论”时直接修改。
• 不随意扩大到未启用的医生端、问诊和随访页面。
• 不重新设计“小脉健康”人物形象，只允许适配背景、留白、尺寸和系统裁切。
• 不为了 UI 修改蓝牙、聊天、删除、注销和历史恢复等业务逻辑。
• 不声称构建、安装或真机验证成功，除非实际执行并看到结果。