# 墨香阁 · 小说阅读

> 一个轻量的个人电子书阅读应用。后端基于 Spring Boot + MongoDB，前端为内置的 PWA（可「添加到主屏幕」当作原生 App 使用），适合部署在 NAS、轻量服务器等小内存设备上。

## 功能特性

- 📚 **书库浏览**：关键词 / 标签搜索、搜索建议、热门标签、随机推荐
- 📖 **沉浸阅读**：章节翻页、上一章 / 下一章、阅读进度记忆
- ⭐ **个人书架**：收藏小说，一键查看是否已收藏
- 🔖 **书签**：按小说记录书签位置
- 🕘 **阅读历史**：自动记录最近阅读
- 📱 **PWA 支持**：Service Worker 离线缓存、可安装到手机主屏
- 📑 **接口文档**：内置 Swagger UI，方便调试

## 技术栈

| 层 | 技术 |
|----|------|
| 运行环境 | Java 8 |
| 框架 | Spring Boot 2.7.18 |
| 数据库 | MongoDB（Spring Data MongoDB） |
| 模板引擎 | Thymeleaf |
| 接口文档 | springdoc-openapi-ui 1.7.0 |
| 工具 | Lombok |
| 前端 | 原生 HTML / CSS / JavaScript + PWA |

## 项目结构

```
src/main/
├── java/com/novelreader/
│   ├── NovelReaderApplication.java   # 启动类
│   ├── config/                       # MongoDB 索引等配置
│   ├── controller/                   # REST 接口 + 页面路由
│   ├── service/                      # 业务逻辑
│   ├── repository/                   # MongoDB 数据访问
│   ├── model/                        # 数据库实体（novelDO / chapterDO / ...）
│   └── dto/                          # 传输对象
└── resources/
    ├── application.yml               # 配置文件
    ├── templates/index.html          # 单页应用入口
    └── static/                       # css / js / manifest / service worker
```

## 快速开始

### 前置要求

- JDK 8、Maven 3.6+
- 一个可访问的 MongoDB 实例

### 本地运行

1. 修改 `src/main/resources/application.yml` 中的 MongoDB 连接：

   ```yaml
   spring:
     data:
       mongodb:
         uri: mongodb://用户名:密码@地址:端口/数据库名
   ```

2. 启动：

   ```bash
   mvn spring-boot:run
   ```

3. 打开浏览器访问 `http://localhost:8080`。

### 打包

```bash
mvn clean package -DskipTests
java -jar target/server-0.0.1-SNAPSHOT.jar
```

## 数据模型

应用读取 MongoDB 中已有的小说数据，主要集合：

- **novelDO**：小说信息（`name`、`author`、`cover`、`status`、`synopsis`、`tags` 等）
- **chapterDO**：章节内容（`novelId`、`index`、`title`、`content`）

书架、书签、历史等用户数据存储在各自对应的集合中。

## API 概览

接口文档（Swagger UI）：启动后访问 `http://localhost:8080/swagger-ui.html`

| 模块 | 前缀 | 说明 |
|------|------|------|
| 小说 | `/api/novels` | 搜索、详情、搜索建议、章节列表、热门标签、随机推荐 |
| 章节 | `/api/chapters` | 按 ID / 小说获取章节，首章、上一章、下一章 |
| 书架 | `/api/shelf` | 收藏列表、添加、移除、是否已收藏 |
| 历史 | `/api/history` | 历史列表、上报阅读记录、删除 |
| 书签 | `/api/bookmarks` | 书签列表、新增、删除 |

## Docker 部署

项目提供多阶段构建的 `Dockerfile` 与 `docker-compose.yml`，适合在 NAS 上一键部署。

### 使用 docker-compose（推荐）

1. 修改 `docker-compose.yml` 中的 MongoDB 地址与内存参数：

   ```yaml
   environment:
     - SPRING_DATA_MONGODB_URI=mongodb://你的MongoDB地址:端口/数据库名
     - JAVA_OPTS=-Xms128m -Xmx256m -XX:+UseG1GC
     - TZ=Asia/Shanghai
   ```

2. 构建并启动：

   ```bash
   docker-compose up -d --build
   ```

3. 查看日志 / 状态：

   ```bash
   docker-compose logs -f
   docker-compose ps
   ```

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `SPRING_DATA_MONGODB_URI` | MongoDB 连接地址 | `mongodb://192.168.18.100:38403/novel` |
| `JAVA_OPTS` | JVM 参数 | `-Xms128m -Xmx256m -XX:+UseG1GC` |
| `TZ` | 时区 | `Asia/Shanghai` |

### 内存调优建议

根据设备可用内存调整 `JAVA_OPTS`：

| 可用内存 | 推荐参数 |
|----------|----------|
| 1GB | `-Xms128m -Xmx256m` |
| 2GB | `-Xms256m -Xmx512m` |
| 4GB+ | `-Xms512m -Xmx1024m` |

> 另提供 `Dockerfile.china`（国内镜像加速）与 `Dockerfile.simple`（基于已有 jar 的精简构建）两种变体，可按需选用。

## 安装到手机

部署成功后，在手机浏览器（iOS 用 Safari）打开 `http://服务器IP:8080`，点击「分享 → 添加到主屏幕」，即可像原生 App 一样使用。

## License

仅供个人学习与使用。