# 电子宠物功能设计方案

> 项目名：lryx-blog  
> 功能模块：电子宠物（阿喵 & 阿汪）  
> 创建日期：2026-06-19  
> 版本：v1  
> 状态：设计中

---

## 1. 功能概述

### 1.1 核心价值

- **趣味性**：增加博客的互动性和趣味性，区别于普通技术博客
- **情感连接**：两只宠物代表两位作者（宁白久 & 刘小Q），体现情侣博客的温馨感
- **游戏化**：养成系统激励作者持续产出内容（写文章 → 宠物成长）
- **AI 载体**：未来接入 AI Agent，宠物可以陪访客聊天互动

### 1.2 核心概念

- **两只宠物**：阿喵（猫，代表宁白久）和阿汪（狗，代表刘小Q）
- **状态系统**：心情、饱腹度、等级等数值驱动宠物表现
- **成长机制**：博客活动（写文章、访客互动）影响宠物成长
- **AI Agent**：后期接入 LLM，宠物可以对话、有性格、有记忆

---

## 2. 页面展示方案

### 2.1 首页：宠物窝卡片

**位置**：放在"最新动态"和"文章列表"之间

**布局结构**：

```
┌─────────────────────────────────────┐
│  🏠 阿喵和阿汪的小窝                 │
├─────────────────────────────────────┤
│                                     │
│   [阿喵动画]        [阿汪动画]       │
│   🐱 吃饭中...      🐶 睡觉中...    │
│                                     │
│   ❤️ 心情: ████████░░ 85  ❤️ 心情: █████████░ 92  │
│   🍖 饱腹: ███████░░░ 70  🍖 饱腹: ██████░░░░ 65  │
│   ⭐ 等级: Lv.5             ⭐ 等级: Lv.3         │
│                                     │
│   [🍖 喂食] [🤚 抚摸] [💬 对话] [📊 成长记录]     │
│                                     │
└─────────────────────────────────────┘
```

**信息展示**：
- 宠物头像/动画（圆形，132x132px）
- 当前动作状态（吃饭、睡觉、玩耍、写代码等）
- 状态条：心情（0-100）、饱腹度（0-100）、等级（Lv.1-Lv.99）
- 互动按钮：喂食、抚摸、对话、成长记录

### 2.2 其他页面：浮动宠物

**位置**：右下角悬浮（距离底部 80px，距离右侧 20px）

**行为**：
- 宠物在页面角落随机走动（CSS 动画）
- 偶尔做动作（摇晃、眨眼、打滚）
- 偶尔"说话"（气泡文字，3-5 秒后消失）
- 点击宠物 → 弹出对话框（AI Agent 对话）

**视觉设计**：
- 宠物尺寸：64x64px（缩小版）
- 气泡样式：圆角矩形，带小尾巴指向宠物
- 点击区域：扩大到 80x80px（方便点击）

### 2.3 智能悬浮交互（Phase 2+）

**触发条件**：页面滚动，宠物窝区块离开视口

**交互逻辑**：
1. 滚动到宠物窝区块不可见时 → 右下角出现"小窝图标"悬浮按钮（64x64px）
2. 鼠标 hover 悬浮按钮 → 展开迷你预览卡片（显示两只宠物的当前状态）
3. 点击悬浮按钮 → 平滑滚动回到宠物窝区块

**视觉设计**：
- 默认状态：小窝图标（🏠）+ 宠物头像（阿喵 + 阿汪，各 24x24px）
- Hover 状态：展开卡片（宽 200px），显示宠物状态条
- 动画：淡入淡出 + 轻微缩放

**实现要点**：
- 使用 Intersection Observer API 检测宠物窝区块是否可见
- 悬浮按钮使用 `position: fixed`，距离右下角 20px
- 滚动回顶部时用 `scrollIntoView({ behavior: 'smooth' })`

### 2.4 宠物专属页（P1）

**路径**：`/pets`

**定位**：比首页宠物窝更丰富的交互和布局，是宠物的"主页面"

