简介

本开发文档面向 DouPHP 小程序“案例”模块的前后台实现，覆盖案例列表页的多媒体展示、分类筛选、分页与归档；案例详情页的图片与视频内容呈现、互动评论、SEO 结构化数据输出。文档同时给出案例数据结构设计、前端视觉效果建议（卡片布局、轮播图、图片放大）、完整开发示例指引（多媒体资源管理、图片画廊组件、视频播放器集成），以及常见问题解决方案（大图片加载优化、视频播放兼容性、移动端触摸手势处理）。

项目结构

案例功能由前台控制器、服务层、模型层、模板层与后台管理共同组成：

• 前台入口：控制器负责路由解析、参数校验、调用服务层组装数据并渲染模板。
• 服务层：封装列表构建、详情构建、点击统计、分类查询等业务逻辑。
• 模型层：定义表映射、关联、查询作用域、附件与多语言格式化、排序等。
• 模板层：默认主题下的案例列表与详情模板，提供基础结构与样式引入。
• 后台管理：提供案例的增删改查与批量操作。

graph TB
A["浏览器/小程序"] --> B["前台控制器<br/>CasesController"]
B --> C["服务层<br/>CasesService"]
C --> D["模型层<br/>Cases"]
D --> E["数据库<br/>cases / cases_category"]
B --> F["模板渲染<br/>cases_category.dwt / cases.dwt"]
B --> G["SEO 结构化数据<br/>SchemaService"]
H["后台管理"] --> I["后台控制器<br/>Admin CasesController"]
I --> C

核心组件

• 前台控制器：处理案例列表/分类/归档与详情请求，组装 SEO、面包屑、导航与视图数据。
• 服务层：构建列表数据（含分页、归档过滤、分类过滤、默认排序）、构建详情数据（Markdown 渲染）、记录点击量、查询分类信息。
• 模型层：声明表名、类型转换、附加字段、可翻译字段、预取器、发布状态过滤、归档过滤、默认排序、主图非空过滤、分类关联。
• 模板层：案例列表采用网格卡片布局，案例详情展示标题、描述、自定义字段、内容与上下篇联动。
• 后台控制器：提供案例列表、新增、编辑、删除、批量操作，支持草稿与附件清理。

架构总览

案例模块遵循“控制器-服务-模型-模板”的分层架构，服务层聚合业务规则，模型层专注数据访问与格式化，模板层仅负责展示。SEO 结构化数据通过统一服务生成，便于搜索引擎理解。

sequenceDiagram
participant U as "用户"
participant C as "前台控制器"
participant S as "服务层"
participant M as "模型层"
participant T as "模板"
participant SEO as "SEO 服务"
U->>C : 访问案例列表/详情
C->>S : 构建列表/详情数据
S->>M : 查询已发布案例/分类/排序
M-->>S : 返回数据(含附件URL/多语言)
S-->>C : 返回视图数据
C->>SEO : 生成结构化数据(JSON-LD)
C->>T : 渲染模板
T-->>U : 展示页面

详细组件分析

案例列表页（分类/归档/分页）

• 路由与参数：支持按分类 id、路径 slug、年/月归档、页码进行查询。
• 数据构建：服务层使用 AR 批量加载分类，应用发布过滤、归档过滤、分类过滤、默认排序后分页。
• 视图数据：包含案例项（id、title、image、description 摘要、url、分类信息等）与分页对象。
• 模板渲染：网格卡片布局，每项显示缩略图与标题，底部包含分页控件。

flowchart TD
Start(["进入列表页"]) --> Parse["解析分类ID/归档/页码"]
Parse --> Query["查询已发布案例<br/>应用归档/分类/排序"]
Query --> BuildList["组装列表数据<br/>截取描述/计算URL/分类信息"]
BuildList --> Render["渲染模板<br/>卡片网格+分页"]
Render --> End(["完成"])

案例详情页（内容/评论/SEO）

• 路由与参数：通过 id 获取详情，支持 slug、分类 slug、年/月归档。
• 数据构建：服务层查找已发布案例，进行多语言与 Markdown 渲染；控制器记录点击量并注入评论数据（若启用）。
• 视图数据：标题、创建时间、点击数、自定义字段、内容、上下篇联动、相关案例。
• SEO：生成结构化数据 JSON-LD，包含标题、描述、封面图、发布时间、作者、发布方与页面标识。

sequenceDiagram
participant U as "用户"
participant C as "前台控制器"
participant S as "服务层"
participant M as "模型层"
participant T as "模板"
participant SEO as "SEO 服务"
U->>C : 访问案例详情(id)
C->>S : 构建详情数据
S->>M : 查找已发布案例
M-->>S : 返回案例模型
S-->>C : 返回详情(含Markdown内容)
C->>C : 记录点击量(+1)
C->>SEO : 生成结构化数据
C->>T : 渲染详情模板
T-->>U : 展示详情页面

后台管理（增删改查与批量）

