# Calendar Widget Android App

基于 Calendar Widget 系统的原生 Android 应用实现。

## 功能特性

- 📱 **原生 Android 体验**：使用 Kotlin 和 Jetpack Compose 构建
- 📋 **任务管理**：完整的任务增删改查功能
- 🎨 **Material Design 3**：现代化的 UI 设计
- 📊 **双视图模式**：控制页面和展示页面
- 🔄 **实时同步**：与服务器 API 实时同步
- 💾 **离线支持**：本地数据库缓存
- ⚡ **桌面小组件**：支持多种尺寸，5分钟自动刷新

## 技术架构

- **语言**：Kotlin
- **UI**：Jetpack Compose
- **架构**：MVVM + Repository Pattern
- **依赖注入**：Hilt
- **网络**：Retrofit + OkHttp
- **数据库**：Room
- **协程**：Kotlin Coroutines + Flow

## 项目结构

```
android-app/
├── app/
│   ├── src/main/java/com/tunpok/calendarwidget/
│   │   ├── data/           # 数据层
│   │   │   ├── api/        # API 接口定义
│   │   │   ├── database/   # Room 数据库
│   │   │   ├── model/      # 数据模型
│   │   │   └── repository/ # 数据仓库
│   │   ├── di/             # Hilt 依赖注入
│   │   ├── ui/             # UI 层
│   │   │   ├── control/    # 控制页面
│   │   │   ├── display/    # 展示页面
│   │   │   ├── widget/     # 桌面小组件
│   │   │   ├── components/ # 共享组件
│   │   │   └── theme/      # 主题配置
│   │   └── utils/          # 工具类
│   └── src/main/res/       # 资源文件
├── gradle/                 # Gradle 配置
└── build.gradle.kts        # 构建脚本
```

## 构建与运行

### 前置要求

- Android Studio Arctic Fox 或更高版本
- JDK 17
- Android SDK 34
- Kotlin 1.9.20+

### 构建步骤

1. 克隆项目：
```bash
cd android-app
```

2. 打开 Android Studio，导入项目

3. 配置 API 设置（首次运行时在应用内配置）：
   - API Key: 你的 API 密钥
   - API Host: 服务器地址

4. 构建并运行：
   - 点击 Run 按钮或使用快捷键 Shift+F10

### 生成 APK

```bash
./gradlew assembleRelease
```

生成的 APK 位于：`app/build/outputs/apk/release/`

## 小组件配置

1. 长按桌面空白处
2. 选择"小组件"
3. 找到"Calendar Widget"
4. 选择合适的尺寸：
   - 小型 (2x1)：显示1个任务
   - 中型 (2x2)：显示4个任务
   - 大型 (4x2)：显示8个任务
5. 拖动到桌面

小组件会每5分钟自动刷新，也可以点击刷新按钮手动更新。

## 开发说明

### 添加新功能

1. 在对应的包中创建新文件
2. 使用 Hilt 注解进行依赖注入
3. 遵循 MVVM 架构模式
4. 使用 Compose 构建 UI

### 调试

- 启用 OkHttp 日志：已在 `AppModule` 中配置
- 查看数据库：使用 Android Studio 的 Database Inspector
- 网络调试：使用 Charles 或 Flipper

## 测试

运行单元测试：
```bash
./gradlew test
```

运行 UI 测试：
```bash
./gradlew connectedAndroidTest
```

## License

MIT