# SimplePet

**Repository Path**: ceogo/simple-pet

## Basic Information

- **Project Name**: SimplePet
- **Description**: 一个简易的家庭互动式宠物养成App
- **Primary Language**: HTML
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-02
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 快乐家庭宠物 - Happy Family Pet

一个陪伴式宠物养成应用，专为家庭设计，让孩子在游戏中学习责任与关爱。项目包含两个版本：静态端和App端，满足不同场景的使用需求。

## 📱 项目版本

### 1. 静态端（直接使用）
- **位置**：根目录下的 `index.html` 文件
- **特点**：纯HTML+CSS+JavaScript实现，无需构建，直接在浏览器中打开即可使用
- **适用场景**：快速体验、无需安装环境、离线使用
- **技术栈**：原生JavaScript、Tailwind CSS（CDN）、Font Awesome
- **数据存储**：localStorage（本地存储）

### 2. App端（现代前端框架）
- **位置**：`app` 目录
- **特点**：基于React的现代前端应用，使用Vite构建，功能更完整
- **适用场景**：开发调试、功能扩展、生产部署
- **技术栈**：React 18+、Framer Motion、Zustand、Tailwind CSS、Vite
- **数据存储**：IndexedDB（浏览器原生数据库）

### 3. Backend端（云存储服务）
- **位置**：`backend` 目录
- **特点**：基于Node.js + SQLite的云存储后端服务
- **适用场景**：多设备数据同步、云端备份
- **技术栈**：Express、sql.js、dotenv
- **数据存储**：SQLite（每个用户独立数据库文件）

## 🎯 核心功能

### 宠物养成系统
- **12生肖宠物**：选择属于你的生肖宠物，每种宠物都有独特的表情和动画
- **状态管理**：通过喂食和玩耍维持宠物的饥饿度和快乐度
- **表情变化**：宠物会根据状态展示不同的表情，增加互动感
- **自定义宠物**：支持添加自定义宠物形象，打造独一无二的伙伴

### 任务与奖励
- **任务系统**：家长可以创建任务，孩子完成后获得金币奖励
- **奖励机制**：通过完成任务赚取金币，用于购买宠物用品
- **经济系统**：通过任务获取金币，合理规划消费
- **完成反馈**：任务完成时有彩纸庆祝动画

### 商店与背包
- **多样化商品**：食品、玩具、装扮等多种商品
- **背包管理**：方便查看和使用已购买的物品
- **消费系统**：使用金币购买物品，培养孩子的理财意识

### 成长系统
- **20层勋章**：从🥚新生蛋到👼圣灵，见证宠物成长历程
- **积分获取**：完成任务、喂养、使用玩具玩耍均可获得成长积分
- **里程碑奖励**：任务、喂养、玩耍、收藏四类里程碑，达成获得额外积分
- **成就展示**：顶栏显示最高已达成成就，点击可查看详细进度
- **成长卡片**：宠物面板内嵌成长等级卡片，展开可查看统计数字
- **独立体系**：金币与成长积分分离，互不影响

### 家长控制
- **角色切换**：家长模式和孩子模式自由切换
- **密码保护**：家长模式需要密码验证，MD5加密存储（访问码作为salt）
- **状态调整**：家长可以调整宠物状态，确保游戏体验平衡
- **任务管理**：家长可以创建、编辑和删除任务
- **切换逻辑**：
  - 孩子切家长 → 弹出密码验证窗
  - 家长切孩子 → 直接进入孩子面板

### 云存储系统
- **极简访问**：无需注册登录，6位访问码即可使用
- **签名认证**：HMAC-SHA256 签名验证，访问码作为密钥
- **直接CRUD**：每次操作实时同步云端，无需手动同步
- **离线队列**：API失败时记录待同步队列，恢复后自动重试
- **最后写入胜出**：冲突解决策略
- **数据隔离**：每个用户独立存储空间，天然隔离
- **隐私友好**：无用户信息收集，符合最小化原则
- **后台管理**：通过配置的访问码路径进入管理界面