• 列表：支持按分类与关键词筛选，分页展示。
• 表单：新增/编辑时清理草稿、生成草稿令牌、准备默认数据与多语言按钮。
• 提交：基于表单请求校验，写入或更新数据，成功后重定向并提示。
• 删除/批量：安全校验与结果响应。

依赖关系分析

• 控制器依赖服务层与 SEO 服务，不直接操作数据库。
• 服务层依赖模型层与 Markdown 渲染器，负责数据组装与业务规则。
• 模型层声明表、关联、类型转换、可翻译字段、预取器与查询作用域。
• 模板层依赖 CSS/JS 资源与通用片段（导航、面包屑、分页）。

classDiagram
class CasesController {
+index(request) Response
+show(request) Response
}
class CasesService {
+buildCasesListData(catId, page, pageSize, archive) array
+buildCasesShowData(id) array|null
+recordCasesView(id) int|false
+findCategoryById(catId) array|false
}
class Cases {
+category() Relation
+scopePublished(query) Builder
+scopeFilterByArchive(query, archive) Builder
+scopeApplyDefaultOrder(query) Builder
+moduleSchema() array
}
class SchemaService {
+generic(module, data, cate_info) string
}
CasesController --> CasesService : "调用"
CasesService --> Cases : "查询/格式化"
CasesController --> SchemaService : "生成JSON-LD"

性能与体验优化

• 列表性能
  • 使用 AR with('category') 批量加载分类，避免 N+1 查询。
  • 使用分页与默认排序，减少单次数据量。
  • 描述文本截断，降低传输体积。
• 图片优化
  • 列表缩略图固定宽高，配合懒加载与占位图提升首屏速度。
  • 详情大图建议使用响应式尺寸与 CDN，开启缓存与压缩。
• 视频体验
  • 优先使用 HTML5 video 标签，提供多格式源以兼容不同浏览器。
  • 移动端考虑自动静音播放与触摸手势控制。
• 交互增强
  • 图片画廊：支持点击放大、左右切换、缩放查看。
  • 轮播图：在列表顶部或详情首图区域使用轻量轮播组件。
  • 评论：分页加载评论，避免首屏过重。
• SEO 优化
  • 设置 meta keywords/description，生成结构化数据 JSON-LD。
  • 为案例详情页提供 canonical 与 open graph 标签（可在模板中扩展）。

故障排查指南

• 列表为空或无数据
  • 检查是否仅查询已发布状态（status=1）。
  • 确认分类过滤与归档过滤条件是否正确。
  • 验证分页参数与每页数量配置。
• 详情无法打开
  • 检查路由 id 是否有效，服务层是否返回 null。
  • 确认 Markdown 渲染是否成功，内容是否为空。
• 点击量未增加
  • 确认控制器是否调用记录点击量方法。
  • 检查数据库写入是否成功。
• 模板变量缺失
  • 核对控制器传入的视图数据键名是否与模板一致。
  • 检查分类树与分页片段是否包含。
• 后台表单校验失败
  • 查看表单请求规则与白名单，确保字段名称与类型正确。
  • 草稿令牌与附件清理流程是否正常执行。

结论

案例模块通过清晰的分层架构实现了列表与详情的完整能力，结合服务层的业务封装与模型层的格式化能力，提供了良好的可扩展性与维护性。模板层提供基础展示结构，可通过样式与组件进一步增强多媒体体验。SEO 结构化数据输出有助于搜索引擎收录与展示。建议在现有基础上按需扩展图片画廊、视频播放器与评论组件，以满足更丰富的展示与互动需求。

附录：字段与模板参考

案例数据结构（基于模型与服务）

• 基础字段
  • id：主键
  • category_id：分类外键
  • title：标题（可翻译）
  • content：内容（Markdown，可翻译）
  • description：描述（可翻译）
  • image：主图（附件类型，自动转为 URL）
  • defined：自定义字段对（键值对）
  • created_at：创建时间（格式化）
  • click：点击量
• 派生字段（appends/accessor）
  • add_time_short：短日期
  • time：时间字符串
  • name：分类名称
  • description：描述摘要（列表页截断）
  • url：详情链接
  • favorites：收藏状态（由 concerns 提供）
  • cate_info：分类信息（id、name、url）
• 查询与作用域
  • published：仅已发布
  • filterByArchive：按年/月归档过滤
  • applyDefaultOrder：默认排序（sort ASC, id DESC）
  • imageNotEmpty：仅含主图的列表项

模板变量与渲染要点

• 列表模板（cases_category.dwt）
  • 变量：cases_list、pager、cases_tree、ur_here
  • 渲染：网格卡片，每项包含缩略图与标题，底部分页
• 详情模板（cases.dwt）
  • 变量：cases.title、cases.created_at、cases.click、cases.defined、cases.content、lift.previous/next
  • 渲染：标题、时间与点击数、自定义字段列表、内容区、上下篇联动

数据库表结构参考

• 表：cases
  • 字段：id、category_id、title、content、description、image、defined、created_at、click、status、sort 等（以备份脚本为准）
• 表：cases_category
  • 字段：id、parent_id、name、slug、keywords、description、sort 等（以系统表结构为准）