asyncapi: 3.0.0
info:
  title: 订单服务异步消息API
  version: 1.0.0
  description: |
    订单服务发布的异步消息API文档
    
    ## 业务场景
    - 订单服务负责还款计划管理、结算处理和资产收益计算
    - 通过异步消息向其他服务（如账单服务、支付服务）发布相关事件
    
    ## 消息流程
    ### 还款计划流程
    1. 还款计划创建 → 发送还款计划创建事件
    2. 还款计划状态变更 → 发送还款计划更新事件
    3. 订单取消 → 发送还款计划取消事件
    
    ### 结算流程
    1. 用户开始结算 → 发送结算创建事件
    2. 结算状态变更 → 发送结算状态更新事件
    3. 结算完成 → 发送结算完成事件
  contact:
    name: 订单服务团队
    email: order-team@company.com
  license:
    name: MIT

defaultContentType: application/json

servers:
  production:
    host: nats.company.com:4222
    protocol: nats
    description: 生产环境NATS服务器
    bindings:
      nats:
        servers:
          - nats://nats.company.com:4222
  development:
    host: localhost:4222
    protocol: nats
    description: 开发环境NATS服务器
    bindings:
      nats:
        servers:
          - nats://localhost:4222

channels:
  orderRepaymentPlanCreated:
    address: order.repayment_plan.created
    messages:
      RepaymentPlanCreated:
        $ref: '#/components/messages/RepaymentPlanCreated'
    description: 还款计划创建事件通道

  orderRepaymentPlanUpdated:
    address: order.repayment_plan.updated
    messages:
      RepaymentPlanUpdated:
        $ref: '#/components/messages/RepaymentPlanUpdated'
    description: 还款计划更新事件通道

  orderRepaymentPlanCancelled:
    address: order.repayment_plan.cancelled
    messages:
      RepaymentPlanCancelled:
        $ref: '#/components/messages/RepaymentPlanCancelled'
    description: 还款计划取消事件通道

  orderStatusChanged:
    address: order.status.changed
    messages:
      OrderStatusChanged:
        $ref: '#/components/messages/OrderStatusChanged'
    description: 订单状态变更事件通道

  orderSettlementCreated:
    address: order.settlement.created
    messages:
      SettlementCreated:
        $ref: '#/components/messages/SettlementCreated'
    description: 订单结算创建事件通道

  orderSettlementStatusUpdated:
    address: order.settlement.status_updated
    messages:
      SettlementStatusUpdated:
        $ref: '#/components/messages/SettlementStatusUpdated'
    description: 订单结算状态更新事件通道

  orderSettlementCompleted:
    address: order.settlement.completed
    messages:
      SettlementCompleted:
        $ref: '#/components/messages/SettlementCompleted'
    description: 结算完成事件通道

operations:
  publishRepaymentPlanCreated:
    action: send
    channel:
      $ref: '#/channels/orderRepaymentPlanCreated'
    summary: 发布还款计划创建事件
    description: 当订单创建完成并生成还款计划后，发布此事件通知其他服务

  publishRepaymentPlanUpdated:
    action: send
    channel:
      $ref: '#/channels/orderRepaymentPlanUpdated'
    summary: 发布还款计划更新事件
    description: 当还款计划状态发生变更时，发布此事件

  publishRepaymentPlanCancelled:
    action: send
    channel:
      $ref: '#/channels/orderRepaymentPlanCancelled'
    summary: 发布还款计划取消事件
    description: 当订单取消或还款计划被取消时，发布此事件

  publishOrderStatusChanged:
    action: send
    channel:
      $ref: '#/channels/orderStatusChanged'
    summary: 发布订单状态变更事件
    description: 当订单状态发生变更时，发布此事件

  publishSettlementCreated:
    action: send
    channel:
      $ref: '#/channels/orderSettlementCreated'
    summary: 发布结算创建事件
    description: 当订单结算创建后，发布此事件通知其他服务

  publishSettlementStatusUpdated:
    action: send
    channel:
      $ref: '#/channels/orderSettlementStatusUpdated'
    summary: 发布结算状态更新事件
    description: 当订单结算状态发生变更时，发布此事件

  publishSettlementCompleted:
    action: send
    channel:
      $ref: '#/channels/orderSettlementCompleted'
    summary: 发布结算完成事件
    description: 当结算流程完成时，发布此事件

