feat: 桌面宠物设计文档 v1.0

docs/superpowers/specs/2026-10-10-desktop-pet-design.md

@@ -0,0 +1,337 @@
+# 浠艾福桌面宠物设计文档
+
+> **日期：** 2026-10-10
+> **版本：** v1.0
+> **状态：** 设计确认
+
+---
+
+## 一、项目概述
+
+### 1.1 目标
+构建一款 Windows 桌面宠物应用，通过浠艾福品牌吉祥物（浠宝/福宝）展现用户当前健康状态与任务执行情况，同时支持与用户互动完成打卡任务。
+
+### 1.2 核心能力
+| 能力 | 说明 |
+|------|------|
+| **状态展示** | 实时反映五维能量值、任务完成进度、健康打卡状态 |
+| **互动提醒** | 支持喝水、吃药等定时提醒，用户可通过点击宠物确认完成 |
+| **形象自定义** | 支持上传 PNG 形象 + JSON 配置，用户可完全自定义 |
+| **小游戏** | 内置舒尔特方格等小游戏，宠物陪伴用户完成 |
+| **顽皮行为** | 支持"偷图标"、"吃文档"等随机互动，增强陪伴感 |
+
+---
+
+## 二、系统架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     WPF 主进程 (C#)                         │
+│                                                             │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │  API Client  │  │  状态管理器  │  │  托盘 / 快捷手势  │  │
+│  │  (HttpClient)│  │  (StateMgr)  │  │  (NotifyIcon)    │  │
+│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
+│         │                 │                    │            │
+│  ┌──────▼─────────────────▼────────────────────▼─────────┐  │
+│  │                  WebView2 渲染层                       │  │
+│  │  ┌──────────────────────────────────────────────────┐  │  │
+│  │  │  HTML/JS 宠物引擎                                 │  │  │
+│  │  │  - 精灵渲染 / CSS 动画 / 状态机                   │  │  │
+│  │  │  - 拖拽 / 点击 / 悬停交互                         │  │  │
+│  │  │  - 对话框气泡                                     │  │  │
+│  │  └──────────────────────────────────────────────────┘  │  │
+│  └────────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │            JS ↔ C# Bridge (CoreWebView2)              │  │
+│  │  C# → JS: window.cfcPetAPI.notifyState(data)         │  │
+│  │  JS → C#: await chrome.webview.hostObjects.sync...    │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+                  ┌──────────────────┐
+                  │  CFC Backend     │
+                  │  localhost:9082  │
+                  │  JWT Bearer Token│
+                  └──────────────────┘
+```
+
+### 模块职责
+
+| 模块 | 职责 |
+|------|------|
+| **API Client** | 定时轮询 / 事件触发时拉取任务、能量、打卡数据；JWT 缓存与刷新 |
+| **State Manager** | 将 API 数据转换为宠物状态（idle/happy/sad/busy/sleeping 等） |
+| **Bridge** | C# 调用 JS 函数推送状态，JS 回调 C# 处理点击/拖拽事件 |
+| **托盘 / 快捷手势** | 右键菜单（设置/最小化/退出）、键盘快捷键（显示/隐藏/唤醒） |
+| **WebView2 渲染层** | 接收状态数据，驱动精灵动画，处理用户交互 |
+
+---
+
+## 三、数据流（API → 宠物状态映射）
+
+### 数据来源
+
+| CFC API | 轮询频率 | 用途 |
+|---------|----------|------|
+| `POST /api/tasks/today` | 30s | 当前用户今日任务列表 |
+| `POST /api/tasks/my-pending` | 30s | 待审核任务数 |
+| `POST /api/energy/overview` | 60s | 五维能量当前值 |
+| `POST /api/daily/checkin` | 60s | 今日打卡状态（身/智/心） |
+| `POST /api/user/mascot/get` | 首次 / 手动刷新 | 获取用户已选形象 |
+
+### 状态映射表
+
+| 数据字段 | 映射宠物状态 | 触发动作 |
+|---------|------------|---------|
+| 今日任务全完成 | `happy` | 翅膀展开/甩尾巴 + 说话气泡"完成了！" |
+| 今日任务进行中（有1+未开始） | `busy` | 低头看时间 / 来回踱步 |
+| 今日任务超过2个未完成（截止后） | `worried` | 皱眉 / 叹气 |
+| 健康打卡完成 | `excited` | 转圈 / 蹦跳 |
+| 健康打卡未做（下午未打卡） | `remind` | 用爪子戳屏幕提示 |
+| 身维度能量高 | `energetic` | 活跃动作，跳跃 |
+| 身维度能量低 | `tired` | 趴下 / 打哈欠 |
+| 智维度能量高 | `curious` | 歪头思考 |
+| 所有维度都低（< 30%） | `sad` | 垂头丧气 / 沉默 |
+| 用户长时间无操作（>15min） | `sleeping` | 闭眼蜷缩，呼吸起伏 |
+| 用户正在操作键盘/鼠标 | `watching` | 抬头注视光标 |
+| 等待用户互动（如喝水提醒） | `waiting_for_interaction` | 戳屏幕 + 气泡提示 |
+| 小游戏激活（如舒尔特） | `mini-game` | 进入专注状态 + 数字/方块出现 |
+
+### 状态流转时序
+
+```
+C# 侧 Timer (30s) ──► POST /api/tasks/today
+          │
+          ▼
+StateMgr.Update(tasks, energy, checkin)
+          │
+          ▼
+  计算宠物状态
+          │
+          ▼
+window.cfcPetAPI.notifyState(state)
+          │
+          ▼
+WebView2 JS 接收 → 触发对应动画帧 → 播放音效（可选）
+```
+
+---
+
+## 四、形象配置格式（JSON Schema）
+
+### 配置文件结构
+
+```json
+{
+  "version": "1.0",
+  "type": "animal|human|custom",
+  "species": "cockatiel|british_shorthair|human|other",
+  "gender": "male|female|neutral",
+
+  "image_base_url": "./assets/pets/xibao/",
+  "default_image": "standing.png",
+
+  "actions": {
+    "idle": "wings_idle",
+    "happy": "wings_spread",
+    "busy": "head_tilt",
+    "waiting_for_interaction": "hand_gesture",
+    "success_animation": "celebrate",
+    "sleeping": "breath_loop",
+    "mini_game": "puzzle_active"
+  },
+
+  "sounds": {
+    "click": "pip.mp3",
+    "complete": "cheer.mp3",
+    "remind": "water_please.mp3"
+  },
+
+  "parameters": {
+    "move_distance": 15,
+    "animation_speed": 1.0,
+    "interaction_timeout": 300
+  }
+}
+```
+
+### 用户自定义流程
+
+1. 用户放置 PNG 图片到 `~/.xaf-pet/images/<pet-name>/`
+2. 同目录放置 `pet-config.json`（使用上述 Schema）
+3. 应用启动时扫描所有配置文件夹
+4. 用户在"设置"界面选择宠物形象
+
+**要求**：每只宠物需要一张基准 PNG（透明背景）+ 一张动作帧图（可选）。CSS 动画驱动，无需多帧精灵图。
+
+---
+
+## 五、交互规则与动作库
+
+### 核心交互动作（内置库）
+
+| 分类 | 动作名称 | 触发条件 | 说明 |
+|------|----------|----------|------|
+| **基础表情** | `nod` | 任务完成、确认打卡 | 缓慢上下点头 |
+| | `shake` | 任务被拒绝、错误 | 横向摇头 |
+| | `blink` | 默认/定时 | 3-5秒一次 |
+| | `look_around` | 进入新环境 | 左右扫视 |
+| **动物特有** | `whistle` | 用户登录、任务开始 | 鹦鹉吹口哨 |
+| | `ear_scrape` | 用户有新提醒 | 耳朵抖动 |
+| | `tail_flick` | 能量充足 | 尾巴摆动 |
+| | `paw_press` | 完成打卡确认 | 前爪按压 |
+| | `belly_rub` | 能量低 + 用户抚摸 | 腹部摩挲 |
+| **人形动作** | `wave` | 问候/离开 | 手挥动 |
+| | `stretch` | 早上唤醒 | 全身拉伸 |
+| | `clap` | 任务成功 | 双手鼓掌 |
+| | `bow` | 表达歉意/感谢 | 身体前倾 |
+| **状态动作** | `celebrate` | 任务全完成 | 跳跃 + 爱心飞出 |
+| | `sad_animation` | 任务连续失败 | 垂头、缓慢呼吸 |
+| | `worried_animation` | 任务超过期限 | 皱眉、踱步 |
+| **用户互动** | `pet` | 用户按住宠物 2s | 触摸波纹 + 依偎动作 |
+| | `feed` | 右键→喂食 | 吃掉食物动画 |
+| | `play_game` | 点击宠物进入 | 小游戏模式 |
+| | `dismiss` | 长按 3s | 宠物飞走/消失 |
+| **顽皮行为** | `steal_icon` | 随机（间隔 >10min） | 宠物靠近某个图标，假装偷走 |
+| | `eat_document` | 随机（用户保存文件后） | 宠物做出"吃东西"动作 |
+| | `hide` | 用户快速移动鼠标 | 宠物躲起来，几秒后重新出现 |
+
+### 交互流程示例：喝水提醒
+
+1. **C# 侧检测**：每 30s 轮询，发现今日未喝到水卡
+2. **状态变更**：`StateMgr` 将状态设为 `waiting_for_interaction`，原因 `drink_water`
+3. **推送通知**：`window.cfcPetAPI.notifyState({state: "waiting_for_interaction", reason: "drink_water"})`
+4. **JS 侧响应**：宠物竖起爪子 + 气泡"该喝水啦~"
+5. **用户点击确认**：`window.cfcPetAPI.onInteract("confirm")`
+6. **C# 处理**：调用 `POST /api/daily/checkin`（水分项）
+7. **反馈循环**：宠物播放 `celebrate` 动画，气泡"喝好啦！"
+
+---
+
+## 六、核心功能细节
+
+### 6.1 拖拽与置顶
+
+- **拖拽**：左键按住拖动，支持多显示器
+- **置顶**：WPF `TopMost=true`，确保始终在其他窗口上方
+- **自动隐藏**：配置 `auto_hide_when_idle=true` 后，>15min 无操作自动隐藏到托盘
+- **唤出**：恢复任意点击、任务提醒触发
+
+### 6.2 五维能量可视化
+
+宠物颜色随五维能量值动态变化：
+
+| 维度 | 颜色 | 能量高表现 | 能量低表现 |
+|------|------|-----------|-----------|
+| 身 | `#FF8C42` | 身体橙色发光 | 身体灰暗 |
+| 智 | `#6366F1` | 眼睛亮紫色 | 眼睛黯淡 |
+| 富 | `#F59E0B` | 金色光环环绕 | 光环消失 |
+| 行 | `#10B981` | 翅膀/尾巴翠绿 | 颜色褪去 |
+| 心 | `#FF6B9D` | 腮红/颈圈鲜艳 | 颜色淡出 |
+
+### 6.3 声音策略
+
+- 默认开启系统音效
+- 每个状态可配置独立音频
+- 用户可在设置中静音
+
+### 6.4 游戏模式
+
+支持的游戏类型：
+| 游戏 | 描述 | 入口 |
+|------|------|------|
+| 舒尔特方格 | 16格数字顺序点击 | 点击宠物 → "玩游戏" |
+| 记忆翻牌 | 翻牌配对 | 点击宠物 → "玩游戏" |
+| 数独 | 9×9 数独 | 点击宠物 → "玩游戏" |
+
+游戏结束后，宠物播放 `celebrate` 或 `sad_animation`。
+
+---
+
+## 七、技术栈
+
+| 层级 | 技术 | 说明 |
+|------|------|------|
+| UI 框架 | WPF (.NET 6) | 原生 Windows 桌面框架 |
+| 渲染引擎 | WebView2 | Edge 内核，支持现代 CSS/JS |
+| API 调用 | HttpClient + HttpClientFactory | 异步轮询，JWT 缓存 |
+| 动画 | CSS Animation + JavaScript | 跨状态动画驱动 |
+| 配置存储 | JSON 文件 | 用户配置 + 宠物形象 |
+| 打包 | MSIX / ClickOnce | 单文件 exe 部署 |
+
+---
+
+## 八、文件结构
+
+```
+XafPet.Desktop/
+├── src/
+│   ├── App.xaml / App.xaml.cs           # 入口
+│   ├── MainWindow.xaml / MainWindow.xaml.cs  # 主窗口
+│   ├── PetEngine/
+│   │   ├── WebViewHost.xaml             # WebView2 容器
+│   │   ├── StateManager.cs              # 状态管理
+│   │   ├── ApiClient.cs                 # CFC API 客户端
+│   │   └── PetState.cs                  # 状态模型
+│   ├── Assets/
+│   │   ├── default-pet/                 # 默认浠宝/福宝
+│   │   │   ├── standing.png
+│   │   │   └── pet-config.json
+│   │   └── sounds/                      # 音效
+│   ├── Scripts/
+│   │   ├── pet-engine.js                # 宠物渲染引擎
+│   │   └── interactions.js              # 交互逻辑
+│   └── Styles/
+│       └── animations.css               # 动画定义
+├── config/
+│   └── app.json                         # 应用配置
+└── user-data/                           # 用户数据（运行时生成）
+    └── pets/
+        └── <user-pet-name>/
+            ├── standing.png
+            └── pet-config.json
+```
+
+---
+
+## 九、部署说明
+
+- **目标平台**：Windows 10/11
+- **依赖**：WebView2 Runtime（已预装在 Win10+，旧版需单独安装）
+- **网络**：需要能访问 `http://localhost:9082`（CFC 后端）
+- **首次启动**：引导用户输入 JWT Token 或扫码登录
+- **自动更新**：可选配置 GitHub Releases 自动检查更新
+
+---
+
+## 十、验收标准
+
+- [ ] 宠物可正常显示在桌面，可拖拽移动
+- [ ] 宠物置顶功能正常工作
+- [ ] 五维能量变化时宠物颜色和状态正确反映
+- [ ] 任务完成/未完成时宠物动画触发正确
+- [ ] 喝水提醒可触发，用户点击后可完成打卡
+- [ ] 小游戏（舒尔特方格）可正常运行
+- [ ] 用户可上传自定义 PNG 形象并配置
+- [ ] 应用可正常最小化到托盘
+- [ ] 所有操作无内存泄漏，资源占用 < 50MB
+
+---
+
+## 十一、非功能性需求
+
+| 需求 | 说明 |
+|------|------|
+| **性能** | 内存占用 < 50MB，CPU < 5% |
+| **响应** | 状态刷新延迟 < 2s |
+| **兼容性** | Windows 10 (1803+)、Windows 11 |
+| **安全性** | JWT Token 加密存储，不记录密码 |
+| **可用性** | 支持中文、英文语言包 |
+| **可维护性** | 代码注释完整，支持后续扩展新游戏 |
+
+---
+
+> **下一步**：编写实现计划（writing-plans）