readme

README.md

@@ -0,0 +1,153 @@
+# 墨香阁 · 小说阅读
+
+> 一个轻量的个人电子书阅读应用。后端基于 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
+
+仅供个人学习与使用。