**页面结构**：
1. **顶部大图区域**：两只宠物的全景图/动画（比首页更大更精美）
2. **宠物详情 Tab**：阿喵 / 阿汪 切换
3. **详情信息**：
   - 宠物档案（名字、年龄、性格、喜好）
   - 详细属性（心情、饱腹度、精力、健康度、经验值、等级）
   - 成长曲线图（历史数据可视化）
4. **互动区**：
   - 喂食（多种食物选择，不同效果）
   - 玩耍（小游戏：接飞盘、追毛线球等）
   - 换装（给宠物换衣服/帽子）
   - 对话（AI Agent 深度对话）
5. **成长时间线**：宠物的成长历史记录
6. **宠物相册**：宠物做各种动作的截图/动画
7. **访客互动排行榜**：哪些访客喂食/互动最多

**与首页小窝的区别**：
- 首页：快速查看状态 + 简单互动（喂食/抚摸）
- 专属页：深度互动 + 详细信息 + 游戏化元素

---

## 3. 数据模型

### 3.1 宠物基础信息

```typescript
interface Pet {
  id: number;
  name: string;           // "阿喵" | "阿汪"
  type: 'cat' | 'dog';    // 宠物类型
  owner: 'jelon' | 'joanna'; // 对应的作者
  avatar: string;         // 头像 URL
  createdAt: Date;        // 创建时间
  level: number;          // 等级 (1-99)
  exp: number;            // 当前经验值
  expToNext: number;      // 升级所需经验值
}
```

### 3.2 宠物状态

```typescript
interface PetState {
  petId: number;
  mood: number;           // 心情 (0-100)
  hunger: number;         // 饱腹度 (0-100)
  energy: number;         // 精力 (0-100)
  health: number;         // 健康度 (0-100)
  currentAction: string;  // 当前动作 ("eating" | "sleeping" | "playing" | "coding")
  lastUpdated: Date;      // 最后更新时间
}
```

### 3.3 成长记录

```typescript
interface GrowthLog {
  id: number;
  petId: number;
  eventType: 'feed' | 'interact' | 'level_up' | 'article_published' | 'visitor_interaction';
  description: string;    // "宁白久发布了一篇文章，阿喵获得 50 经验值"
  impact: {
    mood?: number;
    hunger?: number;
    exp?: number;
  };
  createdAt: Date;
}
```

### 3.4 访客互动记录

```typescript
interface VisitorInteraction {
  id: number;
  petId: number;
  visitorId?: number;     // 可选，已登录访客
  visitorIp: string;      // 未登录时用 IP 标识
  actionType: 'feed' | 'pet' | 'chat';
  createdAt: Date;
}
```

---

## 4. 交互设计

### 4.1 首页宠物窝互动

**喂食**：
- 点击"🍖 喂食"按钮
- 宠物播放吃饭动画
- 饱腹度 +20（上限 100）
- 心情 +5
- 显示提示："阿喵吃饱了，心情变好了！"
- 冷却时间：每个访客每 6 小时只能喂一次

**抚摸**：
- 点击"🤚 抚摸"按钮
- 宠物播放开心动画（摇晃、打滚）
- 心情 +10
- 显示提示："阿喵很开心，蹭了蹭你的手~"
- 冷却时间：每个访客每 1 小时只能摸一次

**对话**：
- 点击"💬 对话"按钮
- 弹出对话框（接入 AI Agent）
- 宠物根据性格回复（阿喵高冷、阿汪热情）
- 对话次数限制：每个访客每天 10 次（防止滥用）

**成长记录**：
- 点击"📊 成长记录"按钮
- 弹出侧边栏，展示宠物的成长时间线
- 包含：升级记录、作者发文记录、访客互动记录

### 4.2 浮动宠物互动

**随机行为**：
- 每 30-60 秒随机做一次动作（走动、摇晃、眨眼）
- 每 5-10 分钟随机"说话"一次（气泡文字）
- 说话内容：问候、吐槽、分享小知识、提醒访客互动

