概要设计文档

📄 智能家庭饮食管家 - 概要设计文档

最后更新： 2026-05-17
相关地点： 浙江省杭州市

一、 文档修订记录

版本	日期	作者	修改说明
v1.0	2026-05-17		基于 PRD v0.2 与 详细设计 v0.3 整理；确立分层架构
v1.1	2026-05-19		新增家庭解散策略：明确「混合删除策略」与接口设计文档、数据库设计文档保持一致

二、 总体技术架构

架构风格： 分层架构 (Layered Architecture) + MVVM 变体
核心原则： 高内聚、低耦合；严禁跨层调用（UI层不得直接访问数据库）。

+---------------------+
|   1. UI 层 (View)    |  [QML]
+---------------------+
         ▲
         | (数据绑定/信号)
         ▼
+---------------------+
| 2. 业务服务层 (Service) |  [C++]
+---------------------+
         ▲
         | (业务请求/DTO)
         ▼
+---------------------+
| 3. 数据访问层 (Repository) | [C++]
+---------------------+
         ▲
         | (SQL/网络请求)
         ▼
+---------------------+
| 4. 基础设施层 (Infrastructure) | [C++/3rd Party]
+---------------------+

三、 详细分层设计

1. UI 层 (View)

• 技术栈： Qt Quick (QML) + JavaScript
• 核心职责：
  • 界面渲染： 负责所有视觉元素的展示，包括首页的环形仪表盘、双柱状图、食谱卡片瀑布流。
  • 交互响应： 处理用户的点击、滑动、输入（如饮食模式切换、步进器增减）。
  • 动效实现： 执行页面左滑进入、环形色块生长、按钮点击反馈等动画。
  • 数据展示： 通过 property 绑定 ViewModel 中的数据模型。
• 严禁行为：
  • 禁止编写任何 SQL 语句。
  • 禁止包含核心业务计算逻辑（如 TDEE 计算、采购清单算法）。
  • 禁止直接调用网络接口。
• 通信方式： 通过 Connections 监听 Service 层信号，或通过 QtObject 调用 Service 层暴露的接口。

2. 业务服务层 (Service / ViewModel)

• 技术栈： C++ (QObject 派生类)
• 核心职责：
  • 算法引擎：
    • TDEE/BMR 计算： 封装 Mifflin-St Jeor 公式，根据用户档案计算每日能量消耗。
    • 采购清单生成： 实现核心算法 实际需采购量 = 菜谱所需总量 - 冰箱现有量，并自动过滤 <=0 的项。
    • 库存核销： 计算 最新库存 = 原库存 - 本次核销量。
  • 权限中心： 管理“掌勺人”权限校验、成员入库权限验证。
  • 状态管理： 维护当前家庭状态、当前掌勺人信息、饮食模式（减脂/增肌）状态。
  • 数据适配： 将 Repository 返回的原始数据转换为 UI 友好的格式（如时间戳格式化）。
• 关键接口示例：
  • calculateTDEE(height, weight, age)
  • generateShoppingList(recipeIds)
  • confirmCooking(dishId) // 触发核销流程

3. 数据访问层 (Repository / DAO)

• 技术栈： C++ (Qt SQL / 自定义 ORM)
• 核心职责：
  • 本地数据库 (SQLite)： 封装对本地 SQLite 的 CRUD 操作。表结构包括：用户表、食材表、菜谱表、消费记录表。
  • 远程数据库 (PostgreSQL)： 封装与云端 PostgreSQL 的交互协议（通过 Infrastructure 层）。
  • 统一数据网关： 提供统一的接口（如 getUserProfile()），内部封装“先读本地缓存，后同步云端”的策略。
  • 实体映射： 负责将数据库记录映射为 C++ 对象（ORM），供 Service 层使用。
• 设计模式： 采用 Repository 模式，UI 和 Service 层无需知道数据是来自本地文件还是云端服务器。

4. 基础设施层 (Infrastructure)

• 技术栈： C++ (Qt Network / 3rd Party SDK)
• 核心职责：
  • 网络通信： 实现 WebSocket 长连接，确保家庭数据在 2秒内 实时同步；封装 HTTP Client 用于 RESTful API 调用。
  • 同步引擎： 管理“待同步操作队列”。在网络断开时缓存操作，网络恢复时自动重试（支持断点续传）。
  • 工具组件：
    • OCR 识别器： 封装第三方 SDK，用于识别食品包装袋上的营养成分表。
    • 日志系统： 记录运行日志与错误追踪。
    • 全局配置： 管理应用的主题色（暖柔青柠绿 #64C288）、圆角规范等常量。

四、 核心业务流程时序图 (逻辑示意)

场景：用户点击“标记制作完成”触发库存核销

1. UI (QML)： 用户点击按钮 -> 发送信号至 CookingService。
2. Service (C++)：
   • 接收信号 -> 校验当前用户是否为“掌勺人”。
   • 计算核销公式 -> 准备核销数据包。
   • 调用 InventoryRepository->updateStock(itemList)。
3. Repository (C++)：
   • 接收数据包 -> 开启事务。
   • 执行本地 SQLite 更新 (UPDATE stock SET qty = ? WHERE id = ?)。
   • 调用 SyncManager 将该操作加入同步队列。
4. Infrastructure (C++)：
   • SyncManager 检测到网络在线 -> 通过 WebSocket 将变更推送到云端 PostgreSQL。
   • 云端广播 -> 其他家庭成员设备收到推送 -> 触发本地 Repository 更新 -> Service 发送刷新信号 -> UI 自动刷新。

五、 数据架构设计

• 本地数据库： SQLite
  • 用途： 离线模式支撑、缓存云端数据、存储用户操作日志。
  • 关键表： local_sync_queue (用于存储待同步的操作)。
• 云端数据库： PostgreSQL
  • 用途： 家庭数据中央存储、多设备一致性保障。
• 同步策略： 基于时间戳 (Timestamp) 的冲突解决机制。云端数据时间戳新于本地时，以云端为准（覆盖本地）；本地独有操作则上传合并。

六、 家庭解散策略

删除原则：家庭解散采用「混合删除策略」，在单个数据库事务中执行：

数据类型	示例表	删除方式	理由
历史业务数据	daily_menus, menu_items, wishlist_items, inventory_batches	软删除 (is_deleted = 1)	保留历史记录，支持审计追溯
临时性/关系型数据	shopping_list_items, family_members	物理删除 (DELETE)	无需保留，减少冗余数据
审计记录	inventory_logs	不删除	保留完整审计记录

事务边界：

• 事务内：按序执行所有删除操作（软删除 + 物理删除）
• 事务外：写入 sync_queue 同步队列、WebSocket 广播 family_dissolved 消息
• 事务失败：全部回滚，无任何数据变更

与接口设计文档/数据库设计文档对齐：详细删除步骤和错误处理见《接口设计文档 v1.5》与《数据库设计文档 v1.8》。

七、 非功能性需求保障

• 性能：
  • UI 线程与数据库/网络线程分离，避免卡顿。
  • 动画帧率锁定在 60FPS。
• 离线支持：
  • 通过分层架构，当 Infrastructure 层检测到网络异常时，Repository 自动降级为纯本地模式，Service 层逻辑不受影响。
• 安全性：
  • 用户密码加密存储。
  • WebSocket 通信采用 WSS 加密。

---