openapi: 3.0.0
info:
  title: 险种管理API
  description: 保险系统险种管理功能相关API接口文档
  version: 1.0.0
  contact:
    name: 开发团队
    email: dev@example.com

servers:
  - url: http://localhost:3000/api
    description: 开发环境

paths:
  /insurance-types:
    get:
      summary: 获取险种列表
      description: 分页获取险种列表，支持多种筛选条件
      tags:
        - 险种管理
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          description: 页码
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: pageSize
          in: query
          description: 每页数量
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
        - name: name
          in: query
          description: 险种名称（模糊搜索）
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: 险种状态
          required: false
          schema:
            type: string
            enum: [active, inactive]
        - name: applicable_livestock
          in: query
          description: 适用牲畜类型（模糊搜索）
          required: false
          schema:
            type: string
        - name: service_area
          in: query
          description: 服务区域（模糊搜索）
          required: false
          schema:
            type: string
        - name: on_sale_status
          in: query
          description: 在售状态
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "获取险种列表成功"
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InsuranceType'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

    post:
      summary: 创建险种
      description: 创建新的保险险种
      tags:
        - 险种管理
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInsuranceTypeRequest'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "创建险种成功"
                  data:
                    $ref: '#/components/schemas/InsuranceType'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /insurance-types/{id}:
    get:
      summary: 获取险种详情
      description: 根据ID获取单个险种的详细信息
      tags:
        - 险种管理
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: 险种ID
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "获取保险类型详情成功"
                  data:
                    $ref: '#/components/schemas/InsuranceType'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

    put:
      summary: 更新险种
      description: 更新指定ID的险种信息
      tags:
        - 险种管理
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: 险种ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInsuranceTypeRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "更新险种成功"
                  data:
                    $ref: '#/components/schemas/InsuranceType'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

    delete:
      summary: 删除险种
      description: 删除指定ID的险种
      tags:
        - 险种管理
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: 险种ID
          schema:
            type: integer
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  status:
                    type: string
                    example: "success"
                  data:
                    type: null
                    example: null
                  message:
                    type: string
                    example: "删除险种成功"
                  timestamp:
                    type: string
                    format: date-time
                    example: "2025-09-28T06:28:03.150Z"
        '400':
          description: 删除失败 - 外键约束错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                status: error
                data: null
                message: "该险种下存在保险申请，无法删除"
                timestamp: "2025-09-28T06:28:02.881Z"
        '404':
          description: 险种不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 404
                status: error
                data: null
                message: "险种不存在"
                timestamp: "2025-09-28T06:28:02.881Z"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /insurance-types/{id}/status:
    patch:
      summary: 更新险种状态
      description: 更新指定ID险种的状态或在售状态
      tags:
        - 险种管理
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: 险种ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInsuranceTypeStatusRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "更新险种状态成功"
                  data:
                    $ref: '#/components/schemas/InsuranceType'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

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

  schemas:
    InsuranceType:
      type: object
      properties:
        id:
          type: integer
          description: 险种ID
          example: 1
        name:
          type: string
          description: 险种名称
          example: "牛羊保险"
        description:
          type: string
          description: 险种描述
          example: "针对牛羊等大型牲畜的综合保险产品"
        applicable_livestock:
          type: string
          description: 适用牲畜类型
          example: "牛、羊"
        insurance_term:
          type: integer
          description: 保险期限（月）
          example: 12
        policy_form:
          type: string
          description: 保单形式
          example: "电子保单"
        coverage_amount_min:
          type: number
          format: decimal
          description: 最低保额
          example: 1000.00
        coverage_amount_max:
          type: number
          format: decimal
          description: 最高保额
          example: 50000.00
        premium_rate:
          type: number
          format: decimal
          description: 保险费率
          example: 0.0350
        service_area:
          type: string
          description: 服务区域
          example: "宁夏回族自治区"
        add_time:
          type: string
          format: date-time
          description: 添加时间
          example: "2024-01-15T10:30:00.000Z"
        on_sale_status:
          type: boolean
          description: 在售状态
          example: true
        sort_order:
          type: integer
          description: 排序顺序
          example: 0
        remarks:
          type: string
          description: 备注
          example: "特殊说明信息"
        status:
          type: string
          enum: [active, inactive]
          description: 险种状态
          example: "active"
        created_by:
          type: integer
          description: 创建人ID
          example: 1
        updated_by:
          type: integer
          description: 更新人ID
          example: 1
        created_at:
          type: string
          format: date-time
          description: 创建时间
          example: "2024-01-15T10:30:00.000Z"
        updated_at:
          type: string
          format: date-time
          description: 更新时间
          example: "2024-01-15T10:30:00.000Z"

    CreateInsuranceTypeRequest:
      type: object
      required:
        - name
        - coverage_amount_min
        - coverage_amount_max
        - premium_rate
      properties:
        name:
          type: string
          description: 险种名称
          example: "牛羊保险"
          minLength: 1
          maxLength: 100
        description:
          type: string
          description: 险种描述
          example: "针对牛羊等大型牲畜的综合保险产品"
        applicable_livestock:
          type: string
          description: 适用牲畜类型，多个类型用逗号分隔。前端可发送数组，后端会自动转换为字符串存储
          example: "牛,羊,猪"
          maxLength: 100
        insurance_term:
          type: integer
          description: 保险期限（月）
          example: 12
          minimum: 1
        policy_form:
          type: string
          description: 保单形式
          example: "电子保单"
          maxLength: 50
        coverage_amount_min:
          type: number
          format: decimal
          description: 最低保额
          example: 1000.00
          minimum: 0
        coverage_amount_max:
          type: number
          format: decimal
          description: 最高保额
          example: 50000.00
          minimum: 0
        premium_rate:
          type: number
          format: decimal
          description: 保险费率
          example: 0.0350
          minimum: 0
          maximum: 1
        service_area:
          type: string
          description: 服务区域
          example: "宁夏回族自治区"
        add_time:
          type: string
          format: date-time
          description: 添加时间
          example: "2024-01-15T10:30:00.000Z"
        on_sale_status:
          type: boolean
          description: 在售状态
          example: true
          default: true
        sort_order:
          type: integer
          description: 排序顺序
          example: 0
          default: 0
        remarks:
          type: string
          description: 备注
          example: "特殊说明信息"
        status:
          type: string
          enum: [active, inactive]
          description: 险种状态
          example: "active"
          default: "active"

    UpdateInsuranceTypeRequest:
      type: object
      properties:
        name:
          type: string
          description: 险种名称
          example: "牛羊保险"
          minLength: 1
          maxLength: 100
        description:
          type: string
          description: 险种描述
          example: "针对牛羊等大型牲畜的综合保险产品"
        applicable_livestock:
          type: string
          description: 适用牲畜类型，多个类型用逗号分隔。前端可发送数组，后端会自动转换为字符串存储
          example: "牛,羊,猪"
          maxLength: 100
        insurance_term:
          type: integer
          description: 保险期限（月）
          example: 12
          minimum: 1
        policy_form:
          type: string
          description: 保单形式
          example: "电子保单"
          maxLength: 50
        coverage_amount_min:
          type: number
          format: decimal
          description: 最低保额
          example: 1000.00
          minimum: 0
        coverage_amount_max:
          type: number
          format: decimal
          description: 最高保额
          example: 50000.00
          minimum: 0
        premium_rate:
          type: number
          format: decimal
          description: 保险费率
          example: 0.0350
          minimum: 0
          maximum: 1
        service_area:
          type: string
          description: 服务区域
          example: "宁夏回族自治区"
        add_time:
          type: string
          format: date-time
          description: 添加时间
          example: "2024-01-15T10:30:00.000Z"
        on_sale_status:
          type: boolean
          description: 在售状态
          example: true
        sort_order:
          type: integer
          description: 排序顺序
          example: 0
        remarks:
          type: string
          description: 备注
          example: "特殊说明信息"
        status:
          type: string
          enum: [active, inactive]
          description: 险种状态
          example: "active"

    UpdateInsuranceTypeStatusRequest:
      type: object
      properties:
        status:
          type: string
          enum: [active, inactive]
          description: 险种状态
          example: "active"
        on_sale_status:
          type: boolean
          description: 在售状态
          example: true

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

  responses:
    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: "请求参数错误"

    Unauthorized:
      description: 未授权
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: "未授权访问"

    Forbidden:
      description: 权限不足
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: "权限不足"

    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: "险种不存在"

    InternalServerError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: "服务器内部错误"