**点击对话**：
- 点击浮动宠物 → 弹出对话框
- AI Agent 回复（带宠物性格）
- 对话历史记录在 localStorage（未登录）或数据库（已登录）

### 4.3 博客活动联动

**作者写文章**：
- 作者发布文章 → 对应宠物获得经验值（50-100）
- 宠物心情 +20，饱腹度 +10
- 首页宠物窝显示提示："宁白久发布了一篇文章，阿喵获得了营养！"

**访客看文章**：
- 访客阅读文章超过 3 分钟 → 两只宠物心情 +2
- 显示浮动提示："有访客在读文章，阿喵和阿汪很开心~"

**访客留言/评论**：
- 访客留言 → 两只宠物心情 +5
- 显示提示："有访客留言了，阿喵和阿汪很兴奋！"

---

## 5. 技术方案

### 5.1 前端动画

**方案 A：CSS 动画（推荐 MVP）**
- 优点：轻量、性能好、实现简单
- 缺点：动画效果有限
- 适用：简单的摇晃、眨眼、走动

**方案 B：Lottie 动画**
- 优点：动画效果丰富、文件小、跨平台
- 缺点：需要设计师制作动画文件
- 适用：复杂的宠物动作（吃饭、睡觉、玩耍）

**方案 C：Canvas / 精灵图动画**
- 优点：完全自定义、性能可控
- 缺点：实现复杂、文件大
- 适用：需要高度自定义的场景

**推荐**：MVP 用 CSS 动画，Phase 2 升级到 Lottie

### 5.2 后端数据

**技术栈**：
- 数据库：MySQL（宠物数据、成长记录）
- 缓存：Redis（宠物实时状态、冷却时间）
- API：RESTful API（CRUD 宠物数据、互动接口）

**关键接口**：
- `GET /api/pets` — 获取两只宠物的基础信息和状态
- `POST /api/pets/:id/feed` — 喂食
- `POST /api/pets/:id/pet` — 抚摸
- `POST /api/pets/:id/chat` — 对话（接入 AI Agent）
- `GET /api/pets/:id/growth-logs` — 获取成长记录

### 5.3 AI Agent（Phase 3）

**技术方案**：
- 接入 LLM（Claude / GPT / 通义千问）
- 宠物性格 Prompt：
  - 阿喵：高冷、毒舌、偶尔傲娇，喜欢技术话题
  - 阿汪：热情、粘人、乐观，喜欢生活话题
- 对话记忆：短期记忆（当前会话）+ 长期记忆（数据库存储）

**对话示例**：
```
访客：你好呀~
阿喵：哦，又有人来了。有什么事吗？（高冷）

访客：今天天气真好~
阿汪：汪汪！是啊是啊，好想出去玩！你今天要做什么呀？（热情）
```

---

## 6. 实现阶段

### Phase 1：MVP（2-3 天）

**目标**：静态展示 + 简单互动

- [ ] 首页宠物窝卡片（静态图片 + 状态条）
- [ ] 喂食、抚摸按钮（前端动画 + 后端记录）
- [ ] 宠物状态数据（MySQL）
- [ ] 冷却时间控制（Redis）

**交付物**：
- 前端：宠物窝卡片组件
- 后端：宠物 CRUD API、互动 API
- 数据库：宠物表、状态表、互动记录表

### Phase 2：动画升级（3-5 天）

**目标**：丰富的动画效果 + 浮动宠物

- [ ] Lottie 动画（吃饭、睡觉、玩耍等 10+ 动作）
- [ ] 浮动宠物组件（其他页面右下角）
- [ ] 随机行为（走动、说话）
- [ ] 气泡文字提示

**交付物**：
- 前端：Lottie 动画文件、浮动宠物组件
- 后端：随机行为生成逻辑

### Phase 3：AI Agent（5-7 天）

**目标**：宠物可以对话

