safety-eval-service/docs/监管端-风险预警中心接口文档.md

监管端 - 风险预警中心接口文档

仅覆盖原型页 风险预警中心，Mock 数据内置于 RegulatorRiskCenterController，无数据库依赖。
统一前缀：/safetyEval/regulator/risk-center
接口数量：2 个（GET /overview、GET /page）
OpenAPI 导入文件：监管端-风险预警中心.openapi.yaml（可直接导入 Apifox）

---

1. 页面与接口映射

页面区域	接口	说明
顶部 4 个统计卡片	GET /overview	页面首屏统计区
搜索栏（关键词/预警大类/预警子类/处理阶段）+ 消息列表	GET /page	分页 + 筛选

---

2. 通用约定

响应格式

成功时 code = "0"：

// 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 — 页面概览

用途：加载统计卡片。

响应示例：

{
  "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=资质预警&current=1&size=10
GET /safetyEval/regulator/risk-center/page?keyword=渝安&subtype=资质条件保持异常
GET /safetyEval/regulator/risk-center/page?stage=未处理&current=1&size=10

响应示例：

{
  "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 数据与前端完全一致