openapi: 3.0.3
info:
  title: 监管端-驾驶舱大屏 API
  description: |
    重庆市安全评价服务平台 - 监管端「驾驶舱大屏」页面接口（`/container/driver` → 监管端 Cockpit）。

    - 统一前缀：`/safetyEval/regulator/cockpit`
    - 全部为**新增**聚合接口（落在 `RegulatorCockpitController`），不依赖/不改动既有监管端接口
    - 成功响应 `code = "0"`
    - 大屏建议对 7 个接口加 30~60s 短 TTL 缓存，降低 DB 压力；面板级接口相互独立，单接口异常不影响其余面板

    **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/cockpit/qualification-overview:
    get:
      tags:
        - 监管端-驾驶舱大屏
      summary: 资质全生命周期管理
      description: |
        资质全生命周期统计：机构备案、评价师、行业分布。

        - 数据源：`org_info`、`org_personnel`、`IndustryEnum`
        - 边界：仅机构/人员/资质维度，不含项目与风险
        - 已知缺口：`logoutOrgCount` 现有字典无「注销」状态，暂置 0（待补来源）
      operationId: qualificationOverview
      parameters:
        - $ref: '#/components/parameters/yearParam'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseCockpitQualificationOverviewCO'
              example:
                success: true
                code: "0"
                data:
                  lifecycleStats:
                    newFilingOrgCount: 12
                    currentFilingOrgCount: 86
                    logoutOrgCount: 0
                    totalFilingOrgCount: 120
                    exitedEvaluatorCount: 5
                    currentEvaluatorCount: 340
                  progress:
                    filingCompleteRate: 71.67
                    bizActiveRate: 63.95
                    newGrowthRate: 13.95
                  industryList:
                    - industryCode: "1"
                      industryName: 危险化学品
                      orgCount: 32
                      typeCount: 32
                    - industryCode: "2"
                      industryName: 非煤矿山
                      orgCount: 24
                      typeCount: 24
                    - industryCode: "3"
                      industryName: 金属冶炼
                      orgCount: 18
                      typeCount: 18

  /safetyEval/regulator/cockpit/kpi:
    get:
      tags:
        - 监管端-驾驶舱大屏
      summary: 核心KPI指标
      description: |
        核心 KPI 统计，仅提供「备案项目开展评价率」（现有数据源可支撑）。

        - 数据源：`eval_project`（`is_statutory=1`）、`eval_risk_analysis`（风险分析已建立=已开展评价）
        - 边界：**不提供**「企业评价项目合格率」（无合格状态字段）、「隐患整改率」（无隐患表）
        - `value`=率值（百分比）；`yoy`=当前周期率 − 上一周期率（百分点）
      operationId: kpi
      parameters:
        - name: cycle
          in: query
          description: 统计周期
          schema:
            type: string
            enum:
              - year
              - quarter
              - month
            default: year
        - $ref: '#/components/parameters/yearParam'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseCockpitKpiCO'
              example:
                success: true
                code: "0"
                data:
                  items:
                    - code: EVAL_RATE
                      name: 备案项目开展评价率
                      value: 78.5
                      yoy: 4.2

  /safetyEval/regulator/cockpit/region-distribution:
    get:
      tags:
        - 监管端-驾驶舱大屏
      summary: 区域地图分布
      description: |
        按区县统计评价项目数与备案机构数。

        - 数据源：`eval_project.district_code`（法定项目按区县计数）、`org_info.district_code`（已备案机构按区县计数）
        - 边界：仅「评价项目数」「备案机构数」两维度；隐患/整改率无数据源，前端可用项目数替代
        - 两路按 `district_code` 分组后对齐，缺侧补 0
      operationId: regionDistribution
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseCockpitRegionDistributionCO'
              example:
                success: true
                code: "0"
                data:
                  list:
                    - districtCode: "500101"
                      districtName: 万州区
                      evalProjectCount: 45
                      filingOrgCount: 8
                    - districtCode: "500103"
                      districtName: 渝中区
                      evalProjectCount: 32
                      filingOrgCount: 6
                  summary:
                    totalEvalProject: 520
                    totalFilingOrg: 86

  /safetyEval/regulator/cockpit/process-overview:
    get:
      tags:
        - 监管端-驾驶舱大屏
      summary: 执业全过程管控 + 项目流程（节点聚合）
      description: |
        执业全过程管控与项目流程节点聚合统计。

        - 数据源：复用 `EvalProjectNodeOverviewAssembler.buildForRegulator(projectId)` 逐项目取节点状态，全局累加
        - `totalCount`=到达该节点项目数（状态≠未开始）；`pendingCount`=未开始（待办）项目数
        - 覆盖 8 个真实节点（风险分析/合同签订/成立项目组/现场勘查/过程管控/报告草稿/内审/技审）；大屏额外的「初勘/从业告知/编制检查表/制定工作计划/归档」无独立实体，由前端并入相邻节点或留空
      operationId: processOverview
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseCockpitProcessOverviewCO'
              example:
                success: true
                code: "0"
                data:
                  nodes:
                    - nodeCode: RISK_ANALYSIS
                      nodeName: 风险分析
                      totalCount: 480
                      pendingCount: 40
                    - nodeCode: CONTRACT_SIGN
                      nodeName: 合同签订
                      totalCount: 455
                      pendingCount: 25
                    - nodeCode: GROUP_SETUP
                      nodeName: 成立项目组
                      totalCount: 450
                      pendingCount: 15
                    - nodeCode: SITE_SURVEY
                      nodeName: 现场勘查
                      totalCount: 430
                      pendingCount: 30
                    - nodeCode: PROCESS_CONTROL
                      nodeName: 过程管控
                      totalCount: 400
                      pendingCount: 50
                    - nodeCode: REPORT_DRAFT
                      nodeName: 报告草稿
                      totalCount: 360
                      pendingCount: 40
                    - nodeCode: INTERNAL_REVIEW
                      nodeName: 内审
                      totalCount: 330
                      pendingCount: 20
                    - nodeCode: TECH_REVIEW
                      nodeName: 技审
                      totalCount: 310
                      pendingCount: 10

  /safetyEval/regulator/cockpit/eval-type-trend:
    get:
      tags:
        - 监管端-驾驶舱大屏
      summary: 评价类型趋势
      description: |
        按评价类型统计各时间桶的项目数与监督检查数。

        - 数据源：`eval_project.eval_type_code`/`create_time`、`insp_notice.create_time`/`project_id`
        - `projectCounts` 来自 `eval_project` 按 `eval_type_code`+时间桶；`inspCounts` 来自 `insp_notice` 经 `project_id` 关联 `eval_project` 的 `eval_type_code`+时间桶
        - 时间桶：月=01..12；季=Q1..Q4；月粒度=`period=month` 时按 `year` 的 1..12
        - 仅统计能关联到项目的检查
      operationId: evalTypeTrend
      parameters:
        - name: period
          in: query
          required: true
          description: 时间粒度
          schema:
            type: string
            enum:
              - year
              - quarter
              - month
        - $ref: '#/components/parameters/yearParam'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseCockpitEvalTypeTrendCO'
              example:
                success: true
                code: "0"
                data:
                  buckets:
                    - "01"
                    - "02"
                    - "03"
                    - "04"
                  series:
                    - evalTypeCode: "1"
                      evalTypeName: 安全预评价
                      projectCounts: [12, 15, 10, 18]
                      inspCounts: [20, 25, 18, 30]
                    - evalTypeCode: "2"
                      evalTypeName: 安全验收评价
                      projectCounts: [8, 9, 11, 7]
                      inspCounts: [15, 18, 20, 12]

  /safetyEval/regulator/cockpit/review-summary:
    get:
      tags:
        - 监管端-驾驶舱大屏
      summary: 复盘评估改进提效
      description: |
        复盘评估统计：监督检查分类、发现问题、超期/处罚分布。

        - 数据源：`insp_notice`、`eval_project`（`plan_end_date` 逾期、未归档）
        - 检查类按 `insp_type_code` 与 `result_code` 分组：`insp_type_code` ∈ PROJECT_PROCESS/QUAL_KEEP/SPECIAL；`result_code` 1未发现问题/2责令整改/3转入风险预警
        - `pie` 仅输出可用的 OVERDUE（超期未完成数）、PUNISH（监管处罚数=resultCode=3）；原大屏「现场确认风险隐患数/复查评估报告数/项目主要负责人变更数」无现成数据源，本次不输出
      operationId: reviewSummary
      parameters:
        - $ref: '#/components/parameters/yearParam'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseCockpitReviewSummaryCO'
              example:
                success: true
                code: "0"
                data:
                  stats:
                    inspCount: 320
                    onsiteCheckCount: 180
                    qualKeepCount: 90
                    specialCount: 50
                    checkedOrgCount: 60
                    foundProblemCount: 75
                  pie:
                    - code: OVERDUE
                      name: 超期未完成
                      value: 28
                    - code: PUNISH
                      name: 监管处罚
                      value: 12

  /safetyEval/regulator/cockpit/project-monitor:
    get:
      tags:
        - 监管端-驾驶舱大屏
      summary: 项目实时监控
      description: |
        项目实时监控与踏勘/打卡统计。

        - 数据源：`eval_project`、`eval_project_process_waring`、复用既有 `selectRegulatorSurveyStat()`
        - `warningCount`=存在过程预警的项目数（**真实计算，替代原硬编码 0**），调用 `EvalProjectProcessWaringGateway.checkProjectHasWaring(projectId)`
        - `survey` 四项（告知书/打卡）复用既有聚合 SQL；监控/预警/计划完成数为本次新实现
      operationId: projectMonitor
      parameters:
        - name: month
          in: query
          required: false
          description: 统计月份（yyyy-MM，默认当前月）
          schema:
            type: string
            example: "2026-07"
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseCockpitProjectMonitorCO'
              example:
                success: true
                code: "0"
                data:
                  monitor:
                    activeProjectCount: 520
                    normalExecCount: 480
                    warningCount: 36
                    monthPlanFinishCount: 45
                  survey:
                    noticeArchived: 500
                    noticeAbnormal: 12
                    clockInNormal: 980
                    clockInAbnormal: 25

