睡了么 (Terra Somnus)

让明天睡的更好————我们的愿景。

项目部分页面预览

产品正面图	App 首页

Agent 页面	设备控制页面

TerraSomnus 由 3 个核心模块组成：

• flutter_app：用户侧 App，负责首页、睡眠报告、设备控制、AI 对话、日程等体验
• terra_somnus_service：云端后端，负责 HTTP API、MQTT 桥接、设备状态快照、数据库、AI 能力
• terra_somnus_loT：硬件侧嵌入式代码，运行在 DuckyClaw / T5 AI board 上，负责雷达、灯光、扬声器、香氛与联网逻辑

这个仓库的目标不是只做一个 App，而是打通整条链路：

硬件设备 -> MQTT -> 云端后端 -> Flutter App

反向控制链路则是：

Flutter App / AI -> 云端后端 -> MQTT -> 硬件设备

---

整体架构

┌────────────────────┐      MQTT       ┌────────────────────────┐      HTTP / SSE / WS      ┌────────────────────┐
│ terra_somnus_loT   │ ─────────────→  │ terra_somnus_service   │  ←──────────────────────→ │ flutter_app        │
│ 硬件设备侧固件      │                 │ FastAPI + MQTT + DB    │                           │ Flutter App        │
│                    │  ←────────────  │                        │                           │                    │
│ 雷达 / 灯光 / 音频  │     download    │ 设备快照 / 事件 / AI    │         REST API          │ 首页 / 对话 / 睡眠  │
│ 香氛 / OpenClaw    │                 │ 日程 / 报告 / 场景      │                           │ 控制 / 日程        │
└────────────────────┘                 └────────────────────────┘                           └────────────────────┘

---

三个模块分别做什么

1. flutter_app

这是用户直接看到的客户端。

它当前主要负责：

• 展示首页、睡眠页、对话页、日程页和设备控制页
• 调用后端设备接口、睡眠接口、场景接口、日程接口、智能体接口
• 展示设备在线状态、灯光/白噪音/香氛状态
• 通过流式接口和 AI 对话

关键入口和配置：

• App 入口：flutter_app/lib/main.dart
• 后端地址配置：flutter_app/lib/config/api_config.dart
• 设备控制页：flutter_app/lib/presentation/screens/device_control_screen.dart
• 设备状态模型：flutter_app/lib/models/device_status.dart

现在这部分已经不仅是纯 UI Demo，而是能直接连真实后端做联调。

2. terra_somnus_service

这是系统的中间层，也是整个项目的“桥”。

它当前主要负责：

• 订阅 MQTT 上报，接收硬件 upload
• 暴露 FastAPI HTTP 接口，供 App 查询和控制
• 维护设备状态快照与最近事件
• 将控制命令转成 MQTT download 发给硬件
• 落库设备快照、事件、雷达帧
• 提供 AI 对话流式接口
• 提供 WebSocket / SSE 实时能力

关键入口和核心模块：

• 应用入口：terra_somnus_service/app/main.py
• API 路由：terra_somnus_service/app/api/routes.py
• MQTT 服务：terra_somnus_service/app/services/mqtt/service.py
• 状态存储：terra_somnus_service/app/services/state/store.py
• 数据库管理：terra_somnus_service/app/db/manager.py

3. terra_somnus_loT

这是硬件固件侧的定制代码。

它不是一个完整独立 SDK，而是基于 DuckyClaw 项目做的嵌入式应用替换文件。目前仓库里保留的是：

• 说明文件：terra_somnus_loT/readme.md
• 主要入口代码：terra_somnus_loT/tuya_app_main.c

当前用法是：

1. 拉取上游 DuckyClaw 仓库
2. 用这里的 tuya_app_main.c 替换对应文件
3. 烧录到 T5 AI board / 目标开发板

这部分负责把硬件能力真正跑起来，包括：

• 雷达数据采集与上报
• 灯光、扬声器、香氛执行
• 板端音频/联网/事件循环
• 与云端 MQTT 协议对接

---

当前真实数据链路

MQTT 约定

当前比赛环境里，topic 是固定的：

• 硬件上报：AI_CMD
• 云端下发：AI_RET

注意：虽然 topic 固定，但消息体内部仍然必须保留协议字段：

• protocol
• version
• type
• device_sn
• timestamp
• msg_id
• modules

设备快照策略

目前代码已经按当前硬件联调现状做了区分：

• radar 模块只根据硬件 upload 上报更新
• led / speaker / atomizer 三个可控模块，只根据后端已接受的 download 控制命令更新

这样做的原因是：当前硬件上报里，除雷达外的三个模块会带默认值，不能作为真实状态来源。

也就是说，现在 App 看到的设备状态口径是：

• 雷达状态：来自硬件真实上报
• 灯光 / 白噪音 / 香氛：来自最近一次后端成功下发的控制

睡眠报告现状

