# garbageClassification

**Repository Path**: kxya23_4/garbage-classification

## Basic Information

- **Project Name**: garbageClassification
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能垃圾分类 AI 助手

## 项目简介

本项目是一个基于 Android 的智能垃圾分类应用，面向日常生活中的垃圾识别、分类查询、回收点查找和环保积分记录等场景。应用通过手机摄像头采集画面，结合本地 TensorFlow Lite 模型进行垃圾识别，并提供垃圾分类知识库、附近回收点、投放提醒和个人环保账户等功能。

项目名称：`garbageClassification`

应用包名：`com.example.garbageclassification`

## 主要功能

### 1. AI 垃圾识别

- 调用手机摄像头实时采集画面。
- 使用 TensorFlow Lite 模型识别垃圾类别。
- 在识别结果区域展示垃圾名称和置信度。
- 支持识别后确认分类，并为用户增加环保积分。

### 2. 垃圾分类知识库

- 内置常见垃圾分类数据。
- 支持按垃圾名称、分类、描述、别名进行搜索。
- 展示垃圾类别、投放说明和回收价值。

### 3. 附近回收点

- 集成高德地图相关能力。
- 用于展示或扩展附近回收点查询功能。
- 需要定位和网络权限支持。

### 4. 智能投放提醒

- 支持设置垃圾投放提醒时间。
- 通过 `AlarmManager` 和广播接收器实现提醒。
- 支持取消已设置的提醒。

### 5. 个人环保账户

- 记录用户环保积分。
- 记录碳减排量。
- 展示用户环保数据和排名信息。

## 技术栈

- 开发语言：Kotlin
- 构建工具：Gradle Kotlin DSL
- Android Gradle Plugin：8.2.2
- Kotlin：1.9.22
- 最低 SDK：24
- 目标 SDK：34
- UI：Android ViewBinding、Material Components、ConstraintLayout、CardView
- 相机能力：CameraX
- AI 识别：TensorFlow Lite、TensorFlow Lite GPU、TensorFlow Lite Support、ML Kit Object Detection
- 数据存储：Room Database
- 异步处理：Kotlin Coroutines、Lifecycle Runtime KTX
- 地图能力：高德地图定位与搜索相关 SDK

## 项目结构

```text
garbageClassification
├── app
│   ├── build.gradle.kts
│   └── src
│       ├── main
│       │   ├── AndroidManifest.xml
│       │   ├── assets
│       │   │   ├── garbage_labels.txt
│       │   │   ├── garbage_model.tflite
│       │   │   └── wastenet_labels_raw.txt
│       │   ├── java/com/example/garbageclassification
│       │   │   ├── MainActivity.kt
│       │   │   ├── core
│       │   │   │   └── ml
│       │   │   │       └── Classifier.kt
│       │   │   ├── data
│       │   │   │   ├── local
│       │   │   │   │   ├── AppDatabase.kt
│       │   │   │   │   └── Entities.kt
│       │   │   │   └── repository
│       │   │   │       └── GarbageRepository.kt
│       │   │   └── feature
│       │   │       ├── knowledge
│       │   │       ├── map
│       │   │       ├── profile
│       │   │       ├── recognition
│       │   │       └── reminder
│       │   └── res
│       │       ├── layout
│       │       └── values
│       ├── test
│       └── androidTest
├── build.gradle.kts
├── settings.gradle.kts
├── gradlew
└── gradlew.bat
```

## 核心模块说明

| 模块 | 目录 | 说明 |
|---|---|---|
| 主页面 | `MainActivity.kt` | 负责首页展示、相机启动、识别结果展示、功能入口跳转 |
| AI 识别 | `core/ml`、`feature/recognition` | 负责模型加载、图像分析、识别结果绘制 |
| 数据层 | `data/local`、`data/repository` | 负责 Room 数据库、实体类、DAO 和数据仓库 |
| 知识库 | `feature/knowledge` | 负责垃圾分类知识查询和列表展示 |
| 地图 | `feature/map` | 负责附近回收点相关功能 |
| 个人中心 | `feature/profile` | 负责积分、碳减排量等用户环保数据展示 |
| 提醒 | `feature/reminder` | 负责投放提醒设置、取消和通知触发 |

## 运行环境

建议使用以下环境运行项目：

- Android Studio Giraffe 或更新版本
- JDK 17
- Gradle Wrapper 使用项目自带版本
- Android SDK 34
- Android 7.0 及以上设备或模拟器

## 运行步骤

1. 使用 Android Studio 打开项目根目录。

2. 等待 Gradle 同步完成。

3. 确认模型文件存在：

