# safety模块前端联调文档

更新时间：2026-05-25

## 1. 公共约定

### 1.1 认证

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

### 1.2 统一返回

普通接口统一返回 `AjaxResult`：

```json
{
  "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 按“租户+日期”控制）。同一天重复调用会返回失败提示：`今日已同步，明天再试`。

返回示例：

```json
{
  "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. 前端封装示例（巡检同步）

```js
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`：导出

新增/修改请求体示例：

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