openapi: 3.0.3
info:
  title: Coupon Service API
  version: 1.0.0
  description: 优惠券服务接口文档
servers:
  - url: http://localhost:8805
    description: 本地环境


paths:
  /coupons/coupon-types:
    get:
      security:
        - userType: [ms_users]
      operationId: listCouponTypes
      tags: [CouponType]
      summary: 查询优惠券种类列表
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/SizeParam'
        - $ref: '#/components/parameters/SortParam'
        - $ref: '#/components/parameters/OrderParam'
        - $ref: '#/components/parameters/StatusesParam'
        - $ref: '#/components/parameters/NameParam'
        - $ref: '#/components/parameters/SentableParam'
        - name: id
          in: query
          schema:
            type: array
            items:
              type: integer
              format: uint
              description: 优惠券种类ID
            example: [1, 2, 3]
          explode: false 
          style: form

      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ListCouponTypesResult'

    post:
      security:
        - userType: [ms_users]
      operationId: createCouponType
      tags: [CouponType]
      summary: 创建优惠券种类（管理员）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCouponTypeRequest'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponType'
        '401':
          description: 未授权
          $ref: "#/components/responses/UnauthorizedError"
            
                
  /coupons/coupon-types/{id}:
    get:
      operationId: getCouponType
      tags: [CouponType]
      summary: 查询优惠券种类详情
      parameters:
        - $ref: '#/components/parameters/CouponTypeIdParam'
      responses:
        '200':  
          description: 查询成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object    
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponType'
        '404':
          description: 优惠券类型不存在
          $ref: "#/components/responses/RecordNotFoundError"
        '401':
          description: 未授权
          $ref: "#/components/responses/UnauthorizedError"
        '403':
          description: 禁止访问
          $ref: "#/components/responses/ForbiddenError"
        '400':
          description: 无效请求
          $ref: "#/components/responses/BadRequestError"
        '500':
          description: 服务器错误
          $ref: "#/components/responses/InternalServerError"
    patch:
      operationId: updateCouponType
      security:
        - userType: [ms_users]
      tags: [CouponType]
      summary: 更新优惠券种类（管理员）
      parameters:
        - $ref: '#/components/parameters/CouponTypeIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCouponTypeRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse' 
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponType'
        '404':
          description: 优惠券类型不存在
          $ref: "#/components/responses/RecordNotFoundError"
        '401':
          description: 未授权
          $ref: "#/components/responses/UnauthorizedError"
        '403':
          description: 禁止访问
          $ref: "#/components/responses/ForbiddenError"
        '400':
          description: 无效请求
          $ref: "#/components/responses/BadRequestError"
        '500':
          description: 服务器错误
          $ref: "#/components/responses/InternalServerError"

  /coupons/coupon-types/{id}/genCodes:
    post:
      security:
        - userType: [ms_users]
      operationId: genCouponCodes
      tags: [CouponType]
      summary: 生成优惠券代码
      parameters:
        - $ref: '#/components/parameters/CouponTypeIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenCouponCodesRequest'
      responses:
        '200':
          description: 生成成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          codes:
                            type: array
                            items:
                              type: string
                              description: 优惠券代码
        '404':
          description: 优惠券类型不存在
          $ref: "#/components/responses/RecordNotFoundError"
        '401':
          description: 未授权
          $ref: "#/components/responses/UnauthorizedError"
        '403':
          description: 禁止访问
          $ref: "#/components/responses/ForbiddenError"
        '400':
          description: 无效请求
          $ref: "#/components/responses/BadRequestError"
        '500':
          description: 服务器错误
          $ref: "#/components/responses/InternalServerError"

  /coupons/coupon-types/{id}/publish:
    post:
      security:
        - userType: [ms_users]
      operationId: publishCouponType
      tags: [CouponType]
      summary: 发布优惠券种类
      parameters:
        - $ref: '#/components/parameters/CouponTypeIdParam'
      responses:
        '200':
          description: 发布成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponType'
        '404':
          description: 优惠券类型不存在
  /coupons/coupon-types/{id}/receive:
    post:
      operationId: claimCouponByMobile
      tags: [CouponType]
      summary: 通过手机号领取优惠券
      parameters:
        - $ref: '#/components/parameters/CouponTypeIdParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CouponReceiveRequest'
      responses:
        '200':
          description: 领取成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponCode'
        '400':
          description: 领取失败（已达上限或无效请求）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '404':
          description: 优惠券类型不存在
      security:
        - BearerAuth: []  # 允许未登录状态（根据业务需求调整）
  /coupons/coupon-codes/confirmUserMobile:
    post:
      security:
        - userType: [ms_users, users]
      operationId: confirmUserMobile
      tags: [CouponCode]
      summary: 确认用户手机号
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmUserMobileRequest'
      responses:
        '200':
          description: 确认成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'

  /coupons/coupon-codes/code/{code}:
    get:
      operationId: getCouponCodeByCode
      tags: [CouponCode]
      summary: 通过优惠券代码查询优惠券详情
      parameters:
        - $ref: '#/components/parameters/CouponCodeExpandParam'
        - $ref: '#/components/parameters/CouponCodeParam'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponCode'
        '404':
          description: 优惠券不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: 无效的优惠券代码
        '401':
          description: 未授权
        '403':
          description: 禁止访问

  /coupons/coupon-codes/code/{code}/check:
    get:
      operationId: checkCouponCode
      tags: [CouponCode]
      summary: 检查优惠券代码是否有效
      parameters:
        - $ref: '#/components/parameters/CouponCodeParam'
      responses:
        '200':
          description: 检查成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponCodeCheckResult'
  /coupons/coupon-codes/code/{code}/receive:
    post:
      operationId: receiveCouponByCode
      tags: [CouponCode]
      summary: 通过优惠券代码领取优惠券
      parameters:
        - $ref: '#/components/parameters/CouponCodeParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CouponReceiveRequest'
      responses:
        '200':
          description: 领取成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponCode'
        '400':
          description: 领取失败（已达上限或无效请求）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '403':
          description: 禁止访问
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '404':
          description: 优惠券不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
      security:
        - BearerAuth: []  # 允许未登录状态（根据业务需求调整）
  /coupons/coupon-codes:
    get:
      security:
        - userType: [ms_users, users]
      operationId: listCouponCodes
      tags: [CouponCode]
      summary: 查询优惠券列表
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/SizeParam'
        - $ref: '#/components/parameters/StatusesParam'
        - $ref: '#/components/parameters/CouponCodeExpandParam'
        - $ref: '#/components/parameters/StatusParam'
        - name: userId
          in: query
          required: false
          schema:
            type: integer
            format: uint
            description: 用户ID
        - name: code
          in: query
          required: false
          schema:
            type: string
            description: 优惠券代码
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponCodeListResult'
  /coupons/coupon-codes/export:
    post:
      security:
        - userType: [ms_users]
      operationId: exportCouponCodes
      tags: [CouponCode]
      summary: 导出优惠券列表
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportCouponCodesRequest'
      responses:
        '200':
          description: 导出成功
          content:
            application/octet-stream:
              schema:
                type: string
                description: 文件二进制流,格式excel
                format: binary
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
                
  /coupons/redemptions:
    post:
      security:
        - userType: [ms_users]
      operationId: registerRedemption
      tags: [Redemption]
      summary: 注册核销方
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
                  description: 核销方名称
                type:
                  type: string
                  description: 核销方类型，如门店、商家等
                contactInfo:
                  type: string
                  description: 联系信息，如电话、地址等
      responses:
        '201':
          description: 注册成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          id:
                            type: integer
                            format: int64
                            description: 核销方ID
        '400':
          description: 注册失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '500':
          description: 服务器错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'

  /coupons/coupon-codes/{id}:
    get:
      security:
        - userType: [ms_users, users]
      operationId: getCouponCode
      tags: [CouponCode]
      summary: 查询优惠券详情
      parameters:
        - $ref: '#/components/parameters/CouponCodeExpandParam'
        - $ref: '#/components/parameters/CouponCodeIdParam'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponCode'
        '404':
          description: 优惠券不存在

  /coupons/coupon-codes/{id}/use:
    post:
      security:
        - userType: [ms_users, users]
      operationId: useCouponCode
      tags: [CouponCode]
      summary: 使用优惠券
      parameters:
        - $ref: '#/components/parameters/CouponCodeIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CouponUseRequest'
      responses:
        '200':
          description: 使用成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponRedemptionResult'
        '400':
          description: 使用失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '404':
          description: 优惠券不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'

  /coupons/coupon-codes/{id}/revokeUse:
    post:
      security:
        - userType: [ms_users, users]
      operationId: revokeUseCouponCode
      tags: [CouponCode]
      summary: 撤销使用优惠券
      parameters:
        - $ref: '#/components/parameters/CouponCodeIdParam' 
      responses:
        '200':
          description: 撤销使用成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponCode'
        '400':
          description: 撤销使用失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
          description: 优惠券不存在
  /coupons/coupon-codes/{id}/calc:
    post:
      operationId: calculateCouponDiscount
      tags: [CouponCode]
      summary: 计算优惠券折扣
      parameters:
        - $ref: '#/components/parameters/CouponCodeIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CouponCalcRequest'
      responses:
        '200':
          description: 计算成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CouponCalcResult'
        '400':
          description: 计算失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '404':
          description: 优惠券不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
      security:
        - BearerAuth: []  # 允许未登录状态