### 视觉效果
- **流畅动画**：精心设计的过渡和互动动画
- **响应式设计**：适配不同设备屏幕
- **精美界面**：可爱的宠物形象和友好的用户界面

## 🛠️ 技术栈

### 静态端
- **前端**：HTML5、CSS3、原生JavaScript
- **样式**：Tailwind CSS（CDN）
- **图标**：Font Awesome（CDN）
- **存储**：localStorage

### App端
- **前端框架**：React 18+
- **动画库**：Framer Motion
- **状态管理**：Zustand / React Context
- **样式方案**：Tailwind CSS
- **构建工具**：Vite
- **图标库**：Lucide React
- **特效库**：Canvas Confetti
- **数据存储**：IndexedDB（浏览器原生数据库）

### Backend端
- **运行环境**：Node.js 18+
- **Web框架**：Express
- **数据库**：sql.js（SQLite纯JS实现）
- **配置管理**：dotenv
- **认证方式**：HMAC-SHA256 签名

## 📁 项目结构

```
SimplePet/
├── app/                    # App端（React版本）
│   ├── public/              # 静态资源
│   │   └── images/          # 宠物图片和表情
│   ├── src/
│   │   ├── components/      # 组件
│   │   ├── db/              # 数据库相关
│   │   ├── services/        # 服务
│   │   ├── stores/          # Zustand状态管理
│   │   ├── utils/           # 工具函数
│   │   ├── App.jsx          # 应用入口
│   │   └── main.jsx         # 渲染入口
│   ├── package.json
│   ├── vite.config.js
│   └── .env.example           # 环境变量示例
├── backend/                 # Backend端（云存储服务）
│   ├── src/
│   │   ├── index.js         # 入口文件
│   │   ├── config.js        # 配置管理
│   │   ├── db/              # 数据库管理
│   │   ├── middleware/      # 中间件
│   │   ├── routes/          # 路由
│   │   └── services/        # 服务
│   ├── storages/            # SQLite存储目录
│   ├── .env                 # 环境变量
│   └── package.json
├── snapshot/                # 应用截图
├── index.html               # 静态端入口文件
├── run-app.ps1              # Windows快速启动脚本
└── README.md                # 项目说明
```

## 📦 安装与运行

### 静态端使用方法
1. 直接在浏览器中打开 `index.html` 文件
2. 开始使用应用，无需安装任何依赖
3. 首次启动时，选择宠物形象
4. 点击右上角的「切换角色」按钮可以切换角色

### App端使用方法

#### 环境要求
- Node.js 18.0 或更高版本
- npm 或 yarn 包管理器

#### 安装步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd SimplePet
   ```

2. **安装依赖**
   ```bash
   cd app
   npm install
   ```

3. **启动开发服务器**
   ```bash
   npm run dev
   ```

4. **构建生产版本**
   ```bash
   npm run build
   ```

### Backend端使用方法

#### 环境要求
- Node.js 18.0 或更高版本
- npm 或 yarn 包管理器

#### 安装步骤

1. **安装依赖**
   ```bash
   cd backend
   npm install
   ```

2. **配置环境变量**
   ```bash
   cp .env.example .env
   # 编辑 .env 配置
   ```

3. **启动服务**
   ```bash
   npm run dev   # 开发模式（热重载）
   npm start     # 生产模式
   ```

4. **访问管理后台**
   ```
   http://localhost:3000/{ADMIN_ACCESS_CODE}
   ```
   `ADMIN_ACCESS_CODE` 在 `.env` 中配置

#### 环境变量配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PORT` | 3000 | 服务端口 |
| `CORS_ENABLED` | false | 是否启用CORS白名单 |
| `CORS_ORIGINS` | - | 允许的域名（逗号分隔） |
| `ADMIN_ACCESS_CODE` | admin123 | 管理后台访问码 |
| `DISABLE_HOME_PAGE` | false | 是否禁止首页访问 |

