# 浠艾福桌面宠物设计文档

> **日期：** 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",

    // 【新增】用户自定义状态映射
    // 键为用户自定义状态名，值为对应的 CSS 动画类名或帧序列
    "custom_state_1": "user_animation_1",
    "custom_state_2": "user_animation_2"
  },

  "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，可在 `actions` 中添加 `custom_state_N` 键值对）
3. 应用启动时扫描所有配置文件夹
4. 用户在"设置 → 自定义状态"界面管理自定义状态映射
5. C# 侧通过 `window.cfcPetAPI.setCustomState("custom_state_1", data)` 发送自定义状态

**要求**：
- 每只宠物需要一张基准 PNG（透明背景）+ 可选的动作帧图
- CSS 动画驱动，无需多帧精灵图
- 支持最多 10 种用户自定义状态（通过配置文件 key 如 `custom_state_1`~`custom_state_10` 定义）

### C# ↔ JS Bridge 新增接口

```csharp
// C# → JS：设置自定义状态
public void SetCustomState(string stateName, object stateData);
```

---

## 五、交互规则与动作库

### 核心交互动作（内置库）

| 分类 | 动作名称 | 触发条件 | 说明 |
|------|----------|----------|------|
| **基础表情** | `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）