简介
本文件为下载中心模块的API参考文档，面向资源分享平台与知识库系统的开发者。基于仓库中已实现的下载模块，文档覆盖以下能力边界：
- 文件管理：列表、详情、后台新增/编辑/删除/批量操作（含附件上传、内容处理）。
- 分类管理：多级分类树、图标/名称/描述等字段、可选同步到导航。
- 预览与缩略图：通过附件系统生成URL；缩略图由附件系统负责。
- 权限与计费：当前实现未内置“积分/会员/限时”等付费逻辑，可通过自定义扩展点接入。
- 搜索与筛选：支持按分类、关键字、分页、归档时间筛选。
- 统计与分析：记录点击量；可扩展埋点用于行为分析。
- 安全与存储：XSS过滤、附件上传、可配置存储后端（由附件系统提供）。
说明：
- 本文所有接口定义均基于仓库实际代码；未实现的能力以“可扩展”方式给出建议方案，不虚构现有接口。
项目结构
下载中心模块采用前后端分离的控制器+服务层+模型层组织方式：
- API层：对外暴露REST风格接口（列表、详情）。
- 前台层：渲染页面、SEO、面包屑、导航。
- 后台层：管理CRUD、批量操作、日志审计。
- 服务层：封装业务规则、数据组装、附件处理、统计记录。
- 模型层：ORM映射、查询作用域、关联关系。
graph TB
Client["客户端"] --> API["API 控制器<br/>DownloadController"]
API --> Svc["前台服务<br/>DownloadService"]
Svc --> ModelD["模型 Download"]
Svc --> ModelC["模型 DownloadCategory"]
Admin["后台控制器"] --> AdminSvc["后台服务"]
AdminSvc --> ModelD
AdminSvc --> ModelC
ModelD --> DB["数据库"]
ModelC --> DB核心组件
- API控制器：提供下载列表与详情接口，复用前台服务进行数据构建与统计。
- 前台控制器：负责页面渲染、SEO、导航、面包屑、归档解析。
- 后台控制器与服务：完成下载的增删改查、批量操作、附件上传、内容清洗、审计日志。
- 分类控制器与服务：维护多级分类树、图标、排序、导航同步。
- 模型：定义表结构、关联、查询作用域、默认排序、附件URL转换。
架构总览
下载中心遵循“控制器→服务→模型”的分层架构，API与前台共享服务层能力，后台提供管理功能。
sequenceDiagram
participant C as "客户端"
participant A as "API控制器"
participant S as "前台服务"
participant M as "模型"
C->>A : GET /api/?route=download (列表)
A->>S : buildDownloadListData(...)
S->>M : 查询下载列表(分类/分页/归档)
M-->>S : 列表数据
S-->>A : 组装结果
A-->>C : JSON响应
C->>A : GET /api/?route=download/{id} (详情)
A->>S : buildDownloadShowData(id)
S->>M : 查询详情
M-->>S : 详情数据
S->>S : recordDownloadView(id)
S-->>A : 详情数据(+点击计数)
A-->>C : JSON响应详细组件分析
API接口：下载列表
- 路径：GET /api/?route=download
- 查询参数
- id/category_slug：分类ID或分类别名（二选一）
- year/month：归档年份/月份
- page：页码
- 返回字段（摘要）
- title：页面标题
- category_id：分类ID
- download_list：下载条目数组
- download_category：分类树
- cate_info：分类信息（名称、关键词、描述、URL）
- 行为
- 根据分类或归档条件构建列表
- 使用配置的每页条数进行分页
- 返回分类树以便前端展示
API接口：下载详情
- 路径：GET /api/?route=download/{id}
- 路径参数
- id：下载项ID（也支持slug/category_slug组合）
- 返回字段（摘要）
- title：详情页标题
- download：下载详情对象
- defined：自定义字段集合
- cate_info：所属分类信息
- 行为
- 校验ID有效性
- 获取详情并自增点击量
- 返回详情数据
前台页面：列表与详情
- 列表页
- 支持分类、归档、分页
- 输出SEO标题、关键词、描述
- 输出导航、面包屑、分类树
- 详情页
- 读取详情并自增点击
- 输出SEO、导航、面包屑、推荐内容
后台管理：下载项CRUD
- 列表
- 支持按分类、关键字、分页查询
- 展示图片、大小、状态、创建时间
- 新增/编辑
- 表单校验在请求层完成
- 内容XSS过滤，远程图片本地化
- 主图上传与更新
- 自定义字段模板加载
- 删除
- 二次确认机制
- 审计日志记录
- 批量操作
- 批量删除
- 批量转移分类
flowchart TD
Start(["进入后台下载列表"]) --> Filter["选择分类/输入关键字/翻页"]
Filter --> Query["查询下载列表"]
Query --> Render["渲染表格与分页"]
Render --> Action{"执行操作?"}
Action --> |新增/编辑| Form["表单提交(校验/XSS/附件)"]
Form --> Save["持久化并记录日志"]
Action --> |删除| Confirm["二次确认"]
Confirm --> Del["删除并记录日志"]
Action --> |批量| Batch["批量删除/转移分类"]
Batch --> Save
Save --> End(["完成"])
Del --> End后台管理：分类CRUD
- 列表：扁平分类树
- 新增/编辑：支持文本或图片图标模式、排序、是否同步到导航
- 删除：检查占用与子分类，二次确认后删除，清理语言与导航数据
classDiagram
class CategoryService {
+buildCategoryDefaultData()
+insert(data, adminId) int
+update(data, adminId) void
+delete(catId, data) array
}
class DownloadCategory {
+flat()
+tree(parentId)
+hasRecords(catId) bool
+hasChildCategory(catId) bool
}
CategoryService --> DownloadCategory : "读写分类"数据模型与关系
- 下载项模型：包含标题、别名、自定义字段、内容、关键词、描述、排序、创建时间、图片、下载链接、大小等字段；支持分类关联、关键字过滤、默认排序。
- 分类模型：支持多级树、扁平列表、记录占用与子分类检查。
erDiagram
DOWNLOAD {
int id PK
int category_id FK
string title
string slug
text content
string keywords
text description
int sort
datetime created_at
string image
string download_link
string size
}
DOWNLOAD_CATEGORY {
int id PK
int parent_id
string name
string slug
string icon
string keywords
text description
int sync_to_nav
int sort
}
DOWNLOAD_CATEGORY ||--o{ DOWNLOAD : "category_id"依赖关系分析
- API控制器依赖前台服务进行数据构建与统计。
- 前台控制器依赖服务、导航、面包屑、SEO、Schema服务。
- 后台控制器依赖后台服务进行CRUD与批量操作。
- 服务层依赖模型进行数据访问，依赖附件系统进行文件上传与URL生成。
- 模型层通过ORM关联分类，提供查询作用域与默认排序。
graph LR
API["API控制器"] --> FS["前台服务"]
FS --> MD["模型 Download"]
FS --> MC["模型 DownloadCategory"]
Admin["后台控制器"] --> AS["后台服务"]
AS --> MD
AS --> MC
MD --> DB["数据库"]
MC --> DB性能与扩展性
- 列表分页：默认每页条数可配置，减少单次响应体积。
- 附件URL预取：模型层对图片字段进行批量预热，降低N+1查询开销。
- 排序策略：支持手动排序开关，优化列表展示顺序。
- 可扩展点
- 权限与计费：可在服务层插入鉴权与计费逻辑（如积分、会员、限时），在详情与下载前拦截。
- 格式转换与预览：可在附件系统中集成在线预览与缩略图生成。
- 病毒扫描：可在上传流程中接入第三方扫描服务，阻断恶意文件。
- 统计埋点：在详情访问时追加用户行为事件，便于后续分析。
故障排查指南
- 页面错误：当分类或详情ID无效时，会抛出领域异常并重定向至首页或返回列表。
- 非法参数：后台新增/编辑/删除时若缺少必要参数，将抛出非法操作异常。
- 删除保护：删除分类时会检查是否存在子分类或被引用，阻止误删。
- 审计日志：所有关键操作（新增、更新、删除、批量）均记录管理员操作日志，便于追溯。
结论
下载中心模块提供了完整的下载项与分类管理能力，具备列表/详情API、后台CRUD、批量操作、附件上传、SEO与导航集成等能力。对于权限控制、计费、预览、病毒扫描、统计等高级能力，建议在服务层与附件系统中扩展实现，以满足不同业务场景需求。
附录：接口清单
- 下载列表
- 方法：GET
- 路径：/api/?route=download
- 参数：id/category_slug、year、month、page
- 返回：title、category_id、download_list、download_category、cate_info
- 下载详情
- 方法：GET
- 路径：/api/?route=download/{id}
- 返回：title、download、defined、cate_info
- 后台下载管理（Web）
- 列表：GET /?route=download
- 新增：GET/POST /?route=download/create
- 编辑：GET/POST /?route=download/edit?id={id}
- 删除：POST /?route=download/destroy?id={id}&confirm=1
- 批量：POST /?route=download&action=del_all|category_move
- 后台分类管理（Web）
- 列表：GET /?route=download/category
- 新增：GET/POST /?route=download/category/create
- 编辑：GET/POST /?route=download/category/edit?id={id}
- 删除：POST /?route=download/category/destroy?id={id}&confirm=1