### 联合运行（推荐）

```bash
# 终端1：启动后端
cd backend
npm run dev

# 终端2：启动前端（会代理API请求到后端）
cd app
npm run dev
```

访问 `http://localhost:5173/{6位访问码}` 即可使用

### 快速启动脚本

Windows 用户可使用 `run-app.ps1` 快速启动：

```powershell
.\run-app.ps1
```

菜单选项：
1. 运行静态页面（端口8000）
2. 运行React应用（端口5173）
3. 运行Backend服务（端口3000）
4. 同时运行前端和后端

### App端环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `VITE_PORT` | 5173 | 开发服务器端口 |
| `VITE_API_SERVER` | - | 后端API地址 |
| `VITE_ALLOWED_HOSTS` | localhost,127.0.0.1 | 允许的主机名 |

## 🎮 使用指南

### 孩子角色

1. **选择角色**：首次进入选择「孩子」或「家长」
2. **选择宠物**：选择喜欢的生肖宠物或自定义宠物
3. **照顾宠物**：通过喂食和玩耍提升宠物状态
4. **完成任务**：完成家长发布的任务获取金币
5. **逛商城**：使用金币购买食物、玩具和装扮
6. **背包管理**：查看和使用购买的物品
7. **查看成长**：顶栏显示最高成就，点击查看详细里程碑

### 家长角色

1. 选择「家长」角色进入
2. **发布任务**：设置任务描述和金币奖励
3. **管理任务**：查看和删除已发布的任务
4. **宠物管理**：设置宠物的饥饿度和快乐度
5. **修改密码**：更改家长密码（自动加密存储到云端）
6. **切换角色**：直接点击切换按钮进入孩子面板

### 角色切换规则

| 切换方向 | 操作 |
|---------|------|
| 孩子 → 家长 | 输入密码验证 |
| 家长 → 孩子 | 直接切换 |

## 📸 应用截图

### 孩子面板
![孩子面板](snapshot/app-preview.png)

### 家长面板
![家长面板](snapshot/app-preview2.png)

## 🌟 特色亮点

- **双重版本**：同时提供静态端和App端，满足不同使用场景
- **寓教于乐**：通过游戏培养孩子的责任感和爱心
- **家庭互动**：家长和孩子共同参与，增进亲子关系
- **个性化体验**：支持自定义宠物，满足孩子的创造力
- **安全保障**：家长模式密码保护，MD5加密存储
- **流畅体验**：精心设计的动画和交互，提供愉悦的游戏体验
- **离线优先**：本地操作优先，网络恢复后自动同步
- **成长激励**：20层勋章 + 四类里程碑，持续激励孩子

## 🐾 宠物状态系统

### 状态值

- **饥饿度**：0-1000，通过喂食增加
- **快乐度**：0-300，通过玩耍增加（随机+5~15）
- **状态衰减**：每10秒自动减少

### 表情状态

| 表情状态 | 触发条件 | 描述 |
|---------|---------|------|
| default | 饥饿度 > 600 且快乐度 > 150 | 正常状态 |
| happy | 饥饿度 > 800 且快乐度 > 180 | 开心状态 |
| confused | 饥饿度 < 200 | 困惑状态（非常饥饿） |
| think | 饥饿度 < 400 | 思考状态（有点饥饿） |
| shy | 快乐度 < 150 | 害羞状态（有点不快乐） |
| sleepy | 其他情况 | 困倦状态 |
| surprise | 快乐度 > 210 | 惊喜状态（很快乐） |
| talk | 快乐度 > 270 | 开心状态（非常快乐） |

## 🏆 成长系统

### 积分获取规则

