openapi: 3.0.3
info:
  title: 监督检查告知 / 通知 API
  description: |
    对齐原型：
    - 监管端 `mod-inspection-notice`（监督检查告知）
    - 机构端消息入口 `reg-message` 中 `bizType=insp_notice` 的办理能力

    ## 原型能力对照（监管）
    | 原型 | 后端 |
    |------|------|
    | 筛选编号/机构/类型/来源/预警号/负责人/时间/确认/反馈/状态 | `GET .../regulator/insp-notice/page` |
    | 列表含机构名、来源预警号、确认与反馈 | `RegulatorInspNoticeCO` |
    | 新建/编辑待下发 | `POST .../save` |
    | 下发 | `POST .../issue`（新建或 `id` 下发草稿） |
    | 查看 / 保存备注 | `GET .../get`、`POST .../remark` |
    | 登记结果 | `POST .../close` |
    | 提醒 | `POST .../urge` |
    | 下载记录 | `GET .../download-record` |
    | 导出台账 | `POST .../export-ledger` |
    | 材料只读 | `GET .../materials` |

    ## 原型能力对照（机构 · insp_notice）
    | 能力 | 后端 |
    |------|------|
    | 本机构告知列表/详情 | `GET .../institution/insp-notice/page|get` |
    | 确认 / 上传材料 / 反馈 | `POST .../confirm|material/upload|feedback` |
    | 材料列表 | `GET .../materials` |

    **说明**：机构端原型「监督检查通知」整页还聚合风险预警类整改/核查/补正消息，不在本文件范围内。

    **字典**
    - 状态：`0待下发 1已下发 2已确认 3已反馈 4已办结`（原型「已完成」=`4`）
    - 来源：`1年度计划 2专项安排 3其他 4风险预警`
    - 结果：`1未发现问题/合格 2责令整改/不合格 3转入风险预警/限期整改`
    - 确认/反馈：`1是/已提交 2否/未提交`

    **Apifox 导入**：项目设置 → 导入数据 → OpenAPI → 选择本文件。

    成功：`success=true` 且 `code="0"`（文件流接口直接返回附件，失败时返回 JSON）
  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: 告知新建/下发/跟踪/办结/导出
  - name: 机构端-监督检查告知
    description: 确认、材料反馈、查看结果