components:
  messages:
    RepaymentPlanCreated:
      name: RepaymentPlanCreated
      title: 还款计划创建事件
      summary: 订单创建完成，生成还款计划后发布的事件
      contentType: application/json
      payload:
        $ref: '#/components/schemas/RepaymentPlanCreatedPayload'
      examples:
        - name: 订单还款计划创建示例
          summary: 包含2期还款计划和2个资产的订单
          payload:
            eventType: order.repayment_plan.created
            timestamp: "2024-01-20T10:00:00Z"
            orderId: 12345
            userId: 67890
            plans:
              - planId: 1
                orderId: 12345
                assetNo: "ASSET001"
                planType: "RENT"
                amount: 500.00
                period: 1
                planRepaymentTime: "2024-02-20T00:00:00Z"
                startTime: "2024-01-20T00:00:00Z"
                endTime: "2024-02-20T00:00:00Z"
                status: "CREATED"

    RepaymentPlanUpdated:
      name: RepaymentPlanUpdated
      title: 还款计划更新事件
      summary: 还款计划状态发生变更时发布的事件
      contentType: application/json
      payload:
        $ref: '#/components/schemas/RepaymentPlanUpdatedPayload'

    RepaymentPlanCancelled:
      name: RepaymentPlanCancelled
      title: 还款计划取消事件
      summary: 订单取消或还款计划被取消时发布的事件
      contentType: application/json
      payload:
        $ref: '#/components/schemas/RepaymentPlanCancelledPayload'

    OrderStatusChanged:
      name: OrderStatusChanged
      title: 订单状态变更事件
      summary: 订单状态发生变更时发布的事件
      contentType: application/json
      payload:
        $ref: '#/components/schemas/OrderStatusChangedPayload'

    SettlementCreated:
      name: SettlementCreated
      title: 结算创建事件
      summary: 订单结算创建后发布的事件
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SettlementCreatedPayload'

    SettlementStatusUpdated:
      name: SettlementStatusUpdated
      title: 结算状态更新事件
      summary: 订单结算状态变更时发布的事件
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SettlementStatusUpdatedPayload'

    SettlementCompleted:
      name: SettlementCompleted
      title: 结算完成事件
      summary: 结算流程完成时发布的事件
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SettlementCompletedPayload'
      examples:
        - name: 买断结算完成示例
          summary: 用户买断结算完成
          payload:
            eventType: order.settlement.completed
            timestamp: "2024-01-20T15:30:00Z"
            settlementId: 1001
            orderId: 12345
            userId: 67890
            settlementType: 1
            totalAmount: 15000.00
            settlementTime: "2024-01-20T15:30:00Z"
            paymentReference: "PAY202401201530001"

  schemas:
    RepaymentPlanCreatedPayload:
      type: object
      required:
        - eventType
        - timestamp
        - orderId
        - userId
        - plans
      properties:
        eventType:
          type: string
          const: order.repayment_plan.created
          description: 事件类型
        timestamp:
          type: string
          format: date-time
          description: 事件发生时间
        orderId:
          type: integer
          format: int64
          description: 订单ID
          example: 12345
        userId:
          type: integer
          format: int64
          description: 用户ID
          example: 67890
        plans:
          type: array
          description: 还款计划列表
          items:
            $ref: '#/components/schemas/RepaymentPlanInfo'

    RepaymentPlanInfo:
      type: object
      required:
        - planId
        - orderId
        - planType
        - amount
        - planRepaymentTime
        - paymentTime
        - status
        - name
      properties:
        planId:
          type: integer
          format: int64
          description: 还款计划ID
        orderId:
          type: integer
          format: int64
          description: 订单ID
        assetNo:
          type: string
          description: 资产编号（资产还款计划专用）
          example: "ASSET001"
        planType:
          type: string
          enum: [RENT, DEPOSIT, BUYOUT, PENALTY, GUARANTEE, OTHER]
          description: 计划类型
        amount:
          type: number
          format: decimal
          description: 应付金额
          example: 1000.00
          x-go-type: decimal.Decimal
          x-go-package: github.com/shopspring/decimal
        period:
          type: integer
          description: 期数（订单还款计划专用）
          example: 1
        sequence:
          type: integer
          description: 期数序号
          minimum: 1
        planRepaymentTime:
          type: string
          format: date-time
          description: 计划还款时间
        paymentTime:
          type: string
          format: date-time
          description: 实际还款时间
        startTime:
          type: string
          format: date-time
          description: 计划开始时间
        endTime:
          type: string
          format: date-time
          description: 计划结束时间
        status:
          type: integer
          enum: [0, 1, 2, 3, 4]
          description: "还款计划状态: 0-已创建, 1-执行中, 2-已完成, 3-已暂停, 4-已取消"
        name:
          type: string
          description: 还款计划名称

    RepaymentPlanUpdatedPayload:
      type: object
      required:
        - eventType
        - timestamp
        - planId
        - orderId
        - oldStatus
        - newStatus
        - amount
      properties:
        eventType:
          type: string
          const: order.repayment_plan.updated
          description: 事件类型
        timestamp:
          type: string
          format: date-time
          description: 事件发生时间
        planId:
          type: integer
          format: int64
          description: 还款计划ID
        orderId:
          type: integer
          format: int64
          description: 订单ID
        oldStatus:
          type: integer
          description: 旧状态
        newStatus:
          type: integer
          description: 新状态
        updatedBy:
          type: string
          description: 更新人
          example: "system"
        amount:
          type: number
          format: decimal
          description: 金额
          x-go-type: decimal.Decimal
          x-go-package: github.com/shopspring/decimal

    RepaymentPlanCancelledPayload:
      type: object
      required:
        - eventType
        - timestamp
        - planId
        - orderId
        - reason
      properties:
        eventType:
          type: string
          const: order.repayment_plan.cancelled
          description: 事件类型
        timestamp:
          type: string
          format: date-time
          description: 事件发生时间
        planId:
          type: integer
          format: int64
          description: 还款计划ID
        orderId:
          type: integer
          format: int64
          description: 订单ID
        reason:
          type: string
          description: 取消原因

    # 注意：基础事件字段（eventId, eventTime, eventSource, eventVersion）
    # 由 lznats.BaseEventArg 自动管理，不在 payload schemas 中定义
    OrderStatusChangedPayload:
      type: object
      required:
        - order
      properties:
        order:
          description: "订单状态变更事件载体，直接引用自 OpenAPI 的 contract.Order 定义。"
          x-go-type: "contract.OrderDetailInfo"
          x-go-type-import:
            path: "e.coding.net/serverless-100010656840/services/order-contract/order/contract"
            name: "contract"

    SettlementInfoSchema:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 结算ID
        orderId:
          type: integer
          format: int64
          description: 订单ID
        userId:
          type: integer
          format: int64
          description: 用户ID
        settlementType:
          type: integer
          enum: [1, 2]
          description: "结算类型: 1-买断, 2-完成"
        status:
          type: integer
          enum: [0, 1, 2, 3, 4, 5]
          description: "结算状态: 0-待审批, 1-已审批, 2-已支付, 3-已完成, 4-已拒绝, 5-已取消"
        totalAmount:
          type: number
          format: decimal
          description: 结算总金额
        remark:
          type: string
          description: 备注
        unitPrice:
          type: number
          format: decimal
          description: 单价
        quantity:
          type: integer
          description: 数量
        settlementTime:
          type: string
          format: date-time
          description: 结算时间

    SettlementCreatedPayload:
      type: object
      required:
        - eventType
        - timestamp
        - settlement
      properties:
        eventType:
          type: string
          const: order.settlement.created
        timestamp:
          type: string
          format: date-time
        settlement:
          $ref: '#/components/schemas/SettlementInfoSchema'

    SettlementStatusUpdatedPayload:
      type: object
      required:
        - eventType
        - timestamp
        - settlementId
        - orderId
        - oldStatus
        - newStatus
      properties:
        eventType:
          type: string
          const: order.settlement.status_updated
        timestamp:
          type: string
          format: date-time
        settlementId:
          type: integer
          format: int64
        orderId:
          type: integer
          format: int64
        oldStatus:
          type: integer
        newStatus:
          type: integer
        updatedBy:
          type: string
          description: 更新人
          example: "admin"
        remark:
          type: string
          description: 状态变更备注
          example: "审批通过"

    SettlementCompletedPayload:
      type: object
      required:
        - eventType
        - timestamp
        - settlementId
        - orderId
        - userId
        - settlementType
        - totalAmount
        - settlementTime
      properties:
        eventType:
          type: string
          const: order.settlement.completed
          description: 事件类型
        timestamp:
          type: string
          format: date-time
          description: 事件发生时间
        settlementId:
          type: integer
          format: int64
          description: 结算记录ID
        orderId:
          type: integer
          format: int64
          description: 订单ID
        userId:
          type: integer
          format: int64
          description: 用户ID
        settlementType:
          type: integer
          enum: [1, 2]
          description: "结算类型: 1-买断, 2-完成"
        totalAmount:
          type: number
          format: decimal
          description: 结算总金额
        settlementTime:
          type: string
          format: date-time
          description: 结算完成时间
        paymentReference:
          type: string
          description: 支付参考号
          example: "PAY202401201530001"

  messageTraits:
    commonHeaders:
      headers:
        type: object
        properties:
          messageId:
            type: string
            description: 消息唯一标识
          correlationId:
            type: string
            description: 关联ID，用于追踪消息链路
          timestamp:
            type: string
            format: date-time
            description: 消息发送时间
          source:
            type: string
            description: 消息来源服务
            const: order-service

  operationTraits:
    withCorrelationId:
      summary: 包含关联ID的操作
      description: 用于消息追踪和关联
    withRetry:
      summary: 支持重试的操作
      description: 消息处理失败时会自动重试

x-go-type-import:
  decimal.Decimal: github.com/shopspring/decimal
  time.Time: time