|
|
# Android 智能图书管理系统 (SLMS)
|
|
|
|
|
|
## 概述
|
|
|
|
|
|
智能图书管理系统（Smart Library Management System）的Android客户端，提供完整的图书管理功能、AI智能助手和扫码借还书功能。
|
|
|
|
|
|
## 版本信息
|
|
|
|
|
|
- **版本号**: 1.0.0
|
|
|
- **最低SDK**: Android 7.0 (API 24)
|
|
|
- **目标SDK**: Android 14 (API 34)
|
|
|
- **编译SDK**: 34
|
|
|
|
|
|
## 主要功能
|
|
|
|
|
|
### 📚 核心功能
|
|
|
| 功能 | 描述 | 状态 |
|
|
|
|------|------|------|
|
|
|
| 图书管理 | 浏览、搜索、添加、编辑、删除图书 | ✅ 已实现 |
|
|
|
| 借阅管理 | 借阅、归还、续借图书 | ✅ 已实现 |
|
|
|
| 用户管理 | 用户登录、角色权限、个人信息 | ✅ 已实现 |
|
|
|
| 数据持久化 | SharedPreferences本地存储 | ✅ 已实现 |
|
|
|
|
|
|
### 🤖 AI智能功能
|
|
|
| 功能 | 描述 | 状态 |
|
|
|
|------|------|------|
|
|
|
| AI智能助手 | 自然语言对话，解答使用问题 | ✅ 已实现 |
|
|
|
| AI智能搜索 | 智能理解搜索意图，提供精准建议 | ✅ 已实现 |
|
|
|
| AI个性化推荐 | 基于用户偏好推荐图书 | ✅ 已实现 |
|
|
|
| 真实AI对话 | DeepSeek、智谱AI集成 | ✅ 已实现 |
|
|
|
| 语音识别 | 讯飞语音识别 | ✅ 已实现 |
|
|
|
| 语音播报 | 讯飞TTS语音合成 | ✅ 已实现 |
|
|
|
|
|
|
### 📱 扫码功能
|
|
|
| 功能 | 描述 | 状态 |
|
|
|
|------|------|------|
|
|
|
| 扫码借书 | 扫描图书二维码快速借阅 | ✅ 已实现 |
|
|
|
| 扫码还书 | 扫描图书二维码快速归还 | ✅ 已实现 |
|
|
|
| 二维码生成 | 为图书生成唯一二维码 | ✅ 已实现 |
|
|
|
| 智能识别 | 自动识别借/还操作 | ✅ 已实现 |
|
|
|
|
|
|
### 📊 其他功能
|
|
|
| 功能 | 描述 | 状态 |
|
|
|
|------|------|------|
|
|
|
| UML图查看 | 查看系统架构和流程图 | ✅ 已实现 |
|
|
|
| UML图生成 | 在线生成PlantUML图表 | ✅ 已实现 |
|
|
|
| 离线运行 | 本地AI功能完全离线 | ✅ 已实现 |
|
|
|
| Mock数据 | 自动生成演示数据 | ✅ 已实现 |
|
|
|
|
|
|
## 架构设计
|
|
|
|
|
|
### 项目结构
|
|
|
|
|
|
```
|
|
|
android/
|
|
|
├── src/
|
|
|
│ ├── main/
|
|
|
│ │ ├── java/com/smartlibrary/android/
|
|
|
│ │ │ ├── ai/ # AI服务
|
|
|
│ │ │ │ ├── AIConfig.java # AI配置
|
|
|
│ │ │ │ ├── RealAIService.java # 真实AI服务
|
|
|
│ │ │ │ ├── SimpleAIService.java # 本地AI服务
|
|
|
│ │ │ │ ├── SpeechRecognitionService.java # 语音识别
|
|
|
│ │ │ │ ├── TextToSpeechService.java # 语音合成
|
|
|
│ │ │ │ └── VoiceService.java # 语音服务
|
|
|
│ │ │ ├── data/ # 数据管理
|
|
|
│ │ │ │ └── DataManager.java # 数据管理器(单例)
|
|
|
│ │ │ ├── factory/ # 对象工厂
|
|
|
│ │ │ │ └── LibraryObjectFactory.java # 工厂模式
|
|
|
│ │ │ ├── mock/ # Mock数据
|
|
|
│ │ │ │ └── MockDataGenerator.java # 数据生成器
|
|
|
│ │ │ ├── model/ # 数据模型
|
|
|
│ │ │ │ ├── Book.java # 图书模型
|
|
|
│ │ │ │ ├── Loan.java # 借阅模型
|
|
|
│ │ │ │ └── User.java # 用户模型
|
|
|
│ │ │ ├── network/ # 网络服务
|
|
|
│ │ │ │ ├── ApiService.java # API服务
|
|
|
│ │ │ │ ├── EnhancedApiService.java # 增强API服务
|
|
|
│ │ │ │ └── LibraryApi.java # Retrofit接口
|
|
|
│ │ │ ├── ui/ # UI组件
|
|
|
│ │ │ │ ├── SmartAIAssistantActivity.java # AI助手
|
|
|
│ │ │ │ ├── ScanBorrowReturnActivity.java # 扫码借还
|
|
|
│ │ │ │ ├── UMLViewerActivity.java # UML查看
|
|
|
│ │ │ │ └── ...
|
|
|
│ │ │ ├── util/ # 工具类
|
|
|
│ │ │ │ └── QRCodeUtil.java # 二维码工具
|
|
|
│ │ │ ├── MainActivity.java # 主Activity
|
|
|
│ │ │ └── SimpleActivity.java # 简单Activity
|
|
|
│ │ └── res/ # 资源文件
|
|
|
│ └── test/ # 单元测试
|
|
|
│ └── java/com/smartlibrary/android/
|
|
|
│ ├── ai/
|
|
|
│ │ └── SimpleAIServiceTest.java
|
|
|
│ ├── factory/
|
|
|
│ │ └── LibraryObjectFactoryTest.java
|
|
|
│ ├── mock/
|
|
|
│ │ └── MockDataGeneratorTest.java
|
|
|
│ └── model/
|
|
|
│ ├── BookTest.java
|
|
|
│ ├── LoanTest.java
|
|
|
│ └── UserTest.java
|
|
|
├── build.gradle # 构建配置
|
|
|
└── README.md # 本文档
|
|
|
```
|
|
|
|
|
|
### 设计模式
|
|
|
|
|
|
| 模式 | 应用 | 说明 |
|
|
|
|------|------|------|
|
|
|
| 单例模式 | SimpleAIService, DataManager, ApiService | 确保全局唯一实例 |
|
|
|
| 工厂模式 | LibraryObjectFactory | 统一对象创建 |
|
|
|
| 观察者模式 | DataManager | 数据变化通知 |
|
|
|
| 回调模式 | ApiCallback, AICallback | 异步操作处理 |
|
|
|
|
|
|
## 快速开始
|
|
|
|
|
|
### 环境要求
|
|
|
|
|
|
- Android Studio Arctic Fox (2020.3.1) 或更高版本
|
|
|
- JDK 21
|
|
|
- Android SDK 34
|
|
|
- Gradle 8.x
|
|
|
|
|
|
### 构建步骤
|
|
|
|
|
|
```bash
|
|
|
# 1. 克隆项目
|
|
|
git clone <repository-url>
|
|
|
cd mcslms
|
|
|
|
|
|
# 2. 构建Debug版本
|
|
|
.\gradlew.bat :android:assembleDebug
|
|
|
|
|
|
# 3. 安装到设备
|
|
|
adb install -r android\build\outputs\apk\debug\mcslms-debug.apk
|
|
|
|
|
|
# 4. 启动应用
|
|
|
adb shell am start -n com.smartlibrary/.android.MainActivity
|
|
|
```
|
|
|
|
|
|
### 运行测试
|
|
|
|
|
|
```bash
|
|
|
# 运行单元测试
|
|
|
.\gradlew.bat :android:test
|
|
|
|
|
|
# 运行UI测试（需要连接设备）
|
|
|
.\gradlew.bat :android:connectedAndroidTest
|
|
|
|
|
|
# 生成测试报告
|
|
|
.\gradlew.bat :android:testDebugUnitTest --info
|
|
|
```
|
|
|
|
|
|
## 测试覆盖
|
|
|
|
|
|
### 单元测试
|
|
|
|
|
|
| 测试类 | 覆盖内容 | 测试数量 |
|
|
|
|--------|----------|----------|
|
|
|
| BookTest | Book模型所有方法 | 15+ |
|
|
|
| UserTest | User模型所有方法 | 20+ |
|
|
|
| LoanTest | Loan模型所有方法 | 15+ |
|
|
|
| LibraryObjectFactoryTest | 工厂方法和参数验证 | 15+ |
|
|
|
| MockDataGeneratorTest | 数据生成逻辑 | 15+ |
|
|
|
| SimpleAIServiceTest | AI服务和意图识别 | 15+ |
|
|
|
|
|
|
### 测试命令
|
|
|
|
|
|
```bash
|
|
|
# 运行所有测试
|
|
|
.\gradlew.bat :android:test
|
|
|
|
|
|
# 运行特定测试类
|
|
|
.\gradlew.bat :android:test --tests "com.smartlibrary.android.model.BookTest"
|
|
|
|
|
|
# 生成覆盖率报告（需要JaCoCo配置）
|
|
|
.\gradlew.bat :android:jacocoTestReport
|
|
|
```
|
|
|
|
|
|
## 使用说明
|
|
|
|
|
|
### 首次启动
|
|
|
|
|
|
应用首次启动时会自动：
|
|
|
1. 初始化DataManager
|
|
|
2. 生成Mock数据（50本图书、20+用户、100条借阅记录）
|
|
|
3. 创建测试账户（admin/librarian/user/guest）
|
|
|
|
|
|
### 测试账户
|
|
|
|
|
|
| 账户 | 邮箱 | 密码 | 角色 |
|
|
|
|------|------|------|------|
|
|
|
| 管理员 | admin@slms.com | admin123 | 系统管理员 |
|
|
|
| 图书管理员 | librarian@slms.com | lib123 | 图书管理员 |
|
|
|
| 普通用户 | user@slms.com | user123 | 普通用户 |
|
|
|
| 访客 | guest@slms.com | guest | 访客 |
|
|
|
|
|
|
### AI功能使用
|
|
|
|
|
|
#### 本地AI助手
|
|
|
- 完全离线运行
|
|
|
- 支持借阅、归还、搜索、推荐等意图识别
|
|
|
- 基于规则的智能响应
|
|
|
|
|
|
#### 真实AI助手
|
|
|
- 需要网络连接
|
|
|
- 支持DeepSeek和智谱AI
|
|
|
- 支持语音输入和语音播报
|
|
|
|
|
|
### 扫码借还书
|
|
|
|
|
|
1. **扫码借书**：点击"扫码借书" → 扫描图书二维码 → 确认借阅
|
|
|
2. **扫码还书**：点击"扫码还书" → 扫描图书二维码 → 确认归还
|
|
|
3. **智能模式**：自动根据图书状态判断借/还操作
|
|
|
|
|
|
## 数据模型
|
|
|
|
|
|
### Book（图书）
|
|
|
```java
|
|
|
- id: String // 图书ID
|
|
|
- title: String // 标题
|
|
|
- author: String // 作者
|
|
|
- isbn: String // ISBN号
|
|
|
- category: String // 分类
|
|
|
- status: String // 状态(available/borrowed/reserved)
|
|
|
- qrCode: String // 二维码内容
|
|
|
- publisher: String // 出版社
|
|
|
- location: String // 馆藏位置
|
|
|
```
|
|
|
|
|
|
### User（用户）
|
|
|
```java
|
|
|
- id: String // 用户ID
|
|
|
- name: String // 姓名
|
|
|
- email: String // 邮箱
|
|
|
- phone: String // 电话
|
|
|
- role: String // 角色(admin/librarian/user/guest)
|
|
|
- borrowLimit: int // 借阅上限
|
|
|
- currentBorrows: int // 当前借阅数
|
|
|
```
|
|
|
|
|
|
### Loan（借阅记录）
|
|
|
```java
|
|
|
- id: String // 借阅ID
|
|
|
- bookId: String // 图书ID
|
|
|
- userId: String // 用户ID
|
|
|
- loanDate: Date // 借阅日期
|
|
|
- dueDate: Date // 应还日期
|
|
|
- returnDate: Date // 实际归还日期
|
|
|
- status: String // 状态(active/returned/overdue)
|
|
|
```
|
|
|
|
|
|
## 权限说明
|
|
|
|
|
|
```xml
|
|
|
<!-- 网络权限 -->
|
|
|
<uses-permission android:name="android.permission.INTERNET" />
|
|
|
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
|
|
|
|
|
|
<!-- 相机权限（扫码） -->
|
|
|
<uses-permission android:name="android.permission.CAMERA" />
|
|
|
|
|
|
<!-- 录音权限（语音识别） -->
|
|
|
<uses-permission android:name="android.permission.RECORD_AUDIO" />
|
|
|
|
|
|
<!-- 存储权限（保存二维码） -->
|
|
|
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
|
|
|
```
|
|
|
|
|
|
## 依赖库
|
|
|
|
|
|
| 库 | 版本 | 用途 |
|
|
|
|----|------|------|
|
|
|
| AndroidX Core | 1.12.0 | 核心库 |
|
|
|
| Material Design | 1.11.0 | UI组件 |
|
|
|
| Retrofit | 2.9.0 | 网络请求 |
|
|
|
| OkHttp | 4.12.0 | HTTP客户端 |
|
|
|
| Gson | 2.9.0 | JSON解析 |
|
|
|
| ZXing | 3.5.2 | 二维码处理 |
|
|
|
| Glide | 4.16.0 | 图片加载 |
|
|
|
| Room | 2.6.1 | 数据库 |
|
|
|
| Biometric | 1.1.0 | 生物识别 |
|
|
|
| CameraX | 1.3.1 | 相机功能 |
|
|
|
|
|
|
## SonarQube配置
|
|
|
|
|
|
项目已配置SonarQube代码质量检查：
|
|
|
|
|
|
```properties
|
|
|
# sonar-project.properties
|
|
|
sonar.sources=android/src/main/java
|
|
|
sonar.tests=android/src/test/java
|
|
|
sonar.java.binaries=android/build/intermediates/javac/debug/classes
|
|
|
```
|
|
|
|
|
|
### 覆盖率要求
|
|
|
|
|
|
- 新代码覆盖率: ≥80%
|
|
|
- 整体覆盖率: ≥60%
|
|
|
- 代码重复率: ≤3%
|
|
|
|
|
|
## 已知限制
|
|
|
|
|
|
1. **离线限制**：真实AI功能需要网络连接
|
|
|
2. **语音功能**：需要在真实设备上测试
|
|
|
3. **图片展示**：UML图暂不支持直接在移动端展示
|
|
|
|
|
|
## 更新日志
|
|
|
|
|
|
### v1.0.0 (2025-12)
|
|
|
- ✅ 完整的图书管理功能
|
|
|
- ✅ 借阅管理（借书、还书、续借）
|
|
|
- ✅ 用户管理和角色权限
|
|
|
- ✅ AI智能助手（本地+真实AI）
|
|
|
- ✅ 扫码借还书功能
|
|
|
- ✅ 语音识别和语音播报
|
|
|
- ✅ 单元测试覆盖
|
|
|
|
|
|
## 贡献指南
|
|
|
|
|
|
1. Fork项目
|
|
|
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
|
|
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
|
|
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
|
|
5. 创建Pull Request
|
|
|
|
|
|
## 许可证
|
|
|
|
|
|
本项目仅供学习和教育目的使用。
|
|
|
|
|
|
## 联系方式
|
|
|
|
|
|
- 项目主页：http://localhost:3000/mcslms/
|
|
|
- 问题追踪：http://localhost:3000/mcslms/issues
|
|
|
- CI/CD：http://localhost:8084/job/mcslms
|