paths:
  /safetyEval/regulator/insp-notice/save:
    post:
      tags: [监管端-监督检查告知]
      summary: 暂存/编辑待下发告知
      operationId: regulatorInspNoticeSave
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegulatorInspNoticeSaveCmd'
            example:
              orgId: 10001
              inspTypeCode: SPECIAL
              inspTypeName: 专项检查
              sourceTypeCode: 1
              sourceTypeName: 年度计划
              planInspTime: "2026-08-05T09:00:00"
              leaderName: 周强
              noticeContent: 请准备专项检查材料
              materialNames: [项目过程记录, 人员到场记录]
      responses:
        '200':
          description: 成功（status=0 待下发）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseRegulatorInspNoticeCO'

  /safetyEval/regulator/insp-notice/issue:
    post:
      tags: [监管端-监督检查告知]
      summary: 新建并下发，或下发草稿
      description: |
        - 传 `id`：将 status=0 草稿下发为已下发，并推送机构消息
        - 不传 `id`：直接新建并下发（需 `orgId`）
      operationId: regulatorInspNoticeIssue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegulatorInspNoticeIssueCmd'
            examples:
              issueDraft:
                summary: 下发草稿
                value: { id: 20001 }
              createAndIssue:
                summary: 新建并下发
                value:
                  orgId: 10001
                  inspTypeCode: PROJECT_PROCESS
                  inspTypeName: 项目过程检查
                  sourceTypeCode: 4
                  sourceTypeName: 风险预警
                  sourceRefNo: W-PROJ-2026-009
                  planInspTime: "2026-07-22T09:30:00"
                  leaderName: 刘敏
                  noticeContent: 请准备项目过程记录、人员到场记录及相关证明材料
                  materialNames: [联系人及准备材料清单]
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseRegulatorInspNoticeCO'

  /safetyEval/regulator/insp-notice/page:
    get:
      tags: [监管端-监督检查告知]
      summary: 分页查询告知
      operationId: regulatorInspNoticePage
      parameters:
        - $ref: '#/components/parameters/current'
        - $ref: '#/components/parameters/size'
        - name: noticeNo
          in: query
          schema: { type: string }
        - name: orgId
          in: query
          schema: { type: integer, format: int64 }
        - name: orgName
          in: query
          description: 评价机构名称（模糊）
          schema: { type: string }
        - name: keyword
          in: query
          schema: { type: string }
        - name: inspTypeCode
          in: query
          schema: { type: string, enum: [PROJECT_PROCESS, QUAL_KEEP, SPECIAL] }
        - name: sourceTypeCode
          in: query
          schema: { type: integer, enum: [1, 2, 3, 4] }
        - name: sourceRefNo
          in: query
          description: 来源预警编号
          schema: { type: string }
        - name: leaderName
          in: query
          schema: { type: string }
        - name: planInspTimeStart
          in: query
          description: yyyy-MM-dd
          schema: { type: string }
        - name: planInspTimeEnd
          in: query
          description: yyyy-MM-dd
          schema: { type: string }
        - name: confirmFlag
          in: query
          description: 1已确认 2未确认
          schema: { type: integer, enum: [1, 2] }
        - name: feedbackFlag
          in: query
          description: 1已提交 2未提交
          schema: { type: integer, enum: [1, 2] }
        - name: statusCode
          in: query
          description: 0待下发 1已下发 2已确认 3已反馈 4已办结
          schema: { type: integer, enum: [0, 1, 2, 3, 4] }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponseRegulatorInspNoticeCO'

  /safetyEval/regulator/insp-notice/get:
    get:
      tags: [监管端-监督检查告知]
      summary: 查询告知详情
      operationId: regulatorInspNoticeGet
      parameters:
        - name: id
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseRegulatorInspNoticeCO'

  /safetyEval/regulator/insp-notice/close:
    post:
      tags: [监管端-监督检查告知]
      summary: 登记结果并办结
      description: 前置状态须为已确认(2)或已反馈(3)
      operationId: regulatorInspNoticeClose
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegulatorInspNoticeCloseCmd'
            example:
              id: 20001
              resultCode: 2
              resultName: 责令整改
              resultContent: 现场检查发现问题，限期整改
              resultUrls: ["https://example.com/record.pdf"]
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseRegulatorInspNoticeCO'

  /safetyEval/regulator/insp-notice/remark:
    post:
      tags: [监管端-监督检查告知]
      summary: 保存监管备注
      operationId: regulatorInspNoticeRemark
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegulatorInspNoticeRemarkCmd'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseRegulatorInspNoticeCO'

  /safetyEval/regulator/insp-notice/materials:
    get:
      tags: [监管端-监督检查告知]
      summary: 材料只读列表
      operationId: regulatorInspNoticeMaterials
      parameters:
        - name: noticeId
          in: query
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseInspNoticeMaterialCOList'

  /safetyEval/regulator/insp-notice/urge:
    post:
      tags: [监管端-监督检查告知]
      summary: 催办（重发机构消息）
      operationId: regulatorInspNoticeUrge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegulatorInspNoticeUrgeCmd'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseVoid'

  /safetyEval/regulator/insp-notice/export-ledger:
    post:
      tags: [监管端-监督检查告知]
      summary: 导出台账（CSV）
      description: 勾选优先；否则按筛选；最多 5000 行。直接下载文件。
      operationId: regulatorInspNoticeExportLedger
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegulatorInspNoticeExportCmd'
      responses:
        '200':
          description: CSV 文件流；失败时 JSON
          content:
            text/csv:
              schema: { type: string, format: binary }
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseBase'

  /safetyEval/regulator/insp-notice/download-record:
    get:
      tags: [监管端-监督检查告知]
      summary: 下载检查记录（CSV）
      operationId: regulatorInspNoticeDownloadRecord
      parameters:
        - name: id
          in: query
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: CSV 文件流；失败时 JSON
          content:
            text/csv:
              schema: { type: string, format: binary }
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseBase'

  /safetyEval/institution/insp-notice/page:
    get:
      tags: [机构端-监督检查告知]
      summary: 分页查询本机构告知（不含待下发草稿）
      operationId: institutionInspNoticePage
      parameters:
        - $ref: '#/components/parameters/current'
        - $ref: '#/components/parameters/size'
        - name: noticeNo
          in: query
          schema: { type: string }
        - name: keyword
          in: query
          schema: { type: string }
        - name: inspTypeCode
          in: query
          schema: { type: string }
        - name: sourceTypeCode
          in: query
          schema: { type: integer }
        - name: sourceRefNo
          in: query
          schema: { type: string }
        - name: confirmFlag
          in: query
          schema: { type: integer }
        - name: feedbackFlag
          in: query
          schema: { type: integer }
        - name: statusCode
          in: query
          description: 1已下发 2已确认 3已反馈 4已办结
          schema: { type: integer, enum: [1, 2, 3, 4] }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponseInstitutionInspNoticeCO'

  /safetyEval/institution/insp-notice/get:
    get:
      tags: [机构端-监督检查告知]
      summary: 查询告知详情
      operationId: institutionInspNoticeGet
      parameters:
        - name: id
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseInstitutionInspNoticeCO'

  /safetyEval/institution/insp-notice/confirm:
    post:
      tags: [机构端-监督检查告知]
      summary: 确认告知
      description: 前置 status=1 已下发 → 2 已确认
      operationId: institutionInspNoticeConfirm
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: integer, format: int64 }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseInstitutionInspNoticeCO'

  /safetyEval/institution/insp-notice/material/upload:
    post:
      tags: [机构端-监督检查告知]
      summary: 上传材料（仅 URL）
      description: 前置告知状态为已确认或已反馈
      operationId: institutionInspNoticeMaterialUpload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstitutionInspNoticeMaterialUploadCmd'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseInspNoticeMaterialCO'

  /safetyEval/institution/insp-notice/feedback:
    post:
      tags: [机构端-监督检查告知]
      summary: 提交材料反馈
      description: 前置 status=2；必填材料须已上传
      operationId: institutionInspNoticeFeedback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstitutionInspNoticeFeedbackCmd'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseInstitutionInspNoticeCO'

  /safetyEval/institution/insp-notice/materials:
    get:
      tags: [机构端-监督检查告知]
      summary: 材料列表
      operationId: institutionInspNoticeMaterials
      parameters:
        - name: noticeId
          in: query
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseInspNoticeMaterialCOList'

