工单管理API | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

graph TB
subgraph "API端"
AR["api/route/work.php"]
AC["api/controller/work/WorkController.php"]
end
subgraph "管理端"
MR["admin/route/work.php"]
MC["admin/controller/work/WorkController.php"]
end
AR --> AC
MR --> MC

核心组件

API工作中心控制器：负责鉴权、权限校验、工作台数据聚合与返回
管理端工作控制器：负责后台工作账号/记录的CRUD与视图渲染
路由层：声明式路由将URL映射到控制器方法

架构总览

下图展示了请求从路由到控制器的基本流程，以及鉴权与权限校验的关键点。

sequenceDiagram
participant C as "客户端"
participant R as "路由层"
participant A as "API控制器"
participant S as "服务层(前端/核心)"
participant Resp as "响应封装"
C->>R : GET /api/?route=work
R->>A : WorkController : : index()
A->>A : 鉴权(auth('api'))
A->>S : getDashboardWorkRow(userId)
S-->>A : 工作台数据
A->>Resp : ApiResponse : : success(...)
Resp-->>C : JSON响应
C->>R : POST /api/?route=work/permission
R->>A : WorkController : : permission()
A->>A : 鉴权 + 参数module
A->>S : checkPermission(module, userId)
S-->>A : 是否允许
A->>Resp : success/fail
Resp-->>C : JSON响应

详细组件分析

API工作中心接口

接口清单
- GET /api/?route=work
  - 功能：获取当前用户的工作中心首页数据
  - 鉴权：需要登录态；未启用用户功能或未登录时返回未授权
  - 权限：若用户无工作台权限，返回禁止访问
  - 返回：标题、工作台数据、跳转链接
- GET /api/?route=work/product
  - 功能：获取工作记录列表（分页）
  - 鉴权：同上
  - 返回：标题、工作记录列表、分页信息、总数
- POST /api/?route=work/permission
  - 功能：校验某模块对当前用户的访问权限
  - 参数：module（字符串）
  - 返回：成功或禁止访问
关键流程
- 鉴权失败：返回未授权
- 无工作台权限：返回禁止访问
- 权限校验失败：返回禁止访问

flowchart TD
Start(["进入控制器"]) --> Auth{"是否已登录且启用用户功能?"}
Auth -- 否 --> Err401["返回未授权"]
Auth -- 是 --> PermCheck{"是否有工作台权限?"}
PermCheck -- 否 --> Err403["返回禁止访问"]
PermCheck -- 是 --> Action{"具体动作"}
Action --> |index| GetDash["获取工作台数据并返回"]
Action --> |product| GetList["获取工作记录列表并返回"]
Action --> |permission| CheckMod["校验模块权限并返回"]

管理端工作账号/记录CRUD

路由：使用资源路由，自动映射 index/create/store/edit/update/destroy
主要行为
- 列表：支持按接收人、用户名、时间范围筛选与分页
- 新增：表单验证后插入并跳转到编辑页
- 编辑：加载数据并渲染表单
- 更新：提交后更新记录
- 删除：根据ID执行删除并返回结果

sequenceDiagram
participant U as "管理员"
participant R as "管理路由"
participant C as "管理控制器"
participant S as "管理服务"
U->>R : GET ?route=work
R->>C : index()
C->>S : buildWorkListData(...)
S-->>C : 列表+分页
C-->>U : 渲染列表页
U->>R : POST ?route=work (store)
R->>C : store()
C->>S : insert(data)
S-->>C : 新ID
C-->>U : 重定向至编辑页

依赖关系分析

API控制器依赖：
- 鉴权：auth('api')
- 配置：Config::get('features.user', false)
- 服务：FrontWorkService、WorkCoreService
- 响应：ApiResponse
管理控制器依赖：
- 表单验证：WorkFormRequest
- 服务：WorkService
- 响应：Response/重定向

graph LR
AR["api/route/work.php"] --> AC["api/controller/work/WorkController.php"]
AC --> FS["FrontWorkService"]
AC --> CS["WorkCoreService"]
AC --> RA["ApiResponse"]
MR["admin/route/work.php"] --> MC["admin/controller/work/WorkController.php"]
MC --> MS["WorkService"]

性能考虑

列表与分页：建议在服务层对查询进行分页与必要索引优化
鉴权与权限：尽量缓存用户权限集合，减少重复计算
响应体：仅返回必要字段，避免大对象传输

故障排查指南

未授权（401）
- 触发条件：未启用用户功能或未登录
- 处理：检查登录态与功能开关
禁止访问（403）
- 触发条件：无工作台权限或模块权限校验失败
- 处理：确认用户角色与模块权限配置
非法参数
- 触发条件：ID为空或无效
- 处理：校验入参并返回明确错误信息

结论

当前仓库提供了工作中心的API与管理端基础能力，可作为工单系统的起点。建议在现有基础上扩展：

工单类型：客服工单、售后工单、投诉工单等
状态流转：创建、分配、处理中、解决、关闭等
评论与附件：图文混排沟通与文件上传
统计报表：工单量、时效、满意度等
升级与转交：复杂工单的协作机制
通知提醒：站内信、邮件、短信等

附录

接口速查
- GET /api/?route=work
- GET /api/?route=work/product
- POST /api/?route=work/permission
- 管理端资源路由：?route=work[/<action>]

添加日期：2026-10-05