# QrApplication
**Repository Path**: cfdy123/qr-application
## Basic Information
- **Project Name**: QrApplication
- **Description**: 可生成和扫描二维码的安卓应用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-29
- **Last Updated**: 2026-10-12
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 二维码资产管理应用
**一个基于 Android 平台的轻量级资产管理系统，支持二维码扫描/生成、本地存储、搜索、批量导出与分享。**
[](https://developer.android.com)
[](https://kotlinlang.org)
[](https://developer.android.com)
[](https://developer.android.com)
[](#-许可证)
[](https://gitee.com/cfdy123/qr-application)
[](README.md)
[](README.en.md)
---
## 目录
- [功能特性](#-功能特性)
- [界面预览](#-界面预览)
- [技术栈](#-技术栈)
- [项目结构](#-项目结构)
- [架构概览](#-架构概览)
- [快速开始](#-快速开始)
- [使用说明](#-使用说明)
- [数据模型](#-资产数据模型)
- [二维码数据格式](#-二维码数据格式)
- [权限与安全](#-权限与安全)
- [路线图](#-路线图)
- [参与贡献](#-参与贡献)
- [更新日志](CHANGELOG.md)
- [许可证](#-许可证)
- [Star 趋势](#-star-趋势)
---
## ✨ 功能特性
| 功能 | 说明 |
| --- | --- |
| 📷 **二维码扫描** | 调用摄像头扫描资产二维码，自动解析并展示资产信息（竖屏扫码界面） |
| 🖨️ **二维码生成** | 手动录入资产信息，实时生成对应的二维码图片 |
| 💾 **资产保存** | 将扫描到的资产一键保存到本地数据库 |
| 📋 **列表展示** | 以 RecyclerView 展示全部资产，无数据时给出空状态提示 |
| 🔍 **搜索** | 按名称 / 规格 / 持有人模糊搜索，输入停顿 300ms 后才查询（防抖） |
| ✏️ **编辑** | 点击列表项进入编辑页，修改名称 / 规格 / 持有人 |
| 🗑️ **删除** | 长按列表项，二次确认后删除 |
| 📤 **CSV 导出** | 将资产列表导出为 CSV：可「保存到本地」（自选目录，长期保留）或「分享到其他应用」 |
## 🖼 界面预览
> 🚧 *截图待补充。*
## 🛠 技术栈
- **语言**：Kotlin
- **UI**：传统 View 体系（XML 布局 + `AppCompatActivity` + `RecyclerView` + `CardView`），Material Design 3 组件
- **主题**：`Theme.Material3.DayNight.NoActionBar`，内置深色模式（`values-night`）
- **架构**：单 Module（`:app`），Activity + Adapter 的经典分层
- **数据持久化**：Room（KSP 注解处理器）
- **异步**：Kotlin Coroutines + `lifecycleScope`
- **二维码**：
- 生成 —— ZXing `core` 3.5.3
- 扫描 —— `zxing-android-embedded` 4.3.0（基于 ZXing 的封装）
- **依赖管理**：Gradle Version Catalog（`gradle/libs.versions.toml`）
### 版本信息
| 项目 | 版本 |
| --- | --- |
| Android Gradle Plugin (AGP) | 9.4.1 |
| Gradle | 9.6.0 |
| KSP | 2.3.6 |
| compileSdk / targetSdk | 37 |
| minSdk | 26（Android 8.0） |
| SDK Build Tools | 36.0.0 |
| Java 语言级别 | 11（编译工具链需 JDK 17+） |
| Room | 2.7.0 |
## 📁 项目结构
```
MyApplication/
├── app/
│ ├── build.gradle.kts # 模块构建脚本与依赖声明
│ └── src/
│ ├── main/
│ │ ├── AndroidManifest.xml # 权限、四大组件与 FileProvider 注册
│ │ ├── java/com/example/myapplication/
│ │ │ ├── MainActivity.kt # 主界面：录入、生成、扫描、保存
│ │ │ ├── ListActivity.kt # 列表界面：展示、搜索、编辑入口、删除、导出
│ │ │ ├── EditActivity.kt # 编辑界面：按主键回表读取并保存修改
│ │ │ ├── PortraitCaptureActivity.kt # 强制竖屏的扫码 Activity
│ │ │ ├── AppDatabase.kt # Room 数据库单例
│ │ │ ├── Asset.kt # 资产实体（Entity）
│ │ │ ├── AssetDao.kt # 数据访问对象（增删查改）
│ │ │ ├── AssetAdapter.kt # RecyclerView 列表适配器（点击编辑 / 长按删除）
│ │ │ ├── QrGenerator.kt # 二维码生成工具
│ │ │ └── CsvExporter.kt # CSV 导出工具（保存到本地 / 分享）
│ │ └── res/
│ │ ├── layout/ # activity_main / activity_list / activity_edit / item_asset
│ │ ├── drawable/ # 矢量图标（ic_search 等）
│ │ ├── values/ # 主题、颜色（界面文案尚未抽离）
│ │ └── xml/ # FileProvider 路径与备份规则
│ ├── test/ # 单元测试
│ └── androidTest/ # Instrumented 测试
├── gradle/
│ ├── libs.versions.toml # 依赖版本目录
│ └── wrapper/ # Gradle Wrapper
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
├── .editorconfig # 统一缩进 / 编码 / 换行符
├── .gitignore
├── CONTRIBUTING.md # 贡献指南
├── CHANGELOG.md # 更新日志
├── LICENSE # 许可声明
├── README.md # 中文文档
└── README.en.md # 英文文档
```
## 🏗 架构概览
```mermaid
flowchart LR
subgraph UI["界面层 (View 体系)"]
M["MainActivity
录入 / 生成 / 扫描 / 保存"]
L["ListActivity
展示 / 搜索 / 编辑入口 / 删除 / 导出"]
E["EditActivity
按主键读取 / 保存修改"]
end
subgraph Helper["工具层"]
Q["QrGenerator"]
C["CsvExporter"]
A["AssetAdapter"]
end
subgraph Data["数据层"]
D["AssetDao"]
R[("Room DB
asset_db")]
end
M -->|"生成"| Q
M -->|"插入"| D
L -->|"查询 / 删除"| D
L -->|"点击列表项"| E
E -->|"按主键查询 / 更新"| D
L -->|"导出：保存 / 分享"| C
L -->|"渲染列表"| A
D --> R
```
## 🚀 快速开始
### 环境要求
| 组件 | 最低要求 | 说明 |
| --- | --- | --- |
| Android Studio | **Quail 4 \| 2026.1.4** 或更高 | AGP 9.4 需要 2026.1.4+，低于该版本无法打开本项目 |
| JDK | **17** 或更高 | AGP 9.4 的运行工具链最低 JDK 17（模块 Java 语言级别仍为 11） |
| Gradle | 9.6.0 | 随项目自带 Wrapper，无需单独安装 |
| SDK Build Tools | 36.0.0 | 通过 SDK Manager 安装 |
| 设备 | Android 8.0（API 26）+ 摄像头 | 应用本身的最低运行版本 |
### 获取代码
```bash
git clone https://gitee.com/cfdy123/qr-application.git
cd qr-application
```
### 编译与安装
```bash
# 编译 Debug 版本
./gradlew assembleDebug
# 编译并安装到已连接的设备
./gradlew installDebug
```
> Windows 环境下请将 `./gradlew` 替换为 `gradlew.bat`。
### 构建产物
编译完成后，APK 位于：
```
app/build/outputs/apk/debug/app-debug.apk
```
### 运行测试
```bash
# 单元测试（JVM）
./gradlew test
# Instrumented 测试（需要连接设备/模拟器）
./gradlew connectedAndroidTest
```
## 📖 使用说明
### 1. 生成二维码
在主界面「手动录入」区域填写 **名称 / 规格 / 持有人**，点击 **「生成二维码」** 即可预览二维码图片（内容格式见下方 [二维码数据格式](#-二维码数据格式)）。
### 2. 扫描二维码
点击 **「扫码」** 按钮，将资产二维码对准取景框，识别成功后资产信息会展示在「扫描结果」卡片中。点击 **「保存到本地」** 将记录写入数据库。
### 3. 查看资产列表
点击 **「查看资产列表」** 进入列表页，可浏览全部资产。
### 4. 搜索资产
在列表页顶部的搜索框中输入关键词，即可按名称 / 规格 / 持有人筛选。输入停顿 300ms 后才会真正查询数据库，避免每敲一个字就查一次。
### 5. 编辑资产
**点击**列表中的任意条目进入编辑页，修改名称 / 规格 / 持有人后点击「保存修改」。返回列表时会自动刷新。
### 6. 删除资产
在列表中 **长按** 目标条目，在确认弹窗中点击「删除」。
### 7. 导出数据
在列表页点击 **「导出 CSV」**，会弹出菜单，提供两种导出方式：
- **保存到本地**：通过 SAF（Storage Access Framework）弹出系统文件保存对话框，可自选保存目录与文件名，文件长期保留；
- **分享到其他应用**：调起系统分享面板，可发送到邮件、云盘或其他 App。
## 🗃 资产数据模型
`Asset` 实体（表名 `assets`）：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | `Long` | 主键，自增 |
| `name` | `String` | 资产名称 |
| `specification` | `String` | 资产规格 |
| `holder` | `String` | 资产持有人 |
| `createdAt` | `Long` | 创建时间戳（毫秒） |
导出的 CSV 表头为：`名称,规格,持有人,创建时间`（时间格式 `yyyy-MM-dd HH:mm:ss`，字段含逗号/引号/换行时会自动转义）。
## 🔗 二维码数据格式
二维码内容为三段式文本，以竖线 `|` 分隔：
```
名称|规格|持有人
```
例如：
```
联想 ThinkPad X1|i7/16G/512G|张三
```
> ⚠️ 扫描时若分段数少于 3，应用会提示「二维码格式不正确」，请确保二维码内容符合上述格式。
## 🔒 权限与安全
| 权限 | 用途 |
| --- | --- |
| `android.permission.CAMERA` | 扫描二维码 |
- 应用申请 `android.hardware.camera` 为必需特性（`required="true"`）。
- CSV 导出的两条路径均**无需申请任何存储权限**（兼容 Android 10+ 分区存储）：「分享到其他应用」写入 **缓存目录（`cacheDir`）** 并通过 **FileProvider** 授予接收方临时读权限；「保存到本地」走 **SAF（Storage Access Framework）**，由用户自选位置、文件长期保留。
- 数据库为应用私有数据（`asset_db`），其他应用无法直接访问。
## 🗺 路线图
### 已知限制
- **暂无数据库迁移**：`AppDatabase` 使用 `exportSchema = false` 且未编写 `Migration`，改动 `Asset` 字段时需要手工处理升级。
- **测试为模板示例**：仓库内的单元测试与 Instrumented 测试仍是新建工程时的模板，未覆盖业务逻辑。
- **仅有中文资源**：界面文案已抽离到 `strings.xml`，但尚未提供 `values-en` 等英文翻译。
- **CSV 表头为固定中文**：导出文件的列名属于数据格式（供 Excel 读取），未纳入 `strings.xml`。
### 计划中
- [ ] 补充 `values-en` 英文资源
- [ ] 为 `AssetDao`、`CsvExporter`、`QrGenerator` 补充单元测试
- [ ] 为 `AppDatabase` 开启 `exportSchema` 并编写迁移
- [ ] 补充界面截图
## 🤝 参与贡献
欢迎提交 Issue 与 Pull Request。完整的开发环境、分支命名、提交规范与 PR 流程请参阅 **[CONTRIBUTING.md](CONTRIBUTING.md)**。
简要流程：
1. Fork 本仓库
2. 新建分支：`git checkout -b feature/your-feature`
3. 提交改动：`git commit -m "feat(asset-list): 新增批量删除功能"`
4. 推送分支：`git push origin feature/your-feature`
5. 提交 Pull Request
> 建议遵循 [Conventional Commits](https://www.conventionalcommits.org/) 提交规范，并保持 Kotlin 官方代码风格（`kotlin.code.style=official`）。
## 📄 许可证
本项目仅供学习与交流使用，详见 [LICENSE](LICENSE)（保留所有权利）。如需商业授权，请先与作者联系。
> 如需改为开源许可（如 MIT 或 Apache-2.0），请替换 `LICENSE` 文件内容并同步更新本节说明。
## ⭐ Star 趋势
如果这个项目对你有帮助，欢迎点个 ⭐ Star 支持一下！
[](https://gitee.com/cfdy123/qr-application)
> 说明：本项目托管在 Gitee；流行的 star-history.com 仅支持 GitHub / GitLab / Bitbucket，暂不支持 Gitee，且 Gitee API 未开放星标历史数据，因此此处以**实时星数徽章**代替星标趋势图。