简介
本模块面向小程序与前端站点的内容管理页面，覆盖文章展示、案例展示、视频播放、文件下载四大类内容。文档聚焦以下目标：
- 列表页的分类筛选、归档与分页；搜索关键词回填与校验
- 详情页的富文本渲染、图片处理、多媒体资源呈现
- 视频播放器的控制与进度管理（前端集成建议）
- 下载文件的权限控制与进度显示（前后端协作方案）
- 数据结构设计：内容字段、多媒体资源、分类标签体系
- SEO 优化与用户体验提升：图片压缩、视频预加载、离线缓存等
- 常见问题：大文件下载优化、视频兼容性、富文本安全过滤
项目结构
内容管理相关的前台控制器与服务层采用“控制器负责路由与视图数据组装，服务层负责业务逻辑与数据格式化”的分层组织方式。每个内容类型均包含：
- 控制器：接收请求、解析路由参数、调用服务、组装视图数据、生成 SEO 信息
- 服务：构建列表/详情数据、统计点击量、Markdown 渲染、分类信息查询
- 模型（由服务间接调用）：查询、关联、分页、排序、过滤
graph TB
subgraph "前台控制器"
AC["ArticleController"]
VC["VideoController"]
DC["DownloadController"]
CC["CasesController"]
end
subgraph "前台服务"
AS["ArticleService"]
VS["VideoService"]
DS["DownloadService"]
CS["CasesService"]
end
subgraph "通用能力"
RB["路由与分页<br/>RouteId/Config"]
SEO["SEO与面包屑<br/>SeoResolver/BreadcrumbBuilder"]
MD["富文本渲染<br/>MarkdownRenderer"]
end
AC --> AS
VC --> VS
DC --> DS
CC --> CS
AS --> MD
VS --> MD
DS --> MD
CS --> MD
AC -.-> SEO
VC -.-> SEO
DC -.-> SEO
CC -.-> SEO
AC -.-> RB
VC -.-> RB
DC -.-> RB
CC -.-> RB核心组件
- 文章模块：列表/分类/归档、详情富文本渲染、评论扩展、SEO 结构化数据
- 视频模块：列表/分类/归档、详情媒体信息与格式识别、点击统计
- 下载模块：列表/分类/归档、详情描述与链接、点击统计
- 案例模块：列表/分类/归档、详情富文本渲染、评论扩展、SEO 结构化数据
各模块统一提供：
- 分页与归档：通过配置项 pagination.* 控制每页数量；支持按年/月归档
- 分类树：tree() 方法用于侧边导航
- 推荐/置顶：lift() 与 related() 用于顶部推荐与相关推荐
- SEO：标题、关键词、描述、面包屑、Schema 结构化数据
架构总览
以“文章”为例的请求流程如下：
sequenceDiagram
participant U as "用户/小程序"
participant C as "ArticleController"
participant S as "ArticleService"
participant M as "Model(Article)"
participant V as "视图(article.dwt)"
U->>C : GET /article/{id}
C->>C : 解析路由ID/归档
C->>S : buildArticleShowData(id)
S->>M : findPublishedById(id)
M-->>S : 文章数据(含多语言/附件URL)
S->>S : MarkdownRenderer.toHtml(content)
S-->>C : 文章数据
C->>C : recordArticleView(id)
C->>C : 组装SEO/面包屑/导航
C-->>V : 渲染 article.dwt
V-->>U : HTML页面详细组件分析
文章模块
- 列表/分类/归档
- 支持按分类 ID、年/月归档、分页；分页大小来自配置
- 返回精简字段：标题、摘要、缩略图、时间、点击量、分类信息等
- 详情
- 使用 Markdown 渲染正文，便于富文本编辑与展示
- 访问统计 +1，并注入 SEO 结构化数据
- 可选评论模块集成
- 搜索
- 列表页支持全站搜索关键词 q 的回填与合法性校验
flowchart TD
Start(["进入文章列表"]) --> Parse["解析分类/归档/分页参数"]
Parse --> Query["查询已发布文章<br/>应用分类/归档/排序"]
Query --> BuildList["构造列表数据<br/>截取摘要/生成URL"]
BuildList --> Render["渲染列表模板"]
Render --> End(["完成"])视频模块
- 列表/分类/归档
- 与文章类似，额外携带媒体文件路径与格式识别
- 详情
- 自动补全绝对地址，识别文件格式；Markdown 渲染正文
- 统计点击量，注入 SEO 结构化数据
sequenceDiagram
participant U as "用户/小程序"
participant C as "VideoController"
participant S as "VideoService"
participant M as "Model(Video)"
participant V as "视图(video.dwt)"
U->>C : GET /video/{id}
C->>S : buildVideoShowData(id)
S->>M : findPublishedById(id)
M-->>S : 视频数据(含file/image)
S->>S : 补全URL/识别format/Markdown渲染
S-->>C : 视频数据
C->>C : recordVideoView(id)
C-->>V : 渲染 video.dwt下载模块
- 列表/分类/归档
- 返回下载链接、文件大小等元信息
- 详情
- Markdown 渲染正文，统计点击量
- 下载入口由模板或前端逻辑触发
flowchart TD
A["进入下载列表"] --> B["解析分类/归档/分页"]
B --> C["查询下载条目"]
C --> D["构造列表数据<br/>download_link/size"]
D --> E["渲染模板"]
E --> F{"用户点击下载?"}
F -- 否 --> G["结束"]
F -- 是 --> H["跳转/发起下载"]
H --> I["记录点击+1"]
I --> G案例模块
- 列表/分类/归档
- 兼容小程序传参 category_id 与路由 id
- 详情
- Markdown 渲染正文，统计点击量，可选评论模块
sequenceDiagram
participant U as "用户/小程序"
participant C as "CasesController"
participant S as "CasesService"
participant M as "Model(Cases)"
participant V as "视图(cases.dwt)"
U->>C : GET /cases/{id}
C->>S : buildCasesShowData(id)
S->>M : findPublishedById(id)
M-->>S : 案例数据
S->>S : Markdown渲染/多语言
S-->>C : 案例数据
C->>C : recordCasesView(id)
C-->>V : 渲染 cases.dwt依赖关系分析
- 控制器依赖服务进行数据准备，服务依赖模型执行查询与格式化
- 富文本渲染统一通过 MarkdownRenderer，确保一致性与安全性
- SEO 能力由 SeoResolver、BreadcrumbBuilder、SchemaService 提供
- 路由与分页由 RouteId、Config 统一管理，保证 URL 规范与可配置性
classDiagram
class ArticleController {
+index(request) Response
+show(request) Response
}
class VideoController {
+index(request) Response
+show(request) Response
}
class DownloadController {
+index(request) Response
+show(request) Response
}
class CasesController {
+index(request) Response
+show(request) Response
}
class ArticleService {
+buildArticleListData(...)
+buildArticleShowData(id)
+recordArticleView(id)
}
class VideoService {
+buildVideoListData(...)
+buildVideoShowData(id)
+recordVideoView(id)
}
class DownloadService {
+buildDownloadListData(...)
+buildDownloadShowData(id)
+recordDownloadView(id)
}
class CasesService {
+buildCasesListData(...)
+buildCasesShowData(id)
+recordCasesView(id)
}
ArticleController --> ArticleService
VideoController --> VideoService
DownloadController --> DownloadService
CasesController --> CasesService性能与体验优化
- 图片优化
- 列表页仅输出缩略图与摘要，避免大图阻塞首屏
- 建议启用 CDN 与 WebP/AVIF 格式，按需懒加载
- 视频优化
- 列表页仅展示封面与时长，详情再加载播放器
- 使用 HLS/m3u8 自适应码率；开启预加载策略与断点续播
- 移动端优先使用原生播放器或轻量级封装，减少 JS 开销
- 下载优化
- 大文件建议使用分片下载与断点续传；服务端支持 Range 请求
- 对敏感文件增加鉴权与防盗链；限制并发与速率
- 富文本与安全
- 后端统一通过 Markdown 渲染，避免直接渲染不可信 HTML
- 如需 HTML 输入，应做白名单过滤与 XSS 防护
- 缓存与离线
- 列表与详情可结合浏览器缓存与 Service Worker 实现离线缓存
- 静态资源（CSS/JS/图片）启用强缓存与版本化
故障排查指南
- 列表为空或分页异常
- 检查分类 ID、归档参数是否有效；确认状态为已发布
- 核对分页配置与数据库索引
- 详情页无法打开
- 确认路由 ID 解析正确；检查是否存在对应记录
- 查看服务返回是否为空，定位模型查询条件
- 富文本显示异常
- 检查 Markdown 渲染是否成功；确认内容字段存在且非空
- 如引入 HTML，需确认过滤规则与安全策略
- 视频无法播放
- 检查文件路径是否补全为绝对地址；确认格式与编码兼容
- 在移动端测试不同浏览器与系统版本
- 下载失败或权限问题
- 确认下载链接有效性；检查服务器权限与防盗链策略
- 对受限资源增加登录态校验与签名
结论
该模块以清晰的分层架构实现了文章、案例、视频、下载四类内容的统一管理与展示。通过服务层的数据组装与 Markdown 渲染，保证了内容的一致性与安全性；通过 SEO 与结构化数据增强搜索引擎友好度。建议在小程序与前端侧配合实现富交互体验（视频播放器、下载进度、图片懒加载），并结合缓存与 CDN 提升性能。
附录：开发示例与最佳实践
文章列表与搜索回填
- 列表页从服务获取分页数据，模板中渲染标题、摘要、缩略图、分类与时间
- 搜索关键词 q 经校验后回填到搜索框，避免非法字符
文章详情富文本渲染
- 服务层将 content 通过 Markdown 渲染为 HTML，模板直接输出
- 若需自定义样式，可在模板中对渲染结果进行 CSS 适配
视频播放器集成与进度管理
- 详情页由服务返回 file 与 format，前端根据格式选择播放器
- 建议实现：
- 封面懒加载与预加载下一集
- 播放进度本地存储，恢复上次位置
- 错误重试与网络状态监听
下载文件权限控制与进度显示
- 列表与详情提供 download_link 与 size，前端发起下载
- 权限控制建议：
- 登录态校验与角色/权限判断
- 临时令牌或签名 URL 防共享
- 进度显示建议：
- 使用 fetch/stream 或 XMLHttpRequest 监听 progress
- 支持断点续传与分片下载
案例展示的多媒体内容与互动
- 详情富文本可嵌入图片、视频等多媒体内容
- 可选评论模块集成，提升互动性
SEO 与结构化数据
- 控制器统一设置 page_title、keywords、description
- 通过 SchemaService 注入结构化数据，提升搜索引擎收录质量