数字刊物系统详细设计说明书
文档版本：1.0
编写日期：2026-06-07
系统名称：数字刊物系统
后端工程：
digial-press/digital-press管理端前端：
ui-admin移动端前端：
ui-mobile编写依据：当前仓库源码、
db/digital_press.sql、后端配置、前端路由与 API 封装、现有需求/概要/架构/权限/上传/统计/加密专题文档。
1. 文档目的、范围与约束
1.1 文档目的
本文档用于对数字刊物系统进行完整详细设计说明，覆盖系统建设内容、功能模块、技术架构、接口分组、数据模型、安全机制、缓存与会话、文件与 PDF/TTS、统计、前端页面、部署运行、测试与质量控制、风险约束等内容，为系统交付、验收、维护、二次开发、测试设计和部署实施提供依据。
1.2 系统建设范围
系统围绕数字刊物的内容生产、发布、移动阅读、用户互动、运营统计和后台管理形成业务闭环，当前建设内容包括：
| 建设内容 | 说明 |
|---|---|
| 管理端前端 | ui-admin，用于后台登录、内容维护、章节编辑、评论/评分管理、PDF、统计、用户、角色权限、系统配置和日志管理。 |
| 移动端前端 | ui-mobile，用于书刊浏览、详情、阅读、登录、收藏、划线、评论、评分、历史、下载、预览和个人中心。 |
| 管理端后端 | dp-admin-web，暴露 /admin/**、/preview/**、/files/** 等接口，承载管理端认证、授权和后台业务入口。 |
| 移动端后端 | dp-app-web，暴露 /app/**、移动端预览接口和文件访问能力，承载移动端认证、业务访问和应用层加密。 |
| 公共业务服务 | dp-service，承载内容、用户、权限、互动、统计、文件、PDF、TTS、短信、配置、日志等核心业务服务。 |
| 数据与模型 | dp-model、dp-mapper、db/digital_press.sql，承载实体、DTO、VO、枚举、Mapper、XML SQL 和数据库初始化脚本。 |
| 基础设施 | MySQL、Redis、本地文件存储、短信服务、TTS 模型资源、PDF 生成依赖。 |
1.3 文档边界
当前仓库未提供完整生产部署编排、CI/CD、容器镜像、Nginx、域名证书、云资源或对象存储配置。因此本文档对部署部分描述到工程运行、端口、依赖、配置项和生产建议，不编造未在系统中实现的具体运维资源。
配置文件中涉及数据库、Redis、JWT、RSA、短信等敏感配置时，本文档只描述配置项职责，不记录具体敏感值。生产环境必须通过环境变量、密钥管理系统或安全配置中心覆盖默认配置。
2. 系统总体设计
2.1 产品定位
数字刊物系统用于支撑电子书/数字刊物从后台创建、章节编辑、富文本内容维护、预览审阅、发布上架、移动端阅读、用户互动、PDF 导出、TTS 语音、运营统计到系统权限管理的完整业务流程。
2.2 用户角色
| 角色 | 使用端 | 主要职责 |
|---|---|---|
| 系统管理员 | 管理端 | 管理后台账号、角色权限、系统配置、操作日志、移动端用户状态。 |
| 内容管理员/编辑 | 管理端 | 创建书刊、维护分类、章节、正文、封面、预览、发布和下架。 |
| 运营人员 | 管理端 | 管理评论/评分、查看数据统计、处理用户禁用/禁言/注销、维护下载和 PDF。 |
| 外部审阅人 | 预览入口/移动端 | 通过预览链接访问指定书刊并提交反馈。 |
| 移动端读者 | 移动端 | 浏览书刊、阅读章节、收藏、划线、评论、评分、下载、查看个人记录。 |
| 游客 | 移动端 | 浏览公开书刊和公开章节，在需登录场景被引导登录。 |
2.3 总体架构
text
管理员/编辑/运营 移动端用户/游客
│ │
▼ ▼
ui-admin 管理端前端 ui-mobile 移动端前端
│ /admin/**、/preview/** │ /app/**、/preview/**
▼ ▼
dp-admin-web 管理端后端 dp-app-web 移动端后端
│ │
└───────────────┬──────────────────────┘
▼
dp-service 业务服务层
│
┌───────────┼───────────┬────────────┐
▼ ▼ ▼ ▼
dp-mapper Redis 本地文件 短信/TTS/PDF
│ 会话/缓存 上传/PDF/TTS 扩展能力
▼
MySQL2.4 分层设计
| 层级 | 组成 | 职责 |
|---|---|---|
| 展示层 | ui-admin、ui-mobile |
页面展示、交互、路由、表单、状态管理、接口调用、移动端统计上报。 |
| 接入层 | dp-admin-web、dp-app-web |
REST Controller、认证过滤器、安全配置、加密过滤器、静态资源映射、接口文档。 |
| 业务层 | dp-service |
业务规则、事务、状态流转、缓存、异步统计、文件/PDF/TTS/短信能力封装。 |
| 数据访问层 | dp-mapper |
MyBatis-Plus Mapper、XML SQL、复杂聚合查询。 |
| 模型层 | dp-model |
Entity、DTO、VO、枚举。 |
| 公共层 | dp-common |
统一响应、分页、异常、工具、公共配置。 |
| 数据与资源层 | MySQL、Redis、本地文件系统 | 业务数据、会话缓存、验证码、上传文件、PDF 文件、TTS 音频。 |
2.5 技术选型
| 类别 | 技术/版本 |
|---|---|
| 后端语言 | Java 8 |
| 后端框架 | Spring Boot 2.7.18、Spring Security |
| ORM/数据访问 | MyBatis-Plus 3.5.5、MyBatis XML |
| 数据库 | MySQL 8 驱动 |
| 缓存/会话 | Redis |
| JWT | io.jsonwebtoken 0.12.6 |
| 接口文档 | Knife4j OpenAPI2 |
| 工具库 | Hutool、Jsoup、MapStruct、Lombok |
| 短信 | sms4j |
| 管理端前端 | Vue 2.7、Vue Router 3、Vuex 3、Element UI、Axios、ECharts、WangEditor |
| 移动端前端 | Vue 2.7、Vue Router 3、Vuex 3、Vant、Axios、amfe-flexible、postcss-pxtorem |
| 文件存储 | 本地文件系统，/files/** 静态映射 |
| 语音能力 | sherpa-onnx/TTS 模型资源与 MP3 编码依赖 |
3. 后端工程详细设计
3.1 Maven 模块设计
| 模块 | 类型 | 主要职责 |
|---|---|---|
dp-common |
jar | 统一返回 Result、分页 PageResult、公共异常、全局异常处理、HTML 文本提取、TTS 公共配置等。 |
dp-model |
jar | 维护实体、DTO、VO、枚举，是业务数据输入输出模型中心。 |
dp-mapper |
jar | 维护 Mapper 接口和 XML SQL，负责数据库访问和统计聚合查询。 |
dp-service |
jar | 维护 Service 接口及实现，承载所有核心业务逻辑。 |
dp-admin-web |
boot jar | 管理端启动应用，提供管理端 Controller、安全认证、RBAC、静态资源、Knife4j。 |
dp-app-web |
boot jar | 移动端启动应用，提供移动端 Controller、安全认证、应用层加密、静态资源、Knife4j。 |
依赖关系为：dp-admin-web、dp-app-web 依赖 dp-service；dp-service 依赖 dp-mapper、dp-model、dp-common；dp-mapper 依赖 dp-model；各 Web 模块不直接承载核心业务实现。
3.2 公共响应设计
普通接口统一返回：
json
{
"code": 200,
"message": "success",
"data": {}
}分页接口通过分页结果承载列表数据、页码、每页条数、总数等信息。文件下载接口根据场景返回文件流、URL 或下载记录。
3.3 Web 接入层设计
3.3.1 管理端接口分组
| Controller | 路径前缀 | 建设内容 |
|---|---|---|
AdminAuthController |
/admin/auth |
管理员登录、当前用户信息、退出登录。 |
EbookController |
/admin/ebooks |
书刊分页、详情、新增、编辑、发布、下架、删除、恢复、字段更新、回收站。 |
CategoryController |
/admin/categories |
分类列表、新增、编辑、删除、排序。 |
ChapterController |
/admin/chapters |
章节树、章节新增/编辑/删除、排序、锁定、解锁、强制解锁。 |
ContentController |
/admin/contents |
章节内容读取、草稿保存、提交正式内容、TTS 生成和状态查询。 |
FileUploadController |
/admin/upload |
文件上传、文档解析导入。 |
PreviewController |
/admin/previews |
预览链接生成、按书刊查询、预览审核。 |
PreviewPublicController |
/preview |
预览密码验证、外部反馈提交。 |
PdfExportController |
/admin/pdf |
PDF 导出记录、导出任务、整书生成、下载。 |
CommentAdminController |
/admin/comments |
评论分页、删除、批量删除。 |
RatingAdminController |
/admin/ratings |
评分分页、删除、批量删除。 |
StatController |
/admin/stats |
概览、单书统计、趋势、用户行为分页。 |
AdminUserController |
/admin/users |
管理员分页、详情、新增、编辑、启停、重置密码、分配角色。 |
AppUserAdminController |
/admin/app-users |
移动端用户分页、详情、启停、禁言、注销审批、删除、重新激活、强制下线。 |
RoleController |
/admin/roles |
角色分页、详情、新增、编辑、删除、权限查询与分配。 |
PermissionController |
/admin/permissions |
权限树查询。 |
SystemConfigController |
/admin/config |
系统配置查询、单项保存、批量保存。 |
OperationLogController |
/admin/logs |
操作类型查询、操作日志分页。 |
3.3.2 移动端接口分组
| Controller | 路径前缀 | 建设内容 |
|---|---|---|
AppAuthController |
/app/auth |
短信验证码、短信登录。 |
AppBookController |
/app/books |
分类、书刊列表、书刊详情、搜索。 |
AppChapterController |
/app/chapters |
章节内容、章节搜索、TTS 音频地址。 |
AppCommentController |
/app/comments |
章节评论、书刊评论、发布评论、删除评论、我的评论。 |
AppRatingController |
/app/ratings |
提交评分、评分汇总、我的评分。 |
AppFavoriteController |
/app/favorites |
收藏、取消收藏、收藏检查、书籍收藏、章节收藏。 |
AppHighlightController |
/app/highlights |
新增标记、删除标记、章节标记、我的标记。 |
AppReadingController |
/app/reading |
阅读进度保存、进度查询、历史查询、历史清理。 |
AppDownloadController |
/app/downloads |
下载链接获取、我的下载记录。 |
AppUserController |
/app/user |
用户信息、头像上传、注销申请、撤销注销。 |
AppStatController |
/app/stat |
页面访问、用户行为、外链点击统计上报。 |
AppConfigController |
/app/config |
加密配置、单项配置、配置批量查询。 |
PreviewPublicController |
/preview |
预览地址解析、密码验证、反馈提交。 |
3.4 业务服务层设计
| 服务 | 主要职责 |
|---|---|
AuthService |
管理端账号登录校验、移动端短信登录、验证码校验、JWT 登录支撑。 |
AdminUserService |
管理员用户增删改查、启停、角色分配、密码重置。 |
AppUserService |
移动端用户信息、头像、禁用/启用、禁言、注销审批、强制下线。 |
PermissionService |
权限树、用户权限码、权限缓存刷新。 |
RoleService |
角色维护和角色权限分配。 |
EbookService |
书刊 CRUD、发布、下架、回收站、移动端列表/详情/搜索。 |
CategoryService |
分类维护与排序。 |
ChapterService |
章节树维护、排序、编辑锁和解锁。 |
ContentService |
章节正文、草稿、正式提交、TTS 状态。 |
FileService |
文件上传、类型校验、路径生成、文档解析。 |
PdfService |
PDF 导出任务、导出记录、文件生成、下载记录。 |
TtsService |
TTS 引擎初始化、章节语音异步生成、状态查询、音频 URL。 |
CommentService |
评论发布、列表、删除、后台管理、我的评论。 |
RatingService |
评分提交、汇总、后台评分管理。 |
FavoriteService |
收藏、取消收藏、收藏列表与状态检查。 |
HighlightService |
划线标记保存、删除、查询。 |
ReadingProgressService |
阅读进度和历史记录维护。 |
StatService |
PV、UV、行为、外链点击写入与后台聚合查询。 |
SystemConfigService |
系统配置查询和保存。 |
OperationLogService |
后台操作日志记录与查询。 |
SmsSenderService |
短信服务调用封装。 |
TokenSessionService |
管理端/移动端 token 活跃会话绑定、刷新、撤销、强制失效。 |
AdminCacheService、AppMobileCacheService |
后台权限/移动端读缓存等缓存能力。 |
3.5 事务与异步设计
| 场景 | 设计说明 |
|---|---|
| 内容编辑提交 | Service 层维护章节内容、草稿和正式内容状态，提交成功后清理或刷新移动端相关缓存。 |
| 发布/下架 | Service 层校验书刊状态、发布时间、删除状态并更新状态字段；定时发布由调度任务处理。 |
| 角色权限分配 | 更新角色权限关联表，权限缓存需失效或重新加载。 |
| 用户状态变更 | 管理端处理移动用户启停、禁言、注销审批和强制下线，必要时撤销 Redis 会话。 |
| 统计写入 | StatServiceImpl 使用异步执行器写入页面访问、行为、外链点击明细，后台查询以持久化数据为准。 |
| PDF 生成 | 通过导出记录保存任务状态，生成完成后回写文件地址、大小、页数和状态。 |
| TTS 生成 | TtsServiceImpl 异步生成音频，章节内容表保存 TTS 文件、内容哈希和生成状态。 |
4. 功能模块详细设计
4.1 管理端登录与首页
管理员通过 /admin/auth/login 输入用户名和密码登录。后端校验用户是否存在、是否禁用、是否锁定、密码是否正确；登录失败累计次数，达到阈值后锁定；登录成功后清空失败状态、签发管理端 JWT 并写入 Redis 活跃会话。
登录成功后，前端保存 token，访问 /admin/auth/info 获取当前用户、角色和权限码。管理端首页展示运营概览、访问趋势和热门书刊等统计信息。
4.2 电子书管理
电子书管理覆盖书刊全生命周期：
- 新建书刊：维护标题、简介、封面、分类、年份、排序、书刊类型、阅读方向、下载模式、价格、评论开关、评分开关等基础信息。
- 编辑书刊：读取已有信息并保存变更。
- 发布上架：支持立即发布和定时发布；移动端仅展示已发布且未删除的书刊。
- 下架：已发布或待上架书刊可下架，移动端停止公开展示。
- 删除与回收站：删除进入回收站，可恢复；系统保留彻底删除或逻辑删除相关能力。
- 字段快速更新：支持评论开关、评分开关等字段更新。
4.3 分类管理
分类用于管理端书刊筛选和移动端分类浏览。管理端支持分类列表、新增、编辑、删除和排序。删除分类时应考虑是否存在关联书刊，避免业务数据失效。
4.4 章节管理
章节按书刊维护树形结构，支持新增、编辑、删除、排序、启停和层级关系。章节编辑引入锁机制：进入内容编辑时可锁定章节，防止多人同时编辑；编辑结束后解锁；具备权限的管理员可强制解锁。系统定时释放过期锁，降低异常退出造成的长期占用。
4.5 内容编辑与文档解析
内容编辑用于维护章节正文，支持富文本编辑、文件/图片等资源上传、文档解析导入、草稿保存和正式提交。
- 草稿保存：将编辑中内容保存到草稿字段，降低内容丢失风险。
- 正式提交：将草稿或提交内容写入正式内容字段，用于移动端阅读展示。
- 文档解析：上传
docx/doc/html/txt等文档后解析为 HTML 内容，供编辑器预览、替换或追加。 - 一键排版：前端提供内容格式整理入口，后端以提交后的正文为准。
4.6 TTS 语音设计
章节内容支持触发 TTS 生成。后端基于 TTS 模型资源初始化语音引擎池，异步生成章节音频，生成状态写入章节内容表。前端通过状态接口轮询生成进度，移动端可通过章节 TTS 接口获取音频资源。TTS 文件本体存储在本地文件目录，数据库保存文件 URL、内容哈希和状态。
4.7 预览管理
预览功能用于外部审阅：
- 管理端为指定书刊生成预览链接、访问密码和有效期。
- 外部审阅人通过预览 URL 访问预览入口。
- 系统校验密码、有效期和错误次数。
- 审阅人可浏览目录、进入阅读并提交反馈。
- 管理端查询预览记录和反馈，并进行通过或拒绝审核。
预览接口同时存在管理端后端和移动端后端中的 /preview 入口，分别承担密码验证、地址解析和反馈提交等能力。
4.8 PDF 导出
PDF 模块提供导出任务和下载记录管理：
- 支持整书导出和按章节导出。
- 导出记录保存导出范围、触发类型、状态、文件 URL、文件大小、页数、创建人等信息。
- 状态包括待处理、处理中、完成、失败等。
- 下载接口按记录返回文件资源，并记录下载行为。
4.9 评论管理
移动端用户可对书刊或章节发表评论。发布评论时需校验登录态、账号启用状态、注销状态、禁言状态以及书刊评论开关。管理端支持评论分页查询、单条删除和批量删除。移动端支持章节评论、书刊评论、我的评论和删除本人评论。
4.10 评分管理
移动端支持提交评分、查询评分汇总和我的评分。后端按用户、书刊/章节维护评分数据并聚合评分结果。管理端支持评分分页、删除和批量删除，相关入口当前归入统计或评分管理权限。
4.11 收藏、划线、阅读进度与历史
| 功能 | 设计说明 |
|---|---|
| 收藏 | 用户可收藏书籍或章节，可取消收藏、检查收藏状态、查看书籍/章节收藏列表。 |
| 划线标记 | 用户可在阅读器中保存划线、笔记或标记信息，可查询章节标记和我的标记。 |
| 阅读进度 | 用户阅读时保存书刊、章节和位置信息，用于下次继续阅读。 |
| 阅读历史 | 系统记录用户阅读历史，个人中心可分页查看和清理。 |
4.12 下载管理
书刊可配置下载模式和相关下载信息。移动端用户在符合业务规则时可获取下载链接；系统记录下载行为和用户下载记录。管理端通过书刊配置、统计和 PDF 模块间接维护下载相关能力。
4.13 移动端用户管理
移动端用户通过短信验证码登录。管理端可查询用户列表和详情，处理启用/禁用、禁言/解除禁言、注销申请通过/拒绝、重新激活和强制下线。强制下线通过 Redis 会话撤销实现，使用户后续请求失效。
4.14 管理端用户、角色与权限
系统采用 RBAC：管理员用户绑定角色，角色绑定权限节点，权限节点包含菜单和按钮权限码。前端根据权限码控制菜单、路由和按钮显示；后端通过 @PreAuthorize 校验接口权限，后端是最终安全边界。
4.15 系统配置
系统配置支持后台查询、单项保存和批量保存。移动端通过 /app/config/get 和 /app/config/list 查询业务配置，例如登录方式、协议、开关或展示内容。配置变更后应避免客户端长期使用旧配置。
4.16 操作日志
后台操作日志记录管理端关键操作，用于审计和追踪。管理端提供操作类型查询和日志分页查询。涉及删除、禁用、权限变更等关键操作应保留操作者、操作对象、时间、类型和结果。
4.17 统计分析
统计模块覆盖：
- 页面访问：PV、UV、来源、停留时长、书刊/章节访问。
- 用户行为：阅读、下载、分享、AI 使用等行为类别。
- 外链点击：第三方链接点击、所属章节、访问来源。
- 后台分析：概览、趋势、热门书刊、单书详情、章节热度、来源渠道和行为分页。
移动端通过路由守卫和 tracker 工具在书刊详情页、阅读器和外链访问场景上报统计；后端异步写入明细表，管理端按时间范围和业务维度聚合展示。
4.18 AI 使用记录
数据库包含 ai_usage_record 表，并在统计行为中预留 AI 使用相关类别。当前移动端 README 和代码材料显示 AI 能力以配置/记录/入口预留为主，不应在交付说明中描述为完整真实 AI 服务已上线。
5. 前端详细设计
5.1 管理端前端设计
ui-admin 使用 Vue 2、Vue Router、Vuex、Element UI、Axios、ECharts 和 WangEditor。开发端口为 9528，开发代理转发到 http://localhost:8080。
5.1.1 管理端路由与页面
| 路由 | 页面 | 功能 |
|---|---|---|
/login |
views/login/index.vue |
管理员登录。 |
/dashboard |
views/dashboard/index.vue |
首页统计概览。 |
/ebook/list |
views/ebook/list.vue |
我的作品/电子书列表。 |
/ebook/create |
views/ebook/create.vue |
新建电子书。 |
/ebook/edit/:id |
views/ebook/edit.vue |
编辑电子书。 |
/ebook/category |
views/ebook/category.vue |
分类管理。 |
/ebook/chapters/:id |
views/ebook/chapters.vue |
章节管理。 |
/ebook/content/:ebookId/:chapterId |
views/ebook/content.vue |
内容编辑。 |
/ebook/comments |
views/ebook/comments.vue |
评论管理。 |
/ebook/stats |
views/ebook/stats.vue |
数据统计。 |
/ebook/stats/:id |
views/ebook/statDetail.vue |
单书统计详情。 |
/ebook/pdf |
views/ebook/pdf.vue |
PDF 导出管理。 |
/ebook/preview/:id |
views/ebook/preview.vue |
预览管理。 |
/system/user |
views/system/user.vue |
管理端用户管理。 |
/system/app-user |
views/system/appUser.vue |
移动端用户管理。 |
/system/app-user/:id |
views/system/appUserDetail.vue |
移动端用户详情。 |
/system/role |
views/system/role.vue |
角色管理。 |
/system/log |
views/system/log.vue |
操作日志。 |
/system/config |
views/system/config.vue |
系统配置。 |
5.1.2 管理端状态与权限
- Vuex
user模块保存 token、用户信息和权限码。 - 请求拦截器统一附加
Authorization: Bearer <token>。 - 响应拦截器处理统一响应码、时间格式、401 登出和跳转登录。
- 路由
meta.permission声明页面权限。 - 路由守卫在无 token 时跳转登录；有 token 但未加载用户信息时请求用户信息；无权限时跳转首页。
- 菜单和按钮通过权限码过滤，最终接口权限以后端
@PreAuthorize为准。
5.1.3 管理端 API 分组
ui-admin/src/api 包含：auth、ebook、chapter、content、category、comment、stat、pdf、preview、user、role、log、config、upload，分别对应后端管理端接口分组。
5.2 移动端前端设计
ui-mobile 使用 Vue 2、Vue Router、Vuex、Vant、Axios、移动端适配。开发端口为 9529，开发代理转发到 http://localhost:8081，通过 amfe-flexible 和 postcss-pxtorem 做移动端尺寸适配。
5.2.1 移动端路由与页面
| 路由 | 页面 | 功能 |
|---|---|---|
/book |
views/book/list.vue |
书刊列表。 |
/book/:id |
views/book/detail.vue |
书刊详情。 |
/reader/:bookId/:chapterId |
views/reader/index.vue |
阅读器。 |
/external-webview |
views/external-webview/index.vue |
外部链接页。 |
/mine |
views/mine/index.vue |
个人中心。 |
/login |
views/mine/login.vue |
短信登录。 |
/agreement/:type |
views/mine/agreement.vue |
协议页面。 |
/mine/favorites |
views/mine/favorites.vue |
我的收藏，需登录。 |
/mine/highlights |
views/mine/highlights.vue |
我的标记，需登录。 |
/mine/comments |
views/mine/comments.vue |
我的评论，需登录。 |
/mine/history |
views/mine/history.vue |
阅读历史，需登录。 |
/mine/downloads |
views/mine/downloads.vue |
我的下载，需登录。 |
/preview/:url |
views/preview/index.vue |
预览访问。 |
5.2.2 移动端状态、登录与请求
- Vuex
user模块保存移动端 token。 - 路由
meta.requireAuth控制个人中心相关页面登录态。 - 未登录访问受保护页面时跳转
/login，并携带redirect参数。 - 请求拦截器统一携带 Bearer token。
- 响应拦截器处理统一响应、401/403/账号注销状态、登出和登录跳转。
5.2.3 移动端统计协作
移动端路由守卫在进入书刊详情页时上报书籍访问，在进入阅读器时上报阅读访问和页面访问；离开相关页面时结束访问并上报停留时长。外链页面通过 tracker 上报外链点击。
5.2.4 移动端 API 分组
ui-mobile/src/api 包含：auth、book、chapter、comment、rating、favorite、highlight、reading、download、user、preview、stat、config，分别对应移动端后端接口分组。
6. 数据库详细设计
6.1 数据表清单
根据 db/digital_press.sql，当前数据库包含以下表：
| 业务域 | 表 |
|---|---|
| AI/统计扩展 | ai_usage_record |
| 移动端用户 | app_user |
| 内容 | ebook、ebook_category、ebook_chapter、ebook_chapter_content |
| 互动 | ebook_comment、ebook_rating、ebook_favorite、ebook_highlight |
| 阅读与下载 | ebook_reading_history、ebook_reading_progress、ebook_download_record |
| 预览 | ebook_preview、ebook_preview_feedback |
pdf_export_record |
|
| 统计 | stat_page_view、stat_user_behavior、stat_external_link_click |
| 权限 | sys_admin_user、sys_admin_user_role、sys_role、sys_role_permission、sys_permission |
| 系统 | sys_config、sys_operation_log |
6.2 内容域
| 表 | 说明 | 关键设计 |
|---|---|---|
ebook |
书刊主表 | 保存标题、简介、封面、分类、年份、类型、阅读方向、下载模式、价格、状态、发布时间、PDF 信息、评论/评分开关、排序和删除标记。 |
ebook_category |
分类表 | 保存分类名称、排序、状态，用于后台筛选和移动端分类。 |
ebook_chapter |
章节表 | 保存书刊 ID、父级章节、标题、层级、排序、状态、锁定用户和锁定时间。 |
ebook_chapter_content |
章节内容表 | 保存正式内容、草稿内容、保存时间、TTS 文件、TTS 内容哈希和生成状态。 |
ebook_preview |
预览表 | 保存预览地址、密码、有效期、访问状态和所属书刊。 |
ebook_preview_feedback |
预览反馈表 | 保存审阅反馈、审核状态和审核意见。 |
pdf_export_record |
PDF 导出记录 | 保存导出范围、章节列表、状态、文件 URL、文件大小、页数、创建人和下载信息。 |
6.3 用户互动域
| 表 | 说明 |
|---|---|
app_user |
移动端用户，保存手机号、昵称、头像、状态、禁言、注销、登录和偏好信息。 |
ebook_comment |
评论明细，关联用户、书刊和章节。 |
ebook_rating |
评分明细，关联用户和评分对象。 |
ebook_favorite |
收藏数据，支持书籍或章节收藏。 |
ebook_highlight |
划线/标记数据，记录章节位置和内容。 |
ebook_reading_progress |
阅读进度，保存用户最后阅读位置。 |
ebook_reading_history |
阅读历史，记录用户历史阅读行为。 |
ebook_download_record |
下载记录，记录用户下载行为。 |
6.4 统计域
| 表 | 说明 | 用途 |
|---|---|---|
stat_page_view |
页面访问明细 | 支撑 PV、UV、停留时长、趋势、书刊/章节访问排行。 |
stat_user_behavior |
用户行为明细 | 支撑阅读、下载、分享、AI 使用等行为统计。 |
stat_external_link_click |
外链点击明细 | 支撑第三方链接点击分析。 |
ai_usage_record |
AI 使用记录 | 支撑 AI 使用次数、限额和统计扩展。 |
6.5 权限与系统域
| 表 | 说明 |
|---|---|
sys_admin_user |
管理端用户，保存账号、密码、状态、登录失败次数和锁定时间。 |
sys_role |
角色信息。 |
sys_permission |
权限树，保存菜单、按钮、权限码、父子关系和排序。 |
sys_admin_user_role |
管理员与角色关联。 |
sys_role_permission |
角色与权限关联。 |
sys_config |
系统配置项。 |
sys_operation_log |
操作日志。 |
6.6 数据一致性策略
- 内容与章节分离：章节结构和章节正文分别存储，便于目录维护和内容编辑。
- 草稿与正式内容分离：编辑态草稿不会立即影响移动端正式阅读内容。
- 权限通过关联表维护：用户-角色、角色-权限解耦，便于权限扩展。
- 文件与数据库解耦：数据库保存 URL、状态和元信息，文件本体存储于本地目录。
- 统计明细优先：后台统计以明细数据聚合，允许异步写入带来短暂延迟。
- 逻辑删除优先：涉及恢复、审计和用户状态的业务优先使用状态字段或逻辑删除。
7. 安全详细设计
7.1 管理端认证授权
管理端采用用户名密码登录、JWT、Redis 活跃会话和 RBAC 权限码：
- 用户提交账号密码到
/admin/auth/login。 - 后端校验账号、密码、状态和锁定时间。
- 登录成功生成
userType=admin的 JWT。 - token 绑定 Redis 活跃会话。
- 后续请求由
AdminJwtAuthenticationFilter校验 Bearer token、JWT 签名、用户类型和 Redis 会话。 - 认证通过后加载权限码，写入 Spring Security 上下文。
- Controller 方法通过
@PreAuthorize校验权限码。
管理端放行登录、预览、文件、静态资源和 Swagger/Knife4j 资源；其他 /admin/** 接口要求认证，具体操作要求权限码。
7.2 移动端认证授权
移动端采用短信验证码登录、JWT 和 Redis 活跃会话：
- 用户请求
/app/auth/sms-code获取验证码。 - 后端发送验证码并写入 Redis。
- 用户通过
/app/auth/login提交手机号和验证码。 - 后端校验验证码、用户状态，必要时创建或更新用户。
- 登录成功生成
userType=app的 JWT 并绑定 Redis 会话。 - 后续请求由
AppJwtAuthenticationFilter校验 token 和会话。
移动端业务权限由 Service 层校验，包括登录态、账号启用状态、禁言状态、注销状态、资源归属、书刊发布状态、评论/评分开关、下载模式和 VIP/登录要求。
7.3 RBAC 权限码
管理端权限码分为菜单级和按钮/操作级。实际接口中使用的权限码包括但不限于：
| 模块 | 权限码示例 |
|---|---|
| 电子书 | ebook:list、ebook:list:edit、ebook:list:publish、ebook:list:delete、ebook:list:restore、ebook:list:chapter、ebook:list:content、ebook:list:preview、ebook:list:unlock |
| 分类 | ebook:category、ebook:category:add、ebook:category:edit、ebook:category:delete |
| 评论/评分 | ebook:comment、ebook:comment:delete、ebook:comment:batch_delete、ebook:stat |
ebook:pdf、ebook:pdf:export |
|
| 用户 | system:admin_user、system:admin_user:add、system:admin_user:edit、system:admin_user:status、system:admin_user:reset_pwd、system:admin_user:role |
| 移动用户 | system:app_user、system:app_user:detail、system:app_user:status、system:app_user:mute、system:app_user:cancel、system:app_user:delete、system:app_user:force_logout |
| 角色权限 | system:role、system:role:add、system:role:edit、system:role:delete、system:role:permission |
| 系统 | system:config、system:config:edit、system:log |
7.4 移动端应用层加密
移动端 /app/** 接口支持应用层加密，排除 /app/config/crypto。加密方案为 RSA-OAEP + AES-GCM：
- 客户端从
/app/config/crypto获取加密开关、keyId 和 RSA 公钥。 - 每次请求生成一次性 AES-256-GCM 密钥。
- 使用 RSA-OAEP 加密 AES 密钥，放入
X-Encrypted-Key。 - 使用 AES-GCM 加密请求参数、请求体和响应体。
- AAD 包含请求方法、路径、时间戳、nonce、requestId。
- 通过时间戳窗口、nonce 和 requestId 防止重放。
multipart/form-data请求体当前不做 AES-GCM 加密，但响应仍可加密。
当前 dp-app-web/src/main/resources/application.yml 中移动端加密由 APP_CRYPTO_ENABLED 控制，默认值以当前环境配置为准。生产环境仍必须使用 HTTPS，应用层加密不能替代 HTTPS。
7.5 文件安全
文件上传设计包含：
- 上传根目录配置化。
- URL 前缀配置化。
- 单文件大小限制。
- 按业务类型限制扩展名。
- 文件名使用 UUID，降低重名覆盖风险。
- 按业务类型和日期分目录保存。
- 通过 WebMvc 静态映射提供
/files/**访问。
当前系统未实现病毒扫描、真实 MIME 嗅探、图片重编码、对象存储私有授权、文件生命周期自动清理等能力；如生产环境面向公网开放上传，应补充这些能力或接入对象存储安全策略。
7.6 敏感配置保护
数据库密码、Redis 密码、JWT 密钥、RSA 私钥、短信服务密钥等必须作为敏感配置处理：
- 不应写入文档、日志、提交信息或前端构建产物。
- 生产环境通过环境变量或密钥管理系统注入。
- JWT 密钥、RSA 私钥和短信密钥应定期轮换。
- 启动和日志中不得输出敏感值。
8. 缓存、会话与配置设计
8.1 Redis 用途
| 用途 | 说明 |
|---|---|
| token 活跃会话 | 管理端和移动端登录后绑定 token，用于退出、强制下线和会话失效。 |
| token TTL 刷新 | 认证过滤器校验通过后刷新活跃会话过期时间。 |
| 权限缓存 | 缓存管理端用户权限码，减少重复查询。 |
| 短信验证码 | 保存验证码和过期时间。 |
| 登录失败/临时状态 | 支撑失败计数、锁定或其他临时业务状态。 |
| 移动端读缓存 | 缓存书刊列表、详情、搜索等读多写少数据。 |
8.2 会话隔离
| 端 | JWT userType |
Redis client/维度 | Spring Security 权限 |
|---|---|---|---|
| 管理端 | admin |
admin |
ROLE_ADMIN + 权限码 |
| 移动端 | app |
app |
ROLE_APP |
该设计避免管理端 token 和移动端 token 混用。
8.3 缓存失效
- 用户退出、注销、强制下线后撤销对应 token。
- 管理端角色或权限变更后刷新权限缓存。
- 书刊发布、下架、删除、恢复、内容提交后清理移动端相关缓存。
- 系统配置变更后避免客户端长期使用旧配置。
9. 文件、PDF 与 TTS 资源设计
9.1 文件上传链路
text
客户端 multipart 上传
→ Controller 接收 MultipartFile
→ FileService 校验大小、扩展名、业务类型
→ 生成 UUID 文件名
→ 按 type/yyyy/MM/dd 保存到 upload-path
→ 返回 url-prefix 下的访问 URL
→ WebMvcConfig 将 /files/** 映射到本地目录9.2 文档解析链路
text
上传 docx/doc/html/txt
→ FileService 校验文档类型
→ 解析为 HTML 或文本内容
→ 返回解析内容
→ 前端预览、替换或追加到富文本编辑器9.3 PDF 导出链路
text
管理端发起导出
→ 创建 pdf_export_record
→ 聚合电子书基础信息和章节内容
→ 生成 PDF 文件
→ 更新导出记录状态、文件 URL、大小、页数
→ 管理端下载或查看导出记录9.4 TTS 生成链路
text
管理端触发章节 TTS
→ 校验章节和内容
→ 异步生成语音文件
→ 写入 TTS 状态、文件 URL、内容哈希
→ 管理端轮询状态
→ 移动端读取章节音频地址10. 运行与部署设计
10.1 后端运行
| 应用 | 启动模块 | 默认端口 | 主要接口 |
|---|---|---|---|
| 管理端后端 | dp-admin-web |
8080 |
/admin/**、/preview/**、/files/** |
| 移动端后端 | dp-app-web |
8081 |
/app/**、/preview/**、/files/** |
后端依赖 MySQL、Redis、本地文件目录、短信配置、TTS 模型资源和 PDF/TTS 相关依赖。MyBatis-Plus 使用 deleted 等逻辑删除字段和 Mapper/XML 完成数据访问。
10.2 前端运行
| 应用 | 默认开发端口 | 代理目标 | 构建输出 |
|---|---|---|---|
管理端前端 ui-admin |
9528 |
http://localhost:8080 |
dist |
移动端前端 ui-mobile |
9529 |
http://localhost:8081 |
dist |
开发环境通过 VUE_APP_API_BASE_URL 配置 API 前缀；生产环境需要由 Web 服务器或网关转发到对应后端服务。
10.3 关键配置项
| 配置域 | 说明 |
|---|---|
server.port |
后端服务端口。 |
spring.datasource |
MySQL 数据源。 |
spring.redis |
Redis 地址、端口和认证信息。 |
mybatis-plus |
Mapper、逻辑删除、驼峰映射等配置。 |
jwt.secret |
JWT 签名密钥。 |
jwt.admin-expiration、jwt.app-expiration |
管理端/移动端 token 有效期。 |
file.upload-path、file.url-prefix |
上传文件保存目录和访问前缀。 |
app.crypto.* |
移动端加密开关、密钥、时间窗口。 |
tts.* |
TTS 模型、音频目录和引擎参数。 |
| 短信配置 | 短信平台、签名、模板、密钥等。 |
11. 测试与质量设计
11.1 后端测试重点
| 测试类别 | 测试内容 |
|---|---|
| 认证鉴权 | 管理端登录、移动端登录、JWT 过期、Redis 会话失效、权限不足、强制下线。 |
| 内容业务 | 书刊新增/编辑/发布/下架/删除/恢复，章节树、锁定、草稿和提交。 |
| 互动业务 | 评论、评分、收藏、划线、进度、历史、下载的登录态和资源归属。 |
| 统计业务 | PV、行为、外链点击写入和后台聚合查询。 |
| 文件业务 | 上传大小、扩展名、文档解析、静态访问、PDF 下载。 |
| 安全业务 | 禁用、禁言、注销、权限码、加密传输、敏感配置不泄露。 |
11.2 前端测试重点
| 应用 | 测试内容 |
|---|---|
| 管理端 | 登录、路由权限、菜单权限、按钮权限、书刊编辑、章节编辑、上传、PDF、统计、系统管理。 |
| 移动端 | 游客浏览、短信登录、阅读器、收藏、评论、评分、标记、历史、下载、预览、账号异常状态处理。 |
| 请求封装 | token 注入、统一响应、错误提示、401/403 跳转、移动端加解密。 |
| 兼容性 | 移动端 WebCrypto 支持、移动端尺寸适配、浏览器路由刷新。 |
11.3 质量控制要求
- 后端接口必须以后端权限和业务校验为最终安全边界。
- 前端权限只作为交互入口控制，不可作为唯一安全控制。
- 重要状态流转应有失败提示和可追踪日志。
- 异步任务应保存任务状态，便于失败排查。
- 文件上传和下载应限制类型、大小和访问路径。
- 生产环境敏感配置不得使用默认值或明文提交值。
12. 当前实现限制与演进建议
| 领域 | 当前限制 | 建议 |
|---|---|---|
| 部署 | 仓库未见完整 Docker、CI/CD、Nginx 或云资源编排。 | 补充生产部署方案、健康检查、回滚和日志采集。 |
| 文件安全 | 当前主要基于扩展名和大小校验。 | 增加 MIME 嗅探、病毒扫描、图片重编码、对象存储、生命周期清理。 |
| 敏感配置 | 配置文件存在默认值或环境变量入口。 | 生产使用密钥管理系统，密钥定期轮换，禁止日志回显。 |
| 移动端加密 | 加密能力可配置启停，multipart 请求体不加密。 | 明确生产开关策略，上传类接口依赖 HTTPS 和服务端安全校验。 |
| AI 能力 | 目前以记录和配置预留为主。 | 如需上线真实 AI 服务，应补充服务接入、限额、审计和内容安全设计。 |
| 文件存储 | 当前为本地文件系统。 | 生产高可用场景建议迁移到对象存储或共享存储，并配置 CDN/鉴权。 |
| 观测能力 | 仓库未见完整监控告警配置。 | 增加应用指标、慢 SQL、接口耗时、错误率、任务失败和磁盘容量告警。 |
13. 与当前系统对照检查
本说明书编写后已按以下内容与当前系统进行对照：
| 对照项 | 对照结果 |
|---|---|
| 后端模块 | 已与根 pom.xml 的 6 个 Maven 模块对照：dp-common、dp-model、dp-mapper、dp-service、dp-admin-web、dp-app-web。 |
| 管理端 Controller | 已与 dp-admin-web/src/main/java/com/cms/web/controller 下实际路由对照，覆盖 /admin/auth、/admin/ebooks、/admin/categories、/admin/chapters、/admin/contents、/admin/upload、/admin/pdf、/admin/previews、/admin/stats、用户、角色、权限、配置、日志等接口。 |
| 移动端 Controller | 已与 dp-app-web/src/main/java/com/cms/web/controller 下实际路由对照，覆盖 /app/auth、/app/books、/app/chapters、/app/comments、/app/ratings、/app/favorites、/app/highlights、/app/reading、/app/downloads、/app/user、/app/stat、/app/config 和 /preview。 |
| 数据表 | 已与 db/digital_press.sql 的 CREATE TABLE 清单对照，覆盖 27 张表。 |
| 管理端前端 | 已与 ui-admin/src/router/index.js、src/views、src/api、src/utils/request.js 和 vue.config.js 对照。 |
| 移动端前端 | 已与 ui-mobile/src/router/index.js、src/views、src/api、src/utils/request.js 和 vue.config.js 对照。 |
| 权限控制 | 已与管理端 @PreAuthorize 权限码、前端路由 meta.permission 和权限专题文档对照。 |
| 移动端加密 | 已与 ui-mobile/src/utils/request.js、doc/mobile-app-crypto-design.md 和移动端配置分组对照。 |
| 统计异步 | 已与 StatServiceImpl 的异步写入和移动端 tracker 路由统计对照。 |
| TTS/PDF/上传 | 已与服务清单、Controller 路由、专题文档和配置分组对照。 |
经对照，本文档以当前代码结构为准；已有旧文档中仍出现的 dp-web、单服务端口等旧描述未作为本文档依据。生产部署、CI/CD、对象存储、病毒扫描、真实 AI 服务等未在当前仓库中固化实现的内容，本文档仅作为限制和演进建议描述。