简介
本文件面向内容平台开发者，提供“文章管理模块”的完整API参考。覆盖后台管理端与前台展示端的文章CRUD、分类树形管理、富文本处理（图片上传与附件）、搜索筛选、访问统计、权限控制、版本管理与草稿等能力。文档以代码为依据，给出调用流程、数据流转与关键实现要点，并辅以图示帮助理解。
项目结构
围绕文章模块，系统采用前后端分离的职责划分：
- 后台管理端（Admin）：负责文章的增删改查、批量操作、分类管理、富文本与附件处理、审计日志等。
- 前台展示端（Front/API）：负责文章列表、详情、归档、点击统计等只读能力。
- 服务层（Service）：封装业务规则、数据组装、第三方能力（如Markdown渲染、附件存储）。
- 模型层（Model）：承载数据表映射、查询构造、关联与树形能力。
graph TB
subgraph "后台管理端"
A_AdminCtrl["后台控制器<br/>admin/controller/article/*"]
A_Service["后台服务<br/>admin/service/article/*"]
A_Model["后台模型<br/>admin/model/article/*"]
end
subgraph "前台展示端"
F_API["前台控制器<br/>api/controller/article/*"]
F_Service["前台服务<br/>front/service/article/*"]
F_Model["前台模型<br/>front/model/article/*"]
end
A_AdminCtrl --> A_Service --> A_Model
F_API --> F_Service --> F_Model核心组件
- 后台文章控制器：提供文章列表、新增、编辑、删除、批量操作等入口。
- 后台分类控制器：提供分类列表、新增、编辑、删除等入口。
- 后台文章服务：实现文章CRUD、富文本清洗、图片与附件处理、分页列表构建、批量动作、审计日志。
- 后台分类服务：实现分类CRUD、图标模式处理、导航同步、删除保护与清理。
- 前台文章控制器：提供文章列表、详情、归档读取与点击统计。
- 前台文章服务：构建列表/详情数据、Markdown渲染、点击量累加。
- 前台分类模型：提供分类树能力与多语言字段支持。
架构总览
后台管理端通过控制器接收请求，交由服务层执行业务逻辑，服务层协调模型、附件存储、Markdown渲染与审计日志；前台展示端通过API控制器暴露只读能力，服务层负责数据组装与统计更新。
sequenceDiagram
participant Admin as "后台控制器"
participant Asvc as "后台文章服务"
participant Model as "文章模型"
participant Attach as "附件服务"
participant Audit as "审计日志"
Admin->>Asvc : 新增/更新/删除/批量
Asvc->>Attach : 处理正文图片/主图
Asvc->>Model : 持久化数据
Model-->>Asvc : 结果
Asvc->>Audit : 记录操作日志
Asvc-->>Admin : 返回结果详细组件分析
后台文章管理（CRUD与批量）
- 列表：支持按分类、关键词过滤与分页。
- 新增：表单校验通过后，清洗富文本内容，处理远程图片本地化，保存主图，认领草稿附件，写入审计日志。
- 编辑：校验存在性，处理富文本与主图更新，写入审计日志。
- 删除：二次确认机制，删除后写审计日志。
- 批量：支持批量删除与批量转移分类。
flowchart TD
Start(["进入新增/编辑"]) --> Validate["表单校验"]
Validate --> |失败| Err["返回错误提示"]
Validate --> |成功| Clean["清洗富文本内容"]
Clean --> Img{"是否包含远程图片?"}
Img --> |是| Local["将远程图片转存为本地附件"]
Img --> |否| SaveMain["保存主图(如有)"]
Local --> SaveMain
SaveMain --> Persist["持久化到数据库"]
Persist --> Claim["认领草稿附件"]
Claim --> Log["记录审计日志"]
Log --> End(["完成"])后台文章分类管理（树形结构与层级）
- 列表：扁平化分类树用于选择父级。
- 新增/编辑：支持图标模式（文本或图片），可选同步至导航菜单。
- 删除：拦截有子分类或被占用的分类，二次确认后删除，清理语言与导航关联。
classDiagram
class CategoryController {
+index()
+create()
+store()
+edit()
+update()
+destroy()
}
class CategoryService {
+buildCategoryDefaultData()
+insert(data, adminId)
+buildCategoryEditData(catId)
+update(data, adminId)
+delete(catId, data)
}
CategoryController --> CategoryService : "调用"前台文章展示（列表、详情、归档、统计）
- 列表：支持分类、归档（年/月）与分页，返回文章摘要与分类信息。
- 详情：根据ID获取已发布文章，Markdown渲染内容，附带评论列表。
- 统计：详情页访问时累计点击量。
sequenceDiagram
participant Client as "客户端"
participant API as "前台文章控制器"
participant Fsvc as "前台文章服务"
participant Model as "文章模型"
Client->>API : GET /article (列表/详情)
API->>Fsvc : buildArticleListData()/buildArticleShowData()
Fsvc->>Model : 查询已发布文章/分类
Model-->>Fsvc : 数据
Fsvc-->>API : 组装后的数据
API->>Fsvc : recordArticleView(id)
Fsvc->>Model : 点击量+1
API-->>Client : 返回JSON富文本与附件处理
- 富文本清洗：对提交的内容进行XSS清洗。
- 远程图片本地化：在新增/编辑时将远程图片转存为本地附件，便于统一管理与CDN缓存。
- 主图上传：支持上传文章主图，自动关联业务主键与上传者信息。
- 草稿附件：新增时生成草稿令牌，提交后认领附件，避免孤儿文件。
SEO与自定义字段
- SEO字段：标题、关键词、描述在新增/编辑时可配置，便于搜索引擎优化。
- 自定义字段：支持通过配置项定义自定义字段模板，并在表单中展示与提交。
搜索与筛选
- 后台列表：支持按分类ID与关键词过滤，分页返回。
- 前台列表：支持按分类ID、归档（年/月）过滤，分页返回。
权限控制
- 后台操作：所有写操作均要求管理员登录态，并通过审计日志记录操作人。
- 前台只读：仅暴露已发布内容的读取接口，未发布内容不可见。
版本管理与草稿
- 草稿令牌：新增时生成草稿令牌，用于暂存富文本中的远程图片与附件，提交后认领归属。
- 版本管理：当前实现以“最新一次保存”为准；如需历史版本对比，可在现有基础上扩展版本表与回滚逻辑。
依赖关系分析
- 控制器依赖服务：后台/前台控制器分别依赖各自的服务层。
- 服务依赖模型与外部能力：服务层使用模型进行数据存取，依赖Markdown渲染器、附件服务、审计日志等。
- 分类树：前台分类模型具备树形能力，供列表页展示分类树。
graph LR
ACtrl["后台文章控制器"] --> ASvc["后台文章服务"]
CCtrl["后台分类控制器"] --> CSvc["后台分类服务"]
ACtrl --> ASvc
CCtrl --> CSvc
ASvc --> AModel["文章模型"]
CSvc --> CModel["分类模型"]
FCtrl["前台文章控制器"] --> FSvc["前台文章服务"]
FSvc --> FModel["前台文章模型"]
FSvc --> FCat["前台分类模型"]性能考虑
- 分页加载：列表接口默认分页，避免一次性加载大量数据。
- 只读优化：前台仅返回必要字段，减少传输体积。
- Markdown渲染：在服务层集中渲染，避免重复计算。
- 附件处理：远程图片本地化可减少跨域请求与提升缓存命中率。
故障排查指南
- 非法参数：当传入无效ID或缺少必填字段时，会抛出领域异常并返回错误提示。
- 资源不存在：删除或编辑不存在的文章/分类时，会返回相应错误。
- 删除保护：删除分类时若存在子分类或被占用，会阻止删除并提示。
- 审计追踪：所有写操作均记录审计日志，便于问题回溯。
结论
该文章管理模块提供了完整的后台CRUD、分类树管理、富文本与附件处理、搜索筛选、访问统计与权限控制能力。通过清晰的分层设计与服务化封装，既保证了后台管理的灵活性，也确保了前台展示的稳定性与性能。建议在后续迭代中引入版本管理与更细粒度的权限策略，以满足复杂内容平台的运营需求。
附录：接口参考
说明：以下为基于源码实现的接口概览，具体路由前缀与响应格式遵循框架约定。
-
后台文章
- 列表：GET/POST 列表页，支持 category_id、keyword、page
- 新增：POST 提交表单，含 draft_token、content、image 等
- 编辑：GET 获取编辑数据；POST 提交更新
- 删除：POST 二次确认删除
- 批量：POST action=del_all 或 action=category_move
-
后台分类
- 列表：GET 分类树（扁平）
- 新增：POST 提交分类信息，可选 sync_to_nav
- 编辑：GET 获取编辑数据；POST 提交更新
- 删除：POST 二次确认删除
-
前台文章
- 列表：GET 支持 id/category_slug、year、month、page
- 详情：GET 支持 id/category_slug/slug，自动累计点击量
-
富文本与附件
- 新增/编辑时支持 content_remote_image_local 标记，触发远程图片本地化
- 主图上传通过 image 字段提交
-
SEO与自定义字段
- keywords、description 可配置
- defined 自定义字段由配置驱动