# 00 — 项目概述与架构

> 对应主项目 Phase 5（v1.5 → v2.0）Android 客户端  
> 主项目文档：`../../docs/dev-plan/04-voice-system-plan.md`

---

## 1. 项目定位

Cyrene for Android 是昔涟的官方 Android 客户端，定位为 **可替换系统自带语音助手的智能体 APP**（替代 Google Assistant / Bixby）。

核心差异点：
- 不是传统 APP（以桌面图标为主要入口），而是**系统级语音助手**
- 除常规全屏 Activity 外，通过 `VoiceInteractionSession` 提供悬浮式覆盖层交互
- 支持息屏热词唤醒、长按 Home / 电源键呼出

## 2. 技术栈

| 层 | 技术 | 版本要求 |
|----|------|---------|
| 语言 | Kotlin | 2.0+ |
| UI 框架 | Jetpack Compose + Material Design 3 | BOM 2025+ |
| 构建 | Gradle (Kotlin DSL) | 8.7+ |
| 架构模式 | MVVM + Repository | — |
| 依赖注入 | Hilt / Koin (待定) | — |
| 网络 | Retrofit + OkHttp | — |
| 实时通信 | OkHttp WebSocket | — |
| 本地存储 | Room (SQLite) + DataStore | — |
| 推送 | FCM (Firebase Cloud Messaging) | — |
| 系统语音 | VoiceInteractionService | API 23+ |
| 热词唤醒 | Always-On Hotword Detection | API 23+ |
| 语音识别 | 服务端 (Whisper API) + 本地兜底 | — |

## 3. 最低系统要求

| 项目 | 要求 |
|------|------|
| minSdk | 26 (Android 8.0) |
| targetSdk | 35+ |
| compileSdk | 35+ |
| JDK | 17 |
| Gradle | 8.7+ |

注：`VoiceInteractionService` 基础 API 要求 23，`AssistAction` 热词唤醒要求 23。minSdk 设为 26 以覆盖绝大多数活跃设备并简化兼容性。

## 4. 项目结构

```
android/
├── app/
│   ├── src/main/
│   │   ├── java/com/cyrene/app/
│   │   │   ├── CyreneApplication.kt       # Application 初始化
│   │   │   ├── MainActivity.kt            # 全屏主界面 (桌面图标入口)
│   │   │   ├── ui/
│   │   │   │   ├── theme/                 # MD3 主题 (Color / Type / Shape)
│   │   │   │   ├── screens/               # 全屏页面 (Compose)
│   │   │   │   │   ├── chat/              # 对话页
│   │   │   │   │   ├── home/              # 首页 / IoT 面板
│   │   │   │   │   ├── settings/          # 设置页
│   │   │   │   │   └── login/             # 登录/注册
│   │   │   │   ├── overlay/               # 悬浮窗对话界面 (VoiceInteractionSession)
│   │   │   │   └── components/            # 共享组件库
│   │   │   ├── viewmodel/                 # ViewModel 层
│   │   │   ├── domain/                    # 领域层 (UseCase / Repository 接口)
│   │   │   ├── data/
│   │   │   │   ├── remote/                # API 接口定义 + DTO
│   │   │   │   ├── local/                 # Room DAO + DataStore
│   │   │   │   └── repository/            # Repository 实现
│   │   │   ├── service/
│   │   │   │   ├── CyreneVoiceInteractionService.kt
│   │   │   │   ├── CyreneVoiceInteractionSession.kt
│   │   │   │   ├── CyreneAssistService.kt
│   │   │   │   └── WebSocketService.kt
│   │   │   ├── voice/
│   │   │   │   ├── hotword/               # 热词唤醒引擎
│   │   │   │   ├── stt/                   # 语音识别客户端
│   │   │   │   └── tts/                   # 语音合成客户端
│   │   │   ├── di/                        # DI 模块定义
│   │   │   └── util/                      # 工具类
│   │   ├── res/                           # 资源文件
│   │   └── AndroidManifest.xml
│   └── build.gradle.kts
├── gradle/
│   ├── libs.versions.toml                 # 版本目录
│   └── wrapper/
├── build.gradle.kts                       # 根构建脚本
├── settings.gradle.kts
└── gradle.properties
```

## 5. 架构分层

```
┌──────────────────────────────────────────────┐
│  UI Layer (Compose)                          │
│  ├─ Screens (全屏 Activity)                   │
│  └─ Overlay (VoiceInteractionSession 悬浮窗)  │
├──────────────────────────────────────────────┤
│  ViewModel Layer                             │
│  ├─ ChatViewModel                            │
│  ├─ HomeViewModel (IoT)                      │
│  ├─ SettingsViewModel                        │
│  └─ OverlayViewModel                         │
├──────────────────────────────────────────────┤
│  Domain Layer                                │
│  ├─ UseCase (SendMessage, ControlIoT, ...)   │
│  └─ Repository Interfaces                    │
├──────────────────────────────────────────────┤
│  Data Layer                                  │
│  ├─ Remote: Retrofit API + WebSocket         │
│  ├─ Local: Room + DataStore                  │
│  └─ Repository Implementation                │
├──────────────────────────────────────────────┤
│  Service Layer                               │
│  ├─ VoiceInteractionService (系统助手)        │
│  ├─ WebSocketService (长连接)                 │
│  └─ FCMMessagingService (推送)               │
└──────────────────────────────────────────────┘
```

UI 层和 Service 层通过 ViewModel 解耦——全屏 Activity 和悬浮窗 Overlay 复用同一组 ViewModel，只是 UI 布局不同。

## 6. 与后端的关系

```
Android Client
  │
  ├─ HTTP REST ──────────► Gateway (:8080)     # 登录、CRUD、配置
  ├─ WebSocket ──────────► Gateway (:8080)     # 实时对话、IoT 状态推送
  ├─ STT Audio ──────────► Voice Service (:8093) # 语音识别
  └─ TTS Stream ◄──────── Voice Service (:8093)  # 语音合成
```

WebSocket 长连接是核心通信通道：对话消息、通知、IoT 状态广播均通过同一连接。HTTP 仅用于一次性操作（登录、文件上传/下载）。

## 7. 关键设计决策

| 决策 | 选择 | 理由 |
|------|------|------|
| UI 框架 | Jetpack Compose + MD3 | 声明式 UI，与悬浮窗的 ComposeView 集成简单 |
| 架构 | MVVM + Repository | Google 官方推荐，ViewModel 可在 Activity 和 Session 间复用 |
| 语音框架 | VoiceInteractionService（系统 API） | 原生支持替换系统助手，无需自定义悬浮窗权限 |
| 热词方案 | 系统 Always-On Hotword API | 息屏低功耗监听，不用自建音频采集 |
| 网络 | OkHttp WebSocket | 比 FCM 更实时，与主项目 Gateway 已有 WS Hub 对应 |
| 最低 API | 26 | 覆盖 95%+ 活跃设备，VoiceInteractionService 兼容 |

## 8. 排期参考

对应主项目路线图：

```
2026 Q4 ─ v1.3   多平台接入（前置依赖）
2027 Q1 ─ v1.8   语音模型训练完成（后端依赖）
2027 Q2 ─ v2.0   开始 Android 客户端开发
2027 Q3 ─ v2.3   语音助手 APP MVP 版本
2027 Q4 ─ v3.0   APP 上架（Google Play / 国内应用商店）
```