xianyan/docs/widget_management_dev_doc.md

# 桌面小部件管理 — 开发文档

> 创建时间: 2026-05-19 | 最后更新: 2026-05-19
> 版本: v14.9.0 | 优先级: P0-P3
> 状态: 开发完成，待审计验收

---

## 一、功能概述

将个人中心「会员中心」按钮替换为「桌面小部件」，创建小部件管理页面，支持 Android/iOS/鸿蒙 三平台原生小部件的安装、数据推送、动态主题和深度链接。

## 二、架构设计

```
Flutter UI (WidgetManagementPage)
  → Riverpod State (WidgetNotifier/WidgetState)
    → HomeWidgetService (数据推送 + 主题推送 + 深度链接)
      → home_widget 插件 (MethodChannel)
        → Android: AppWidgetProvider + RemoteViews (light/dark布局切换)
        → iOS: WidgetKit + SwiftUI (WidgetColors动态配色)
        → 鸿蒙: FormExtensionAbility + ArkUI (isDark状态驱动)
```

## 三、文件清单与归档状态

### Flutter 端

| 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|
| `lib/features/widget/models/widget_type.dart` | 新建 | ✅ 已完成 | 8种小部件枚举+平台标识+深度链接+数据键前缀+主题键 |
| `lib/features/widget/providers/widget_provider.dart` | 新建 | ✅ 已完成 | Riverpod Notifier + pushThemeToAllWidgets |
| `lib/features/widget/presentation/widget_management_page.dart` | 新建 | ✅ 已完成 | 分组展示+同步主题+深度链接预览 |
| `lib/features/profile/presentation/profile_page.dart` | 修改 | ✅ 已完成 | 会员中心→桌面小部件 |
| `lib/core/router/app_router.dart` | 修改 | ✅ 已完成 | 新增/widget-management路由 |
| `lib/core/router/ohos_nav_bridge.dart` | 修改 | ✅ 已完成 | 鸿蒙路由桥接 |
| `lib/core/services/data/home_widget_service.dart` | 修改 | ✅ 已完成 | pushThemeMode + 5种小部件数据推送 + 深度链接回调 |

### home_widget 插件（本地 packages/home_widget）

| 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|
| `packages/home_widget/lib/src/home_widget.dart` | 修改 | ✅ 已完成 | updateWidget/requestPinWidget增加ohosName参数 |
| `packages/home_widget/lib/src/home_widget_info.dart` | 修改 | ✅ 已完成 | 新增ohosFormId/ohosFormName字段 |
| `packages/home_widget/ohos/src/main/ets/HomeWidgetPlugin.ets` | 已有 | ✅ 已完成 | 鸿蒙端MethodChannel实现 |

### Android 原生（8个Provider + 16个布局 + 8个配置 + 2个drawable）

