slms/docs/PROJECT_STRUCTURE.md

# SLMS 项目结构说明

## 项目概述

智能图书管理系统（SLMS）是一个多平台图书管理解决方案，支持 CLI、GUI、Web 和 Android 四端应用。

## 目录结构

```
SLMS/
├── src/                          # Java 源代码（CLI/GUI/Web 共享）
│   ├── main/
│   │   ├── java/
│   │   │   └── com/smartlibrary/
│   │   │       ├── cli/          # CLI 应用
│   │   │       ├── gui/          # GUI 应用（JavaFX）
│   │   │       ├── web/          # Web 应用（Spring Boot）
│   │   │       ├── database/     # 数据库层
│   │   │       ├── service/      # 业务逻辑层
│   │   │       ├── model/        # 数据模型
│   │   │       ├── factory/      # 工厂模式
│   │   │       ├── observer/     # 观察者模式
│   │   │       └── notification/ # 通知系统
│   │   └── resources/            # 资源文件
│   │       ├── templates/        # Thymeleaf 模板
│   │       ├── static/           # 静态资源
│   │       └── application.properties
│   └── test/                     # 测试代码
│
├── android/                      # Android 应用
│   ├── src/
│   │   └── main/
│   │       ├── java/
│   │       │   └── com/smartlibrary/android/
│   │       │       ├── data/     # 数据管理
│   │       │       ├── model/    # 数据模型
│   │       │       ├── ui/       # UI 组件
│   │       │       ├── network/  # 网络层
│   │       │       └── utils/    # 工具类
│   │       ├── res/              # Android 资源
│   │       └── AndroidManifest.xml
│   └── build.gradle              # Android 构建配置
│
├── backend/                      # 后端服务（可选）
│   └── src/
│
├── gradle/                       # Gradle 配置
├── .gradle/                      # Gradle 缓存（忽略）
├── build/                        # 构建输出（忽略）
├── target/                       # Maven 输出（忽略）
│
├── library.db                    # SQLite 数据库
│
├── pom.xml                       # Maven 配置
├── build.gradle                  # Gradle 配置
├── settings.gradle               # Gradle 设置
├── gradle.properties             # Gradle 属性
├── gradlew                       # Gradle Wrapper (Unix)
├── gradlew.bat                   # Gradle Wrapper (Windows)
│
├── .gitignore                    # Git 忽略文件
│
├── README.md                     # 项目说明
├── PROJECT_OVERVIEW.md           # 项目概览
├── PROJECT_STRUCTURE.md          # 项目结构（本文件）
├── DATABASE_README.md            # 数据库说明
├── START_APPLICATIONS.md         # 应用启动指南
├── START_WEB_APP.md              # Web 应用启动指南
│
├── CLI_TEST_REPORT.md            # CLI 测试报告
├── GUI_TEST_REPORT.md            # GUI 测试报告
├── WEB_TEST_REPORT.md            # Web 测试报告
├── ANDROID_TEST_REPORT.md        # Android 测试报告
├── COMPREHENSIVE_TEST_REPORT.md  # 综合测试报告
├── FINAL_SUMMARY.md              # 最终总结
│
├── run_cli.bat                   # 运行 CLI 应用
├── run_gui.bat                   # 运行 GUI 应用
├── run_web.bat                   # 运行 Web 应用
├── run_tests.bat                 # 运行测试
├── run_gui_tests.bat             # 运行 GUI 测试
├── run_web_tests.bat             # 运行 Web 测试
├── run_all_tests.bat             # 运行所有测试
│
├── init_database.bat             # 初始化数据库
├── reset_database.bat            # 重置数据库
├── cleanup_project.bat           # 清理项目
├── package_web.bat               # 打包 Web 应用
├── generate_test_report.bat      # 生成测试报告
│
├── cicd.md                       # CI/CD 配置说明
└── Jenkinsfile                   # Jenkins 配置

```

## 技术栈

### 后端
- **Java 21**: 主要编程语言
- **Maven 3.x**: 依赖管理和构建工具
- **Gradle 8.5**: Android 构建工具
- **SQLite 3.36**: 嵌入式数据库
- **Spring Boot 2.7.5**: Web 框架
- **JavaFX 17**: GUI 框架

### Android
- **Android SDK 34**: Android 开发工具包
- **Kotlin**: Android 开发语言（部分）
- **Material Design 3**: UI 设计规范
- **Retrofit**: 网络请求库
- **Gson**: JSON 解析库

