297 lines
8.9 KiB
Markdown
297 lines
8.9 KiB
Markdown
# 监管端 - 风险预警中心接口文档
|
||
|
||
> 仅覆盖原型页 **风险预警中心**，Mock 数据内置于 `RegulatorRiskCenterController`，无数据库依赖。
|
||
> 统一前缀：`/safetyEval/regulator/risk-center`
|
||
> 接口数量：**4 个**
|
||
> **OpenAPI 导入文件**：[监管端-风险预警中心.openapi.yaml](./openapi/监管端-风险预警中心.openapi.yaml)（可直接导入 Apifox）
|
||
|
||
---
|
||
|
||
## 1. 页面与接口映射
|
||
|
||
| 页面区域 | 接口 | 说明 |
|
||
|----------|------|------|
|
||
| 顶部 4 个统计卡片 + 处理动作说明 | `GET /overview` | 页面首屏统计区 |
|
||
| 高优先级消息区块 | `GET /high-priority-alerts` | 支持等级/类型/来源等筛选 |
|
||
| search-bar + 筛选 + 消息列表 | `GET /page` | 分页 + 筛选 |
|
||
| 处理 / 发函 / 闭环 / 提醒 / 审核 | `POST /handle` | 更新预警状态 |
|
||
|
||
---
|
||
|
||
## 2. 通用约定
|
||
|
||
### 响应格式
|
||
|
||
成功时 `code = "0"`：
|
||
|
||
```json
|
||
// SingleResponse
|
||
{ "success": true, "code": "0", "data": {} }
|
||
|
||
// PageResponse
|
||
{ "success": true, "code": "0", "data": [], "total": 8 }
|
||
```
|
||
|
||
### 分页参数
|
||
|
||
| 参数 | 类型 | 默认 | 说明 |
|
||
|------|------|------|------|
|
||
| current | Long | 1 | 当前页 |
|
||
| size | Long | 10 | 每页条数 |
|
||
|
||
---
|
||
|
||
## 3. 领域模型
|
||
|
||
### RegulatorRiskOverviewCO — 页面概览
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| stats | List\<StatCardCO\> | 统计卡片 |
|
||
| processGuide | String | 消息处理动作说明文案 |
|
||
|
||
**StatCardCO**：`label` / `value` / `hint`
|
||
|
||
### RegulatorRiskPriorityAlertCO — 高优先级消息
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| title | String | 标题 |
|
||
| description | String | 描述（含来源与触发规则） |
|
||
| messageId | String | 关联预警编号 |
|
||
| level | String | danger / warning / info |
|
||
| warningType | String | 预警类型 |
|
||
| sourceModule | String | 来源模块 |
|
||
| status | String | 当前状态 |
|
||
|
||
### RegulatorRiskMessageCO — 预警消息
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | String | 预警编号，如 W-2026-008 |
|
||
| warningType | String | 证书过期 / 证书临期 / 社保异常 / 人员离职 / 信息变更 |
|
||
| level | String | 紧急 / 重要 / 一般 |
|
||
| levelName | String | 紧急 / 重要 / 一般 |
|
||
| sourceModule | String | 来源模块名称 |
|
||
| sourceFields | List\<String\> | 来源字段标签 |
|
||
| content | String | 预警内容 |
|
||
| status | String | 未处理 / 处理中 / 待确认 / 已闭环 / 已发函 / 已提醒 / 已处置 |
|
||
| sourceModuleKey | String | 来源跳转模块标识（evaluator、qual-monitor、qual-change 等） |
|
||
|
||
---
|
||
|
||
## 4. 接口详情
|
||
|
||
### 4.1 GET `/overview` — 页面概览
|
||
|
||
**用途**：加载统计卡片、处理流程说明。
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": "0",
|
||
"data": {
|
||
"stats": [
|
||
{ "label": "未处理预警", "value": "5", "hint": "需监管人员处置" },
|
||
{ "label": "紧急消息", "value": "4", "hint": "证书过期、社保异常" },
|
||
{ "label": "重要提醒", "value": "2", "hint": "证书临期、变更停滞" },
|
||
{ "label": "今日已处置", "value": "2", "hint": "含发函、确认、转办" }
|
||
],
|
||
"processGuide": "查看来源 → 核查材料/字段 → 发函或转办 → 设置处理结论 → 标记闭环。所有按钮均写入处置记录，用于监管留痕。"
|
||
}
|
||
}
|
||
```
|
||
|
||
> 统计数值由 Mock 消息列表动态计算，处置后再次请求会变化。
|
||
|
||
---
|
||
|
||
### 4.2 GET `/high-priority-alerts` — 高优先级消息
|
||
|
||
**用途**：加载页面中部「高优先级消息」区块，默认展示紧急且未处理的前 2 条。
|
||
|
||
**查询参数**：
|
||
|
||
| 参数 | 必填 | 默认 | 说明 |
|
||
|------|------|------|------|
|
||
| level | 否 | 紧急 | 预警等级：紧急 / 重要 / 一般 |
|
||
| warningType | 否 | — | 证书过期、证书临期、社保异常、人员离职、信息变更 |
|
||
| sourceModule | 否 | — | 来源模块，如 评价师信息管理 |
|
||
| keyword | 否 | — | 标题/预警编号/预警内容关键字 |
|
||
| onlyUntreated | 否 | true | 仅未处理（未处理/待确认/处理中） |
|
||
| limit | 否 | 2 | 返回条数上限 |
|
||
|
||
**请求示例**：
|
||
|
||
```
|
||
GET /safetyEval/regulator/risk-center/high-priority-alerts
|
||
GET /safetyEval/regulator/risk-center/high-priority-alerts?level=紧急&onlyUntreated=true&limit=2
|
||
GET /safetyEval/regulator/risk-center/high-priority-alerts?level=重要&limit=5
|
||
```
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": "0",
|
||
"data": [
|
||
{
|
||
"title": "评价师证书已过期",
|
||
"description": "来源：评价师信息管理.证书有效期；触发：有效期至 2026-06-01。",
|
||
"messageId": "W-2026-008",
|
||
"level": "danger",
|
||
"warningType": "证书过期",
|
||
"sourceModule": "评价师信息管理",
|
||
"status": "未处理"
|
||
},
|
||
{
|
||
"title": "社保多处缴纳",
|
||
"description": "来源：资质保持监控.社保缴纳单位；触发：同一人员两家机构。",
|
||
"messageId": "W-2026-007",
|
||
"level": "danger",
|
||
"warningType": "社保异常",
|
||
"sourceModule": "资质保持监控",
|
||
"status": "未处理"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 GET `/page` — 分页查询消息列表
|
||
|
||
**查询参数**：
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| keyword | 否 | 机构/人员/项目/预警编号 |
|
||
| warningType | 否 | 证书过期、证书临期、社保异常、人员离职、信息变更 |
|
||
| level | 否 | 紧急、重要、一般 |
|
||
| processStatus | 否 | 未处理、处理中、已处理 |
|
||
| current | 否 | 当前页 |
|
||
| size | 否 | 每页条数 |
|
||
|
||
**请求示例**：
|
||
|
||
```
|
||
GET /safetyEval/regulator/risk-center/page?level=紧急¤t=1&size=10
|
||
GET /safetyEval/regulator/risk-center/page?keyword=张建国&warningType=证书过期
|
||
GET /safetyEval/regulator/risk-center/page?processStatus=未处理¤t=1&size=10
|
||
```
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": "0",
|
||
"total": 4,
|
||
"data": [
|
||
{
|
||
"id": "W-2026-008",
|
||
"warningType": "证书过期",
|
||
"level": "紧急",
|
||
"levelName": "紧急",
|
||
"sourceModule": "评价师信息管理",
|
||
"sourceFields": ["人员姓名", "证书类型", "有效期至"],
|
||
"content": "张建国一级安全评价师证书已过期，机构未上传延续材料。",
|
||
"status": "未处理",
|
||
"sourceModuleKey": "evaluator"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.4 POST `/handle` — 处置预警
|
||
|
||
**用途**：处理弹窗提交、列表行内「闭环」「发函」「提醒」等操作。
|
||
|
||
**请求体**：
|
||
|
||
```json
|
||
{
|
||
"id": "W-2026-008",
|
||
"handleType": "标记闭环",
|
||
"deadline": "2026-07-18",
|
||
"opinion": "请核查证书延续材料",
|
||
"status": "已闭环"
|
||
}
|
||
```
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| id | 是 | 预警编号 |
|
||
| handleType | 是 | 发函核查 / 转备案审核 / 要求整改 / 标记闭环 / 已发函 / 已提醒 等 |
|
||
| deadline | 否 | 办理期限 |
|
||
| opinion | 否 | 处置意见 |
|
||
| status | 否 | 不传时根据 handleType 自动推断 |
|
||
|
||
**status 自动推断规则**：
|
||
|
||
| handleType 含 | 默认 status |
|
||
|---------------|-------------|
|
||
| 闭环 | 已闭环 |
|
||
| 发函 | 已发函 |
|
||
| 提醒 | 已提醒 |
|
||
| 转办 / 转备案 | 处理中 |
|
||
| 其他 | 已处置 |
|
||
|
||
**响应**：返回更新后的 `RegulatorRiskMessageCO`。
|
||
|
||
---
|
||
|
||
## 5. 前端对接建议
|
||
|
||
```javascript
|
||
const BASE = '/safetyEval/regulator/risk-center';
|
||
|
||
// 1. 页面初始化 - 统计区
|
||
const overview = await fetch(`${BASE}/overview`).then(r => r.json());
|
||
|
||
// 2. 高优先级消息（默认紧急未处理前2条）
|
||
const alerts = await fetch(`${BASE}/high-priority-alerts`).then(r => r.json());
|
||
|
||
// 3. Tab 切换 / 搜索
|
||
const list = await fetch(`${BASE}/page?level=紧急¤t=1&size=10`).then(r => r.json());
|
||
|
||
// 4. 处置
|
||
await fetch(`${BASE}/handle`, {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
body: JSON.stringify({ id: 'W-2026-008', handleType: '标记闭环', status: '已闭环' })
|
||
});
|
||
```
|
||
|
||
**来源跳转**：使用 `sourceModuleKey` 切换监管端左侧菜单模块（与原型 `openRegSource()` 一致）。
|
||
|
||
---
|
||
|
||
## 6. 代码位置
|
||
|
||
| 类型 | 路径 |
|
||
|------|------|
|
||
| Controller（含 Mock） | `safety-eval-adapter/.../web/regulator/RegulatorRiskCenterController.java` |
|
||
| 响应模型 | `safety-eval-client/.../co/regulator/RegulatorRiskOverviewCO.java` |
|
||
| | `safety-eval-client/.../co/regulator/RegulatorRiskPriorityAlertCO.java` |
|
||
| | `safety-eval-client/.../co/regulator/RegulatorRiskMessageCO.java` |
|
||
| 入参模型 | `safety-eval-client/.../dto/regulator/RegulatorRiskPriorityAlertQuery.java` |
|
||
| | `safety-eval-client/.../dto/regulator/RegulatorRiskMessagePageQuery.java` |
|
||
| | `safety-eval-client/.../dto/regulator/RegulatorRiskHandleCmd.java` |
|
||
|
||
---
|
||
|
||
## 7. 后续真实数据对接
|
||
|
||
保留上述 4 个接口契约不变，将 Controller 内 Mock 逻辑替换为领域服务调用即可，前端无需改动。
|
||
|
||
| 日期 | 说明 |
|
||
|------|------|
|
||
| 2026-07-14 | 初版：风险预警中心 3 接口 + Controller 内 Mock |
|
||
| 2026-07-14 | 拆分 highPriorityAlerts 为独立接口 `/high-priority-alerts` |
|