简介
本文件面向企业用户与管理员，系统化梳理“工作中心”模块的API能力，覆盖工作台首页、工作记录列表、权限校验等对外接口；同时提供后台工作人员（员工）管理的CRUD流程说明。文档聚焦以下目标：
- 工作分配、任务审批、完成确认等业务流在系统中的入口与数据流转
- 进度跟踪与状态更新的数据来源与展示方式
- 工作数据统计与报表能力的接入点
- 权限控制模型（查看、编辑、审批）
- 通知、提醒、协作等扩展点的说明与建议
项目结构
工作相关能力由“前台/小程序端API”、“后台管理端”、“核心服务”三层组成：
- API层：暴露工作中心对外接口（工作台首页、工作记录、权限校验）
- 后台管理端：提供工作人员（员工）账号的增删改查与权限配置
- 核心服务：封装权限判断、导航树构建、通用逻辑复用
graph TB
subgraph "API端"
A["api/controller/work/WorkController"]
R1["api/route/work.php"]
end
subgraph "后台管理端"
B["admin/controller/work/WorkController"]
R2["admin/route/work.php"]
Q["admin/request/work/WorkFormRequest"]
end
subgraph "核心服务"
S1["core/service/work/WorkService"]
S2["admin/service/work/WorkService"]
S3["front/service/work/WorkService"]
end
R1 --> A
R2 --> B
A --> S3
A --> S1
B --> S2
S2 --> S1
S3 --> S1图示来源
- api/route/work.php:15-33
- admin/route/work.php:15-28
- api/controller/work/WorkController.php:15-49
- admin/controller/work/WorkController.php:15-43
- core/service/work/WorkService.php:15-49
- admin/service/work/WorkService.php:15-46
- front/service/work/WorkService.php:15-43
章节来源
- api/route/work.php:15-33
- admin/route/work.php:15-28
核心组件
- API控制器 WorkController：负责鉴权、参数校验、调用服务并返回统一响应
- 后台控制器 WorkController：实现工作人员（员工）的CRUD与表单处理
- 核心服务 WorkService：权限校验、工作中心导航树构建、模块名映射
- 前台服务 WorkService：工作台行数据组装、工作日志列表、总数统计
- 后台服务 WorkService：列表过滤、分页、新增/更新/删除、附件处理、审计日志
- 表单请求 WorkFormRequest：字段白名单与规则校验
章节来源
- api/controller/work/WorkController.php:30-122
- admin/controller/work/WorkController.php:29-187
- core/service/work/WorkService.php:25-140
- front/service/work/WorkService.php:29-131
- admin/service/work/WorkService.php:32-322
- admin/request/work/WorkFormRequest.php:23-72
架构总览
工作中心API采用“路由→控制器→服务→数据源”的分层架构。API端通过声明式路由绑定到控制器方法，控制器进行鉴权后委托给服务完成业务逻辑；后台管理端同样遵循该分层，但侧重管理员视角的CRUD与审计。
sequenceDiagram
participant C as "客户端"
participant R as "路由"
participant AC as "API控制器"
participant FS as "前台服务"
participant CS as "核心服务"
C->>R : GET /api/?route=work
R->>AC : index()
AC->>AC : 鉴权与功能开关检查
AC->>FS : getDashboardWorkRow(userId)
FS->>CS : linkWorkCenter(current_module, userId)
CS-->>FS : work_tree
FS-->>AC : 工作台行数据
AC-->>C : 成功响应{title, work, link_work_center}图示来源
- api/route/work.php:29-32
- api/controller/work/WorkController.php:51-73
- front/service/work/WorkService.php:45-67
- core/service/work/WorkService.php:101-139
详细组件分析
API端：工作台首页
- 路径与方法：GET /api/?route=work → WorkController::index
- 鉴权：要求开启用户功能且已登录
- 业务：获取当前用户的工作台行，若不存在则拒绝访问
- 返回：标题、工作台信息、工作中心链接集合
flowchart TD
Start(["进入 index"]) --> Auth{"是否已登录且功能已启用?"}
Auth -- 否 --> Err401["返回未授权"]
Auth -- 是 --> Fetch["获取工作台行"]
Fetch --> HasWork{"是否存在工作台行?"}
HasWork -- 否 --> Err403["返回无权限"]
HasWork -- 是 --> Build["组装标题/工作信息/链接"]
Build --> Ok["返回成功"]图示来源
- api/controller/work/WorkController.php:51-73
章节来源
- api/controller/work/WorkController.php:51-73
API端：工作记录列表
- 路径与方法：GET /api/?route=work/product → WorkController::product
- 鉴权：同上
- 业务：按页获取当前用户的工作记录（财务明细），并返回分页与总数
- 返回：标题、工作记录列表、分页信息、总数
sequenceDiagram
participant C as "客户端"
participant AC as "API控制器"
participant FS as "前台服务"
C->>AC : GET /api/?route=work/product?page=1
AC->>AC : 鉴权
AC->>FS : buildWorkLogListData(userId, page, url)
FS-->>AC : {work_log_list, pager}
AC->>FS : getWorkTotalForUser(userId)
FS-->>AC : total
AC-->>C : 成功响应{title, work_log_list, pager, total}图示来源
- api/controller/work/WorkController.php:75-99
- front/service/work/WorkService.php:69-130
章节来源
- api/controller/work/WorkController.php:75-99
- front/service/work/WorkService.php:69-130
API端：模块权限校验
- 路径与方法：POST /api/?route=work/permission → WorkController::permission
- 入参：module（字符串）
- 业务：校验当前用户对指定模块的工作端访问权限
- 返回：成功或无权限错误
flowchart TD
PStart(["进入 permission"]) --> CheckAuth{"已登录且功能启用?"}
CheckAuth -- 否 --> E401["返回未授权"]
CheckAuth -- 是 --> ReadMod["读取 module"]
ReadMod --> CallCheck["调用核心服务 checkPermission(module, userId)"]
CallCheck --> Allow{"是否允许?"}
Allow -- 否 --> E403["返回无权限"]
Allow -- 是 --> OK["返回成功"]图示来源
- api/controller/work/WorkController.php:102-121
- core/service/work/WorkService.php:75-99
章节来源
- api/controller/work/WorkController.php:102-121
- core/service/work/WorkService.php:75-99
后台管理端：工作人员（员工）管理
- 路由：基于资源路由，支持 index/create/store/edit/update/destroy
- 列表：支持按“收件人/联系人”、会员关键字、时间范围筛选与分页
- 新增/编辑：表单字段校验，写入工作账号、权限模块、联系方式等，支持头像上传
- 删除：二次确认后执行删除，清理附件并记录审计日志
classDiagram
class AdminWorkController {
+index(request)
+create()
+store(formRequest, request)
+edit(request)
+update(formRequest, request)
+destroy(request)
}
class AdminWorkService {
+buildWorkDefaultData()
+getActionListForForm(csv)
+buildWorkListData(consignee, username, start, end, page)
+insert(data)
+buildWorkEditData(id)
+update(data)
+delete(id, post)
}
class CoreWorkService {
+actionList(cur)
+checkPermission(module, user_id)
+linkWorkCenter(current_module, user_id)
}
AdminWorkController --> AdminWorkService : "调用"
AdminWorkService --> CoreWorkService : "复用权限/导航"图示来源
- admin/controller/work/WorkController.php:55-187
- admin/service/work/WorkService.php:48-322
- core/service/work/WorkService.php:54-139
章节来源
- admin/controller/work/WorkController.php:55-187
- admin/service/work/WorkService.php:48-322
权限控制模型
- 工作台行存在性：API端要求用户必须拥有工作台行，否则拒绝访问
- 模块级权限：通过 action_list 字段控制可访问的模块集合；核心服务根据当前用户ID与模块标识进行校验
- 后台配置：管理员可为工作人员勾选可用模块，形成 action_list 逗号分隔字符串
flowchart TD
MStart["模块访问请求"] --> LoadWork["加载用户工作台行"]
LoadWork --> HasAL{"是否包含目标模块?"}
HasAL -- 否 --> Deny["拒绝访问"]
HasAL -- 是 --> Allow["允许访问"]图示来源
- core/service/work/WorkService.php:75-99
- core/service/work/WorkService.php:101-139
- admin/service/work/WorkService.php:176-180
- admin/service/work/WorkService.php:261-265
章节来源
- core/service/work/WorkService.php:75-99
- admin/service/work/WorkService.php:176-180
- admin/service/work/WorkService.php:261-265
数据模型关系（概念图）
- 用户与工作台行一对一关联
- 工作台行包含 action_list 用于模块权限控制
- 工作记录（财务明细）通过 work_id 关联到工作台行
erDiagram
USER {
int id PK
string username
}
WORK {
int id PK
int user_id FK
string contact
string phone
string company
string address
string avatar
string action_list
int status
datetime created_at
}
MONEY {
int id PK
int user_id FK
int work_id FK
string action
string from
decimal money
decimal total
datetime created_at
}
USER ||--o| WORK : "拥有"
WORK ||--o{ MONEY : "产生记录"[此图为概念示意，不直接对应具体代码文件]
依赖分析
- API控制器依赖前台服务与核心服务，完成鉴权后的业务编排
- 后台控制器依赖后台服务，实现CRUD与审计
- 核心服务被前台与后台共同复用，保证权限与导航一致性
- 表单请求对象集中管理字段校验规则，降低控制器复杂度
graph LR
API_C["API控制器"] --> FS["前台服务"]
API_C --> CS["核心服务"]
ADMIN_C["后台控制器"] --> AS["后台服务"]
AS --> CS
FORM["表单请求"] --> ADMIN_C图示来源
- api/controller/work/WorkController.php:15-49
- admin/controller/work/WorkController.php:15-43
- admin/request/work/WorkFormRequest.php:23-72
章节来源
- api/controller/work/WorkController.php:15-49
- admin/controller/work/WorkController.php:15-43
- admin/request/work/WorkFormRequest.php:23-72
性能考虑
- 列表分页：后台与前台均使用分页查询，避免一次性加载大量数据
- 权限判断：基于单表条件查询与内存数组匹配，开销较低
- 附件处理：仅在新增/更新时进行存储与回写，减少IO
- 建议：对高频查询可增加缓存层（如模块树、权限结果），并对大列表增加索引优化
故障排查指南
- 未授权（401）：检查是否已登录以及用户功能开关是否启用
- 无权限（403）：确认工作台行是否存在且包含目标模块
- 非法参数：后台CRUD会校验必填字段与ID合法性，出现异常需检查表单提交
- 删除失败：确认是否已二次确认，并检查附件删除与审计日志写入
章节来源
- api/controller/work/WorkController.php:51-121
- admin/controller/work/WorkController.php:117-187
- admin/service/work/WorkService.php:160-205
- admin/service/work/WorkService.php:234-283
- admin/service/work/WorkService.php:293-321
结论
工作中心模块以清晰的分层架构实现了工作台展示、权限控制与后台管理。API端提供稳定的工作台与记录查询能力，后台端提供完整的工作人员管理与权限配置。结合现有能力，可在上层扩展任务审批、进度跟踪、通知协作等业务流程。
附录：接口清单与示例
API端接口
-
工作台首页
- 方法：GET
- 路径：/api/?route=work
- 鉴权：需要登录且功能启用
- 返回：标题、工作台信息、工作中心链接集合
- 参考：api/controller/work/WorkController.php:51-73
-
工作记录列表
- 方法：GET
- 路径：/api/?route=work/product
- 参数：page（默认1）
- 鉴权：需要登录且功能启用
- 返回：标题、工作记录列表、分页信息、总数
- 参考：api/controller/work/WorkController.php:75-99
-
模块权限校验
- 方法：POST
- 路径：/api/?route=work/permission
- 参数：module（字符串）
- 鉴权：需要登录且功能启用
- 返回：成功或无权限错误
- 参考：api/controller/work/WorkController.php:102-121
后台管理端接口（资源路由）
- 列表：?route=work
- 新增表单：?route=work/create
- 新增提交：?route=work/store
- 编辑表单：?route=work/edit?id={id}
- 编辑提交：?route=work/update
- 删除：?route=work/destroy&id={id}
- 参考：
- admin/route/work.php:15-28
- admin/controller/work/WorkController.php:55-187
- admin/request/work/WorkFormRequest.php:23-72
业务场景与数据流
- 工作分配：管理员在后台创建工作人员并勾选可用模块（action_list）
- 参考：admin/service/work/WorkService.php:176-180
- 任务审批：可在上层基于模块权限（action_list）扩展审批节点
- 参考：core/service/work/WorkService.php:75-99
- 完成确认：在工作记录（财务明细）中体现完成动作与金额变动
- 参考：front/service/work/WorkService.php:69-117
- 进度跟踪：通过工作记录列表展示历史操作与时间
- 参考：front/service/work/WorkService.php:69-117
- 数据统计：可基于工作记录聚合统计（如总额、次数）
- 参考：front/service/work/WorkService.php:119-130
权限控制要点
- 查看权限：API端先校验工作台行存在性
- 参考：api/controller/work/WorkController.php:51-73
- 编辑权限：后台管理员可修改工作人员信息与模块权限
- 参考：admin/service/work/WorkService.php:234-283
- 审批权限：通过模块权限控制可访问的模块，再在上层实现审批流程
- 参考：core/service/work/WorkService.php:75-99
通知、提醒、协作
- 通知与提醒：可在工作记录生成时触发消息队列或站内信（建议在业务层扩展）
- 协作：基于模块权限与工作台导航，将多角色纳入同一工作流（建议在业务层扩展）