- [ ] 接入 LLM API
- [ ] 宠物性格 Prompt 设计
- [ ] 对话记忆（短期 + 长期）
- [ ] 对话界面（弹窗组件）
- [ ] 对话次数限制（防止滥用）

**交付物**：
- 前端：对话弹窗组件
- 后端：AI Agent 服务、对话记录存储
- Prompt：宠物性格配置

### Phase 4：游戏化（7-10 天）

**目标**：完整的养成系统

- [ ] 宠物等级系统（经验值、升级）
- [ ] 宠物成就系统（喂食次数、互动次数）
- [ ] 宠物专属页（详细信息、成长历史、相册）
- [ ] 访客互动排行榜
- [ ] 宠物日记（自动生成）

**交付物**：
- 前端：宠物专属页、成就展示组件
- 后端：等级系统、成就系统、排行榜 API

---

## 7. 设计资源

### 7.1 宠物形象设计

**阿喵（猫）**：
- 颜色：蓝灰色（呼应宁白久的蓝色主题）
- 性格：高冷、优雅、偶尔傲娇
- 标志性动作：舔爪子、伸懒腰、盯着屏幕看代码

**阿汪（狗）**：
- 颜色：粉棕色（呼应刘小Q 的粉色主题）
- 性格：热情、粘人、乐观
- 标志性动作：摇尾巴、打滚、叼着骨头跑

**参考**：
- QQ 宠物（企鹅）的成长形态变化
- 旅行青蛙的简单互动模式
- 电子鸡/电子狗的经典养成游戏

### 7.2 动画资源

**需要制作的动画**：
- 待机动画（站立、呼吸）
- 吃饭动画（咀嚼、舔嘴）
- 睡觉动画（闭眼、打呼噜）
- 玩耍动画（追球、打滚）
- 开心动画（摇晃、跳跃）
- 走路动画（左右移动）

**格式**：Lottie JSON（推荐）或 GIF

---

## 8. 风险与注意事项

### 8.1 技术风险

- **性能问题**：浮动宠物动画可能影响页面性能
  - 解决：使用 CSS transform（GPU 加速）、限制动画复杂度
- **AI 成本**：LLM API 调用费用
  - 解决：限制对话次数、使用缓存、选择性价比高的模型
- **数据一致性**：宠物状态需要实时更新
  - 解决：Redis 缓存 + 定时同步到 MySQL

### 8.2 产品风险

- **用户参与度低**：访客可能不感兴趣
  - 解决：宠物主动互动（随机说话）、首页突出展示
- **互动过度**：访客频繁喂食/对话
  - 解决：冷却时间、每日次数限制
- **宠物形象不讨喜**：设计不符合预期
  - 解决：先做 MVP 验证、收集反馈后迭代

### 8.3 合规风险

- **AI 生成内容**：宠物对话可能包含不当内容
  - 解决：Prompt 限制、内容审核、敏感词过滤
- **隐私问题**：访客互动记录涉及 IP 地址
  - 解决：隐私政策说明、数据加密存储

---

## 9. 成功指标

### 9.1 量化指标

- 宠物互动率：首页访客中，多少人点击了喂食/抚摸/对话
- 平均互动次数：每个访客每天互动几次
- AI 对话时长：每次对话平均多少轮
- 回访率：看过宠物的访客，下次是否还来

### 9.2 质化指标

- 访客反馈：留言板是否有提到宠物的评论
- 社交分享：是否有人截图分享宠物
- 作者感受：两位作者是否喜欢这个功能

---

## 10. 下一步行动

1. **确认设计方案**：和两位作者确认宠物形象、性格、互动方式
2. **设计宠物形象**：找设计师或使用 AI 生成宠物图片
3. **制作动画**：制作 Lottie 动画文件（10+ 动作）
4. **开发 MVP**：先实现静态展示 + 简单互动
5. **测试反馈**：上线 MVP，收集访客反馈
6. **迭代优化**：根据反馈升级到 Phase 2/3/4

---

**设计确认人**：待确认  
**确认日期**：待定