当前睡眠报告接口主要用于演示和联调，后端目前返回的是稳定 Mock 睡眠报告，而不是最终版真实睡眠算法结果。

这个策略适合黑客松演示：

• 首页和睡眠页有稳定内容可展示
• 不会因为硬件雷达数据不完整导致报告内容频繁失真

---

仓库结构

TerraSomnus/
├── README.md
├── docs/
│   ├── PRD-睡了么AI水母睡眠伴侣.md
│   ├── API接口定义-睡了么App.md
│   ├── AI水母睡眠伴侣 - MQTT通信协议.md
│   ├── 国际化方案-FlutterApp.md
│   └── 05-项目对齐文档-v1.0.md
├── flutter_app/
│   ├── lib/
│   │   ├── main.dart
│   │   ├── config/
│   │   │   └── api_config.dart
│   │   ├── core/
│   │   │   ├── router.dart
│   │   │   ├── theme/
│   │   │   └── utils/
│   │   ├── models/
│   │   ├── services/
│   │   └── presentation/
│   │       ├── screens/
│   │       └── widgets/
│   ├── assets/
│   └── pubspec.yaml
├── terra_somnus_service/
│   ├── app/
│   │   ├── main.py
│   │   ├── api/
│   │   ├── config/
│   │   ├── db/
│   │   ├── schemas/
│   │   ├── services/
│   │   └── utils/
│   ├── scripts/
│   ├── sql/
│   ├── tests/
│   └── README.md
└── terra_somnus_loT/
    ├── readme.md
    └── tuya_app_main.c

---

快速开始

1. 启动后端

cd terra_somnus_service
source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000

或者：

cd terra_somnus_service
docker compose up -d --build

启动后可访问：

• Swagger: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

---

2. 启动 Flutter App

cd flutter_app
flutter pub get
flutter run

如果要连真实后端，先检查：

• flutter_app/lib/config/api_config.dart

这里控制了：

• baseUrl
• wsBaseUrl
• 默认设备号 defaultDeviceSn

---

3. 硬件侧接入

terra_somnus_loT 当前是基于 DuckyClaw 的替换式开发。

按当前仓库说明，流程是：

1. 克隆 DuckyClaw 原仓库
2. 用本仓库 terra_somnus_loT/tuya_app_main.c 替换上游对应文件
3. 编译并烧录到开发板
4. 让设备按当前 MQTT 协议连接云端

---

前后端典型调用顺序

用户查看设备控制页

1. App 调 GET /api/v1/devices/{device_sn}/state
2. 后端返回设备在线状态和完整快照
3. App 渲染灯光、音频、香氛和在线状态

用户点一个灯光颜色

1. App 调 POST /api/v1/devices/{device_sn}/commands
2. 后端把命令发到 MQTT AI_RET
3. 后端立即更新 led 模块快照
4. App 轮询或刷新状态，看到新灯光结果

用户进入 AI 对话页

1. App 调 POST /api/v1/agent/chat/stream
2. 后端走 SSE 流式返回
3. 如有需要，AI 也可以联动设备控制、查询设备状态或睡眠信息

---

当前项目亮点

• 不是单端 Demo，而是完整软硬协同链路
• App、后端、硬件代码都在同一个仓库内，方便联调
• 后端已支持 MQTT、HTTP、SSE、WebSocket、数据库、AI 对话
• 设备状态管理已经针对当前硬件假上报问题做了专门策略修正
• Flutter 侧已经具备真实设备控制和状态同步能力

---

建议阅读顺序

如果你是第一次接手这个仓库，建议按这个顺序看：

1. 先看本 README，理解 3 个模块分工
2. 再看 docs/API接口定义-睡了么App.md
3. 再看 docs/AI水母睡眠伴侣 - MQTT通信协议.md
4. 想看 App，就从 flutter_app/lib/main.dart 和各个 screen 开始
5. 想看后端，就从 terra_somnus_service/app/main.py 和 terra_somnus_service/app/api/routes.py 开始
6. 想看硬件，就从 terra_somnus_loT/readme.md 和 terra_somnus_loT/tuya_app_main.c 开始

---

团队

成员	角色
肥柴	项目负责人
小鹅	工业设计 + UI
Robben	硬件开发
W	产品经理
明陌	软件开发

---

许可证与商业权利

本项目是小红书黑客松巅峰赛作品。

• 仓库原创代码与文档默认采用 PolyForm Noncommercial License 1.0.0
• 也就是说：允许非商用前提下查看、学习、修改与传播
• 本项目的商业化权利由项目团队保留；任何商业使用、商用部署、商用分发或基于本项目的商业衍生合作，都需要额外取得著作权人的书面授权
• 第三方代码、SDK、依赖和带有上游版权声明的文件，不受本仓库顶层许可证重新授权，详见 THIRD_PARTY_NOTICES.md

如果后续需要对外合作、商用授权或比赛后的成果转化，建议直接由项目维护团队统一对接授权。