# 小脉健康项目交接文档 更新时间：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 修改蓝牙、聊天、删除、注销和历史恢复等业务逻辑。 - 不声称构建、安装或真机验证成功，除非实际执行并看到结果。