safety-eval-service/docs/openapi/监管端-风险预警中心.openapi.yaml

openapi: 3.0.3
info:
  title: 监管端-风险预警中心 API
  description: |
    重庆市安全评价服务平台 - 监管端「风险预警中心」页面接口。

    - 统一前缀：`/safetyEval/regulator/risk-center`
    - 当前为 Mock 实现，数据存于 Controller 内存
    - 成功响应 `code = "0"`

    **Apifox 导入方式**：项目设置 → 导入数据 → 选择本文件（OpenAPI/Swagger 格式）
  version: 1.0.0
  contact:
    name: safety-eval-service

servers:
  - url: http://localhost:8095
    description: 本地开发
  - url: http://192.168.20.100:30140
    description: 测试网关（100）

tags:
  - name: 监管端-风险预警中心
    description: 风险预警中心页面相关接口

paths:
  /safetyEval/regulator/risk-center/overview:
    get:
      tags:
        - 监管端-风险预警中心
      summary: 页面概览
      description: 加载统计卡片与消息处理动作说明
      operationId: regulatorRiskOverview
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseRegulatorRiskOverviewCO'
              example:
                success: true
                code: "0"
                data:
                  stats:
                    - label: 未处理预警
                      value: "5"
                      hint: 需监管人员处置
                    - label: 紧急消息
                      value: "4"
                      hint: 证书过期、社保异常
                    - label: 重要提醒
                      value: "2"
                      hint: 证书临期、变更停滞
                    - label: 今日已处置
                      value: "2"
                      hint: 含发函、确认、转办
                  processGuide: 查看来源 → 核查材料/字段 → 发函或转办 → 设置处理结论 → 标记闭环。所有按钮均写入处置记录，用于监管留痕。

  /safetyEval/regulator/risk-center/high-priority-alerts:
    get:
      tags:
        - 监管端-风险预警中心
      summary: 高优先级消息列表
      description: 加载页面中部「高优先级消息」区块，默认返回紧急且未处理的前 2 条
      operationId: regulatorRiskHighPriorityAlerts
      parameters:
        - $ref: '#/components/parameters/levelParam'
        - name: warningType
          in: query
          description: 预警类型
          schema:
            type: string
            enum:
              - 证书过期
              - 证书临期
              - 社保异常
              - 人员离职
              - 信息变更
        - name: sourceModule
          in: query
          description: 来源模块
          schema:
            type: string
            example: 评价师信息管理
        - name: keyword
          in: query
          description: 标题/预警编号/预警内容关键字
          schema:
            type: string
        - name: onlyUntreated
          in: query
          description: 仅未处理（未处理/待确认/处理中）
          schema:
            type: boolean
            default: true
        - name: limit
          in: query
          description: 返回条数上限
          schema:
            type: integer
            default: 2
            minimum: 1
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseRegulatorRiskPriorityAlertList'
              example:
                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: 未处理

  /safetyEval/regulator/risk-center/page:
    get:
      tags:
        - 监管端-风险预警中心
      summary: 分页查询预警消息
      description: |
        消息列表分页查询，支持搜索栏与 Tab 筛选。

        Tab 对应关系：
        - 全部消息：`filterKind=all` 或不传
        - 紧急：`filterKind=urgent`
        - 未读/未处理：`filterKind=unread`
      operationId: regulatorRiskPage
      parameters:
        - name: keyword
          in: query
          description: 机构/人员/项目/预警编号
          schema:
            type: string
        - name: warningType
          in: query
          description: 预警类型
          schema:
            type: string
            enum:
              - 证书过期
              - 证书临期
              - 社保异常
              - 人员离职
              - 信息变更
        - $ref: '#/components/parameters/levelParam'
        - name: processStatus
          in: query
          description: 处理状态
          schema:
            type: string
            enum:
              - 未处理
              - 处理中
              - 已处理
        - $ref: '#/components/parameters/currentParam'
        - $ref: '#/components/parameters/sizeParam'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponseRegulatorRiskMessageCO'
              example:
                success: true
                code: "0"
                total: 4
                data:
                  - id: W-2026-008
                    warningType: 证书过期
                    level: urgent
                    levelName: 紧急
                    sourceModule: 评价师信息管理
                    sourceFields:
                      - 人员姓名
                      - 证书类型
                      - 有效期至
                    content: 张建国一级安全评价师证书已过期，机构未上传延续材料。
                    status: 未处理
                    sourceModuleKey: evaluator

  /safetyEval/regulator/risk-center/handle:
    post:
      tags:
        - 监管端-风险预警中心
      summary: 处置预警
      description: |
        处理弹窗提交、列表行内「闭环」「发函」「提醒」等操作。

        status 自动推断规则（未传 status 时）：
        - handleType 含「闭环」→ 已闭环
        - handleType 含「发函」→ 已发函
        - handleType 含「提醒」→ 已提醒
        - handleType 含「转办」「转备案」→ 处理中
        - 其他 → 已处置
      operationId: regulatorRiskHandle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegulatorRiskHandleCmd'
            example:
              id: W-2026-008
              handleType: 标记闭环
              deadline: "2026-07-18"
              opinion: 请核查证书延续材料
              status: 已闭环
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseRegulatorRiskMessageCO'
              example:
                success: true
                code: "0"
                data:
                  id: W-2026-008
                  warningType: 证书过期
                  level: urgent
                  levelName: 紧急
                  sourceModule: 评价师信息管理
                  sourceFields:
                    - 人员姓名
                    - 证书类型
                    - 有效期至
                  content: 张建国一级安全评价师证书已过期，机构未上传延续材料。
                  status: 已闭环
                  sourceModuleKey: evaluator
        '404':
          description: 预警不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseError'
              example:
                success: false
                code: "404"
                message: 预警不存在
                errMessage: 预警不存在

