openapi: 3.0.3
info:
  title: 监管任务结项API
  description: |
    保险端监管任务结项管理系统API接口文档
    
    ## 功能概述
    - 监管任务结项记录的增删改查
    - 任务审核流程管理
    - 附件上传和管理
    - 操作日志记录
    - 统计数据查询
    
    ## 认证方式
    使用JWT Bearer Token进行身份认证
    
    ## 响应格式
    所有API响应都遵循统一的格式：
    ```json
    {
      "code": 200,
      "message": "success",
      "data": {},
      "timestamp": "2025-01-19T10:00:00Z"
    }
    ```
  version: 1.0.0
  contact:
    name: 开发团队
    email: dev@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3000/api
    description: 开发环境
  - url: https://api.example.com/api
    description: 生产环境

security:
  - bearerAuth: []

paths:
  /regulatory-task-completion:
    get:
      tags:
        - 监管任务结项
      summary: 获取监管任务结项列表
      description: 分页查询监管任务结项记录，支持多条件筛选
      parameters:
        - name: application_no
          in: query
          description: 申请编号（模糊查询）
          schema:
            type: string
            example: "APP20250119"
        - name: policy_no
          in: query
          description: 保单号（模糊查询）
          schema:
            type: string
            example: "POL20250119"
        - name: product_name
          in: query
          description: 产品名称（模糊查询）
          schema:
            type: string
            example: "养殖保险"
        - name: customer_name
          in: query
          description: 客户名称（模糊查询）
          schema:
            type: string
            example: "张三"
        - name: completion_date
          in: query
          description: 结项日期
          schema:
            type: string
            format: date
            example: "2025-01-19"
        - name: status
          in: query
          description: 状态筛选
          schema:
            type: string
            enum: [pending, approved, rejected, completed]
            example: "pending"
        - name: reviewer_name
          in: query
          description: 审核人员（模糊查询）
          schema:
            type: string
            example: "审核员"
        - name: page
          in: query
          description: 页码
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: limit
          in: query
          description: 每页数量
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            example: 10
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      list:
                        type: array
                        items:
                          $ref: '#/components/schemas/RegulatoryTaskCompletion'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                  timestamp:
                    type: string
                    format: date-time
                    example: "2025-01-19T10:00:00Z"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    post:
      tags:
        - 监管任务结项
      summary: 创建监管任务结项记录
      description: 创建新的监管任务结项记录
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRegulatoryTaskCompletionRequest'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      message:
                        type: string
                        example: "监管任务结项记录创建成功"
                  timestamp:
                    type: string
                    format: date-time
                    example: "2025-01-19T10:00:00Z"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /regulatory-task-completion/{id}:
    get:
      tags:
        - 监管任务结项
      summary: 获取监管任务结项详情
      description: 根据ID获取监管任务结项记录详情，包含附件和操作日志
      parameters:
        - name: id
          in: path
          required: true
          description: 记录ID
          schema:
            type: integer
            example: 1
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "success"
                  data:
                    $ref: '#/components/schemas/RegulatoryTaskCompletionDetail'
                  timestamp:
                    type: string
                    format: date-time
                    example: "2025-01-19T10:00:00Z"
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    put:
      tags:
        - 监管任务结项
      summary: 更新监管任务结项记录
      description: 更新指定ID的监管任务结项记录
      parameters:
        - name: id
          in: path
          required: true
          description: 记录ID
          schema:
            type: integer
            example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRegulatoryTaskCompletionRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: "监管任务结项记录更新成功"
                  timestamp:
                    type: string
                    format: date-time
                    example: "2025-01-19T10:00:00Z"
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    delete:
      tags:
        - 监管任务结项
      summary: 删除监管任务结项记录
      description: 删除指定ID的监管任务结项记录及相关数据
      parameters:
        - name: id
          in: path
          required: true
          description: 记录ID
          schema:
            type: integer
            example: 1
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: "监管任务结项记录删除成功"
                  timestamp:
                    type: string
                    format: date-time
                    example: "2025-01-19T10:00:00Z"
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /regulatory-task-completion/{id}/review:
    patch:
      tags:
        - 监管任务结项
      summary: 审核监管任务结项记录
      description: 对指定ID的监管任务结项记录进行审核
      parameters:
        - name: id
          in: path
          required: true
          description: 记录ID
          schema:
            type: integer
            example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewRequest'
      responses:
        '200':
          description: 审核成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: "监管任务结项记录审核成功"
                  timestamp:
                    type: string
                    format: date-time
                    example: "2025-01-19T10:00:00Z"
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /regulatory-task-completion/stats:
    get:
      tags:
        - 监管任务结项
      summary: 获取监管任务结项统计数据
      description: 获取监管任务结项的统计分析数据
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: "success"
                  data:
                    $ref: '#/components/schemas/StatisticsData'
                  timestamp:
                    type: string
                    format: date-time
                    example: "2025-01-19T10:00:00Z"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    RegulatoryTaskCompletion:
      type: object
      properties:
        id:
          type: integer
          description: 记录ID
          example: 1
        application_no:
          type: string
          description: 申请编号
          example: "APP20250119001"
        policy_no:
          type: string
          description: 保单号
          example: "POL20250119001"
        product_name:
          type: string
          description: 产品名称
          example: "养殖保险"
        customer_name:
          type: string
          description: 客户名称
          example: "张三"
        customer_phone:
          type: string
          description: 客户电话
          example: "13800138000"
        insurance_amount:
          type: number
          format: decimal
          description: 保险金额
          example: 100000.00
        premium_amount:
          type: number
          format: decimal
          description: 保费金额
          example: 5000.00
        start_date:
          type: string
          format: date
          description: 保险起期
          example: "2025-01-01"
        end_date:
          type: string
          format: date
          description: 保险止期
          example: "2025-12-31"
        completion_date:
          type: string
          format: date
          description: 结项日期
          example: "2025-01-19"
        status:
          type: string
          enum: [pending, approved, rejected, completed]
          description: 状态
          example: "pending"
        reviewer_name:
          type: string
          description: 审核人员
          example: "审核员张三"
        review_comments:
          type: string
          description: 审核意见
          example: "审核通过"
        created_at:
          type: string
          format: date-time
          description: 创建时间
          example: "2025-01-19T10:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: 更新时间
          example: "2025-01-19T10:00:00Z"

    RegulatoryTaskCompletionDetail:
      allOf:
        - $ref: '#/components/schemas/RegulatoryTaskCompletion'
        - type: object
          properties:
            attachments:
              type: array
              items:
                $ref: '#/components/schemas/Attachment'
            operation_logs:
              type: array
              items:
                $ref: '#/components/schemas/OperationLog'

    Attachment:
      type: object
      properties:
        id:
          type: integer
          description: 附件ID
          example: 1
        file_name:
          type: string
          description: 文件名
          example: "保单文件.pdf"
        file_path:
          type: string
          description: 文件路径
          example: "/uploads/documents/policy_001.pdf"
        file_size:
          type: integer
          description: 文件大小（字节）
          example: 1024000
        file_type:
          type: string
          description: 文件类型
          example: "application/pdf"
        upload_time:
          type: string
          format: date-time
          description: 上传时间
          example: "2025-01-19T10:00:00Z"

    OperationLog:
      type: object
      properties:
        id:
          type: integer
          description: 日志ID
          example: 1
        operation_type:
          type: string
          description: 操作类型
          example: "create"
        operation_description:
          type: string
          description: 操作描述
          example: "创建监管任务结项记录"
        operator_name:
          type: string
          description: 操作人员
          example: "系统管理员"
        operation_time:
          type: string
          format: date-time
          description: 操作时间
          example: "2025-01-19T10:00:00Z"
        ip_address:
          type: string
          description: IP地址
          example: "192.168.1.100"

    CreateRegulatoryTaskCompletionRequest:
      type: object
      required:
        - application_no
        - policy_no
        - product_name
        - customer_name
      properties:
        application_no:
          type: string
          description: 申请编号
          example: "APP20250119002"
        policy_no:
          type: string
          description: 保单号
          example: "POL20250119002"
        product_name:
          type: string
          description: 产品名称
          example: "养殖保险"
        customer_name:
          type: string
          description: 客户名称
          example: "李四"
        customer_phone:
          type: string
          description: 客户电话
          example: "13800138001"
        insurance_amount:
          type: number
          format: decimal
          description: 保险金额
          example: 150000.00
        premium_amount:
          type: number
          format: decimal
          description: 保费金额
          example: 7500.00
        start_date:
          type: string
          format: date
          description: 保险起期
          example: "2025-01-01"
        end_date:
          type: string
          format: date
          description: 保险止期
          example: "2025-12-31"
        completion_date:
          type: string
          format: date
          description: 结项日期
          example: "2025-01-19"
        status:
          type: string
          enum: [pending, approved, rejected, completed]
          description: 状态
          default: "pending"
          example: "pending"
        review_comments:
          type: string
          description: 审核意见
          example: "待审核"
        attachments:
          type: array
          description: 附件列表
          items:
            type: object
            properties:
              file_name:
                type: string
                example: "保单文件.pdf"
              file_path:
                type: string
                example: "/uploads/documents/policy_002.pdf"
              file_size:
                type: integer
                example: 1024000
              file_type:
                type: string
                example: "application/pdf"

    UpdateRegulatoryTaskCompletionRequest:
      type: object
      properties:
        application_no:
          type: string
          description: 申请编号
          example: "APP20250119002"
        policy_no:
          type: string
          description: 保单号
          example: "POL20250119002"
        product_name:
          type: string
          description: 产品名称
          example: "养殖保险（更新）"
        customer_name:
          type: string
          description: 客户名称
          example: "李四"
        customer_phone:
          type: string
          description: 客户电话
          example: "13800138001"
        insurance_amount:
          type: number
          format: decimal
          description: 保险金额
          example: 160000.00
        premium_amount:
          type: number
          format: decimal
          description: 保费金额
          example: 8000.00
        start_date:
          type: string
          format: date
          description: 保险起期
          example: "2025-01-01"
        end_date:
          type: string
          format: date
          description: 保险止期
          example: "2025-12-31"
        completion_date:
          type: string
          format: date
          description: 结项日期
          example: "2025-01-19"
        status:
          type: string
          enum: [pending, approved, rejected, completed]
          description: 状态
          example: "pending"
        review_comments:
          type: string
          description: 审核意见
          example: "信息已更新"

    ReviewRequest:
      type: object
      required:
        - status
        - reviewer_name
      properties:
        status:
          type: string
          enum: [approved, rejected]
          description: 审核状态
          example: "approved"
        review_comments:
          type: string
          description: 审核意见
          example: "审核通过，符合监管要求"
        reviewer_name:
          type: string
          description: 审核人员
          example: "审核员张三"

    StatisticsData:
      type: object
      properties:
        statusStats:
          type: array
          description: 状态统计
          items:
            type: object
            properties:
              status:
                type: string
                example: "pending"
              count:
                type: integer
                example: 5
        monthlyStats:
          type: array
          description: 月度统计
          items:
            type: object
            properties:
              month:
                type: string
                example: "2025-01"
              count:
                type: integer
                example: 10
              total_amount:
                type: number
                format: decimal
                example: 1000000.00
        productStats:
          type: array
          description: 产品统计
          items:
            type: object
            properties:
              product_name:
                type: string
                example: "养殖保险"
              count:
                type: integer
                example: 20
              total_amount:
                type: number
                format: decimal
                example: 2000000.00

    Pagination:
      type: object
      properties:
        current:
          type: integer
          description: 当前页码
          example: 1
        pageSize:
          type: integer
          description: 每页数量
          example: 10
        total:
          type: integer
          description: 总记录数
          example: 100
        totalPages:
          type: integer
          description: 总页数
          example: 10

    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: 错误码
        message:
          type: string
          description: 错误信息
        timestamp:
          type: string
          format: date-time
          description: 时间戳

  responses:
    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 400
            message: "申请编号、保单号、产品名称、客户名称为必填项"
            timestamp: "2025-01-19T10:00:00Z"

    Unauthorized:
      description: 未授权访问
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 401
            message: "未授权访问"
            timestamp: "2025-01-19T10:00:00Z"

    Forbidden:
      description: 权限不足
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 403
            message: "权限不足"
            timestamp: "2025-01-19T10:00:00Z"

    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 404
            message: "监管任务结项记录不存在"
            timestamp: "2025-01-19T10:00:00Z"

    InternalServerError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 500
            message: "服务器内部错误"
            timestamp: "2025-01-19T10:00:00Z"

tags:
  - name: 监管任务结项
    description: 监管任务结项管理相关接口