简介

本文件面向 DouPHP 小程序“客户支持”功能的开发文档，聚焦于支持系统的完整实现与扩展能力。内容涵盖：

• 工单（技术支持）的创建、分类管理、列表与详情展示
• 状态机与生命周期管理（参考售后状态机设计）
• 优先级排序与分类处理机制
• 用户体验优化：实时更新、进度可视化、多端同步
• 开发示例：模板配置、自动化规则、通知机制
• 常见问题：状态同步、权限控制、数据一致性

说明：当前仓库中“支持系统”以“技术支持（support）”模块为核心，提供后台管理与前台 API；同时项目中存在成熟的“售后状态机”实现，可作为工单状态流转与自动化的参考范式。

项目结构

支持系统涉及的管理端、API 端、服务层与模型层如下：

• 管理端控制器：负责后台列表、新增、编辑、删除、批量操作
• API 控制器：对外暴露支持列表、详情等接口，供小程序调用
• 服务层：封装查询、格式化、统计等业务逻辑
• 模型层：ORM 实体定义、字段映射、发布态过滤、多语言与附件处理

graph TB
subgraph "管理端"
AC["Admin SupportController"]
CC["Admin CategoryController"]
end
subgraph "API端"
API_SC["Api SupportController"]
end
subgraph "服务层"
FS["Front SupportService"]
end
subgraph "模型层"
M_SUP["Model Support"]
end
AC --> FS
CC --> FS
API_SC --> FS
FS --> M_SUP

核心组件

• 管理端支持控制器：提供列表、新增、编辑、删除、批量操作，表单校验由 Request 完成，业务规则在 Service 中处理，统一异常输出
• 管理端分类控制器：支持支持分类的增删改查，扁平树形数据用于前端选择
• API 支持控制器：提供支持列表、详情接口，支持按分类、归档筛选，返回分页与分类信息
• 前台支持服务：构建列表/详情数据，Markdown 渲染内容，点击量统计，分类信息查询
• 支持模型：声明表名、字段类型转换、可翻译字段、预取器、发布态过滤、模块 schema

架构总览

支持系统采用分层架构：控制器负责请求路由与响应组装，服务层封装业务逻辑，模型层负责数据访问与实体映射。通过 ORM 的 with 预加载、published 过滤、filterByCategory/filterByArchive 条件组合，实现高效的数据查询与展示。

sequenceDiagram
participant Client as "小程序客户端"
participant ApiCtrl as "Api SupportController"
participant Svc as "Front SupportService"
participant Model as "Model Support"
Client->>ApiCtrl : GET /api/support (category_id, page)
ApiCtrl->>Svc : buildSupportListData(catId, page, pageSize, archive)
Svc->>Model : published()->filterByCategory()->filterByArchive()->applyDefaultOrder()
Model-->>Svc : 分页结果(含关联分类)
Svc-->>ApiCtrl : 列表数据+分页
ApiCtrl-->>Client : JSON{title, category_id, support_list, support_category, cate_info}

详细组件分析

管理端支持控制器

职责：

• 列表：按分类、关键词、页码查询并渲染
• 新增/编辑：表单校验后调用 Service 插入/更新，支持草稿 token
• 删除/批量：调用 Service 执行删除或批量动作，返回统一结果

关键点：

• 使用 SupportFormRequest 进行字段白名单与校验
• 统一 DomainException 捕获与消息输出
• 草稿机制：清理旧草稿并生成新 token，便于富文本编辑

管理端分类控制器

职责：

• 分类列表：扁平树形数据
• 新增/编辑/删除：表单校验后调用 CategoryService 处理
• 语言按钮：支持多语言字段的快速切换

关键点：

• 使用 CategoryFormRequest 进行校验
• 错误统一抛出 DomainException，入口全局处理

API 支持控制器

职责：

• 列表：支持分类、归档、分页
• 详情：获取详情并记录点击量

关键点：

• 使用 RouteId 解析分类与 slug
• 返回结构化 payload，包含标题、分类信息与列表数据

