MoonReader：基于 SpringBoot 3.4 & React 的沉浸式协作阅读平台

项目地址：MoonPointer-Byte/MoonReader

1. 项目概述

MoonReader (XS项目) 是一款集"静默阅读（大文件小说）"、"动态沟通（即时通讯）"以及"外部链接（邮件系统）"于一体的综合性 Web 应用。

该项目旨在解决信息碎片化问题，通过技术手段将阅读、社交与办公协作有机融合，打造一个轻量级、响应式的数字化空间。

1.1 项目核心场景

• 协作阅读：支持超大 TXT 文档的流式分片阅读，支持多端书签同步。

• 即时通讯：基于 WebSocket/STOMP 协议实现的一对一聊天及在线状态感知。

• 邮件办公：集成 POP3/SMTP 协议，支持邮件的异步同步与富文本发送。

• 系统审计：完善的后台管理功能，支持用户封禁、操作日志审计及书籍上架维护。

2. 技术选型

项目采用现代化的前后端分离架构，确保系统的高可用性与可扩展性。

• 前端：React 18 + TypeScript + Vite（极致的开发体验与首屏加载速度）

• 后端：SpringBoot 3.4.1 + MyBatis + Redis + MySQL 8.0

• 通信：WebSocket (STOMP) + Java Mail API

• 并发处理：ThreadPoolExecutor (JUC)（用于邮件异步同步）

• 内网穿透：Cloudflare Tunnel（用于演示与临时访问）

---

3. 数据库设计 (Schema)

系统设计了 8 张核心表，通过索引优化确保在百万级数据下的响应速度。

codeSQL

-- 1. 用户表
CREATE TABLE `sys_user` (
    `id` BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `username` VARCHAR(50) NOT NULL UNIQUE COMMENT '账号',
    `password` VARCHAR(100) NOT NULL COMMENT 'BCrypt加密密码',
    `nickname` VARCHAR(50) COMMENT '昵称',
    `avatar` VARCHAR(255) DEFAULT NULL COMMENT '用户头像URL',
    `role` VARCHAR(20) DEFAULT 'USER' COMMENT '角色: USER, ADMIN',
    `status` TINYINT DEFAULT 1 COMMENT '1:正常, 0:封禁',
    `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 2. 邮件配置表
CREATE TABLE `sys_email_config` (
    `user_id` BIGINT NOT NULL PRIMARY KEY,
    `smtp_host` VARCHAR(100),
    `smtp_port` INT,
    `pop3_host` VARCHAR(100),
    `pop3_port` INT,
    `email_account` VARCHAR(100),
    `auth_code` VARCHAR(200) COMMENT '授权码(加密存储)'
);

-- 3. 小说/文档信息表
CREATE TABLE `sys_novel` (
    `id` BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `title` VARCHAR(100) NOT NULL,
    `file_name` VARCHAR(255) NOT NULL COMMENT 'UUID文件名',
    `original_name` VARCHAR(255),
    `file_size` BIGINT,
    `uploader_id` BIGINT,
    `is_deleted` TINYINT DEFAULT 0,
    `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 4. 小说书签表 (字节级同步)
CREATE TABLE `sys_novel_bookmark` (
    `id` BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `user_id` BIGINT NOT NULL,
    `novel_id` BIGINT NOT NULL,
    `byte_offset` BIGINT DEFAULT 0 COMMENT '当前读取的字节位置',
    `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY `uk_read` (`user_id`, `novel_id`)
);

-- 5. 好友关系表
CREATE TABLE `sys_friend` (
    `id` BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `user_id` BIGINT NOT NULL,
    `friend_id` BIGINT NOT NULL,
    `status` TINYINT DEFAULT 0 COMMENT '0:申请, 1:好友, 2:拉黑',
    `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 6. 聊天记录表
CREATE TABLE `sys_chat_msg` (
    `id` BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `sender_id` BIGINT NOT NULL,
    `receiver_id` BIGINT NOT NULL,
    `content` TEXT,
    `msg_type` TINYINT DEFAULT 0 COMMENT '0:文本, 1:图片',
    `is_read` TINYINT DEFAULT 0,
    `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 7. 操作日志表
CREATE TABLE `sys_log` (
    `id` BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `user_id` BIGINT,
    `operation` VARCHAR(50),
    `details` VARCHAR(255),
    `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 8. 邮件收件箱表
CREATE TABLE `sys_email` (
    `id` BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `user_id` BIGINT NOT NULL,
    `message_id` VARCHAR(255) COMMENT 'UID',
    `sender` VARCHAR(255),
    `subject` VARCHAR(500),
    `content` LONGTEXT,
    `sent_date` DATETIME,
    `has_attachment` TINYINT(1) DEFAULT 0,
    INDEX `idx_user_id` (`user_id`)
);

---

4. 核心功能及技术亮点

4.1 大文件"流式分片"阅读

针对几十兆甚至上百兆的 TXT 小说，MoonReader 摒弃了传统的全量加载方案：

• 后端：利用 RandomAccessFile 和文件通道实现基于偏移量的精准存取，前端请求多少，后端读取多少。

• 前端：配合虚拟滚动技术，内存占用极低，真正实现"大书秒开"。

• 同步：字节级自动书签。无论在 PC 端还是移动端，均可无感衔接上次阅读进度。

4.2 高并发异步邮件引擎

由于 POP3/SMTP 协议响应较慢，为避免前端"死锁"或长时间转圈：

• JUC 线程池：系统利用 ThreadPoolExecutor 将邮件同步任务提交至后台。

• 增量拉取：通过邮件 UID 判断，仅抓取新邮件，有效避免重复存储与带宽浪费。

4.3 实时交互与在线感知

• WebSocket + STOMP：实现了一套轻量级的即时通讯机制，支持文本与图片混合排版。

• 在线追踪：利用 Redis 的过期回调或心跳机制，实时感知好友在线状态。

4.4 安全与动态管控

• JWT + Redis 认证：通过 Redis 维护"黑名单"与"在线令牌"，支持管理员对违规用户进行"秒级强制下线"。

• 全链路日志：sys_log 记录所有关键操作，确保系统安全可追溯。

---

5. API 接口概览

5.1 认证模块

• POST /api/auth/login：登录并获取 JWT 令牌。

• POST /api/auth/logout：注销并销毁 Redis 中的 Token。

5.2 阅读模块

• GET /api/novel/content：获取文档切片内容。参数：novelId, start (起始偏移量), size (读取长度)。

• POST /api/novel/bookmark：同步当前阅读位置。

5.3 社交模块

• GET /api/chat/online：发现当前在线用户。

• POST /api/friend/request：发送好友申请。

5.4 邮件模块

• POST /api/email/sync：触发异步拉取任务，即刻返回 200 成功状态。

• POST /api/email/send：发送富文本邮件。

---

6. 项目总结

MoonReader 不仅仅是功能的简单堆砌，它在细节上做了大量打磨：

1. 用户体验：针对移动端进行了深度适配，支持触摸翻页与列表极致优化。

2. 性能平衡：通过 Redis 缓存与分片读取技术，降低了普通配置服务器的内存压力。

3. 协作属性：后端强大的管理员权限控制与审计日志，使其不仅适合个人使用，也能胜任小团队内部的资源协作。

7. 运行图片展示

---

项目状态 ：页面搭建完成，后端功能完全实现，移动端初步适配。
未来计划：进一步完善移动端的手势操作，增加 PDF 格式的支持。

---