openapi: 3.0.3
info:
  title: 订单服务API
  description: |
    基于微服务架构的订单管理系统
    
    ## 更新日志
    - v1.1.0: 新增订单资产管理、还款计划和结算相关接口
  version: 1.1.0
servers:
  - url: http://localhost:8801
    description: 本地环境
paths:
  /order/orders/preview:
    post:
      security:
        - userType:
          - users
          - ms_users
      operationId: OrderPreview
      tags: [OrderManagement]
      summary: 预下单接口
      description: 生成订单预览信息（不实际创建订单）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPreviewRequest'
      responses:
        '200':
          description: 预下单成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderPreview'

  /order/orders/preview/toPay:
    post:
      operationId: GetOrderPreviewToPayInfo
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 获取订单预览待支付信息
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPreviewToPayRequest'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderToPayInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  /order/orders:
    post:
      security:
        - userType:
          - users
          - ms_users
      operationId: CreateOrder
      tags: [OrderManagement]
      summary: 创建订单
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreateRequest'
      responses:
        '201':
          description: 订单创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedResponse'
        '400':
          description: 参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'

    get:
      security:
        - userType:
          - users
          - ms_users
      operationId: OrderList
      tags: [OrderManagement]
      summary: 获取订单列表
      parameters:
        - $ref: '#/components/parameters/PagingPageNum'
        - $ref: '#/components/parameters/PagingPageSize'
        - $ref: '#/components/parameters/PagingSortBy'
        - $ref: '#/components/parameters/PagingSortOrder'
        - $ref: '#/components/parameters/OrderExpand'

        - name: userId
          in: query
          schema:
            type: integer
        - name: userIds
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
              example: [1,2,3]
        - name: vendorId
          in: query
          required: false
          schema:
            type: integer
            example: 1
        - name: startTime
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: 2021-01-01T00:00:00Z
        - name: endTime
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: 2021-01-01T00:00:00Z
        - name: orderNo
          in: query
          required: false
          schema:
            type: string
            example: "DD1234567890"
        - name: orderNoProductName
          in: query
          schema:
            type: string
            example: "小布"
        - name: status
          in: query
          required: false
          description: 订单状态
          style: form
          explode: false 
          schema:
            type: array
            items:
              $ref: '#/components/schemas/OrderStatus'
            example: [1,2,3]
        - name: id
          in: query
          required: false
          description: 订单ID
          schema:
            type: integer
            example: 1
        - name: approvalStatus
          in: query
          required: false
          description: 审批状态
          schema:
            $ref: '#/components/schemas/ApprovalStatus'
            example: 1
        - name: rentBegin
          in: query
          required: false
          description: 租赁开始时间范围
          schema:
            type: array
            items:
              $ref: '#/components/schemas/DateTime'
            example: ["2021-01-01", "2021-01-01"]
          style: form
          explode: true
        - name: rentEnd
          in: query
          required: false
          description: 租赁结束时间范围
          schema:
            type: array
            items:
              $ref: '#/components/schemas/DateTime'
            example: ["2021-01-01", "2021-01-01"]
        - name: createdAt
          in: query
          required: false
          description: 创建时间范围
          schema:
            type: array
            items:
              $ref: '#/components/schemas/DateTime'
            example: ["2021-01-01", "2021-01-01"]
          style: form
          explode: false 
        - name: periods
          in: query
          required: false
          description: 租期数
          schema:
            type: integer
            example: 1
              
      responses:
        '200':
          description: 成功获取订单列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PagedResponse'
                  - type: object
                    properties:
                      data:
                        properties:
                          list:
                            items:
                              $ref: '#/components/schemas/OrderDetailInfo'
        "400":
          $ref: '#/components/responses/BadRequest'
        "500":
          $ref: '#/components/responses/ServerError'
        "401":
          $ref: '#/components/responses/Unauthorized'

  /order/orders/{orderId}:
    get:
      security:
        - userType:
          - users
          - ms_users
      operationId: GetOrderDetail
      tags: [OrderManagement]
      summary: 获取订单详情
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
        - $ref: '#/components/parameters/OrderExpand'
            
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderDetailInfo'
        '404':
          $ref: '#/components/responses/NotFound'

  /order/orders/{orderId}/toPay:
    get:
      operationId: GetOrderToPayInfo
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 获取订单待支付信息
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
        - name: couponId
          in: query
          required: false
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderToPayInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
          
          
  /order/orders/{orderId}/cancel:
    post:
      operationId: CancelOrder
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 取消订单
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelRequest'
      responses:
        '200':
          description: 取消成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  /order/orders/{orderId}/confirm:
    post:
      operationId: ConfirmOrder
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 确认收货
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmRequest'

      responses:
        '200':
          description: 确认收货成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
  /order/orders/{orderId}/upgrade:
    post:
      operationId: CreateOrderUpgrade
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 订单升级
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - upgradeAssets
              properties:
                upgradeAssets:
                  type: array
                  items:
                    $ref: '#/components/schemas/ProductItem'
                upgradeReason:
                  type: string
                  description: 升级原因
      responses:
        '200':
          description: 升级成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          newOrderId:
                            type: integer
                            description: 新订单ID
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  /order/orders/{orderId}/renewal:
    post:
      operationId: CreateOrderRenewal
      security:
        - userType:
          - users
          - ms_users      
      tags: [OrderManagement]
      summary: 订单续租
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - renewalMonths
              properties:
                renewalMonths:
                  type: integer
                  minimum: 1
                  description: 续租月数
                renewalAssets:
                  type: array
                  items:
                    $ref: '#/components/schemas/ProductItem'
                renewalReason:
                  type: string
                  description: 续租原因
      responses:
        '200':
          description: 续租成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          newOrderId:
                            type: integer
                            description: 新订单ID
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
  /order/orders/{orderId}/return:
    post:
      operationId: CreateOrderReturn
      security:
        - userType:
          - ms_users
          - users
      tags: [OrderManagement]
      summary: 订单退租
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - returnAssets
              properties:
                returnAssets:
                  type: array
                  items:
                    type: object
                    required:
                      - assetId
                    properties:
                      assetId:
                        type: string
                      returnReason:
                        type: string
                      assetCondition:
                        type: string
                        enum: [GOOD, DAMAGED, LOST]
                returnTime:
                  type: string
                  format: date-time
      responses:
        '200':
          description: 退租申请成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'


  /order/orders/{orderId}/approve:
    post:
      operationId: ApprovalOrder
      security:
        - userType:
          - ms_users
      tags: [OrderManagement]
      summary: 订单审批
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalOrderRequest'
      responses:
        '200':
          description: 审批完成
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderDetailInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  /order/orders/{orderId}/status:
    post:
      operationId: UpdateOrderStatus
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 更新订单状态 订单状态流转
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderStatusRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderDetailInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
  /order/orders/{orderId}/delivery:
    post:
      operationId: CreateOrderDelivery
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 订单发货
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliveryRequest'
      responses:
        '200':
          description: 发货成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
    get:
      operationId: GetOrderDelivery
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 获取当前有效发货信息
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: 成功获取
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DeliveryInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  /order/orders/events:
    post:
      operationId: OrderEvent
      tags: [OrderManagement]
      summary: 订单事件
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderEventPayload'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  /order/orders/{orderId}/close:
    post:
      operationId: CloseOrder
      security:
        - userType:
          - ms_users
      tags: [OrderManagement]
      summary: 关闭订单
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloseOrderRequest'
      responses:
        '200':
          description: 关闭成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  /order/orders/{orderId}/settlement:
    post:
      operationId: createOrderSettlement
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 订单结算
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderSettlementRequest'
      responses:
        '200':
          description: 结算申请成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/SettlementInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
    
    get:
      operationId: getOrderSettlement
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 获取结算详情
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/SettlementInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  /order/orders/settlements:
    get:
      operationId: GetOrderSettlements
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 获取结算列表
      parameters:
        - $ref: '#/components/parameters/PagingPageNum'
        - $ref: '#/components/parameters/PagingPageSize'
        - name: orderIds
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
              example: 12345
        - name: userId
          in: query
          required: false
          schema:
            type: integer
            example: 1
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SettlementStatusEnum'
        - name: settlementType
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SettlementType'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PagedResponse'
                  - type: object
                    properties:
                      data:
                        properties:
                          list:
                            items:
                              $ref: '#/components/schemas/SettlementInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  /order/orders/settlements/check:
    post:
      operationId: checkOrderSettlement
      security:
        - userType:
          - users
          - ms_users
      tags: [OrderManagement]
      summary: 检查订单结算条件
      description: 批量检查多个订单是否满足结算条件
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderIds
                - settlementType
              properties:
                orderIds:
                  type: array
                  items:
                    type: integer
                  description: 订单ID列表
                  example: [1, 2, 3]
                settlementType:
                  $ref: '#/components/schemas/SettlementType'
      responses:
        '200':
          description: 检查成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/OrderSettlementCheckResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  # v0.9 新增接口：订单还款计划管理
  /order/orders/{orderId}/repayment-plans:
    post:
      summary: 创建订单还款计划
      operationId: createOrderRepaymentPlan
      tags: [OrderRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - required: true  # 路径参数必须为 true
          name: orderId
          in: path
          schema:
            type: integer
            format: int64

          description: 订单ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRepaymentPlanRequest'

      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderRepaymentPlan'
        '400':
          description: 参数错误
        '404':
          description: 订单不存在或还款计划不存在

    get:
      summary: 获取订单还款计划
      operationId: getOrderRepaymentPlan
      tags: [OrderRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      list:
                        type: array
                        items:  
                          $ref: '#/components/schemas/OrderRepaymentPlan'
        '404':
          description: 订单不存在或还款计划不存在

    put:
      summary: 更新订单还款计划
      operationId: updateOrderRepaymentPlan
      tags: [OrderRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderRepaymentPlanRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderRepaymentPlan'
        '400':
          description: 参数错误
        '404':
          description: 订单不存在或还款计划不存在

    delete:
      summary: 删除订单还款计划
      operationId: deleteOrderRepaymentPlan
      tags: [OrderRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
        '404':
          description: 订单不存在或还款计划不存在

  # 资产还款计划管理
  /order/orders/{orderId}/assets/{assetNo}/repayment-plans:
    post:
      summary: 创建订单中资产的还款计划
      operationId: createAssetRepaymentPlan
      tags: [AssetRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
        - name: assetNo
          in: path
          required: true
          schema:
            type: string
          description: 资产编号
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssetRepaymentPlanRequest'
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AssetRepaymentPlan'
        '400':
          description: 参数错误
        '404':
          description: 订单或资产不存在

    get:
      summary: 获取订单中资产的还款计划
      operationId: getAssetRepaymentPlan
      tags: [AssetRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
        - name: assetNo
          in: path
          required: true
          schema:
            type: string
          description: 资产编号
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AssetRepaymentPlan'
        '404':
          description: 订单或资产不存在

    put:
      summary: 更新订单中资产的还款计划
      operationId: updateAssetRepaymentPlan
      tags: [AssetRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
        - name: assetNo
          in: path
          required: true
          schema:
            type: string
          description: 资产编号
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAssetRepaymentPlanRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AssetRepaymentPlan'
        '400':
          description: 参数错误
        '404':
          description: 订单或资产不存在

    delete:
      summary: 删除订单中资产的还款计划
      operationId: deleteAssetRepaymentPlan
      tags: [AssetRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
        - name: assetNo
          in: path
          required: true
          schema:
            type: string
          description: 资产编号
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
        '404':
          description: 订单或资产不存在

  # 资产还款计划（跨订单查询）
  /order/assets/{assetNo}/repayment-plans:
    get:
      summary: 获取资产的所有还款计划（跨订单）
      operationId: getAssetRepaymentPlans
      tags: [AssetRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: assetNo
          in: path
          required: true
          schema:
            type: string
          description: 资产编号
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/PaymentPlanStatus'
          description: 过滤特定状态的还款计划
        - name: pageNum
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: 页码
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: 每页大小
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        allOf:
                          - $ref: '#/components/schemas/PagedResponse'
                          - type: object
                            properties:
                              list:
                                type: array
                                items:
                                  $ref: '#/components/schemas/AssetRepaymentPlan'
        '404':
          description: 资产不存在
          
  /order/orders/{orderId}/repayment-plans/batch-create:
    post:
      summary: 批量创建还款计划
      operationId: batchCreatePaymentPlan
      tags: [RepaymentPlanManagement]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plans]
              properties:
                totalPeriod:
                  type: integer
                  description: 总期数
      responses:
        '200':
          description: 批量创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
                

  # 批量操作
  /order/repayment-plans/batch-update:
    put:
      summary: 批量更新还款计划状态
      operationId: batchUpdatePaymentPlanStatus
      tags: [RepaymentPlanManagement]
      security:
        - userType: [users, ms_users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plans, status]
              properties:
                plans:
                  type: array
                  items:
                    type: object
                    required: [type, id]
                    properties:
                      type:
                        type: string
                        enum: [order, asset]
                        description: 还款计划类型
                      id:
                        type: integer
                        format: int64
                        description: 还款计划ID
                status:
                  $ref: '#/components/schemas/PaymentPlanStatus'
      responses:
        '200':
          description: 批量更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          successCount:
                            type: integer
                            description: 成功更新数量
                          failedPlans:
                            type: array
                            items:
                              type: object
                              properties:
                                type:
                                  type: string
                                id:
                                  type: integer
                                error:
                                  type: string
                            description: 更新失败的还款计划及错误信息
        '400':
          description: 参数错误

  # 订单资产管理
  /order/orders/{orderId}/assets:
    post:
      summary: 向订单添加资产
      operationId: addOrderAsset
      tags: [OrderAsset]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [assetId, assetNo]
              properties:
                assetId:
                  type: integer
                  format: int64
                  description: 资产服务中的资产ID
                assetNo:
                  type: string
                  description: 资产编号
      responses:
        '200':
          description: 添加成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderAsset'
        '400':
          description: 参数错误
        '404':
          description: 订单不存在

    get:
      summary: 获取订单的所有资产
      operationId: getOrderAssets
      tags: [OrderAsset]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/OrderAssetStatus'
          description: 过滤特定状态的资产
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: 页码
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: 每页大小
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        allOf:
                          - $ref: '#/components/schemas/PagedResponse'
                          - type: object
                            properties:
                              list:
                                type: array
                                items:
                                  $ref: '#/components/schemas/OrderAsset'
        '404':
          description: 订单不存在

  /order/orders/{orderId}/assets/{assetNo}:
    get:
      summary: 获取订单中的特定资产
      operationId: getOrderAsset
      tags: [OrderAsset]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
        - name: assetNo
          in: path
          required: true
          schema:
            type: string
          description: 资产编号
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderAsset'
        '404':
          description: 订单或资产不存在

    put:
      summary: 更新订单中的资产信息
      operationId: updateOrderAsset
      tags: [OrderAsset]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
        - name: assetNo
          in: path
          required: true
          schema:
            type: string
          description: 资产编号
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/OrderAssetStatus'
                  description: 资产状态
                configInfo:
                  type: object
                  description: 资产配置信息（JSON格式）
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OrderAsset'
        '400':
          description: 参数错误
        '404':
          description: 订单或资产不存在

    delete:
      summary: 从订单中移除资产
      operationId: removeOrderAsset
      tags: [OrderAsset]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
        - name: assetNo
          in: path
          required: true
          schema:
            type: string
          description: 资产编号
      responses:
        '200':
          description: 移除成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
        '404':
          description: 订单或资产不存在
 
  /order/orders/{orderId}/assets/{assetNo}/repayment-plans/{planId}/status:
    put:
      summary: 更新资产还款计划状态
      operationId: updateAssetRepaymentPlanStatus
      tags: [AssetRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
        - name: assetNo
          in: path
          required: true
          schema:
            type: string
          description: 资产编号
        - name: planId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 还款计划ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  $ref: '#/components/schemas/PaymentPlanStatus'
                actualAmount:
                  type: string
                  format: decimal
                  description: 实际还款金额
                  x-go-type: decimal.Decimal
                  x-go-type-import:
                    path: github.com/shopspring/decimal
                    name: decimal
                actualRepaymentTime:
                  type: string
                  format: date-time
                  description: 实际还款时间
                remark:
                  type: string
                  description: 状态变更说明
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'

  /order/orders/{orderId}/repayment-plans/{planId}/status:
    put:
      summary: 更新订单还款计划状态
      operationId: updateOrderRepaymentPlanStatus
      tags: [OrderRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 订单ID
        - name: planId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 还款计划ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  $ref: '#/components/schemas/PaymentPlanStatus'
                remark:
                  type: string
                  description: 状态变更说明
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'

  /order/orders/{orderId}/repayment-plans/batch:
    post:
      summary: 批量创建订单还款计划
      operationId: batchCreateOrderRepaymentPlans
      tags: [OrderRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
            x-go-type: uint
          description: 订单ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plans]
              properties:
                plans:
                  type: array
                  items:
                    $ref: '#/components/schemas/CreateOrderRepaymentPlanRequest'
                  description: 还款计划创建请求列表
      responses:
        '200':
          description: 批量创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          successCount:
                            type: integer
                            description: 成功创建数量
                          failedPlans:
                            type: array
                            items:
                              type: object
                              properties:
                                index:
                                  type: integer
                                  description: 失败的plans数组下标
                                error:
                                  type: string
                                  description: 错误信息
                            description: 创建失败的还款计划及错误信息
        '400':
          description: 参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 订单不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    put:
      summary: 批量更新订单还款计划
      operationId: batchUpdateOrderRepaymentPlans
      tags: [OrderRepaymentPlan]
      security:
        - userType: [users, ms_users]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            format: int64
            x-go-type: uint
          description: 订单ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plans]
              properties:
                plans:
                  type: array
                  items:
                    type: object
                    required: [planId]
                    properties:
                      planId:
                        type: integer
                        format: int64
                        description: 还款计划ID
                      update:
                        $ref: '#/components/schemas/UpdateOrderRepaymentPlanRequest'
                  description: 还款计划更新请求列表
      responses:
        '200':
          description: 批量更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BasicResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          successCount:
                            type: integer
                            description: 成功更新数量
                          failedPlans:
                            type: array
                            items:
                              type: object
                              properties:
                                planId:
                                  type: integer
                                  format: int64
                                  description: 失败的还款计划ID
                                error:
                                  type: string
                                  description: 错误信息
                            description: 更新失败的还款计划及错误信息
        '400':
          description: 参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 订单不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    userType:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 用户类型认证 
      x-scopes:
        - ms_users
        - users
  schemas:
    # asset repayment plan
    CreateAssetRepaymentPlanRequest:
      type: object
      required:
        - orderId
        - assetNo
        - startTime
        - endTime
        - amount
        - period
        - planRepaymentTime
      properties:
        orderId:
          type: integer
          description: 订单ID
          example: 1
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        assetNo:
          type: string
          description: 资产编号
          example: "1234567890"
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        amount:
          $ref: '#/components/schemas/Amount'
          description: 金额
        period:
          type: integer
          minimum: 1
          description: 期数 从1开始
          example: 1
          x-oapi-codegen-extra-tags:
            binding: required,min=1
            validate: required,min=1
        startTime:
          $ref: '#/components/schemas/DateTime'
          description: 开始时间
          example: "2024-01-01 00:00:00"
        endTime:
          $ref: '#/components/schemas/DateTime'
          description: 结束时间
          example: "2024-01-01 00:00:00"
        planRepaymentTime:
          $ref: '#/components/schemas/DateTime'
          description: 计划还款时间
          example: "2024-01-01 00:00:00"


    OrderCreateRequest:
      type: object
      required:
        - userId
        - orderType
        - rentInfo
        - items
      properties:
        userId:
          type: integer
          example: 1
          description: 用户ID
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        orderType:
          $ref: '#/components/schemas/OrderType'
        rentInfo:
          $ref: '#/components/schemas/RentInfo'
          x-oapi-codegen-extra-tags:
            binding: dive,required
            validate: dive,required
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderCreateProductItem'
          x-oapi-codegen-extra-tags:
            binding: dive,required
            validate: dive,required

    OrderPreviewRequest:
      allOf:
        - $ref: '#/components/schemas/OrderCreateRequest'
        - type: object
          properties:
            couponCodeId:
              type: integer
              description: 优惠券码ID

    OrderPreviewToPayRequest:
      allOf:
        - $ref: '#/components/schemas/OrderCreateRequest'
        - type: object
          properties:
            couponId:
              type: integer
              description: 优惠券ID

    # 基础响应结构
    BasicResponse:
      type: object
      properties:
        code:
          type: integer
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        message:
          type: string
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required

    # 分页响应
    PagedResponse:
      allOf:
        - $ref: '#/components/schemas/BasicResponse'
        - type: object
          required: [data]
          properties:
            data:
              type: object
              properties:
                total:
                  type: integer
                list:
                  type: array
                  items: {}

    # 成功创建响应
    CreatedResponse:
      allOf:
        - $ref: '#/components/schemas/BasicResponse'
        - type: object
          required: [data]
          properties:
            data:
              type: object
              properties:
                id:
                  type: integer

    # 错误响应
    ErrorResponse:
      allOf:
        - $ref: '#/components/schemas/BasicResponse'

    CancelRequest:
      type: object
      required:
        - cancelType
        - reason
      properties:
        cancelType:
          $ref: '#/components/schemas/CancelType'
          example: 1
          description: 取消类型
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        reason:
          type: string
          example: "改变租赁计划"
          description: 取消原因
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
    ConfirmRequest:
      type: object
      properties:
        confirmTime:
          type: string
          format: date-time
          description: 确认收货时间
        remark:
          type: string
          description: 备注信息
    ApprovalOrderRequest:
      type: object
      required:
        - approvalStatus
      properties:
        approvalStatus:
          $ref: '#/components/schemas/ApprovalStatus'
          example: 1
        approvalRemark:
          type: string
          description: 审批意见
        depositAmount:
          type: string
          format: decimal
          description: 押金金额(当状态为ApprovalStatusPartialDeposit时必填)
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
    UpdateOrderStatusRequest:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/OrderStatus'
          example: 1
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
    
    # 订单还款计划相关
    OrderRepaymentPlanCreateRequest:
      required: [amount, period, startTime, endTime,planRepaymentTime]
      properties:
        amount:
          type: string
          format: decimal
          description: 应还金额
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
        period:
          type: integer
          minimum: 1
          description: 总期数
        startTime:
          $ref: '#/components/schemas/DateTime'
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
          description: 开始时间
        endTime:
          $ref: '#/components/schemas/DateTime'
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
          description: 结束时间
        planRepaymentTime:
          $ref: '#/components/schemas/DateTime'
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
          description: 计划还款时间

    # 枚举类型定义
    OrderType:
      type: integer
      default: 0
      enum: [0, 1, 2]
      x-enum-varnames:
      - OrderTypeNew
      - OrderTypeRenew
      - OrderTypeUpgraded
      x-enum-descriptions:
      - 新租赁
      - 续租订单
      - 升级订单
    
    CancelType:
      type: integer
      enum: [1, 2, 3]
      x-enum-varnames:
        - UserInitiated
        - SystemAuto
        - RiskControl 
      x-enum-values:
        - 1 # 用户发起
        - 2 # 系统自动
        - 3 # 风控
      x-enum-descriptions:
        - 用户发起
        - 系统自动
        - 风控

    RentInfo:
      type: object
      required:
        - rentStart
        - rentPeriods
        - rentType
      properties:
        rentStart:
          type: string
          format: date-time
          example: "2024-04-01T00:00:00"
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        rentPeriods:
          type: integer
          description: 租期
          minimum: 1
          example: 12
        rentEnd:
          type: string
          format: date-time
          example: "2025-03-31T23:59:59"
        rentType:
          $ref: '#/components/schemas/RentType'
          example: 1
          description: 租期类型
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required

    RentType:
      type: integer
      enum: [1, 2]
      x-enum-varnames:
        - RentTypeFixed
        - RentTypeCustom
      x-enum-descriptions:
        - 固定租期
        - 自选租期

    OrderToPayInfo:
      type: object
      properties:
        totalAmount:
          type: number
          $ref: '#/components/schemas/Amount'
          description: 总金额
        discountAmount:
          type: number
          $ref: '#/components/schemas/Amount'
          description: 优惠金额
        depositAmount:
          type: number
          $ref: '#/components/schemas/Amount'
          description: 押金金额
        firstAmount:
          type: number
          $ref: '#/components/schemas/Amount'
          description: 首付金额
        rentAmount:
          type: number
          $ref: '#/components/schemas/Amount'
          description: 租金
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderToPayInfoItem'

    OrderToPayInfoItem:
      type: object
      properties:
        orderItemId:
          type: integer
          description: 订单项ID
        parentItemId:
          type: integer
          description: 父订单项ID
        totalAmount:
          $ref: '#/components/schemas/Amount'
          description: 总金额
        rentAmount:
          $ref: '#/components/schemas/Amount'
          description: 租金
        depositAmount:
          $ref: '#/components/schemas/Amount'
        discountAmount:
          $ref: '#/components/schemas/Amount'
          description: 优惠金额
        firstAmount:
          $ref: '#/components/schemas/Amount'
          description: 首付金额
        couponCodeId:
          type: integer
          description: 优惠券码ID
        

    OrderCreateProductItem:
      type: object
      required:
        - productId
        - skuId
        - quantity
      properties:
        productId:
          type: integer
          example: 1
          description: 商品ID
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        skuId:
          type: integer
          example: 1
          description: skuID
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        pricingId:
          type: integer
          example: 1
          description: 定价ID
        quantity:
          type: integer
          minimum: 1
          example: 1
          default: 1
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        assets:
          type: array
          items:
            type: integer
          example: [1,2] 
        parent:
          type: object
          description: Information about the parent product (if this is an accessory).  Null if this is a main product.
          $ref: '#/components/schemas/ParentOrderCreateProductItem'        

    ParentOrderCreateProductItem:
      type: object
      required:
        - productId
        - skuId
      properties:
        productId:
          type: integer
          example: 1
          description: 商品ID
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        skuId:
          type: integer
          example: 10
          description: skuID
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        pricingId:
          type: integer
          example: 100
          description: 定价ID
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required

    ProductItem:
      allOf:
        - $ref: '#/components/schemas/OrderCreateProductItem'
        - type: object
          properties:
            itemId:
              type: integer
              example: 1
              description: 订单项ID
            periodId:
              type: integer
              example: 1
            periodUnitDuration:
              type: integer
              example: 1
              description: 周期单位时长(秒)
            periodName:
              type: string
              example: "年|月|周|日"
            pricingId:
              type: integer
              example: 1
              description: 价格ID
            pricingName:
              type: string
              example: "基础租金"
              description: 价格名称
            unitPrice:
              $ref: '#/components/schemas/Amount'
              description: 单价
            totalPrice:
              $ref: '#/components/schemas/Amount'
              description: 总价
            productName:
              type: string
            thumbnail:
              type: string
            skuSpecs:
              type: array
              description: sku规格
              items:
                $ref: '#/components/schemas/SkuSpec'
            orderPayPeriods:
              type: integer
              description: 订单支付周期
              example: 1
            firstPayPeriods:
              type: integer
              description: 首付期数
              example: 3
            depositAmount:
              $ref: '#/components/schemas/Amount'
              description: 押金金额
            pricePerPeriod:
              $ref: '#/components/schemas/Amount'
              description: 每个周期的租金
            depositUnitPrice:
              $ref: '#/components/schemas/Amount'
              description: 押金单价
            parentItemId:
              type: integer
              description: 父订单Item ID

    OrderDetailInfo:
      type: object
      required:
        - id
        - orderNo
        - userId
        - status
        - parentOrderId
        - rentType
      properties:
        id:
          type: integer
          description: 订单ID
        orderNo:
          type: string
          description: 订单编号
        userId:
          type: integer
          description: 用户ID
        rentBegin:
          type: string
          format: date-time
          description: 租赁起始时间
          example: "2024-04-01T00:00:00"
        rentEnd:
          type: string
          format: date-time
          description: 租赁结束时间
          example: "2025-03-31T23:59:59"
        rentType:
          $ref: '#/components/schemas/RentType'
          example: 1
          description: 租期类型
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        periods:
          type: integer
          description: 租期数(与主商品同)
          example: 12
        totalAmount:
          $ref: '#/components/schemas/Amount'
          description: 总租金(不含押金)
          example: 1000.00
        createdAt:
          type: string
          format: date-time
          description: 创建时间
          example: "2024-04-01T00:00:00"
        updatedAt:
          type: string
          format: date-time
          description: 更新时间
          example: "2024-04-01T00:00:00"
        orderType:
          $ref: '#/components/schemas/OrderType'
        approvalStatus:
          $ref: '#/components/schemas/ApprovalStatus'
        deliveryInfo:
          $ref: '#/components/schemas/DeliveryInfo'
        status:
          $ref: '#/components/schemas/OrderStatus'
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProductItem'
          description: 商品明细
        parentOrderId:
          type: integer
          description: 父订单ID
        parentOrder:
          $ref: '#/components/schemas/OrderDetailInfo'
        childOrders:
          type: array
          items:
            $ref: '#/components/schemas/OrderDetailInfo'
          description: 子订单

    PaymentPlan:
      type: object
      properties:
        planId:
          type: string
        billDate:
          type: string
          format: date
        dueDate:
          type: string
          format: date
        amount:
          type: number
          format: double
        status:
          type: string
          enum: [PENDING, BILLED, PAID, OVERDUE]
        billId:
          type: string

    OrderStatus:
      type: integer
      enum: [0, 1, 2, 3, 4, 5, 6, 10, 7, 41]
      description: 订单状态
      x-enum-varnames:
        # 0
        - OrderStatusUnpaid 
        # 1
        - OrderStatusPaid
        # 2
        - OrderStatusShipped
        # 3
        - OrderStatusInService
        # 4
        - OrderStatusAllBillPaid
        # 5
        - OrderStatusCompleted
        # 6
        - OrderStatusClosed
        # 10
        - OrderStatusCanceled
        # 7
        - OrderStatusBuyout
        # 41
        - OrderStatusSettled
      x-enum-descriptions:
        # 0
        - 待支付
        # 1
        - 已支付
        # 2
        - 已发货
        # 3
        - 服务中
        # 4
        - 已付清账单
        # 5
        - 已完成
        # 6
        - 已关闭
        # 10
        - 已取消
        # 7
        - 已买断
        # 41 已结算待支付
        - 已结算待支付
    DateTime:
      type: string
      format: date-time
      description: 时间
      x-go-type: types.DateTime
      x-go-import: code.kuaizu.cn/lz_new/lizu-util/lzutil/types

    Amount:
      type: string
      format: decimal
      description: 金额
      x-go-type: decimal.Decimal
      x-go-type-import:
        path: github.com/shopspring/decimal
        name: decimal

    ApprovalStatus:
      type: integer 
      enum: [0, 1, 2, 10]
      description: 审批状态
      x-enum-varnames:
        # 0
        - ApprovalStatusPending
        # 1
        - ApprovalStatusApproved
        # 2
        - ApprovalStatusRejected
        # 3
        - ApprovalStatusPartialDeposit
        # 10
        - ApprovalStatusCancel
      x-enum-descriptions:
        # 0
        - 待审批
        # 1
        - 已批准
        # 2
        - 已拒绝
        # 3
        - 部分押金
        # 10
        - 已取消

    PageNum:
      type: integer
      minimum: 1
      default: 1
      example: 1

    PageSize:
      type: integer
      minimum: 1
      maximum: 100
      default: 20
      example: 20

    SortBy:
      type: string
      x-oapi-codegen-extra-tags:
        binding: "omitempty,oneof=createdAt updatedAt orderNo"

    SortOrder:
      type: string
      enum: [ASC, DESC]

    Order:
      type: object
      properties:
        id:
          type: integer
          description: 订单ID
        orderNo:
          type: string
          description: 订单编号
          example: "DD1234567890"
        userId:
          type: integer
          description: 用户ID
        vendorId:
          type: integer
          description: 商户ID
        orderType:
          $ref: '#/components/schemas/OrderType'
        orderSource:
          type: string
          enum: [web, mobile, pos, api]
          description: 订单来源
        status:
          $ref: '#/components/schemas/OrderStatus'
        approvalStatus:
          $ref: '#/components/schemas/ApprovalStatus'
        createdTime:
          type: string
          format: date-time
          description: 创建时间
        updatedTime:
          type: string
          format: date-time
          description: 更新时间
        completedTime:
          type: string
          format: date-time
          description: 完结时间
        rentBegin:
          type: string
          format: date-time
          description: 租赁起始时间
        rentEnd:
          type: string
          format: date-time
          description: 租赁结束时间
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProductItem'
          description: 商品明细

    AmountDetail:
      type: object
      properties:
        amountType:
          type: string
          enum: [RENT, DEPOSIT, SERVICE_FEE, DISCOUNT, OTHER]
          description: 费用类型
        amount:
          type: string
          format: decimal
          description: 金额数值
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
        displayName:
          type: string
          description: 前端显示名称
          x-examples: 
            - value: "基础租金"
            - value: "设备押金"
        editable:
          type: boolean
          description: 是否允许用户修改
          default: false
        originalAmount:
          type: string
          format: decimal
          description: 原始金额（优惠前）
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
        remark:
          type: string
          description: 费用说明
      required:
        - amountType
        - amount

    OrderPreview:
      type: object
      properties:
        amounts:
          type: array
          items:
            $ref: '#/components/schemas/AmountDetail'
        rentPeriod:
          type: integer
        rentDates:
          type: object
          properties:
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
        productsPreview:
          type: array
          items:
            $ref: '#/components/schemas/ProductPreview'

    ProductPreview:
      type: object
      properties:
        productId:
          type: integer
        productName:
          type: string
        thumbnail:
          type: string

    # 新增发货请求结构
    DeliveryRequest:
      type: object
      required:
        - deliveryTime
        - deliveredBy
        - deliveryMethodId
      properties:
        deliveryTime:
          type: string
          format: date-time
          example: "2024-04-01 14:00:00"
          description: 实际发货时间
        deliveredBy:
          type: string
          example: "system_auto"
          description: 发货操作人
        deliveryMethodId:
          type: integer
          example: 1
          description: 发货方式ID
        trackingNo:
          type: string
          example: "SF123456789"
          description: 物流单号
        warehouse:
          type: string
          example: "上海仓"
        attachments:
          type: array
          items:
            type: string
          example: ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
          description: 发货凭证
        sign:
          type: array
          items:
            type: string
          example: ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
          description: 签收凭证
        parameters:
          type: string
          description: 发货参数(JSON格式)

    # 在已有组件基础上新增
    OrderDetailResponse:
      allOf:
        - $ref: '#/components/schemas/BasicResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/Order'

    # 新增资产项定义
    AssetItem:
      type: object
      properties:
        assetId:
          type: string
          description: 资产唯一标识
          example: "ASSET-12345"
        assetName:
          type: string
          description: 资产名称
          example: "MacBook Pro 2023"
        assetStatus:
          type: string
          enum: [IN_STOCK, DELIVERED, RETURNED, BUYOUT]
          description: 资产状态
        sn:
          type: string
          description: 序列号
          example: "C02XL0XXXXX"
        thumbnail:
          type: string
          description: 资产图片
          example: "https://example.com/image.jpg"
        returnTime:
          type: string
          format: date-time
          description: 归还时间
        buyoutTime:
          type: string
          format: date-time
          description: 买断时间

    # 补充发货信息实体
    DeliveryInfo:
      type: object
      properties:
        deliveryId:
          type: integer
          example: 1
        deliveryTime:
          type: string
          format: date-time
          example: "2024-04-01 14:00:00"
        deliveredBy:
          type: string
          example: "system_auto"
        deliveryMethod:
          type: string
          example: "快递"
        trackingNo:
          type: string
          example: "SF123456789"
        warehouse:
          type: string
          example: "上海仓"
        attachments:
          type: array
          items:
            type: string
          example: ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
          description: 发货凭证
        sign:
          type: array
          items:
            type: string
          example: ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
          description: 签收凭证
        status:
          $ref: '#/components/schemas/DeliveryStatus'
          description: 发货状态
          example: 1
        actualPickupTime:
          type: string
          format: date-time
          example: "2024-04-01 15:30:00"
          description: 实际取车时间
        actualReturnTime:
          type: string
          format: date-time
          example: "2024-04-15 10:00:00"
          description: 实际还车时间

    # 新增发货状态枚举
    DeliveryStatus:
      type: integer
      enum: 
        - 0    # 待发货
        - 1    # 已发货
        - 2    # 已送达
        - 3    # 物流异常
      x-enum-varnames:
        - DeliveryStatusPending
        - DeliveryStatusShipped
        - DeliveryStatusDelivered
        - DeliveryStatusException

    # sku规格定义
    SkuSpec:
      type: object
      properties:
        name:
          type: string
          description: 规格名称
          example: "颜色"
        value:
          type: string
          description: 规格值
          example: "深空灰"
        image:
          type: string
          description: 规格图片
          example: "https://example.com/gray.jpg"
    OrderEventPayload:
      type: object
      required:
        - recordName
        - recordId
      properties:
        recordName:
          type: string
          description: 记录名称
          example: "订单创建"
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        recordId:
          type: integer
          description: 记录ID
          example: 12345
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        payload:
          type: object
          description: 事件负载
          example: {
            "orderId": 12345,
            "orderNo": "DD1234567890",
            "userId": 1,
            "vendorId": 1,
          }

    # 订单关闭请求
    CloseOrderRequest:
      type: object
      required:
        - closeType
        - reason
      properties:
        closeType:
          type: integer
          enum: [1, 2, 3]
          x-enum-varnames:
            - AdminInitiated
          x-enum-descriptions:
            - 管理员发起
          description: 关闭类型
        reason:
          type: string
          description: 关闭原因
        closeAt:
          type: string
          format: datetime
          description: 关闭时间
        operator:
          type: string
          description: 操作人

    # 结算类型枚举
    SettlementType:
      type: integer
      enum: [1, 2]
      description: 结算类型
      x-enum-varnames:
        - SettlementTypeBuyout    # 买断
        - SettlementTypeCompletion # 结算
      x-enum-descriptions:
        - 买断
        - 结算

    # 结算状态枚举
    SettlementStatusEnum:
      type: integer
      enum: [0, 1, 2, 3, 4, 5]
      description: 结算状态
      x-enum-varnames:
        - SettlementStatusPending    # 待审批
        - SettlementStatusApproved   # 已审批，待支付
        - SettlementStatusPaid       # 已支付
        - SettlementStatusCompleted  # 已完成
        - SettlementStatusRejected   # 已拒绝
        - SettlementStatusCanceled   # 已取消
      x-enum-descriptions:
        - 待审批
        - 已审批，待支付
        - 已支付
        - 已完成
        - 已拒绝
        - 已取消

    # 结算信息
    SettlementInfo:
      type: object
      properties:
        id:
          type: integer
          description: 结算记录ID
        orderId:
          type: integer
          description: 订单ID
        userId:
          type: integer
          description: 用户ID
        settlementType:
          $ref: '#/components/schemas/SettlementType'
        status:
          $ref: '#/components/schemas/SettlementStatusEnum'
        assets:
          type: array
          items:
            type: object
            properties:
              assetId:
                type: string
              settlementPrice:
                type: string
                format: decimal
                description: 结算价格
                x-go-type: decimal.Decimal
                x-go-type-import:
                  path: github.com/shopspring/decimal
                  name: decimal
        totalAmount:
          type: string
          format: decimal
          description: 结算总金额
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
        unpaidAmount:
          type: string
          format: decimal
          description: 未洁清账单金额
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
        unitPrice:
          type: string
          format: decimal
          description: 单价
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
        quantity:
          type: integer
          description: 数量
        createdAt:
          type: string
          format: date-time
          description: 创建时间
        updatedAt:
          type: string
          format: date-time
          description: 更新时间
        remark:
          type: string
          description: 备注信息

    # 订单结算检查结果
    OrderSettlementCheckResult:
      type: object
      required:
        - orderId
        - canSettle
        - items
      properties:
        orderId:
          type: integer
          description: 订单ID
        canSettle:
          type: boolean
          description: 是否可结算
        reason:
          type: string
          description: 不可结算原因
        items:
          type: array
          items:
            $ref: '#/components/schemas/orderSettlementCheckResultItem'
        totalAmount:
          $ref: '#/components/schemas/Amount'
          description: 预估结算总金额
        unpaidAmount:
          $ref: '#/components/schemas/Amount'
          description: 未洁清账单金额
        unitPrice:
          type: string
          format: decimal
          description: 单价
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
        quantity:
          type: integer
          description: 数量
          
    orderSettlementCheckResultItem:
      type: object
      required:
        - itemId
        - canSettle
      properties:
        itemId:
          type: integer
          description: 订单项ID
        settlementPrice:
          type: string
          format: decimal
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
          description: 结算价格
        unpaidAmount:
          type: string
          format: decimal
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
          description: 未洁清账单
        canSettle:
          type: boolean
          description: 是否可结算
        reason:
          type: string
          description: 不可结算原因

    # v0.9 新增数据模型
    OrderAsset:
      type: object
      required:
        - id
        - orderId
        - assetId
        - assetNo
        - status
      properties:
        id:
          type: integer
          format: int64
          description: 记录ID
        orderId:
          type: integer
          format: int64
          description: 订单ID
        assetId:
          type: integer
          format: int64
          description: 资产服务中的资产ID
        assetNo:
          type: string
          description: 资产编号
        status:
          $ref: '#/components/schemas/OrderAssetStatus'
        configInfo:
          type: object
          description: 资产配置信息（JSON格式）
        createdAt:
          type: string
          format: date-time
          description: 创建时间
        updatedAt:
          type: string
          format: date-time
          description: 更新时间

    OrderAssetStatus:
      type: integer
      enum: [0, 1, 2, 3, 4]
      x-enum-varnames:
        - AssetStatusCreated
        - AssetStatusInUse
        - AssetStatusReturned
        - AssetStatusBuyout
        - AssetStatusCanceled
      x-enum-descriptions:
        - 已创建
        - 使用中
        - 已归还
        - 已买断
        - 已取消

    UpdateOrderRepaymentPlanRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: uint
          description: 还款计划ID
        startTime:
          $ref: '#/components/schemas/DateTime'
          description: 开始时间
        endTime:
          $ref: '#/components/schemas/DateTime'
          description: 结束时间
        amount:
          type: string
          format: decimal
          description: 应还金额
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
        period:
          type: integer
          minimum: 1
          description: 总期数
        planRepaymentTime:
          $ref: '#/components/schemas/DateTime'
          description: 计划还款时间 
        status:
          $ref: '#/components/schemas/PaymentPlanStatus'
          description: 还款计划状态

    CreateOrderRepaymentPlanRequest:
      type: object
      required:
        - startTime
        - endTime
        - amount
        - period
        - planRepaymentTime
      properties:
        startTime:
          $ref: '#/components/schemas/DateTime'
          description: 开始时间
        endTime:
          $ref: '#/components/schemas/DateTime'
          description: 结束时间
        amount:
          type: string
          format: decimal
          description: 应还金额
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
        period:
          type: integer
          minimum: 1
          description: 总期数
        planRepaymentTime:
          $ref: '#/components/schemas/DateTime'
          description: 计划还款时间 


    OrderRepaymentPlan:
      type: object
      required:
        - id
        - orderId
        - amount 
        - period
        - sequence
        - status
        - startTime
        - endTime
      properties:
        id:
          type: integer
          format: int64
          description: 还款计划ID
        orderId:
          type: integer
          format: int64
          description: 订单ID
        amount:
          $ref: '#/components/schemas/Amount'
        period:
          type: integer
          minimum: 1
          description: 期数
        sequence:
          type: integer
          minimum: 1
          description: 期数序号
        status:
          $ref: '#/components/schemas/PaymentPlanStatus'
        startTime:
          $ref: '#/components/schemas/DateTime'
          description: 开始时间
        endTime:
          $ref: '#/components/schemas/DateTime'
          description: 结束时间
        createdAt:
          $ref: '#/components/schemas/DateTime'
          description: 创建时间
        updatedAt:
          $ref: '#/components/schemas/DateTime'
          description: 更新时间

    AssetRepaymentPlan:
      type: object
      required:
        - id
        - orderId
        - assetNo
        - planType
        - amount
        - status
        - planRepaymentTime
        - startTime
        - endTime
      properties:
        id:
          type: integer
          format: int64
          description: 还款计划ID
        orderId:
          type: integer
          format: int64
          description: 订单ID
        assetNo:
          type: string
          description: 资产编号
        planType:
          $ref: '#/components/schemas/PlanType'
        amount:
          type: number
          format: double
          description: 应付金额
        status:
          $ref: '#/components/schemas/PaymentPlanStatus'
        planRepaymentTime:
          type: string
          format: date-time
          description: 计划还款时间
        actualAmount:
          type: number
          format: double
          description: 实际还款金额
        actualRepaymentTime:
          $ref: '#/components/schemas/DateTime'
          description: 实际还款时间
        startTime:
          $ref: '#/components/schemas/DateTime'
          description: 开始时间
        endTime:
          $ref: '#/components/schemas/DateTime'
          description: 结束时间
        createdAt:
          $ref: '#/components/schemas/DateTime'
          description: 创建时间
        updatedAt:
          $ref: '#/components/schemas/DateTime'
          description: 更新时间
    UpdateAssetRepaymentPlanRequest:
      type: object
      properties:
        planRepaymentTime:
          $ref: '#/components/schemas/DateTime'
          description: 计划还款时间
        startTime:
          $ref: '#/components/schemas/DateTime'
          description: 开始时间
        endTime:
          $ref: '#/components/schemas/DateTime'
          description: 结束时间
        status:
          $ref: '#/components/schemas/PaymentPlanStatus'
          description: 还款计划状态
        amount:
          type: number
          format: double
          description: 应付金额
        period:
          type: integer
          minimum: 1
          description: 总期数
        actualAmount:
          type: number
          format: double
          description: 实际还款金额
        actualRepaymentTime:
          $ref: '#/components/schemas/DateTime'
          description: 实际还款时间
        remark:
          type: string
          description: 备注
    PaymentPlanStatus:
      type: integer
      enum: [0, 1, 2, 3, 4]
      x-enum-varnames:
        - PaymentPlanStatusCreated
        - PaymentPlanStatusExecuting
        - PaymentPlanStatusCompleted
        - PaymentPlanStatusPaused
        - PaymentPlanStatusCanceled
      x-enum-descriptions:
        - 已创建
        - 执行中
        - 已完成
        - 已暂停
        - 已取消

    PlanType:
      type: string
      enum: [DEPOSIT, RENT, GUARANTEE, BUYOUT, PENALTY, OTHER]
      x-enum-varnames:
        - PlanTypeDeposit
        - PlanTypeRent
        - PlanTypeGuarantee
        - PlanTypeBuyout
        - PlanTypePenalty
        - PlanTypeOther
      x-enum-descriptions:
        - 首付/定金
        - 租金
        - 保证金
        - 买断款
        - 违约金
        - 其他费用
    # 订单结算
    CreateOrderSettlementRequest:
      type: object
      required:
        - settlementType
      properties:
        settlementType:
          $ref: '#/components/schemas/SettlementType'
        remark:
          type: string
          description: 备注

  responses:
    BadRequest:
      description: 非法请求参数
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: 资源未找到
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: 未授权
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  parameters:
    PagingPageNum:
      name: pageNum
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
        x-oapi-codegen-extra-tags:
          binding: "omitempty,min=1"
          validate: "omitempty,min=1"

    PagingPageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
        x-oapi-codegen-extra-tags:
          binding: "omitempty,min=1,max=100"
          validate: "omitempty,min=1,max=100"

    PagingSortBy:
      name: sort
      in: query
      schema:
        type: string
        default: "createdAt"
        x-oapi-codegen-extra-tags:
          binding: "omitempty,oneof=createdAt updatedAt orderNo"

    PagingSortOrder:
      name: order
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: "desc"
        x-oapi-codegen-extra-tags:
          binding: "omitempty,oneof=asc desc"

    # 标准数组参数定义模板
    StatusFilter:
      name: statuses
      in: query
      description: 状态过滤
      style: form  # 定义参数序列化方式
      explode: false  # 关闭自动展开
      schema:
        type: array
        items:
          type: integer
          enum: [0,1,2]  # 枚举值定义在items层级
          x-enum-varnames: [StatusPending, StatusActive, StatusClosed]
      x-oapi-codegen-extra-tags:  # 校验标签在参数层级
        binding: "omitempty,dive,oneof=0 1 2"
        validate: "omitempty,dive,oneof=0 1 2"

    # Expand参数优化版
    OrderExpand:
      name: expand
      in: query
      style: form
      explode: false
      schema:
        type: array
        items: 
          type: string  # 直接定义类型
          enum: [items, delivery, parent, children]  # 内联枚举值
          x-enum-varnames: [ExpandItems, ExpandDelivery, ExpandParent, ExpandChildren]  # 保持代码常量
          x-enum-descriptions: ["订单商品", "发货信息", "父订单", "子订单"]