components:
  parameters:
    current:
      name: current
      in: query
      schema: { type: integer, format: int64, default: 1 }
    size:
      name: size
      in: query
      schema: { type: integer, format: int64, default: 10 }

  schemas:
    SingleResponseBase:
      type: object
      properties:
        success: { type: boolean, example: true }
        code: { type: string, example: "0" }
        errMessage: { type: string, nullable: true }
        traceId: { type: string, nullable: true }

    RegulatorInspNoticeCO:
      type: object
      properties:
        id: { type: string }
        orgId: { type: string }
        orgName: { type: string, description: 评价机构名称 }
        noticeNo: { type: string, example: JC2026000018 }
        inspTypeCode: { type: string, example: PROJECT_PROCESS }
        inspTypeName: { type: string, example: 项目过程检查 }
        sourceTypeCode: { type: integer, example: 4 }
        sourceTypeName: { type: string, example: 风险预警 }
        sourceRefId: { type: string }
        sourceRefNo: { type: string, example: W-PROJ-2026-009 }
        projectId: { type: string }
        planInspTime: { type: string, format: date-time }
        leaderName: { type: string }
        noticeContent: { type: string }
        noticeUrls: { type: string }
        statusCode: { type: integer, example: 3 }
        statusName: { type: string, example: 已反馈 }
        confirmFlag: { type: integer, example: 1 }
        feedbackFlag: { type: integer, example: 1, description: 1已提交 2未提交 }
        confirmTime: { type: string, format: date-time }
        sendTime: { type: string, format: date-time }
        resultCode: { type: integer }
        resultName: { type: string }
        resultContent: { type: string }
        resultUrls: { type: string }
        resultRecorderName: { type: string }
        resultTime: { type: string, format: date-time }
        remarks: { type: string }

    InstitutionInspNoticeCO:
      type: object
      properties:
        id: { type: string }
        noticeNo: { type: string }
        inspTypeCode: { type: string }
        inspTypeName: { type: string }
        sourceTypeCode: { type: integer }
        sourceTypeName: { type: string }
        sourceRefNo: { type: string }
        planInspTime: { type: string, format: date-time }
        leaderName: { type: string }
        noticeContent: { type: string }
        noticeUrls: { type: string }
        statusCode: { type: integer }
        statusName: { type: string }
        confirmFlag: { type: integer }
        feedbackFlag: { type: integer }
        confirmTime: { type: string, format: date-time }
        sendTime: { type: string, format: date-time }
        resultCode: { type: integer }
        resultName: { type: string }
        resultContent: { type: string }
        resultUrls: { type: string }
        resultTime: { type: string, format: date-time }
        remarks: { type: string }

    InspNoticeMaterialCO:
      type: object
      properties:
        id: { type: string }
        noticeId: { type: string }
        materialName: { type: string }
        requiredFlag: { type: integer, description: 1必需 2非必需 }
        uploadStatusCode: { type: integer, description: 1待上传 2已上传 }
        uploadStatusName: { type: string }
        fileUrl: { type: string }

    RegulatorInspNoticeSaveCmd:
      type: object
      required: [orgId]
      properties:
        id: { type: integer, format: int64, description: 空=新建草稿，非空=编辑待下发 }
        orgId: { type: integer, format: int64 }
        inspTypeCode: { type: string }
        inspTypeName: { type: string }
        sourceTypeCode: { type: integer }
        sourceTypeName: { type: string }
        sourceRefId: { type: integer, format: int64 }
        sourceRefNo: { type: string }
        projectId: { type: integer, format: int64 }
        planInspTime: { type: string, format: date-time }
        leaderName: { type: string }
        noticeContent: { type: string }
        noticeUrls:
          type: array
          items: { type: string }
        remarks: { type: string }
        materialNames:
          type: array
          items: { type: string }
          description: 仅新建草稿时预置材料行

    RegulatorInspNoticeIssueCmd:
      type: object
      properties:
        id: { type: integer, format: int64, description: 传则下发草稿 }
        orgId: { type: integer, format: int64, description: 新建下发时必填 }
        inspTypeCode: { type: string }
        inspTypeName: { type: string }
        sourceTypeCode: { type: integer }
        sourceTypeName: { type: string }
        sourceRefId: { type: integer, format: int64 }
        sourceRefNo: { type: string }
        projectId: { type: integer, format: int64 }
        planInspTime: { type: string, format: date-time }
        leaderName: { type: string }
        noticeContent: { type: string }
        noticeUrls:
          type: array
          items: { type: string }
        remarks: { type: string }
        materialNames:
          type: array
          items: { type: string }

    RegulatorInspNoticeCloseCmd:
      type: object
      required: [id]
      properties:
        id: { type: integer, format: int64 }
        resultCode: { type: integer, description: "1未发现问题 2责令整改 3转入风险预警" }
        resultName: { type: string }
        resultContent: { type: string }
        resultUrls:
          type: array
          items: { type: string }

    RegulatorInspNoticeRemarkCmd:
      type: object
      required: [id]
      properties:
        id: { type: integer, format: int64 }
        remarks: { type: string }

    RegulatorInspNoticeUrgeCmd:
      type: object
      required: [id]
      properties:
        id: { type: integer, format: int64 }

    RegulatorInspNoticeExportCmd:
      type: object
      properties:
        ids:
          type: array
          items: { type: integer, format: int64 }
        scope: { type: string, enum: [SELECTED, FILTERED, ALL] }
        noticeNo: { type: string }
        orgId: { type: integer, format: int64 }
        orgName: { type: string }
        keyword: { type: string }
        inspTypeCode: { type: string }
        sourceTypeCode: { type: integer }
        sourceRefNo: { type: string }
        leaderName: { type: string }
        planInspTimeStart: { type: string }
        planInspTimeEnd: { type: string }
        confirmFlag: { type: integer }
        feedbackFlag: { type: integer }
        statusCode: { type: integer }

    InstitutionInspNoticeMaterialUploadCmd:
      type: object
      required: [materialId, fileUrl]
      properties:
        materialId: { type: integer, format: int64 }
        fileUrl: { type: string }

    InstitutionInspNoticeFeedbackCmd:
      type: object
      required: [id]
      properties:
        id: { type: integer, format: int64 }
        materials:
          type: array
          items:
            $ref: '#/components/schemas/InstitutionInspNoticeMaterialUploadCmd'

    SingleResponseRegulatorInspNoticeCO:
      allOf:
        - $ref: '#/components/schemas/SingleResponseBase'
        - type: object
          properties:
            data: { $ref: '#/components/schemas/RegulatorInspNoticeCO' }

    SingleResponseInstitutionInspNoticeCO:
      allOf:
        - $ref: '#/components/schemas/SingleResponseBase'
        - type: object
          properties:
            data: { $ref: '#/components/schemas/InstitutionInspNoticeCO' }

    PageResponseRegulatorInspNoticeCO:
      allOf:
        - $ref: '#/components/schemas/SingleResponseBase'
        - type: object
          properties:
            data:
              type: array
              items: { $ref: '#/components/schemas/RegulatorInspNoticeCO' }
            total: { type: integer, format: int64 }

    PageResponseInstitutionInspNoticeCO:
      allOf:
        - $ref: '#/components/schemas/SingleResponseBase'
        - type: object
          properties:
            data:
              type: array
              items: { $ref: '#/components/schemas/InstitutionInspNoticeCO' }
            total: { type: integer, format: int64 }

    SingleResponseInspNoticeMaterialCO:
      allOf:
        - $ref: '#/components/schemas/SingleResponseBase'
        - type: object
          properties:
            data: { $ref: '#/components/schemas/InspNoticeMaterialCO' }

    SingleResponseInspNoticeMaterialCOList:
      allOf:
        - $ref: '#/components/schemas/SingleResponseBase'
        - type: object
          properties:
            data:
              type: array
              items: { $ref: '#/components/schemas/InspNoticeMaterialCO' }

    SingleResponseVoid:
      allOf:
        - $ref: '#/components/schemas/SingleResponseBase'
        - type: object
          properties:
            data: { nullable: true }