| 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|
| `DailySentenceProvider.kt` | 已有 | ✅ 已完成 | P0 + dark主题 |
| `ReadlaterProvider.kt` | 已有 | ✅ 已完成 | P0 + dark主题 |
| `DailyCardProvider.kt` | 新建 | ✅ 已完成 | P1 + dark主题 |
| `FortuneProvider.kt` | 新建 | ✅ 已完成 | P2 + dark主题 |
| `CountdownProvider.kt` | 新建 | ✅ 已完成 | P2 + dark主题 |
| `PomodoroProvider.kt` | 新建 | ✅ 已完成 | P3 + dark主题 |
| `SolarTermProvider.kt` | 新建 | ✅ 已完成 | P3 + dark主题 |
| `CheckinProvider.kt` | 新建 | ✅ 已完成 | P3 + dark主题 |
| `widget_*_dark.xml` (8个) | 新建 | ✅ 已完成 | 深色布局(#1C1C1E) |
| `widget_*.xml` (8个) | 新建 | ✅ 已完成 | 浅色布局(#FFFFFF) |
| `*_info.xml` (8个) | 新建 | ✅ 已完成 | Widget配置 |
| `widget_background_dark.xml` | 新建 | ✅ 已完成 | 深色圆角背景 |
| `AndroidManifest.xml` | 修改 | ✅ 已完成 | 注册8个receiver |

### iOS 原生（8个Widget + 深色主题）

| 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|
| `ios/XianyanWidget/XianyanWidget.swift` | 新建 | ✅ 已完成 | 8个Widget + WidgetColors深色主题 |
| `ios/XianyanWidget/Info.plist` | 新建 | ✅ 已完成 | Widget Extension配置 |
| `ios/XianyanWidget/Assets.xcassets/` | 新建 | ✅ 已完成 | Asset Catalog |

### 鸿蒙原生（8个FormAbility + 8个ArkUI页面 + 8个表单配置）

| 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|
| `*FormAbility.ets` (8个) | 新建 | ✅ 已完成 | FormExtension + isDark读取 |
| `*FormPage.ets` (8个) | 新建 | ✅ 已完成 | ArkUI页面 + 动态配色 |
| `*_form.json` (8个) | 新建 | ✅ 已完成 | 表单配置JSON |
| `module.json5` | 修改 | ✅ 已完成 | 注册8个extensionAbilities |
| `string.json` (base + zh_CN) | 修改 | ✅ 已完成 | 8个Widget描述字符串 |

## 四、小部件类型与优先级

| 小部件 | 优先级 | Android | iOS | 鸿蒙 | 深度链接 | 状态 |
|--------|--------|---------|-----|------|----------|------|
| 📜 每日一句 | P0 | ✅ | ✅ | ✅ | /home | ✅ 已完成 |
| 📖 稍后读 | P0 | ✅ | ✅ | ✅ | /home?tab=readlater | ✅ 已完成 |
| 🃏 日签卡片 | P1 | ✅ | ✅ | ✅ | /home | ✅ 已完成 |
| 🔮 每日运势 | P2 | ✅ | ✅ | ✅ | /inspiration | ✅ 已完成 |
| ⏳ 倒计时 | P2 | ✅ | ✅ | ✅ | /widget-management | ✅ 已完成 |
| 🍅 番茄钟 | P3 | ✅ | ✅ | ⚠️ | /widget-management | ✅ 已完成 |
| 🌿 节气诗词 | P3 | ✅ | ✅ | ✅ | /inspiration | ✅ 已完成 |
| ✅ 每日签到 | P3 | ✅ | ✅ | ✅ | /signin | ✅ 已完成 |

✅ 已完成 | ⚠️ 鸿蒙端受限（无实时刷新） | ❌ 平台不支持

## 五、动态主题机制

### 数据流
```
Flutter: pushThemeMode(isDark)
  → home_widget.saveWidgetData('widget_theme_mode', 'dark'/'light')
    → Android: SharedPreferences → Provider读取 → 切换light/dark布局XML
    → iOS: UserDefaults → Provider读取 → WidgetColors动态配色
    → 鸿蒙: dataPreferences → FormAbility读取 → isDark状态驱动ArkUI
```

### 统一配色
| 元素 | 浅色 | 深色 |
|------|------|------|
| 背景 | #FFFFFF | #1C1C1E |
| 正文 | #333333 | #E0E0E0 |
| 副文字 | #888888 | #AAAAAA |
| 圆角 | 16dp | 16dp |

## 六、深度链接

### 路由映射
| 小部件 | 深度链接路由 | 说明 |
|--------|------------|------|
| 每日一句 | /home | 打开首页 |
| 稍后读 | /home?tab=readlater | 打开稍后读Tab |
| 日签卡片 | /home | 打开首页 |
| 每日运势 | /inspiration | 打开灵感页 |
| 倒计时 | /widget-management | 打开小部件管理 |
| 番茄钟 | /widget-management | 打开小部件管理 |
| 节气诗词 | /inspiration | 打开灵感页 |
| 每日签到 | /signin | 打开签到页 |

### 回调处理
`HomeWidgetService._backgroundCallback` 处理 URI scheme `homeWidget://open_<action>`

## 七、数据键对照表

| 小部件 | 数据键 | 类型 |
|--------|--------|------|
| 每日一句 | daily_sentence, daily_sentence_author | String |
| 稍后读 | readlater_count, readlater_preview_text, readlater_preview_author | Int, String |
| 日签卡片 | daily_sentence, daily_sentence_author | String |
| 每日运势 | fortune_text, fortune_keyword | String |
| 倒计时 | countdown_title, countdown_target | String (ISO8601) |
| 番茄钟 | pomodoro_remaining, pomodoro_state | Int, String |
| 节气诗词 | solar_term_name, solar_term_poem | String |
| 每日签到 | checkin_days, checkin_today | Int, Bool |
| 主题 | widget_theme_mode | String ('light'/'dark') |

## 八、审计清单

### 功能审计
- [ ] Android: 8个小部件添加到桌面，验证数据显示正确
- [ ] Android: 深色模式下小部件样式正确
- [ ] Android: 点击小部件跳转到App对应页面
- [ ] iOS: Xcode添加Widget Extension Target后验证
- [ ] iOS: 8个小部件数据显示正确
- [ ] iOS: 深色模式下小部件样式正确
- [ ] 鸿蒙: 长按桌面添加8种卡片，验证数据显示
- [ ] 鸿蒙: 深色模式下卡片样式正确
- [ ] Flutter: 管理页面按优先级分组展示
- [ ] Flutter: "同步主题"按钮推送当前主题到所有小部件
- [ ] Flutter: 深度链接预览正确显示

### 代码审计
- [ ] Android 8个Provider空指针检测
- [ ] iOS 8个Provider空指针检测
- [ ] 鸿蒙 8个FormAbility空指针检测
- [ ] Flutter WidgetState空安全
- [ ] MethodChannel通信异常处理
- [ ] 深度链接路由是否已注册

### 待完成项
- [ ] iOS: Xcode项目配置（Widget Extension Target + App Group）
- [ ] 番茄钟实时刷新（仅Android支持，iOS/鸿蒙受限）
- [ ] 小部件交互式按钮（Android 12+ / iOS 17+）