components:
  parameters:
    yearParam:
      name: year
      in: query
      required: false
      description: 统计年份（默认当前年）
      schema:
        type: integer
        format: int32
        example: 2026

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

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

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

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

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

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

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

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

    # ---------- 业务模型 ----------
    CockpitQualificationOverviewCO:
      type: object
      description: 资质全生命周期管理
      properties:
        lifecycleStats:
          $ref: '#/components/schemas/LifecycleStat'
        progress:
          $ref: '#/components/schemas/Progress'
        industryList:
          type: array
          description: 行业分布（机构数）
          items:
            $ref: '#/components/schemas/IndustryItem'

    LifecycleStat:
      type: object
      description: 生命周期核心指标
      properties:
        newFilingOrgCount:
          type: integer
          format: int32
          description: 本年新增备案机构数
        currentFilingOrgCount:
          type: integer
          format: int32
          description: 当前备案机构数
        logoutOrgCount:
          type: integer
          format: int32
          description: 本年注销机构数（现有字典无注销状态，暂置 0，待补源）
        totalFilingOrgCount:
          type: integer
          format: int32
          description: 全部备案机构数
        exitedEvaluatorCount:
          type: integer
          format: int32
          description: 退出备案评价师数
        currentEvaluatorCount:
          type: integer
          format: int32
          description: 当前备案评价师数

    Progress:
      type: object
      description: 完成率/开展率/新增率（百分比）
      properties:
        filingCompleteRate:
          type: number
          format: double
          description: 备案完成率
        bizActiveRate:
          type: number
          format: double
          description: 开展业务率
        newGrowthRate:
          type: number
          format: double
          description: 新增率

    IndustryItem:
      type: object
      description: 行业分布项
      properties:
        industryCode:
          type: string
          description: 行业编码
        industryName:
          type: string
          description: 行业名称
        orgCount:
          type: integer
          format: int32
          description: 机构数
        typeCount:
          type: integer
          format: int32
          description: 类型数（口径待定，暂与机构数一致）

    CockpitKpiCO:
      type: object
      description: 核心KPI指标
      properties:
        items:
          type: array
          description: KPI指标列表
          items:
            $ref: '#/components/schemas/KpiItem'

    KpiItem:
      type: object
      description: KPI指标项
      properties:
        code:
          type: string
          description: 指标编码
          example: EVAL_RATE
        name:
          type: string
          description: 指标名称
          example: 备案项目开展评价率
        value:
          type: number
          format: double
          description: 当前值（百分比）
        yoy:
          type: number
          format: double
          description: 同比（百分点）

    CockpitRegionDistributionCO:
      type: object
      description: 区域地图分布
      properties:
        list:
          type: array
          description: 各区县分布
          items:
            $ref: '#/components/schemas/DistrictItem'
        summary:
          $ref: '#/components/schemas/RegionSummary'

    DistrictItem:
      type: object
      description: 区县分布项
      properties:
        districtCode:
          type: string
          description: 区县编码
        districtName:
          type: string
          description: 区县名称
        evalProjectCount:
          type: integer
          format: int32
          description: 评价项目数
        filingOrgCount:
          type: integer
          format: int32
          description: 备案机构数

    RegionSummary:
      type: object
      description: 汇总
      properties:
        totalEvalProject:
          type: integer
          format: int32
          description: 评价项目总数
        totalFilingOrg:
          type: integer
          format: int32
          description: 备案机构总数

    CockpitProcessOverviewCO:
      type: object
      description: 执业全过程管控 + 项目流程（节点聚合）
      properties:
        nodes:
          type: array
          description: 节点聚合（totalCount=到达该节点项目数；pendingCount=未开始/待办项目数）
          items:
            $ref: '#/components/schemas/NodeItem'

    NodeItem:
      type: object
      description: 节点项
      properties:
        nodeCode:
          type: string
          description: 节点编码
        nodeName:
          type: string
          description: 节点名称
        totalCount:
          type: integer
          format: int32
          description: 到达该节点项目数
        pendingCount:
          type: integer
          format: int32
          description: 待办（未开始）项目数

    CockpitEvalTypeTrendCO:
      type: object
      description: 评价类型趋势
      properties:
        buckets:
          type: array
          description: 时间桶（月=01..12；季=Q1..Q4；月粒度=01..月末）
          items:
            type: string
        series:
          type: array
          description: 各评价类型序列
          items:
            $ref: '#/components/schemas/EvalTypeSeries'

    EvalTypeSeries:
      type: object
      description: 评价类型趋势序列
      properties:
        evalTypeCode:
          type: string
          description: 评价类型编码
        evalTypeName:
          type: string
          description: 评价类型名称
        projectCounts:
          type: array
          description: 项目数（与 buckets 对齐）
          items:
            type: integer
            format: int32
        inspCounts:
          type: array
          description: 监督检查数（与 buckets 对齐）
          items:
            type: integer
            format: int32

    CockpitReviewSummaryCO:
      type: object
      description: 复盘评估改进提效
      properties:
        stats:
          $ref: '#/components/schemas/ReviewStat'
        pie:
          type: array
          description: 饼图分布
          items:
            $ref: '#/components/schemas/ReviewPieItem'

    ReviewStat:
      type: object
      description: 检查类统计
      properties:
        inspCount:
          type: integer
          format: int32
          description: 监督检查总数
        onsiteCheckCount:
          type: integer
          format: int32
          description: 项目过程检查数
        qualKeepCount:
          type: integer
          format: int32
          description: 资质保持检查数
        specialCount:
          type: integer
          format: int32
          description: 专项检查数
        checkedOrgCount:
          type: integer
          format: int32
          description: 检查机构数（去重）
        foundProblemCount:
          type: integer
          format: int32
          description: 发现问题数（resultCode=2/3）

    ReviewPieItem:
      type: object
      description: 饼图分布项
      properties:
        code:
          type: string
          description: 编码
          enum:
            - OVERDUE
            - PUNISH
        name:
          type: string
          description: 名称
          enum:
            - 超期未完成
            - 监管处罚
        value:
          type: integer
          format: int32
          description: 数值

    CockpitProjectMonitorCO:
      type: object
      description: 项目实时监控
      properties:
        monitor:
          $ref: '#/components/schemas/ProjectMonitor'
        survey:
          $ref: '#/components/schemas/SurveyStat'

    ProjectMonitor:
      type: object
      description: 项目监控核心指标
      properties:
        activeProjectCount:
          type: integer
          format: int32
          description: 在监项目数
        normalExecCount:
          type: integer
          format: int32
          description: 正常执行数
        warningCount:
          type: integer
          format: int32
          description: 预警数（基于过程预警真实计算）
        monthPlanFinishCount:
          type: integer
          format: int32
          description: 本月计划完成数

    SurveyStat:
      type: object
      description: 踏勘/打卡统计
      properties:
        noticeArchived:
          type: integer
          format: int32
          description: 告知书已归档数
        noticeAbnormal:
          type: integer
          format: int32
          description: 告知异常数
        clockInNormal:
          type: integer
          format: int32
          description: 人员打卡正常数
        clockInAbnormal:
          type: integer
          format: int32
          description: 打卡异常数