前台支持服务

职责：

• 列表数据构建：应用 published 过滤、分类过滤、归档过滤、默认排序、分页
• 详情数据构建：查找已发布条目，多语言字段覆写，Markdown 渲染
• 点击量统计：原子递增 click 字段
• 分类查询：按 id 查询分类信息

关键点：

• 使用 ORM 链式查询提升可读性与性能
• 字符串摘要截取，减少传输体积

支持模型

职责：

• 声明表名、字段类型转换、可翻译字段、预取器
• 模块 schema：声明 hasStatus、publishedValue、export 能力
• 辅助方法：findPublishedById、published 过滤、URL 构建等

关键点：

• casts 确保类型安全
• prefetchers 批量预热 URL、语言、附件
• moduleSchema 为 Reader/导出等读层提供能力开关

工单状态机与生命周期（参考售后状态机）

虽然当前支持模块未直接实现状态机，但项目中的售后状态机提供了成熟的状态迁移、乐观锁、超时自动流转与协商时间线记录模式，可作为工单状态管理的参考实现。

关键设计：

• 状态字符串枚举 + 表驱动迁移校验
• 乐观锁：并发冲突时拒绝迁移
• 每次迁移写入日志行，形成协商时间线
• 进入待办态时设置过期时间，供定时任务扫描自动流转

flowchart TD
Start(["进入状态"]) --> CheckTimeout{"是否到达超时阈值?"}
CheckTimeout --> |是| AutoFlow["自动流转至下一状态"]
CheckTimeout --> |否| ManualTransit["人工触发状态迁移"]
ManualTransit --> Validate["校验迁移合法性"]
Validate --> |合法| ApplyLock["乐观锁更新版本"]
ApplyLock --> WriteLog["写入协商时间线"]
WriteLog --> NextState["进入下一状态"]
AutoFlow --> NextState
NextState --> End(["结束"])

依赖关系分析

• 控制器依赖服务：管理端与 API 端均通过各自控制器调用服务层，解耦业务逻辑
• 服务依赖模型：服务层使用 ORM 进行查询与格式化，模型提供发布态过滤与多语言支持
• 外部依赖：Markdown 渲染器用于内容格式化；配置项控制分页大小

graph LR
AdminSC["Admin SupportController"] --> FS["Front SupportService"]
AdminCC["Admin CategoryController"] --> FS
ApiSC["Api SupportController"] --> FS
FS --> MSup["Model Support"]
FS --> MD["MarkdownRenderer"]

性能考虑

• 使用 ORM 的 with 预加载关联数据，减少 N+1 查询
• 应用 published 过滤与分类/归档条件，缩小查询范围
• 字符串摘要截取，降低响应体大小
• 分页查询，避免一次性加载大量数据
• 点击量统计使用原子递增，减少锁竞争

故障排查指南

• 页面不存在：API 控制器在分类或详情 ID 无效时抛出 DomainException，检查路由参数与数据是否存在
• 列表为空：确认分类过滤、归档条件与 published 状态是否正确
• 详情内容空白：检查 Markdown 渲染与多语言字段是否配置
• 点击量未增加：确认 recordSupportView 调用与数据库字段类型正确

结论

DouPHP 的支持系统以清晰的分层架构为基础，提供后台管理与前台 API 的完整能力。通过 ORM 的灵活查询与格式化、Markdown 渲染与多语言支持，满足小程序端的展示需求。结合售后状态机的设计范式，可进一步扩展工单状态流转、自动化处理与通知机制，提升客户支持体验与效率。

附录

• 工单模板配置：可在后台支持编辑器中配置标题、内容、关键词、描述等多语言字段，并通过 Markdown 渲染呈现
• 自动化处理规则：参考售后状态机，为支持工单引入状态迁移、超时自动流转与协商时间线
• 通知机制实现：可在状态迁移或服务层中集成邮件、短信或站内信通知，确保用户及时获知工单进展
• 多端同步：通过 API 返回统一数据结构，小程序与 Web 端均可复用同一套数据源，保证一致性