# VirtualPet

**Repository Path**: Solbrilo/virtual-pet

## Basic Information

- **Project Name**: VirtualPet
- **Description**: 移动应用大作业
- **Primary Language**: Kotlin
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-12-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🐱 掌上猫宠 (Pocket Cat Pet)

> **Motion is Interaction.**
> 连接物理与数字世界的分布式虚拟宠物系统。
> A distributed virtual pet system bridging the physical and digital worlds via sensor fusion.

![Kotlin](https://img.shields.io/badge/Language-Kotlin%201.9-purple.svg) ![Architecture](https://img.shields.io/badge/Architecture-MVVM-blue.svg) ![Platform](https://img.shields.io/badge/Platform-Android-green.svg) ![LBS](https://img.shields.io/badge/LBS-AMap_SDK-red.svg) ![Backend](https://img.shields.io/badge/Backend-Firebase-orange.svg)

## 📖 项目愿景 (Vision)

**掌上猫宠** 不仅仅是一个电子宠物应用，它构建了一个高性能的移动端系统，实现了 **"物理运动 → 数字资产 → 社交特权"** 的完整闭环。

我们致力于解决传统虚拟宠物应用的“数据孤岛”痛点，通过深度融合 Android 硬件传感器、MVVM 架构与实时云服务，让用户的现实运动直接转化为宠物的生命动力。

## ✨ 核心功能 (Key Features)

### 🏃 运动工作量证明 (Proof of Walk)
创新性的 "Move-to-Earn" 经济模型：
* **核心算法**：利用传感器捕获步数，按 `100 步 = 1 积分` 的比例转化为数字资产。
* **价值流转**：积分是系统中的硬通货，用于购买猫粮维持宠物生命，或兑换稀有道具。

### ❤️ 生命引擎 (Life Engine)
* **智能代谢**：基于 **Kotlin Coroutines** 实现非阻塞式心跳机制，每 60 秒触发一次状态衰减（饥饿/心情/清洁度），模拟真实生物代谢。
* **零负担运行**：相比传统 Timer 方案，UI 阻塞率降低至 0%。

### 🗺️ LBS 社交特权 (LBS Social Privilege)
* **地图留言**：集成高德地图 SDK，支持在真实地理坐标上发布“地理位置弹幕”。
* **稀缺性设计**：地图留言权限并非默认开启，必须通过运动积分兑换 `MapUnlock` 道具解锁，构建高质量 UGC 社区。

## 🏗️ 技术架构 (Technical Architecture)

本项目采用 **分层解耦架构**，确保了系统的高内聚与低耦合。

### 1. 硬件抽象层 (HAL & Sensor Fusion)
* **StepCounterManager**: 实现了低功耗传感器抽象层。
* **策略**: 优先直接读取 `TYPE_STEP_COUNTER` 硬件数据；在无传感器设备上自动降级为软件模拟计步线程。
* **权限**: 动态适配 Android 10+ `ACTIVITY_RECOGNITION` 隐私权限。

### 2. 本地核心引擎 (Local Core Engine)
* **单一数据源 (Single Source of Truth)**: `PetRepository` 采用单例模式，作为全应用唯一的数据中心，确保数据 100% 一致性。
* **MVVM 驱动**: ViewModel 通过 `LiveData` 观察 Repository，实现跨页面（主页/商店/地图）数据 0ms 延迟同步。

### 3. 云端与社交层 (Cloud & Social)
* **Firebase Realtime Database**: NoSQL 后端，毫秒级同步社交状态与留言数据。
* **AMap SDK**: 提供精准定位与 Marker 渲染能力。

## 📂 VirtualPet 项目全景结构图

### 1. 核心代码层 (app/src/main/java/edu/hrbeu/virtualpet)
*架构模式：MVVM (Model-View-ViewModel) + Repository*
```
edu.hrbeu.virtualpet
├── 🧱 [实体与核心逻辑 - Domain Layer]
│   ├── 📄 Pet.kt                # [核心] 宠物业务逻辑对象 (纯Kotlin, 不含Android代码)
│   │                              └─ 优化: 包含升级/进食算法，便于单元测试
│   └── 📄 PetState.kt           # [状态] 宠物状态定义
│                                  └─ 优化: 使用 sealed class (如: Sleep, Happy) 替代 enum
│
├── 📦 [数据与仓库 - Data Layer]
│   ├── 📄 PetData.kt            # [模型] 数据库实体模型 (DTO)
│   │                              └─ 优化: 使用 @Entity 注解配合 Room 数据库
│   ├── 📄 CloudRepository.kt    # [源头] 远程数据源接口 (Firebase/API)
│   │                              └─ 优化: 使用 Kotlin Coroutines (协程) 处理网络请求
│   └── 📄 PetRepository.kt      # [仓库] 数据唯一真实来源 (SSOT)
│                                  └─ 优化: 协调本地与云端数据，负责缓存策略
│
├── 🧠 [业务逻辑 - ViewModel Layer]
│   └── 📄 PetViewModel.kt       # [大脑] UI 状态容器与业务桥梁
│                                  └─ 优化: 使用 StateFlow 暴露数据，不持有 View 引用
│
├── ⚙️ [服务与硬件 - Service Layer]
│   ├── 📄 PetWorker.kt          # [后台] WorkManager 后台任务
│   │                              └─ 优化: 处理离线逻辑、定时扣除饱食度
│   └── 📄 StepCounterManager.kt # [硬件] 传感器管理封装
│                                  └─ 优化: 封装 SensorManager，通过 Flow 发送步数更新
│
└── 🎨 [界面展示 - UI Layer]
    ├── 📄 MainActivity.kt       # [主页] 宠物展示与互动
    │                              └─ 优化: 使用 ViewBinding，订阅 ViewModel 状态更新
    ├── 📄 MapActivity.kt        # [地图] LBS 社交与探索
    │                              └─ 优化: 严格管理 MapView 生命周期，防内存泄漏
    ├── 📄 RewardsActivity.kt    # [商店] 积分兑换列表
    │                              └─ 优化: 使用 RecyclerView + ListAdapter 高效刷新
    └── 📄 SettingsActivity.kt   # [设置] 应用偏好设置
                                   └─ 优化: 建议使用 AndroidX Preference 库
```
## 2. 资源文件层 (app/src/main/res)
*负责视觉与布局*
```
res
├── 📂 drawable (图形)
│   ├── 🖼️ cat_happy.webp        # [优化] 将 PNG 转为 WebP，减小体积
│   ├── 🖼️ cat_sad.webp
│   ├── 🖌️ button_bg.xml         # [优化] 使用 <ripple> 标签实现点击水波纹效果
│   └── 🖌️ item_card_bg.xml      # 圆角卡片背景
│
├── 📂 layout (布局)
│   ├── 📱 activity_main.xml     # [优化] 根布局使用 ConstraintLayout 提升性能
│   ├── 📱 item_reward.xml       # [优化] 使用 MaterialCardView 美化列表项
│   └── ...
│
└── 📂 values
    ├── 📄 strings.xml           # 国际化字符串
    └── 📄 themes.xml            # 应用主题与颜色定义
```


## 3. 构建配置层 (Root & Gradle)
*负责项目编译与依赖管理*
```
Root Project
├── 🐘 build.gradle.kts (Project)# 全局配置 (Kotlin版本, 仓库地址)
├── 🐘 build.gradle.kts (App)    # 模块配置 (依赖库, ViewBinding开启)
│                                  └─ 优化: 开启 buildFeatures { viewBinding = true }
├── 📄 settings.gradle.kts       # 模块包含与统一仓库管理
├── 📄 gradle.properties         # 编译器配置 (JVM内存优化)
└── 📄 libs.versions.toml        # [建议] Version Catalog (统一管理依赖版本)
```

## 🛠️ 技术栈 (Tech Stack)

* **语言**: Kotlin
* **架构模式**: MVVM (Model-View-ViewModel)
* **异步并发**: Kotlin Coroutines & Flow
* **数据通信**: LiveData (Observer Pattern)
* **地图服务**: AMap SDK (高德地图)
* **后端服务**: Firebase Realtime Database
* **硬件接口**: Android SensorManager / HAL

## 🚀 快速开始 (Getting Started)

### 1. 环境准备
* **IDE**: Android Studio Iguana 或更高版本
* **JDK**: JDK 17
* **设备**: Android Device (推荐使用真机以测试计步传感器功能)

### 2. 安装步骤

**克隆仓库**
```bash
git clone [https://gitee.com/Solbrilo/virtual-pet.git](https://gitee.com/Solbrilo/virtual-pet.git)
cd virtual-pet
```

**配置 API Keys**
1. 在项目根目录的 local.properties 文件中配置高德地图 Key：
```java
    AMAP_KEY=your_amap_key_here
```
2. 下载 Firebase 的 google-services.json 配置文件，并将其放入 app/ 根目录。

**运行项目**
1.点击 Sync Project with Gradle Files。
2.连接真机，点击 Run。
3.注意：首次运行时，请务必授予应用“身体活动 (Physical Activity)”权限，以启用计步功能。

## 🔮 未来展望 (Roadmap)
* **AI健康预测**: 引入机器学习模型，根据步数频率分析用户健康状态。
* **Web3资产上链**: 探索将宠物数据与稀有道具 NFT 化，实现数字资产确权。

## License
**MIT © 2024 Pocket Cat Pet Team.**