产品供销存-后端
编辑 | blame | 历史 | 原始文档

safety模块前端联调文档

更新时间：2026-05-25

1. 公共约定

1.1 认证

  • 请求头：Authorization: Bearer ${token}
  • 登录接口：POST /login

1.2 统一返回

普通接口统一返回 AjaxResult：

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

1.3 分页返回

safety 模块列表接口返回 MyBatis Plus Page，核心字段：

  • data.records
  • data.total
  • data.current
  • data.size

分页参数建议统一使用：

  • pageNum
  • pageSize

1.4 日期格式

  • LocalDate：yyyy-MM-dd
  • LocalDateTime：yyyy-MM-dd HH:mm:ss

1.5 公共字段

所有 safety 实体都包含以下公共字段（新增时无需传）：

  • id
  • createBy
  • createTime
  • updateBy
  • updateTime
  • remark
  • delFlag（逻辑删除）
  • tenantId

2. 接口清单

2.1 基础档案

  • 人员档案
  • GET /safety/personnel/list
  • POST /safety/personnel/add
  • PUT /safety/personnel/update
  • DELETE /safety/personnel/delete/{id}
  • GET /safety/personnel/detail/{id}
  • 岗位风险
  • GET /safety/risk/list
  • POST /safety/risk/add
  • PUT /safety/risk/update
  • DELETE /safety/risk/delete/{id}
  • GET /safety/risk/detail/{id}
  • 作业区域
  • GET /safety/workArea/list
  • GET /safety/workArea/all
  • POST /safety/workArea/add
  • PUT /safety/workArea/update
  • DELETE /safety/workArea/delete/{id}
  • GET /safety/workArea/detail/{id}
  • 设备设施
  • GET /safety/equipment/list
  • POST /safety/equipment/add
  • PUT /safety/equipment/update
  • DELETE /safety/equipment/delete/{id}
  • GET /safety/equipment/detail/{id}
  • 应急资源
  • GET /safety/emergency/list
  • POST /safety/emergency/add
  • PUT /safety/emergency/update
  • DELETE /safety/emergency/delete/{id}
  • GET /safety/emergency/detail/{id}

2.2 巡检

  • 巡检记录
  • GET /safety/inspection/record/list
  • POST /safety/inspection/record/add
  • PUT /safety/inspection/record/update
  • DELETE /safety/inspection/record/delete/{id}
  • POST /safety/inspection/record/sync（新增：模拟子系统同步，自动创建18条）
  • 巡检统计
  • GET /safety/inspection/statistics/today
  • GET /safety/inspection/statistics/trend
  • GET /safety/inspection/statistics/type
  • GET /safety/inspection/statistics/inspector

2.3 培训学习

  • 培训资料
  • GET /safety/training/material/list
  • POST /safety/training/material/upload（保存元数据）
  • PUT /safety/training/material/update
  • DELETE /safety/training/material/delete/{id}
  • GET /safety/training/material/detail/{id}
  • 培训计划
  • GET /safety/training/plan/list
  • POST /safety/training/plan/add
  • PUT /safety/training/plan/update
  • DELETE /safety/training/plan/delete/{id}
  • GET /safety/training/plan/detail/{id}
  • 培训完成记录
  • GET /safety/training/record/list
  • POST /safety/training/record/add
  • PUT /safety/training/record/update
  • DELETE /safety/training/record/delete/{id}
  • GET /safety/training/record/detail/{id}
  • GET /safety/training/record/export
  • 员工学习记录
  • GET /safety/learning/record/list
  • GET /safety/learning/record/statistics

2.4 测评与报告

  • 测评任务
  • GET /safety/learning/assessment/list
  • POST /safety/learning/assessment/start
  • POST /safety/learning/assessment/submit
  • 考核报告
  • GET /safety/learning/report/list
  • GET /safety/learning/report/detail/{id}

3. 巡检模块联调重点

3.1 巡检记录查询

GET /safety/inspection/record/list

可用筛选参数：

  • startDate、endDate（按巡检时间区间）
  • inspectorId、inspector
  • areaId、area
  • type
  • status
  • pageNum、pageSize

关键字段：

  • inspectionTime
  • inspectorId、inspector
  • areaId、area
  • type
  • status
  • abnormalDesc
  • isMissed

3.2 巡检状态口径（后端统计口径）

  • status=0：已完成（正常）
  • status=1：已完成（异常）
  • status=2：已完成（漏检）
  • status=3：未执行
  • isMissed=1：也计入漏检统计

3.3 同步模拟子系统数据（新增）

接口：POST /safety/inspection/record/sync

用途：前端点击“同步数据”按钮时调用，系统会自动生成 18 条模拟巡检数据写入数据库，并将这 18 条记录返回给前端。

请求参数：无

调用限制：每天只能成功调用 1 次（Redis 按“租户+日期”控制）。同一天重复调用会返回失败提示：今日已同步，明天再试。

返回示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "count": 18,
    "records": [
      {
        "inspectionTime": "2026-05-25 08:20:00",
        "inspectorId": 101,
        "inspector": "inspector-a",
        "areaId": 1,
        "area": "workshop-a",
        "type": "daily",
        "status": 0,
        "abnormalDesc": null,
        "isMissed": 0
      }
    ]
  }
}

联调建议调用顺序：

  1. 点击同步按钮后先调用 POST /safety/inspection/record/sync
  2. 成功后刷新列表：GET /safety/inspection/record/list
  3. 再刷新统计卡片和图表：
  • GET /safety/inspection/statistics/today
  • GET /safety/inspection/statistics/trend
  • GET /safety/inspection/statistics/type
  • GET /safety/inspection/statistics/inspector

3.4 巡检统计默认时间范围

trend/type/inspector 三个统计接口若不传 startDate/endDate，后端默认最近 7 天（当天往前推 6 天）。

4. 培训资料上传说明

/safety/training/material/upload 只保存资料元数据，不接收二进制文件。

推荐流程：

  1. 先调用 POST /common/upload 上传文件
  2. 拿到 url/fileName/originalFilename 后调用 POST /safety/training/material/upload 保存元数据

5. 前端封装示例（巡检同步）

import request from '@/utils/request'

export function syncInspectionData() {
  return request({
    url: '/safety/inspection/record/sync',
    method: 'post'
  })
}

6. 培训完成记录补充（增删改查）

基础地址：/safety/training/record

已开放接口：

  1. GET /list：分页查询
  2. POST /add：新增
  3. PUT /update：修改
  4. DELETE /delete/{id}：删除
  5. GET /detail/{id}：详情
  6. GET /export：导出

新增/修改请求体示例：

{
  "planId": 1,
  "employeeId": 1001,
  "employeeName": "张三",
  "content": "三级安全教育培训",
  "completeTime": "2026-05-25 10:00:00",
  "duration": 2.0,
  "method": "线下授课",
  "result": "通过",
  "score": 92,
  "status": 1,
  "remark": "补录"
}