简介
本文件面向企业官网与作品集平台开发者，提供“案例展示模块”的完整API参考。内容覆盖案例生命周期管理（录入、编辑、审核、发布）、分类体系（多级分类、标签与专题组织）、多媒体资源处理（图片集、视频嵌入、文件下载）、详情展示（富文本、交互展示、响应式布局）、搜索与推荐（按分类、标签、时间等维度筛选），以及统计与分析（浏览量、用户互动）和模板系统/自定义字段扩展能力。文档严格基于仓库中实际代码实现进行说明，并提供可视化架构图与流程图辅助理解。
项目结构
案例模块在前后端分离的结构下组织：
- 前台API层：负责对外暴露案例列表与详情接口，调用前台服务层组装数据并返回统一响应。
- 后台管理：提供案例与分类的增删改查、批量操作、附件上传、草稿与多语言支持等管理能力。
- 服务层：封装业务逻辑，协调模型、Markdown渲染、附件存储、审计日志等。
- 路由：通过声明式路由将 /api/?route=cases[/<action>] 映射到控制器方法。
graph TB
Client["客户端"] --> API["前台API<br/>CasesController"]
API --> SvcFront["前台服务<br/>CasesService"]
SvcFront --> Model["案例模型<br/>Cases"]
API --> Route["路由注册<br/>cases.php"]
AdminUI["后台管理界面"] --> AdminCtrl["后台控制器<br/>CasesController / CategoryController"]
AdminCtrl --> AdminSvc["后台服务<br/>CasesService / CategoryService"]
AdminSvc --> Model核心组件
- 前台API控制器：提供案例列表与详情两个核心接口，支持分类过滤、归档查询、分页、点击量统计。
- 前台服务：构建列表与详情数据，处理Markdown渲染、分类树、访问统计。
- 后台控制器与服务：提供案例与分类的CRUD、批量操作、附件上传、草稿、多语言、导航同步与审计日志。
- 路由：声明式资源路由，仅暴露 index 与 show 动作。
架构总览
前台API请求经路由分发至 CasesController，再由 CasesService 完成数据组装与业务处理；后台管理通过独立控制器与服务完成案例与分类的全生命周期管理。
sequenceDiagram
participant C as "客户端"
participant R as "路由 cases.php"
participant A as "前台控制器 CasesController"
participant S as "前台服务 CasesService"
participant M as "案例模型 Cases"
C->>R : GET /api/?route=cases/index?category_id=...&page=...
R->>A : 调用 index()
A->>S : buildCasesListData(catId, page, pageSize, archive)
S->>M : with('category')->published()->filterByCategory()->paginate()
M-->>S : 分页结果
S-->>A : 列表数据
A-->>C : 成功响应 {title, category_id, cases_list, cases_category, cate_info}
C->>R : GET /api/?route=cases/show&id=...
R->>A : 调用 show()
A->>S : buildCasesShowData(id)
S->>M : findPublishedById(id)
M-->>S : 案例数据
S-->>A : 详情数据含Markdown渲染后的content
A->>S : recordCasesView(id)
S->>M : updateClick(id)
A-->>C : 成功响应 {cases, comment, defined}详细组件分析
前台案例API（列表与详情）
- 列表接口
- 路径：/api/?route=cases/index
- 功能：按分类或归档获取已发布案例列表，支持分页；返回标题、缩略图、描述、链接、分类信息、分类树等。
- 关键参数：category_id（兼容 id）、page、year/month（归档）。
- 数据来源：前台服务根据分类与归档条件查询模型，附带分类关联，格式化输出。
- 详情接口
- 路径：/api/?route=cases/show&id=...
- 功能：获取案例详情，包含富文本内容（Markdown渲染）、评论列表、自定义字段、URL等；自动记录点击量。
- 数据来源：前台服务查找已发布案例，渲染内容，控制器追加评论与统计数据。
flowchart TD
Start(["进入列表/详情"]) --> Parse["解析参数<br/>分类ID/页码/归档/ID"]
Parse --> Validate{"参数有效?"}
Validate -- 否 --> Err["抛出领域异常"]
Validate -- 是 --> ListOrDetail{"列表还是详情?"}
ListOrDetail -- 列表 --> BuildList["构建列表数据<br/>分页+分类树"]
ListOrDetail -- 详情 --> BuildDetail["构建详情数据<br/>Markdown渲染"]
BuildList --> ReturnList["返回列表响应"]
BuildDetail --> RecordView["记录点击量"]
RecordView --> ReturnDetail["返回详情响应"]后台案例管理（录入、编辑、删除、批量操作）
- 列表：支持按分类、关键词筛选，分页展示。
- 新增/编辑：表单校验由请求对象完成；正文XSS过滤、远程图片本地化、主图上传、草稿令牌、多语言按钮生成。
- 删除：二次确认流程，记录审计日志。
- 批量操作：批量删除、批量转移分类。
sequenceDiagram
participant U as "管理员"
participant AC as "后台控制器 CasesController"
participant AS as "后台服务 CasesService"
participant ATT as "附件服务"
participant AUD as "审计日志"
U->>AC : POST 提交新增/更新
AC->>AS : insert/update(data, adminId)
AS->>ATT : 存储正文图片/主图
ATT-->>AS : 返回附件标识
AS->>AUD : 写入创建/更新日志
AS-->>AC : 返回结果
AC-->>U : 重定向并提示后台案例分类管理（多级分类、图标、导航同步）
- 列表：扁平化分类树，便于选择父级。
- 新增/编辑：支持文本或图片两种图标模式；可同步到导航菜单。
- 删除：检查占用与子分类，二次确认后删除，清理语言与导航关联。
classDiagram
class CategoryController {
+index()
+create()
+store()
+edit()
+update()
+destroy()
}
class CategoryService {
+buildCategoryDefaultData()
+buildCategoryEditData(catId)
+insert(data, adminId)
+update(data, adminId)
+delete(catId, data)
}
CategoryController --> CategoryService : "调用"多媒体内容处理
- 图片集与主图：后台新增/编辑时支持上传主图；正文中的远程图片可本地化存储；分类图标支持文本或图片模式。
- 视频嵌入与文件下载：详情富文本支持嵌入视频与下载链接；媒体资源通过附件服务统一管理，前端通过URL访问。
- 附件策略：使用统一的附件上传选项与存储策略，确保路径安全与可追溯。
案例详情展示（富文本、交互、响应式）
- 富文本：详情内容通过Markdown渲染为HTML，便于编辑器集成与跨端展示。
- 交互：详情页附带评论模块，支持分页加载。
- 响应式：列表与详情均返回结构化数据，前端可按设备自适应布局。
搜索与推荐
- 搜索：后台列表支持关键词筛选；前台列表支持按分类与归档（年/月）筛选。
- 推荐：可通过分类树与排序规则在前端组合出“推荐”视图；具体推荐算法可在服务层扩展。
统计与分析
- 浏览量：每次查看案例详情会记录点击量，并在响应中返回累计值。
- 用户互动：详情页返回评论列表，可用于统计点赞、收藏等互动行为（由评论模块提供）。
模板系统与自定义字段
- 自定义字段：后台新增/编辑表单支持定义的自定义字段（defined），以配置项驱动，支持多行输入与多语言。
- 模板：前台列表与详情返回的数据结构稳定，便于模板引擎渲染；后台模板用于管理界面。
依赖关系分析
- 控制器依赖服务：前台与后台控制器分别依赖对应服务层，保证职责清晰。
- 服务依赖模型与工具：服务层调用模型进行数据查询与更新，使用Markdown渲染器、附件服务、审计日志等。
- 路由解耦：通过声明式路由将API路径映射到控制器方法，便于维护与扩展。
graph LR
Route["路由 cases.php"] --> Ctrl["CasesController"]
Ctrl --> Svc["CasesService"]
Svc --> Model["Cases 模型"]
Svc --> MD["MarkdownRenderer"]
Svc --> ATT["Attachment 服务"]
Ctrl --> Resp["ApiResponse"]性能考虑
- 分页与懒加载：列表接口默认分页，减少首屏数据量；详情按需加载评论。
- 关联预取：列表查询使用 with('category') 避免N+1问题。
- 缓存建议：对分类树与热门案例可引入缓存层以提升读取性能。
- 图片优化：建议使用CDN与缩略图策略，降低带宽消耗。
故障排查指南
- 页面错误：当分类ID无效或案例不存在时，会抛出领域异常并返回统一错误提示。
- 权限与安全：后台操作需登录与权限控制；正文内容经过XSS过滤，附件上传受控。
- 常见问题
- 列表为空：检查分类ID、归档参数与发布状态。
- 详情空白：确认案例是否已发布且存在；检查Markdown内容与附件路径。
- 附件未显示：确认上传是否成功与URL生成是否正确。
结论
该案例展示模块提供了完善的前台API与后台管理能力，覆盖案例全生命周期、分类体系、多媒体处理、详情展示、搜索筛选、统计分析与模板扩展。通过清晰的层次划分与声明式路由，便于企业官网与作品集平台快速集成与定制。
附录：接口清单与数据模型
前台API接口
- 案例列表
- 路径：/api/?route=cases/index
- 方法：GET
- 参数：category_id（或 id）、page、year、month
- 返回：title、category_id、cases_list、cases_category、cate_info
- 案例详情
- 路径：/api/?route=cases/show
- 方法：GET
- 参数：id
- 返回：cases（含 content、click、image、url 等）、comment、defined
后台管理接口（示例）
- 案例列表：GET /admin/cases
- 新增：POST /admin/cases/create -> store
- 编辑：GET /admin/cases/edit?id=...
- 更新：POST /admin/cases/update
- 删除：POST /admin/cases/destroy?id=...
- 批量操作：POST /admin/cases/action
- 分类管理：类似CRUD与同步导航
数据模型概览（概念）
- 案例（Cases）
- 字段：id、title、slug、keywords、description、content、image、sort、status、created_at、click、defined、category_id
- 案例分类（CasesCategory）
- 字段：id、name、slug、icon、parent_id、keywords、description、sync_to_nav、sort