components:
  parameters:
    levelParam:
      name: level
      in: query
      description: 等级编码
      schema:
        type: string
        enum:
          - urgent
          - important
          - normal
        default: urgent
    currentParam:
      name: current
      in: query
      description: 当前页
      schema:
        type: integer
        format: int64
        default: 1
        minimum: 1
    sizeParam:
      name: size
      in: query
      description: 每页条数
      schema:
        type: integer
        format: int64
        default: 10
        minimum: 1

  schemas:
    # ---------- 通用响应 ----------
    SingleResponseError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          example: "404"
        message:
          type: string
        errMessage:
          type: string

    SingleResponseRegulatorRiskOverviewCO:
      type: object
      properties:
        success:
          type: boolean
          example: true
        code:
          type: string
          example: "0"
        message:
          type: string
        errMessage:
          type: string
        data:
          $ref: '#/components/schemas/RegulatorRiskOverviewCO'

    SingleResponseRegulatorRiskPriorityAlertList:
      type: object
      properties:
        success:
          type: boolean
          example: true
        code:
          type: string
          example: "0"
        message:
          type: string
        errMessage:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/RegulatorRiskPriorityAlertCO'

    SingleResponseRegulatorRiskMessageCO:
      type: object
      properties:
        success:
          type: boolean
          example: true
        code:
          type: string
          example: "0"
        message:
          type: string
        errMessage:
          type: string
        data:
          $ref: '#/components/schemas/RegulatorRiskMessageCO'

    PageResponseRegulatorRiskMessageCO:
      type: object
      properties:
        success:
          type: boolean
          example: true
        code:
          type: string
          example: "0"
        message:
          type: string
        errMessage:
          type: string
        total:
          type: integer
          format: int64
          description: 总条数
          example: 8
        data:
          type: array
          items:
            $ref: '#/components/schemas/RegulatorRiskMessageCO'

    # ---------- 业务模型 ----------
    RegulatorRiskOverviewCO:
      type: object
      description: 页面概览
      properties:
        stats:
          type: array
          description: 统计卡片
          items:
            $ref: '#/components/schemas/StatCardCO'
        processGuide:
          type: string
          description: 消息处理动作说明

    StatCardCO:
      type: object
      properties:
        label:
          type: string
          description: 标签
          example: 未处理预警
        value:
          type: string
          description: 数值
          example: "5"
        hint:
          type: string
          description: 提示
          example: 需监管人员处置

    RegulatorRiskPriorityAlertCO:
      type: object
      description: 高优先级预警消息
      properties:
        title:
          type: string
          description: 标题
          example: 评价师证书已过期
        description:
          type: string
          description: 描述（含来源与触发规则）
        messageId:
          type: string
          description: 关联预警编号
          example: W-2026-008
        level:
          type: string
          description: 展示级别
          enum:
            - danger
            - warning
            - info
          example: danger
        warningType:
          type: string
          description: 预警类型
          example: 证书过期
        sourceModule:
          type: string
          description: 来源模块
          example: 评价师信息管理
        status:
          type: string
          description: 当前状态
          example: 未处理

    RegulatorRiskMessageCO:
      type: object
      description: 预警消息
      properties:
        id:
          type: string
          description: 预警编号
          example: W-2026-008
        warningType:
          type: string
          description: 预警类型
          enum:
            - 证书过期
            - 证书临期
            - 社保异常
            - 人员离职
            - 信息变更
        level:
          type: string
          description: 等级编码
          enum:
            - urgent
            - important
            - normal
        levelName:
          type: string
          description: 等级名称
          enum:
            - 紧急
            - 重要
            - 一般
        sourceModule:
          type: string
          description: 来源模块
        sourceFields:
          type: array
          description: 来源字段
          items:
            type: string
        content:
          type: string
          description: 预警内容
        status:
          type: string
          description: 状态
          enum:
            - 未处理
            - 处理中
            - 待确认
            - 已闭环
            - 已发函
            - 已提醒
            - 已处置
        sourceModuleKey:
          type: string
          description: 来源模块跳转标识
          enum:
            - evaluator
            - qual-monitor
            - qual-change
            - institution-account

    RegulatorRiskHandleCmd:
      type: object
      description: 预警处置请求
      required:
        - id
        - handleType
      properties:
        id:
          type: string
          description: 预警编号
          example: W-2026-008
        handleType:
          type: string
          description: 处置方式
          example: 标记闭环
        deadline:
          type: string
          format: date
          description: 办理期限 yyyy-MM-dd
          example: "2026-07-18"
        opinion:
          type: string
          description: 处置意见
          example: 请核查证书延续材料
        status:
          type: string
          description: 处置后状态（不传则根据 handleType 自动推断）
          example: 已闭环