components:
  securitySchemes:
    userType:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 用户类型认证 
      x-scopes:
        - ms_users
        - users
  schemas:
    CouponRedemptionResult:
      type: object
      properties:
        couponCodeID:
          type: integer
          format: uint 
          description: 券码ID
        redemptionId:
          type: string
          description: 核销ID(UUID)
        redemptionCode:
          type: string
          description: 核销码(CYYMMDDHHMMSS0123)
        status:
          type: integer
          format: uint8
          description: 核销状态
          enum: [1, 2, 3]
          x-enum-varnames: [Success, Failed, Revoked]
          x-enum-descriptions: [成功, 失败, 撤销]
    CouponUseRequest:
      type: object
      properties:
        userId:
          type: integer
          format: uint
          description: 用户ID，用于计算特定用户可用的优惠券
        redeemerType:
          type: string
          description: 核销类型，如门店、商家、交易等
        redeemerId:
          type: integer
          format: uint
          description: 核销方ID
        redeemerName:
          type: string
          description: 核销方名称
        redeemAt:
          type: string
          format: date-time
          description: 核销时间
        redeemerCode:
          type: string
          description: 核销方编码

    CouponCalcRequest:
      type: object
      required: [items]
      properties:
        userId:
          type: integer
          format: int64
          description: 用户ID，用于计算特定用户可用的优惠券
        totalAmount:
          type: number
          format: double
          description: 订单总金额（可选，系统可根据items计算）
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
          description: 订单商品项列表
    
    OrderItem:
      type: object
      required: [spuId, skuId, quantity]
      properties:
        spuId:
          type: integer
          format: int64
          description: 商品SPU ID
        skuId:
          type: integer
          format: int64
          description: 商品SKU ID
        pricingId:
          type: integer
          format: int64
          description: 价格ID
        quantity:
          type: integer
          format: int32
          minimum: 1
          description: 商品数量
        amounts:
          type: array
          items:
            $ref: '#/components/schemas/PriceAmount'
          description: 价格金额明细，按科目划分
        categoryId:
          type: integer
          format: int64
          description: 商品分类ID
        brandId:
          type: integer
          format: int64
          description: 商品品牌ID
        attributes:
          type: object
          additionalProperties: true
          description: 商品其他属性，用于高级匹配规则
    
    PriceAmount:
      type: object
      required: [subjectId, amount]
      properties:
        subjectId:
          type: integer
          format: int64
          description: 收支科目ID
        amount:
          type: number
          format: double
          description: 该科目的金额

    CouponCalcResult:
      type: object
      properties:
        originalAmount:
          type: number
          format: double
          description: 原始订单金额
        discountAmount:
          type: number
          format: double
          description: 折扣总金额
        finalAmount:
          type: number
          format: double
          description: 最终金额
        applicable:
          type: boolean
          description: 优惠券是否适用于当前订单
        applicableItems:
          type: array
          items:
            $ref: '#/components/schemas/DiscountItem'
          description: 适用的商品项列表及其折扣情况
        discountBySubject:
          type: array
          items:
            $ref: '#/components/schemas/SubjectDiscount'
          description: 按科目划分的折扣情况
        message:
          type: string
          description: 计算结果说明或不适用原因
    CouponCodeListResult:
      type: object
      properties:
        list:
          type: array
          items:
              $ref: '#/components/schemas/CouponCode'
        total:
          type: integer
          format: int64
          description: 总数量
        receiveUrlRoot:
          type: string
          description: 领取URL根路径(用于前端生成领取URL=receiveUrlRoot+code)
    SubjectDiscount:
      type: object
      properties:
        subject:
          type: string
          description: 金额科目，如"base"(基础价)、"tax"(税费)、"shipping"(运费)等
        originalAmount:
          type: number
          format: double
          description: 该科目的原始金额
        discountAmount:
          type: number
          format: double
          description: 该科目的折扣金额
        finalAmount:
          type: number
          format: double
          description: 该科目的最终金额
    
    DiscountItem:
      type: object
      properties:
        spuId:
          type: integer
          format: int64
          description: 商品SPU ID
        skuId:
          type: integer
          format: int64
          description: 商品SKU ID
        quantity:
          type: integer
          format: int32
          description: 数量
        originalAmounts:
          type: array
          items:
            $ref: '#/components/schemas/PriceAmount'
          description: 原始价格明细
        discountAmounts:
          type: array
          items:
            $ref: '#/components/schemas/PriceAmount'
          description: 折扣金额明细
        finalAmounts:
          type: array
          items:
            $ref: '#/components/schemas/PriceAmount'
          description: 最终价格明细

    CouponCodeCheckResult:
      type: object
      properties:
        isExist:
          type: boolean
          description: 优惠券是否存在
        claimable:
          type: boolean
          description: 优惠券是否可被领取
        usable:
          type: boolean
          description: 优惠券是否可被使用
        status:
          $ref: "#/components/schemas/CouponCodeStatus"
          description: 优惠券状态码
        unUsableReason:
          type: string
          description: 不可用/不可领取的详细原因
        unClaimableReason:
          type: string
          description: 不可领取的详细原因
    UpdateCouponTypeRequest:
      $ref: '#/components/schemas/CouponType'
    GenCouponCodesRequest:
      type: object
      required: [count]
      properties:
        count:
          type: integer
          format: int64
          description: 生成数量
          x-oapi-codegen-extra-tags:
            binding: required,gt=0
            validate: required,gt=0

    CreateCouponTypeRequest:
      type: object
      required: [name, discountType, discountValue, validityType]
      properties:
        name:
          type: string
          maxLength: 100
          x-oapi-codegen-extra-tags:
            binding: required,max=100
            validate: required,max=100
        discountType:
          $ref: '#/components/schemas/DiscountType'

        discountValue:
          type: number
          format: double
          minimum: 0.0001
          exclusiveMinimum: true
          description: 优惠值（必须大于0）
          x-oapi-codegen-extra-tags:
            binding: required,gt=0
            validate: required,gt=0
        minDealAmount:
          type: number
          minimum: 0
          description: 满减金额
          x-oapi-codegen-extra-tags:
            binding: omitempty,min=0
            validate: omitempty,min=0
        validityType:
          $ref: '#/components/schemas/ValidType'
          description: 有效期类型
          x-oapi-codegen-extra-tags:
            binding: required,oneof=1 2
            validate: required,oneof=1 2

        validDays:
          type: integer
          minimum: 0
          description: 有效期天数
        validStartTime:
          type: string
          format: datetime
          description: 有效开始时间（日期时间格式）
        validEndTime:
          type: string
          format: datetime
          description: 有效结束时间（日期时间格式）
        totalCount:
          type: integer
          minimum: 0
          description: 总数量 0表示无限制
        userLimit:
          type: integer
          minimum: 0
          description: 用户限制 0表示无限制
        applicableRules:
          $ref: '#/components/schemas/ApplicableRules'
        description:
          type: string
          maxLength: 255
          description: 优惠券说明

    ValidType:
      type: integer
      enum: [1, 2]
      x-enum-varnames: [Fixed, Dynamic]
      x-enum-descriptions: [固定, 动态]
      x-oapi-codegen-extra-tags:
        binding: required,oneof=1 2
        validate: required,oneof=1 2
    DiscountType:
      type: integer
      enum: [1, 2, 3]
      x-enum-varnames: [FullReduction, Percentage, InstantDiscount]
      x-enum-descriptions: [满减, 折扣, 立减]
      x-oapi-codegen-extra-tags:
        binding: required,oneof=1 2 3
        validate: required,oneof=1 2 3
      description: 优惠类型 1.满减 2.折扣 3.立减 满减时 minDealAmount并填; 折扣时，discountValue为0-100的值，抵扣金额=订单金额*discountValue% 
      
      
    ApplicableRules:
      type: object
      description: 适用规则配置
      properties:
        applicableProducts:
          type: array
          items:
            type: integer
            format: int64
          maxItems: 50
        applicableMemberCard:
          type: array
          items:
            type: integer
            format: int64 
          maxItems: 50
    ApplicableProduct:
      type: object
      properties:
        spuId:
          type: integer
          format: int64
          description: 商品SPU ID
        skuId:
          type: integer
          format: int64
          description: 商品SKU ID
        pricingId:
          type: integer
          format: int64
          description: 价格ID
        categoryId:
          type: integer
          format: int64
          description: 商品分类ID
        brandId:
          type: integer
          format: int64
          description: 品牌ID
    ListCouponTypesResult:
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/CouponType'
        total:
          type: integer
          format: int64
          description: 总数量
    CouponType:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
          maxLength: 100
        totalCount:
          type: integer
          format: int64
          description: 总数量 0表示无限制
        userLimit:
          type: integer
          format: int64
          description: 用户限制 0表示无限制
        description:
          type: string
          maxLength: 255
        discountType:
          type: integer
          enum: [1, 2, 3]
          x-enum-varnames: [FullReduction, Percentage, InstantDiscount]
          x-enum-descriptions: [满减, 折扣, 立减]
        discountValue:
          type: number
          format: double
          description: 优惠值
        minDealAmount:
          type: number
          format: double
        status:
          $ref: '#/components/schemas/CouponTypeStatus'
        validityType:
          type: integer
          enum: [1, 2]
          x-enum-varnames: [Fixed, Dynamic]
          x-enum-descriptions: [固定, 动态]
        validDays:
          type: integer 
          format: int32
        validStartTime:
          type: string
          format: datetime
          description: 优惠券开始时间(固定有效期时有效)
        validEndTime:
          type: string
          format: datetime
          description: 优惠券结束时间(固定有效期时有效)
        applicableRules:
          $ref: '#/components/schemas/CouponApplicableRules'


    CouponCodeStatus:
      type: integer
      enum: [1, 2, 3, 4, 5]
      x-enum-varnames: [Unclaimed, Claimed, Used, Expired, Invalid]
      x-enum-descriptions: [未领取, 已领取, 已使用, 已过期, 已作废]
      description: 优惠券状态码

    CouponCode:
      type: object
      properties:
        id:
          type: integer
          format: int64
        code:
          type: string
          maxLength: 32
        name:
          type: string
          maxLength: 50
          description: 优惠券名称(type名)
        status:
          $ref: "#/components/schemas/CouponCodeStatus"
        startTime:
          type: string
          format: date-time
          maxLength: 32
          description: 优惠券开始时间
        endTime:
          type: string
          format: date-time
          maxLength: 32
        couponType:
          type: object
          $ref: '#/components/schemas/CouponType'
          description: 优惠券类型, 当expand参数包含couponType时返回
        mobile:
          type: string
          maxLength: 11
          pattern: '^1[3-9]\\d{9}$'
          x-oapi-codegen-extra-tags:
            binding: omitempty,len=11
            validate: omitempty,len=11
        userId:
          type: integer
          description: 可选，登录用户的ID，不能与mobile同时为空
          format: int64
          maximum: 9223372036854775807
        validateType:
          type: integer
          enum: [1, 2]
          x-enum-varnames: [Fixed, Dynamic]
          x-enum-descriptions: [固定, 动态]
          description: 有效期类型
        validateDays:
          type: integer
          description: 有效期天数
        receivedAt:
          type: string
          format: date-time
          description: 领取时间
        usedAt:
          type: string
          format: date-time
          description: 使用时间
        discountType:
          type: integer
          enum: [1, 2, 3]
          x-enum-varnames: [FullReduction, Percentage, InstantDiscount]
          x-enum-descriptions: [满减, 折扣, 立减]
        minDealAmount:
          type: number
          format: double
          description: 满减金额
        discountValue:
          type: number
          format: double
        description:
          type: string
          maxLength: 200
          description: 说明
        redemption:
          $ref: '#/components/schemas/CouponRedemption'
          description: 核销信息，仅已使用状态的优惠券返回
        usable:
          type: boolean
          description: 是否有效
    
    CouponRedemption:
      type: object
      properties:
        redemptionId:
          type: string 
          description: 核销ID
        redemptionCode: 
          type: string
          description: 核销码(CYYMMDDHHMMSS0123)
        status:
          type: integer
          description: 状态码
        redeemedAt:
          type: string
          format: datetime
          description: 核销时间
        redeemerCode:
          type: string
          description: 核销方编码
    ReceiveByCodeRequest:
      type: object
      properties:
        mobile:
          type: string
          pattern: '^1[3-9]\\d{9}$'
          description: 手机号, 可选，不能与userId同时为空
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        userId:
          type: integer
          description: 可选，登录用户的ID，不能与mobile同时为空
          format: int64
          maximum: 9223372036854775807
    CouponReceiveRequest:
      type: object
      properties:
        mobile:
          type: string
          pattern: '^1[3-9]\\d{9}$'
          x-oapi-codegen-extra-tags:
            binding: omitempty,len=11
            validate: omitempty,len=11
          description: 手机号, 可选，不能与userId同时为空
        userId:
          type: integer
          description: 可选，登录用户的ID，不能与mobile同时为空
          format: int64
          maximum: 9223372036854775807
          minimum: 0

    CouponApplicableRules:
      type: object
      properties:
        minDealAmount:
          type: number
          format: double
        applicableProducts:
          type: array
          items:
            type: integer
            format: int64
        excludeProducts:
          type: array
          items:
            type: integer
            format: int64
        userLevels:
          type: array
          items:
            type: integer
            enum: [1, 2, 3]
          x-enum-varnames: [Regular, VIP, SVIP]
          x-enum-descriptions: [普通用户, VIP用户, 超级VIP用户]

    ConfirmUserMobileRequest:
      type: object
      required: [mobile, userId]
      properties:
        mobile:
          type: string
          pattern: '^1[3-9]\\d{9}$'
          description: 手机号
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        userId:
          type: integer
          format: int64
          description: 用户ID
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required

    ExportCouponCodesRequest:
      type: object
      properties:
        code:
          type: string
          description: 优惠券码 (支持模糊，不支持多个)
        typeId:
          type: integer
          format: int64
          description: 优惠券类型ID
        status:
          type: integer
          enum: [1, 2, 3, 4, 5]
          x-enum-varnames: [Unclaimed, Claimed, Used, Expired, Invalid]
          description: 优惠券状态码
        startTime:
          type: string
          format: datetime
          description: 优惠券开始时间
        endTime:
          type: string
          format: datetime
          description: 优惠券结束时间
        pageNum:
          type: integer
          default: 1
          description: 页码
        pageSize:
          type: integer
          default: 20
          description: 每页数量

    BaseResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: 响应状态码（0表示成功）
        message:
          type: string
    CouponTypeStatus:
      type: integer
      enum: [1, 2, 3, 4, 5]
      x-enum-varnames: [Draft, Published, Paused, Ended, Invalid]
      x-enum-descriptions: [草稿, 已发布, 已暂停, 已结束, 已作废]
  
  parameters:
    PageParam:
      name: pageNum
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1

    SizeParam:
      name: pageSize
      in: query
      schema:
        type: integer
        default: 20
        maximum: 100

    SortParam:
      name: sort
      in: query
      schema:
        type: string
        enum: [createdAt, validStartTime, discountValue]
        default: createdAt
    OrderParam:
      name: order
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: desc
        description: 排序方式
    SentableParam:
      name: sentable
      in: query
      schema:
        type: integer
        description: 是否可领取
        default: null 
        enum: [1]
        nullable: true
    NameParam:
      name: name
      in: query
      schema:
        type: string
        maxLength: 50
        description: 名称
    StatusParam:
      name: status
      in: query
      schema:
        type: integer
        enum: [1, 2, 3, 4, 5]
        x-enum-varnames: [Unclaimed, Claimed, Used, Expired, Invalid]
        
    StatusesParam:
      name: statuses
      in: query
      schema:
        type: array
        maxItems: 5
        items:
          type: integer
          enum: [1, 2, 3, 4, 5]
          x-enum-varnames: [Unclaimed, Claimed, Used, Expired, Invalid]
          x-enum-descriptions: [未领取, 已领取, 已使用, 已过期, 已作废]
      style: form
      explode: false
      description: 状态码, 多个状态码用逗号分隔
    CouponTypeIdParam:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64
    CouponCodeParam:
      name: code
      in: path
      required: true
      schema:
        type: string
      x-oapi-codegen-extra-tags:
        binding: required
        validate: required
    CouponCodeIdParam:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64
    CouponCodeExpandParam:
      name: expand
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          enum: [couponType, redemption]
          x-enum-varnames: [CouponType, Redemption]
          x-enum-values: [couponType, redemption]
          x-enum-descriptions: [优惠券类型, 核销信息]
        description: 扩展参数，可选值为couponType，表示返回优惠券类型信息，可选值为redemption，表示返回核销信息
      
  
  responses:
    RecordNotFoundError:
      description: 记录不存在
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'
    UnauthorizedError:
      description: 未授权
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'
    ForbiddenError:
      description: 禁止访问
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'
    BadRequestError:
      description: 无效请求
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'
            
    InternalServerError:
      description: 服务器错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'
            
            

