173 lines
6.1 KiB
Markdown
173 lines
6.1 KiB
Markdown
# 监管端 - 风险预警中心接口文档
|
||
|
||
> 仅覆盖原型页 **风险预警中心**，Mock 数据内置于 `RegulatorRiskCenterController`，无数据库依赖。
|
||
> 统一前缀：`/safetyEval/regulator/risk-center`
|
||
> 接口数量：**2 个**（`GET /overview`、`GET /page`）
|
||
> **OpenAPI 导入文件**：[监管端-风险预警中心.openapi.yaml](./openapi/监管端-风险预警中心.openapi.yaml)（可直接导入 Apifox）
|
||
|
||
---
|
||
|
||
## 1. 页面与接口映射
|
||
|
||
| 页面区域 | 接口 | 说明 |
|
||
|----------|------|------|
|
||
| 顶部 4 个统计卡片 | `GET /overview` | 页面首屏统计区 |
|
||
| 搜索栏（关键词/预警大类/预警子类/处理阶段）+ 消息列表 | `GET /page` | 分页 + 筛选 |
|
||
|
||
---
|
||
|
||
## 2. 通用约定
|
||
|
||
### 响应格式
|
||
|
||
成功时 `code = "0"`：
|
||
|
||
```json
|
||
// SingleResponse
|
||
{ "success": true, "code": "0", "data": {} }
|
||
|
||
// PageResponse
|
||
{ "success": true, "code": "0", "data": [], "total": 7 }
|
||
```
|
||
|
||
### 分页参数
|
||
|
||
| 参数 | 类型 | 默认 | 说明 |
|
||
|------|------|------|------|
|
||
| current | Long | 1 | 当前页 |
|
||
| size | Long | 10 | 每页条数 |
|
||
|
||
---
|
||
|
||
## 3. 领域模型
|
||
|
||
### RegulatorRiskOverviewCO — 页面概览
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| stats | List\<StatCardCO\> | 统计卡片（4 个） |
|
||
|
||
**StatCardCO**：`label` / `value` / `hint`
|
||
|
||
### RegulatorRiskMessageCO — 预警消息
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | String | 预警编号，如 W-QUAL-2026-012 |
|
||
| category | String | 预警大类：资质预警 / 项目预警 |
|
||
| subtype | String | 预警子类（见下方 9 项枚举） |
|
||
| riskObject | String | 风险对象（机构或项目） |
|
||
| sourceFields | List\<String\> | 来源字段标签 |
|
||
| content | String | 触发内容 |
|
||
| stage | String | 处理阶段：未处理 / 已发机构 / 待复核 / 已闭环 |
|
||
| orgStatus | String | 机构端状态：未发送 / 机构未读 / 已提交材料 / 处理中 / 已提交说明 / 整改完成 |
|
||
|
||
---
|
||
|
||
## 4. 接口详情
|
||
|
||
### 4.1 GET `/overview` — 页面概览
|
||
|
||
**用途**：加载统计卡片。
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": "0",
|
||
"data": {
|
||
"stats": [
|
||
{ "label": "资质预警", "value": "6", "hint": "条件保持、人员比例、属地材料" },
|
||
{ "label": "项目预警", "value": "7", "hint": "进度、人员、告知、勘查、质控" },
|
||
{ "label": "待机构反馈", "value": "4", "hint": "整改说明或证明材料" },
|
||
{ "label": "今日闭环", "value": "5", "hint": "监管复核已完成" }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
> 统计数值取自原型页展示值。
|
||
|
||
---
|
||
|
||
### 4.2 GET `/page` — 分页查询消息列表
|
||
|
||
**查询参数**（与前端下拉选项完全一致）：
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| keyword | 否 | 关键词：机构/项目/人员/预警编号 |
|
||
| type | 否 | 预警大类：资质预警、项目预警 |
|
||
| subtype | 否 | 预警子类：资质条件保持异常、人员比例异常、属地材料待核验、项目启动超期、关键节点超期、项目人员异常、从业告知异常、现场勘查异常、过程控制/归档异常 |
|
||
| stage | 否 | 处理阶段：未处理、已发机构、待复核、已闭环 |
|
||
| current | 否 | 当前页 |
|
||
| size | 否 | 每页条数 |
|
||
|
||
**请求示例**：
|
||
|
||
```
|
||
GET /safetyEval/regulator/risk-center/page?type=资质预警¤t=1&size=10
|
||
GET /safetyEval/regulator/risk-center/page?keyword=渝安&subtype=资质条件保持异常
|
||
GET /safetyEval/regulator/risk-center/page?stage=未处理¤t=1&size=10
|
||
```
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": "0",
|
||
"total": 7,
|
||
"data": [
|
||
{
|
||
"id": "W-QUAL-2026-012",
|
||
"category": "资质预警",
|
||
"subtype": "资质条件保持异常",
|
||
"riskObject": "重庆渝安风险评估中心",
|
||
"sourceFields": ["财务材料.固定资产", "场所核验.建筑面积", "人员库.专职人数"],
|
||
"content": "固定资产、场所面积、档案室面积和专职人员数量不满足保持条件。",
|
||
"stage": "未处理",
|
||
"orgStatus": "未发送"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**Mock 数据清单**（7 条，参考前端原型）：
|
||
|
||
| 预警编号 | 预警大类 | 预警子类 | 风险对象 | 处理阶段 | 机构端状态 |
|
||
|----------|----------|----------|----------|----------|------------|
|
||
| W-QUAL-2026-012 | 资质预警 | 资质条件保持异常 | 重庆渝安风险评估中心 | 未处理 | 未发送 |
|
||
| W-QUAL-2026-011 | 资质预警 | 人员比例异常 | 重庆恒安安全评价有限公司 | 已发机构 | 机构未读 |
|
||
| W-QUAL-2026-013 | 资质预警 | 属地材料待核验 | 北京中安评价中心重庆分公司 | 待复核 | 已提交材料 |
|
||
| W-PROJ-2026-021 | 项目预警 | 项目启动超期 | 华安化工年度安全现状评价 | 未处理 | 未发送 |
|
||
| W-PROJ-2026-018 | 项目预警 | 关键节点超期 | 安环检测年度安全现状评价 | 已发机构 | 处理中 |
|
||
| W-PROJ-2026-015 | 项目预警 | 项目人员异常 | 鼎信建设安全验收评价 | 待复核 | 已提交说明 |
|
||
| W-PROJ-2026-009 | 项目预警 | 现场勘查异常 | 华安化工园区安全预评价 | 已闭环 | 整改完成 |
|
||
|
||
---
|
||
|
||
## 5. 代码位置
|
||
|
||
| 类型 | 路径 |
|
||
|------|------|
|
||
| Controller（含 Mock） | `safety-eval-adapter/.../web/regulator/RegulatorRiskCenterController.java` |
|
||
| 响应模型 | `safety-eval-client/.../co/regulator/RegulatorRiskOverviewCO.java` |
|
||
| | `safety-eval-client/.../co/regulator/RegulatorRiskMessageCO.java` |
|
||
| 入参模型 | `safety-eval-client/.../dto/regulator/RegulatorRiskMessagePageQuery.java` |
|
||
| 枚举 | `safety-eval-client/.../enums/regulator/RegulatorRiskCategoryEnum.java` |
|
||
| | `safety-eval-client/.../enums/regulator/RegulatorRiskSubtypeEnum.java` |
|
||
| | `safety-eval-client/.../enums/regulator/RegulatorRiskStageEnum.java` |
|
||
|
||
---
|
||
|
||
## 6. 后续真实数据对接
|
||
|
||
保留上述 2 个接口契约不变，将 Controller 内 Mock 逻辑替换为领域服务调用即可，前端无需改动。
|
||
|
||
| 日期 | 说明 |
|
||
|------|------|
|
||
| 2026-07-14 | 初版：风险预警中心接口 + Controller 内 Mock |
|
||
| 2026-07-16 | 参考前端原型重构：仅保留 overview/page，查询条件与下拉选项、Mock 数据与前端完全一致 |
|