1
2
3
4
5
6

{
  "msg": "成功",
  "code": 0,
  "data": null,
  "success": true
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

POST /hazard/monitorEquip/add         # 重大危险源-监测设备-新增
POST /hazard/monitorEquip/update      # 重大危险源-监测设备-修改
POST /hazard/monitorEquip/delete      # 重大危险源-监测设备-删除
POST /prevent/riskUnit/add            # 双预防-风险分析单元-新增
POST /prevent/riskEvents/add          # 双预防-安全风险事件-新增
POST /prevent/riskMeasures/add        # 双预防-管控措施-新增
POST /prevent/troubleshootTask/add     # 双预防-隐患排查任务-新增
POST /prevent/troubleshootRecord/add  # 双预防-隐患排查记录-新增
POST /prevent/troubleshootInfo/add    # 双预防-隐患排查信息-新增
POST /prevent/ticketBaseInfo/add      # 特殊作业票-票证信息-新增
POST /prevent/trainBaseInfo/add       # 教育培训-培训信息-新增

1
2
3
4

POST   /api/v1/hazard/monitor-equip        # 新增
GET    /api/v1/hazard/monitor-equip/{id}   # 查询
PUT    /api/v1/hazard/monitor-equip/{id}   # 修改
DELETE /api/v1/hazard/monitor-equip/{id}   # 删除

1
2
3

POST /hazard/monitorEquip/add
POST /hazard/monitorEquip/update
POST /hazard/monitorEquip/delete

1
2
3
4
5
6
7

# 驼峰（这份规范）
/hazard/monitorEquip
/prevent/riskUnit

# 短横线（RESTful 推荐）
/hazard/monitor-equip
/prevent/risk-unit

1
2

POST /system/login
Content-Type: application/json

1
2
3
4

{
  "userName": "{{USERNAME}}",
  "password": "{{PASSWORD}}"
}

1
2
3
4
5
6
7
8

{
  "msg": "",
  "code": 0,
  "data": {
    "token": "{{TOKEN}}"
  },
  "success": true
}

1
2
3

POST /hazard/monitorEquip/add
Authorization: Bearer {{TOKEN}}
Content-Type: application/json

1
2

POST /system/refresh
Authorization: Bearer {{REFRESH_TOKEN}}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

字段值是什么？
├── 中文/枚举/编号
│   ├── 固定有限集合 → string（"男"/"女"、"已处理"/"未处理"）
│   ├── 不定文本     → string（地址、姓名、备注）
│   └── 编号/UUID   → string（不直接用 number！避免 JS 精度问题）
│
├── 数值
│   ├── 整数计数     → int（年龄、数量）
│   ├── 小数金额     → string 或 long（避免精度问题，"1.23"）
│   ├── 经纬度       → number（前端 leaflet/高德直接用）
│   └── 大 ID        → string（雪花 ID 19 位超出 JS Number 安全范围）
│
└── 时间
    ├── 精确到秒     → string ISO 8601（"2026-06-04T10:30:00+08:00"）
    ├── 仅日期       → string（"2026-06-04"）
    └── 时间戳       → long（毫秒，前端 new Date(ms)）

1
2
3
4
5

# 推荐：仅标注"必选"（默认是可选）
"id": { "type": "string", "required": true, "desc": "主键" }
"monitorName": { "type": "string", "required": true, "desc": "监测点名称" }

# 不推荐：每个字段都标注 required: false（噪音）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// 业务错误（4xx + 业务 code）
{
  "msg": "监测点编号已存在",
  "code": 1001,
  "data": null,
  "success": false
}

// 系统错误（5xx + 异常 trace）
{
  "msg": "系统繁忙，请稍后重试",
  "code": -1,
  "data": null,
  "success": false
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

@PostMapping("/hazard/monitorEquip/add")
public Result<?> addMonitorEquip(@RequestBody MonitorEquipDTO dto) {
    // 1. 参数校验
    validator.validate(dto);
    
    // 2. 业务校验（编号唯一性、权限等）
    if (monitorEquipRepository.existsByCode(dto.getMonitorCode())) {
        return Result.fail(1001, "监测点编号已存在");
    }
    
    // 3. 企业版落库
    monitorEquipRepository.save(dto);
    
    // 4. 同步园区版（这里是关键！）
    try {
        parkApiClient.pushMonitorEquip(dto);
    } catch (Exception e) {
        // 5. 园区版同步失败的处理（决定了一致性策略）
        log.warn("园区版同步失败，已加入重试队列: id={}", dto.getId(), e);
        retryQueue.push("park_sync", dto);  // 异步重试
        // 注意：这里**不要抛异常给前端**，因为企业版已经成功了
    }
    
    return Result.ok();
}

1
2

POST /prevent/riskUnit/add-batch
Content-Type: application/json

1
2
3
4
5
6
7

{
  "list": [
    { "id": "1", "riskUnitName": "反应釜 A 单元" },
    { "id": "2", "riskUnitName": "储罐区 B 单元" },
    { "id": "3", "riskUnitName": "装卸区 C 单元" }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

@RestController
@RequestMapping("/hazard/monitorEquip")
@Tag(name = "重大危险源-监测设备")
public class MonitorEquipController {

    @Operation(summary = "新增监测设备")
    @PostMapping("/add")
    public Result<MonitorEquipVO> add(@Valid @RequestBody MonitorEquipDTO dto) {
        // ...
    }
}

1
2
3
4
5
6

<!-- pom.xml -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

// 统一响应体
@Data
public class Result<T> {
    private String msg;
    private int code;
    private T data;
    private boolean success;
    
    public static <T> Result<T> ok() { return ok(null); }
    public static <T> Result<T> ok(T data) {
        Result<T> r = new Result<>();
        r.setCode(0);
        r.setMsg("成功");
        r.setData(data);
        r.setSuccess(true);
        return r;
    }
    public static <T> Result<T> fail(int code, String msg) {
        Result<T> r = new Result<>();
        r.setCode(code);
        r.setMsg(msg);
        r.setSuccess(false);
        return r;
    }
}

// 鉴权拦截器
@Component
public class AuthInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) {
        String auth = req.getHeader("Authorization");
        if (auth == null || !auth.startsWith("Bearer ")) {
            throw new AuthException("未登录");
        }
        String token = auth.substring(7);
        // 校验 token：从 Redis 取用户信息
        Long userId = tokenService.getUserIdByToken(token);
        if (userId == null) {
            throw new AuthException("Token 已过期");
        }
        // 放入 ThreadLocal
        UserContext.set(userId);
        return true;
    }
}