| 行为 | 获得积分 | 说明 |
|------|---------|------|
| 完成任务 | 金币×0.5 | 任务奖励金币的一半转化为积分 |
| 喂养宠物 | +2 | 使用背包食物喂养 |
| 使用玩具 | +2 | 使用背包玩具玩耍 |

### 20层勋章等级

| 等级 | 名称 | 所需积分 | 等级 | 名称 | 所需积分 |
|-----|------|---------|-----|------|---------|
| 1 | 🥚 新生蛋 | 0 | 11 | 🦊 智慧 | 2500 |
| 2 | 🐣 破壳 | 50 | 12 | 🦄 神秘 | 3200 |
| 3 | 🐥 学步 | 120 | 13 | 🐉 神圣 | 4000 |
| 4 | 🐤 成长 | 200 | 14 | 🦁 传说 | 5000 |
| 5 | 🐥 活泼 | 320 | 15 | 🦋 史诗 | 6200 |
| 6 | 🦅 勇敢 | 480 | 16 | 🐲 神话 | 7800 |
| 7 | 🦉 聪慧 | 700 | 17 | 🌟 永恒 | 10000 |
| 8 | 🦢 优雅 | 1000 | 18 | 👑 至尊 | 13000 |
| 9 | 🐕 守护 | 1400 | 19 | 💫 神圣守护 | 17000 |
| 10 | 🐺 忠诚 | 1900 | 20 | 👼 圣灵 | 22000 |

## 🔐 安全机制

### 密码加密
- **算法**：MD5
- **Salt**：6位访问码
- **存储**：数据库中只存哈希值，不存明文

### API签名
- **算法**：HMAC-SHA256
- **密钥**：6位访问码
- **流程**：请求时生成签名 → 服务端验证签名 → 通过后执行操作

### 管理后台
- **访问路径**：`/{ADMIN_ACCESS_CODE}`
- **删除确认**：需手动输入访问码确认

## 🛒 商城物品价格表

### 食品类

| 物品名称 | 价格（金币） | 效果（饥饿度） |
|---------|------------|--------------|
| 小鱼干 | 10 | +20 |
| 饼干 | 3 | +20 |
| 披萨 | 15 | +60 |
| 汉堡 | 12 | +55 |
| 冰淇淋 | 6 | +35 |
| 西瓜 | 8 | +40 |
| 烤鸡 | 18 | +70 |
| 面包 | 4 | +25 |
| 苹果 | 5 | +30 |

### 玩具类

| 物品名称 | 价格（金币） | 效果（快乐度） |
|---------|------------|--------------|
| 皮球 | 8 | +20 |
| 风筝 | 10 | +25 |
| 气球 | 5 | +15 |

### 装扮类

| 物品名称 | 价格（金币） | 效果 |
|---------|------------|------|
| 帽子 | 20 | 永久装扮 |
| 蝴蝶结 | 15 | 永久装扮 |
| 眼镜 | 25 | 永久装扮 |

## ⚠️ 注意事项

1. **数据存储**
   - 静态版本：数据存储在localStorage中
   - React版本：数据存储在IndexedDB中
   - 启用云同步后数据同时保存到云端
   - 清除浏览器数据会导致本地数据丢失

2. **宠物状态**
   - 宠物状态会随时间自动衰减
   - 需要定期照顾宠物

3. **密码安全**
   - 密码使用MD5+访问码加密存储
   - 请妥善保管访问码

4. **云同步**
   - 每次本地操作都会自动触发API请求
   - 网络异常时会排队等待恢复后重试

## 🚀 未来计划

- 添加更多宠物种类和表情
- 增加更多玩具和装扮选项
- 实现家长和孩子之间的消息通知
- 添加数据导出/导入功能
- 支持多宠物同时养成

## 📄 开源许可证

本项目采用 MIT 许可证。

## 👨‍💻 开发者

**小胡先森** - 致力于创建优质的家庭互动应用

---

✨ 快乐家庭宠物 | 陪伴式成长 | 小胡先森 ✨