```text
app/src/main/assets/garbage_model.tflite
app/src/main/assets/garbage_labels.txt
app/src/main/assets/wastenet_labels_raw.txt
```

4. 连接 Android 设备或启动模拟器。

5. 点击 Android Studio 的 Run 按钮运行应用。

也可以在命令行中执行：

```bash
./gradlew assembleDebug
```

Windows 环境可执行：

```bash
gradlew.bat assembleDebug
```

## 权限说明

应用运行时可能使用以下权限：

| 权限 | 用途 |
|---|---|
| `CAMERA` | 调用摄像头进行垃圾识别 |
| `INTERNET` | 地图、定位、网络能力支持 |
| `ACCESS_FINE_LOCATION` | 获取精确位置，用于附近回收点 |
| `ACCESS_COARSE_LOCATION` | 获取粗略位置 |
| `ACCESS_NETWORK_STATE` | 判断网络状态 |
| `ACCESS_WIFI_STATE` | 获取 Wi-Fi 状态 |
| `CHANGE_WIFI_STATE` | 地图 SDK 相关能力支持 |
| `READ_PHONE_STATE` | 高德地图 SDK 可能需要 |
| `SCHEDULE_EXACT_ALARM` | 设置精确投放提醒 |
| `POST_NOTIFICATIONS` | Android 13 及以上发送提醒通知 |

## 数据库说明

项目使用 Room Database，数据库名称为：

```text
garbage-db
```

当前主要实体：

- `GarbageItem`：垃圾分类条目，包含名称、类别、描述、价值、别名等字段。
- `UserAccount`：用户环保账户，包含积分、碳减排量、排名等字段。

数据库版本：

```text
version = 2
```

当前项目使用 `fallbackToDestructiveMigration()`，数据库结构变化时会重建数据库。正式版本中如需保留用户数据，应补充 Room Migration。

## 小组开发约定

### 代码提交

每名成员每天至少完成 1 次有效提交。提交信息格式如下：

```text
类型: 具体说明
```

示例：

```text
feat: 完成垃圾分类识别页面
fix: 修复知识库搜索无结果问题
docs: 更新 README 文档
test: 增加数据库查询测试
style: 调整首页按钮样式
```

### 分支管理

建议使用以下分支：

```text
main        稳定版本
develop     日常开发整合分支
feature/*   功能开发分支
fix/*       bug 修复分支
```

开发流程：

1. 从 `develop` 拉取最新代码。
2. 创建个人功能分支。
3. 完成功能并本地自测。
4. 合并前先同步最新 `develop`。
5. 确认无冲突、能运行后再合并。

### 沟通方式

A01 组统一使用 QQ 群沟通，不安排线上会议和线下讨论。

每日 21:30 前在 QQ 群同步：

```text
今日完成：
遇到问题：
明日计划：
```

遇到问题时，先自行排查 15 分钟。仍无法解决时，在 QQ 群说明问题现象、涉及文件、操作步骤、报错信息和已尝试方法。

## 测试说明

项目已配置基础测试依赖：

- JUnit
- AndroidX Test
- Espresso

建议测试范围：

1. 垃圾识别结果是否正常显示。
2. 摄像头权限被拒绝时是否有提示。
3. 知识库搜索是否能返回正确结果。
4. 个人中心积分和碳减排量是否正确更新。
5. 投放提醒是否能正常设置和取消。
6. 数据库读写是否正常。

运行单元测试：

```bash
./gradlew test
```

Windows 环境：

```bash
gradlew.bat test
```

运行 Android Instrumented Test：

```bash
./gradlew connectedAndroidTest
```

Windows 环境：

```bash
gradlew.bat connectedAndroidTest
```

## 已知注意事项

1. 当前部分中文字符串在源码中显示为乱码，建议统一检查文件编码，使用 UTF-8 保存。
2. `AndroidManifest.xml` 中配置了高德地图 API Key，如用于正式发布，应确认 Key 权限和安全配置。
3. `fallbackToDestructiveMigration()` 会在数据库结构变更时清空旧数据，正式版本应补充迁移逻辑。
4. 当前 `test` 和 `androidTest` 目录尚未看到完整测试用例，后续应补充核心功能测试。
5. 如果模型识别效果不稳定，需要检查模型文件、标签文件和输入图像预处理逻辑是否一致。

## 后续优化方向

- 修复源码中文乱码问题。
- 按照 `docs/training-set-expansion.md` 扩充垃圾识别训练集，提高模型准确率。
- 增加垃圾分类知识库数据量。
- 补充 Room 数据库迁移逻辑。
- 增加识别结果历史记录。
- 增加更多单元测试和功能测试。
- 优化附近回收点展示和搜索体验。
- 增加用户积分等级、成就等环保激励功能。