简介
本模块提供完整的下载资源管理能力，覆盖后台的增删改查、分类体系、文件上传与附件管理、前台列表与详情展示、访问统计、SEO优化等。通过控制器-服务-模型的分层设计，将请求校验、业务规则、数据持久化与展示组装解耦，便于扩展与维护。
项目结构
下载模块在前后端分别实现：
- 后台（Admin）：负责下载条目与分类的CRUD、批量操作、日志记录、附件上传与草稿处理。
- 前台（Front）：负责下载列表、分类浏览、归档浏览、详情页渲染、点击统计与SEO信息输出。
graph TB
subgraph "后台 Admin"
AC["DownloadController"]
CC["CategoryController"]
ASvc["DownloadService"]
CSvc["CategoryService"]
AModelD["Download(后台)"]
AModelC["DownloadCategory(后台)"]
end
subgraph "前台 Front"
FC["DownloadController"]
FSvc["DownloadService"]
FModelD["Download(前台)"]
FModelC["DownloadCategory(前台)"]
end
AC --> ASvc
CC --> CSvc
FC --> FSvc
ASvc --> AModelD
CSvc --> AModelC
FSvc --> FModelD
FSvc --> FModelC核心组件
- 后台控制器
- 下载控制器：列表、新增、编辑、更新、删除、批量操作。
- 分类控制器：分类列表、新增、编辑、更新、删除。
- 前台控制器
- 下载控制器：分类/归档列表、详情页展示、点击统计。
- 服务层
- 后台下载服务：列表构建、新增/更新/删除、批量操作、附件与内容处理、审计日志。
- 后台分类服务：分类默认数据、新增/更新/删除、导航同步。
- 前台下载服务：列表构建、详情构建、分类查询、点击统计。
- 模型层
- 后台模型：字段白名单、关联分类、关键字筛选、默认排序。
- 前台模型：发布状态过滤、归档时间窗、列表附加字段、URL生成、导出能力。
架构总览
采用“控制器-服务-模型”分层，职责清晰：
- 控制器：接收请求、参数绑定、视图渲染、跳转与消息。
- 服务：编排业务逻辑，协调模型、附件、Markdown、审计日志等。
- 模型：数据表映射、查询作用域、属性转换、关联关系。
sequenceDiagram
participant U as "管理员"
participant C as "后台下载控制器"
participant S as "后台下载服务"
participant M as "下载模型"
participant A as "附件服务"
participant L as "审计日志"
U->>C : 提交新增表单
C->>S : insert(data, draftToken, adminId)
S->>A : 存储正文图片/主图
A-->>S : 返回附件标识
S->>M : create(清洗后的数据)
M-->>S : 返回新ID
S->>L : 写入创建日志
S-->>C : 返回新ID
C-->>U : 重定向到编辑页并提示成功详细组件分析
后台下载管理
- 列表与筛选
- 支持按分类、关键词分页，附带排序与状态、大小等字段。
- 新增/编辑
- 正文XSS清洗、远程图片本地化、主图上传、自定义字段模板加载。
- 草稿机制：清理旧草稿、生成草稿令牌、提交后认领草稿。
- 删除与批量
- 二次确认删除；批量删除或批量转移分类。
- 审计日志
- 创建、更新、删除均记录管理员行为。
flowchart TD
Start(["进入新增"]) --> Clean["清洗正文<br/>处理远程图片"]
Clean --> UploadMain["上传主图"]
UploadMain --> Persist["持久化记录"]
Persist --> ClaimDraft["认领草稿"]
ClaimDraft --> Log["写入审计日志"]
Log --> End(["完成"])后台分类管理
- 分类树与扁平化展示
- 新增/编辑：图标模式（文本/图片）、可选同步至导航
- 删除：占用检查、子分类检查、二次确认、语言与导航清理
classDiagram
class CategoryService {
+buildCategoryDefaultData()
+insert(data, adminId) int
+update(data, adminId) void
+delete(catId, data) array
}
class DownloadCategory {
+table : download_category
+fillable : name, slug, parent_id, icon, keywords, description, sync_to_nav, sort
}
CategoryService --> DownloadCategory : "CRUD"前台下载展示
- 列表/分类/归档
- 支持分页、归档时间窗、分类过滤、默认排序。
- 详情页
- 读取已发布记录、Markdown渲染、SEO标题/描述/关键词、面包屑与Schema。
- 点击统计
- 每次查看详情时点击量+1。
sequenceDiagram
participant B as "浏览器"
participant FC as "前台下载控制器"
participant FS as "前台下载服务"
participant MD as "Markdown渲染"
participant DB as "数据库"
B->>FC : GET /download/{id}
FC->>FS : buildDownloadShowData(id)
FS->>DB : 查询已发布记录
DB-->>FS : 下载数据
FS->>MD : 渲染content
MD-->>FS : HTML内容
FS-->>FC : 下载数组
FC->>FS : recordDownloadView(id)
FS->>DB : click+1
FC-->>B : 渲染详情页依赖关系分析
- 控制器依赖服务，服务依赖模型与第三方服务（附件、Markdown、审计）。
- 模型使用Trait与Scope复用通用能力（分类树、过滤器、排序、附件URL预热等）。
- 前台与后台共享同一张数据表，但通过不同模型与查询条件隔离职责。
graph LR
AC["后台下载控制器"] --> ASvc["后台下载服务"]
CC["后台分类控制器"] --> CSvc["后台分类服务"]
FC["前台下载控制器"] --> FSvc["前台下载服务"]
ASvc --> AModelD["后台下载模型"]
CSvc --> AModelC["后台分类模型"]
FSvc --> FModelD["前台下载模型"]
FSvc --> FModelC["前台分类模型"]
ASvc -.->|附件/Markdown/审计| Ext["外部服务"]
CSvc -.->|导航同步| NavSvc["导航服务"]性能与存储策略
- 列表性能
- 仅选择必要字段，避免N+1查询；使用with预加载关联分类。
- 附件URL预热，减少重复解析。
- 分页与归档
- 分页大小可配置；归档按年月范围过滤，降低大数据集扫描。
- 附件存储
- 主图与正文图片统一通过附件服务存储，支持草稿与认领机制，确保一致性。
- Markdown渲染
- 仅在详情与编辑预览时渲染，避免不必要的计算。
安全与权限控制
- 输入校验
- 表单校验由Request类完成（如DownloadFormRequest、CategoryFormRequest），失败抛出领域异常。
- XSS防护
- 正文内容经XSS清洗后再入库。
- 权限与审计
- 所有写操作记录管理员审计日志，便于追溯。
- 删除保护
- 分类删除前检查是否被占用、是否存在子分类，并提供二次确认。
SEO与在线预览
- SEO
- 页面标题、关键词、描述由SEO解析器根据分类与内容动态生成。
- 详情页支持结构化数据（Schema）注入。
- 在线预览
- 详情页以Markdown渲染正文，便于在线查看文档内容。
统计与版本管理
- 访问统计
- 详情页每次访问对click字段+1，用于衡量热度。
- 版本管理
- 当前未内置版本历史功能；可通过扩展模型与审计日志实现版本快照或差异对比。
API参考与扩展指南
- 后台接口（Web表单驱动）
- 列表：GET 下载列表，支持category_id、keyword、page。
- 新增：POST 提交新增，包含正文、主图、自定义字段、草稿令牌。
- 编辑：GET/POST 获取与更新，支持主图替换与正文更新。
- 删除：POST 二次确认后删除。
- 批量：POST action=del_all/category_move。
- 前台接口（路由驱动）
- 列表：GET /download/category/{?category_id}/{year}/{month}/{page}
- 详情：GET /download/{id}/{category_slug}/{slug}
- 扩展点
- 自定义字段：通过defined配置项定义键值对，服务层自动转换为多行文本供编辑。
- 附件策略：通过AttachmentUploadOptions指定上传者、业务字段与主键策略。
- 导航同步：分类可选项同步至导航，便于前端展示。
故障排查
- 新增失败
- 检查表单校验是否通过；确认草稿令牌与管理员ID有效；查看附件上传是否成功。
- 编辑失败
- 确认记录存在；检查XSS清洗与附件替换逻辑；核对字段白名单。
- 删除失败
- 分类删除需无占用且无子分类；下载删除需提供二次确认。
- 列表为空
- 检查分类过滤、归档时间窗、发布状态与排序配置。
结论
下载管理模块以清晰的分层与职责划分，提供了完善的CRUD、分类体系、附件管理、SEO与统计能力。通过服务层集中业务规则与外部协作，模型层专注数据与查询，控制器聚焦交互与视图，整体具备良好的可维护性与扩展性。建议在生产环境中结合缓存、CDN与限流策略进一步优化带宽与性能，并通过审计日志与权限控制保障数据安全。