简介
本开发文档围绕 DouPHP 的“在线支持”模块，系统化说明其作为企业级客服工单系统的技术实现与扩展点。当前仓库中的“支持（support）”模块提供后台内容管理与前台展示能力，具备分类管理、列表分页、详情展示、点击统计、附件处理、Markdown 渲染、多语言字段等特性。基于这些基础能力，可进一步构建完整的工单生命周期：创建、分配、处理、关闭，以及优先级、SLA、满意度评价、数据统计与分析等企业级功能。
项目结构
“在线支持”模块采用前后端分离的职责划分：
- 后台（Admin）：负责支持条目与支持分类的增删改查、批量操作、审计日志记录。
- 前台（Front）：面向用户的支持文章列表与详情展示、SEO、导航、归档与分页。
- 模型（Model）：定义数据表映射、关联、筛选器、排序策略与属性转换。
- 服务（Service）：封装业务逻辑，协调模型、附件、Markdown、审计等基础设施。
- 控制器（Controller）：接收请求、调用服务、组织视图数据并返回响应。
graph TB
subgraph "后台"
AC["Admin SupportController"]
CC["Admin CategoryController"]
ASvc["Admin SupportService"]
AModelS["Admin Support Model"]
AModelC["Admin SupportCategory Model"]
end
subgraph "前台"
FC["Front SupportController"]
FSvc["Front SupportService"]
FModelS["Front Support Model"]
end
AC --> ASvc
CC --> AModelC
ASvc --> AModelS
FC --> FSvc
FSvc --> FModelS
AModelS --> |"category_id"| AModelC核心组件
- 后台支持控制器：提供列表、新增、编辑、更新、删除、批量操作等入口，统一通过表单校验与服务层完成业务。
- 后台分类控制器：提供分类树形结构的增删改查，支撑支持条目的分类管理。
- 前台支持控制器：提供按分类、归档、分页的列表页与详情页，集成 SEO、导航、面包屑与 Schema。
- 后台支持服务：封装列表查询、默认数据构建、新增/更新/删除/批量操作、附件存储、Markdown 渲染、审计日志。
- 前台支持服务：封装列表/详情数据构建、点击量统计、分类信息查询。
- 模型：
- 后台支持模型：定义表名、可写字段、状态语言化、分类关联、关键字过滤、默认排序。
- 后台分类模型：定义分类树、记录表关联、可写字段。
- 前台支持模型：用于发布态查询、详情读取与语言化。
架构总览
整体采用 MVC + Service 的分层架构：
- 控制器仅做参数接收与视图组装，复杂逻辑下沉至服务层。
- 服务层聚合模型、附件、Markdown、审计等能力，保证业务规则集中且可测试。
- 模型层聚焦数据访问、关联、筛选器与格式化。
- 前台与后台共享同一领域概念（支持条目、分类），但职责边界清晰。
sequenceDiagram
participant U as "用户/管理员"
participant AC as "后台支持控制器"
participant AS as "后台支持服务"
participant AM as "后台支持模型"
participant AU as "审计日志"
U->>AC : 提交新增/更新/删除
AC->>AS : 调用 insert/update/delete/action
AS->>AM : 持久化数据
AM-->>AS : 返回结果
AS->>AU : 写入操作日志
AS-->>AC : 返回成功/错误
AC-->>U : 重定向或响应详细组件分析
后台支持控制器
- 列表：支持按分类、关键词、分页查询，注入分类树与页面动作。
- 新增/编辑：准备默认数据、草稿令牌、多语言按钮、Markdown 预览。
- 更新/删除：使用表单校验与异常统一处理，删除支持二次确认。
- 批量操作：支持批量删除与批量转移分类。
flowchart TD
Start(["进入后台支持列表"]) --> Query["按分类/关键词/分页查询"]
Query --> Render["渲染列表视图"]
Render --> Action{"选择操作"}
Action --> |新增| Create["准备默认数据与草稿令牌"]
Action --> |编辑| Edit["加载记录并渲染编辑页"]
Action --> |删除| Del["二次确认后删除并记录日志"]
Action --> |批量| Batch["批量删除或转移分类"]
Create --> Store["调用服务保存并跳转编辑"]
Edit --> Update["调用服务更新并跳转编辑"]
Del --> Done(["完成"])
Batch --> Done
Store --> Done
Update --> Done后台分类控制器
- 列表：展示分类树，支持新增入口。
- 新增/编辑：准备默认数据、多语言按钮、父级分类选择。
- 更新/删除：校验与异常处理，删除时清理关联。
前台支持控制器
- 列表：支持按分类、归档、分页查询，构建 SEO、导航、面包屑与 Schema。
- 详情：读取已发布记录，Markdown 渲染正文，记录点击量，构建分类信息与页面元数据。
sequenceDiagram
participant U as "访客"
participant FC as "前台支持控制器"
participant FS as "前台支持服务"
participant FM as "前台支持模型"
U->>FC : 访问列表/详情
FC->>FS : 构建列表/详情数据
FS->>FM : 查询已发布记录/分类
FM-->>FS : 返回数据
FS-->>FC : 返回列表/详情数组
FC->>FC : 记录点击量(详情)
FC-->>U : 渲染页面后台支持服务
- 列表数据：带分类预加载、关键字过滤、默认排序、分页。
- 新增：XSS 清洗、远程图片本地化、附件上传、草稿认领、审计日志。
- 编辑：Markdown 渲染、附件 URL 生成、时间格式化、自定义字段解析。
- 更新：附件与内容处理、填充更新、审计日志。
- 删除：存在性校验、二次确认、审计日志。
- 批量：批量删除与批量转移分类，审计日志。
classDiagram
class SupportService {
+buildSupportListData(catId, keyword, page) array
+buildSupportDefaultData() array
+insert(data, draftToken, adminId) int
+buildSupportEditData(id) array|null
+update(data, adminId) void
+delete(id, data) array
+action(data) array
}
class Support {
+category() BelongsTo
+scopeFilterByKeyword(query, keyword) Builder
+scopeApplyDefaultOrder(query) Builder
}
SupportService --> Support : "CRUD 与查询"前台支持服务
- 列表：支持分类、归档、分页，构建展示字段与链接。
- 详情：读取已发布记录、语言化、Markdown 渲染。
- 分类查询：按 ID 获取分类信息。
- 点击统计：原子自增点击数。
模型与数据关系
- 支持条目与支持分类为一对多关系（category_id）。
- 支持条目具备状态字段的语言化转换、附件与时间格式化、关键字过滤与默认排序。
- 分类模型支持树形结构与记录表关联。
erDiagram
SUPPORT_CATEGORY {
int id PK
string name
string slug
int parent_id FK
string icon
string keywords
text description
boolean sync_to_nav
int sort
}
SUPPORT {
int id PK
string operator_type
int operator_id
int category_id FK
string title
string slug
text defined
text content
string keywords
text description
int sort
datetime created_at
string image
}
SUPPORT_CATEGORY ||--o{ SUPPORT : "包含"依赖关系分析
- 控制器依赖服务，服务依赖模型与基础设施（附件、Markdown、审计）。
- 前台与后台通过相同领域概念协作，但各自关注不同场景（管理 vs 展示）。
- 模型间通过外键与关联方法建立关系，便于批量预加载与查询优化。
graph LR
AC["后台支持控制器"] --> ASvc["后台支持服务"]
CC["后台分类控制器"] --> AModelC["后台分类模型"]
ASvc --> AModelS["后台支持模型"]
FC["前台支持控制器"] --> FSvc["前台支持服务"]
FSvc --> FModelS["前台支持模型"]
AModelS --> |"category_id"| AModelC性能考虑
- 列表查询使用 with('category') 预加载分类，减少 N+1 查询。
- 使用 field() 限制返回字段，降低数据传输开销。
- 分页查询结合 URL 规范化，避免重复计算。
- 详情点击统计采用原子自增，避免锁竞争。
- Markdown 渲染仅在需要时执行，减少 CPU 消耗。
- 附件 URL 与日期在模型层进行格式化，减少模板层计算。
故障排查指南
- 非法参数：控制器在 ID 无效时抛出领域异常，统一由全局处理器捕获并返回友好提示。
- 记录不存在：服务层在删除/更新前校验记录存在性，缺失时抛出异常。
- 批量操作：未选择项或动作类型不支持时抛出异常，需检查前端传参与后端分支。
- 附件与内容：新增/更新时对内容进行 XSS 清洗与远程图片本地化，确保数据安全；若图片未生效，检查草稿令牌与上传选项。
- 审计日志：所有关键操作均记录审计日志，便于回溯问题。
结论
DouPHP 的“在线支持”模块提供了完善的后台管理与前台展示能力，具备分类管理、列表分页、详情展示、附件处理、Markdown 渲染、多语言字段与审计日志等企业级特性。基于现有架构，可快速扩展为完整的客服工单系统：增加工单状态机、优先级、SLA 监控、自动分配规则、客户满意度评价、数据统计与分析等功能。建议在服务层集中实现业务规则，保持控制器轻量，并通过模型筛选器与关联提升查询性能。
附录
工单生命周期扩展建议（概念性）
- 创建：在前台支持表单中增加工单字段（如产品、订单、问题描述），在后端服务中校验并落库。
- 分配：在服务层根据规则（技能组、负载、优先级）自动分配处理人，并记录分配日志。
- 处理：支持内部备注、外部回复、附件上传、状态流转（待处理→处理中→已解决）。
- 关闭：支持手动关闭与自动关闭（超时未处理），触发 SLA 告警与通知。
- 评价：工单关闭后邀请客户评分与反馈，统计满意度指标。
- 统计：按分类、处理人、时间段统计工单量、平均处理时长、SLA 达成率。