### 设计模式
- **Singleton（单例模式）**: DatabaseConnection, DataManager
- **Factory（工厂模式）**: BookFactoryProvider
- **Observer（观察者模式）**: BookStatusManager
- **Strategy（策略模式）**: Notification 接口
- **MVC（模型-视图-控制器）**: Web 应用架构

## 数据库设计

### 表结构

#### books（图书表）
- id: 图书ID（主键）
- title: 书名
- author: 作者
- isbn: ISBN 号
- publisher: 出版社
- publish_date: 出版日期
- category: 分类
- available: 是否可借
- book_type: 图书类型（实体书/电子书/期刊）

#### users（用户表）
- id: 用户ID（主键）
- name: 姓名
- email: 邮箱
- phone: 电话
- registration_date: 注册日期

#### loans（借阅表）
- id: 借阅ID（主键）
- book_id: 图书ID（外键）
- user_id: 用户ID（外键）
- borrow_date: 借阅日期
- due_date: 应还日期
- return_date: 实际归还日期
- returned: 是否已归还
- fine_amount: 罚金金额

## 构建和运行

### 构建项目

```bash
# Maven 构建
mvn clean compile

# Gradle 构建
gradlew build

# Android 构建
cd android
gradlew assembleDebug
```

### 运行应用

```bash
# CLI 应用
run_cli.bat

# GUI 应用
run_gui.bat

# Web 应用
run_web.bat

# Android 应用
# 使用 Android Studio 或命令行安装 APK
```

### 运行测试

```bash
# 运行所有测试
run_all_tests.bat

# 运行特定测试
run_tests.bat        # CLI 测试
run_gui_tests.bat    # GUI 测试
run_web_tests.bat    # Web 测试
```

## 数据管理

### 初始化数据库
```bash
init_database.bat
```

### 重置数据库
```bash
reset_database.bat
```

### 数据库位置
- 主数据库: `library.db`
- 所有应用共享同一数据库文件

## 清理项目

```bash
# 清理构建缓存和临时文件
cleanup_project.bat
```

清理内容：
- 构建输出目录（build/, target/）
- Gradle 缓存（.gradle/）
- 备份文件（*.bak）
- 临时文件（*.tmp, *.log）

## 开发规范

### 代码规范
- 遵循 Java 命名规范
- 使用有意义的变量名
- 添加必要的注释
- 保持代码简洁

### 提交规范
- 提交前运行测试
- 编写清晰的提交信息
- 一次提交解决一个问题

### 分支策略
- `main` - 生产分支
- `develop` - 开发分支
- `feature/*` - 功能分支
- `bugfix/*` - 修复分支

## 文档说明

### 核心文档
- **README.md**: 项目快速入门
- **PROJECT_OVERVIEW.md**: 项目详细概览
- **PROJECT_STRUCTURE.md**: 项目结构说明（本文件）
- **DATABASE_README.md**: 数据库设计和使用

### 启动指南
- **START_APPLICATIONS.md**: 应用启动总指南
- **START_WEB_APP.md**: Web 应用详细启动指南

### 测试报告
- **CLI_TEST_REPORT.md**: CLI 应用测试报告
- **GUI_TEST_REPORT.md**: GUI 应用测试报告
- **WEB_TEST_REPORT.md**: Web 应用测试报告
- **ANDROID_TEST_REPORT.md**: Android 应用测试报告
- **COMPREHENSIVE_TEST_REPORT.md**: 综合测试报告
- **FINAL_SUMMARY.md**: 项目最终总结

### 配置文档
- **cicd.md**: CI/CD 配置说明
- **Jenkinsfile**: Jenkins 持续集成配置

## 常见问题

### Q: 如何重置数据库？
A: 运行 `reset_database.bat`

### Q: GUI 应用无法启动？
A: 确保安装了 JavaFX，运行 `mvn javafx:run`

### Q: 数据不同步？
A: 所有应用共享同一个 `library.db` 文件，确保文件未被锁定

### Q: 如何清理项目？
A: 运行 `cleanup_project.bat` 清理构建缓存和临时文件

### Q: Android 应用如何构建？
A: 运行 `gradlew assembleDebug` 构建 Debug APK

## 许可证

本项目仅用于教育和学习目的。

## 联系方式

- **项目**: Smart Library Management System
- **版本**: 1.0
- **团队**: SmartLibrary Development Team
- **更新**: 2025-11-19