baiyue-firstleg/order/src/main/resources/openapi/order-v1.yaml

openapi: 3.0.3
info:
  title: 柏悦头程订单 API
  version: 1.1.0
security:
  - bearerAuth: []
paths:
  /api/merchant/v1/orders/first-leg:
    post:
      summary: 创建订单草稿
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: 创建成功或同请求重放成功，返回相同订单ID
        '400':
          description: 缺少或使用了无效幂等键
        '409':
          description: 相同幂等键对应不同请求或请求仍在处理中
        '503':
          description: 仓库或往来单位下游服务异常
  /api/merchant/v1/orders/first-leg/{id}/submit:
    post:
      summary: 提交订单
      parameters:
        - $ref: '#/components/parameters/OrderId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: 提交成功或同请求重放成功
        '400':
          description: 缺少或使用了无效幂等键
        '404':
          description: 订单不存在
        '409':
          description: 幂等键冲突、请求处理中或订单状态冲突
        '503':
          description: 仓库或往来单位下游服务异常
  /api/platform/v1/orders/first-leg:
    post:
      summary: 平台代客创建订单草稿
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: 创建成功或同请求重放成功
        '403':
          description: 需要 platform:order:create 权限
        '409':
          description: 幂等键冲突或请求仍在处理
  /api/platform/v1/orders/first-leg/{id}/submit:
    post:
      summary: 平台代客提交指定订单
      parameters:
        - $ref: '#/components/parameters/OrderId'
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: 提交成功或同请求重放成功
        '403':
          description: 需要 platform:order:submit 权限
        '404':
          description: 订单不存在
        '409':
          description: 幂等键冲突或当前订单不可提交
  /api/platform/v1/orders/first-leg/{id}:
    put:
      summary: 平台编辑指定订单草稿
      parameters:
        - $ref: '#/components/parameters/OrderId'
        - $ref: '#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: 编辑成功
        '403':
          description: 需要 platform:order:edit 权限
        '404':
          description: 订单不存在
        '409':
          description: 当前订单不可编辑
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    TenantId:
      name: tenantId
      in: query
      required: true
      schema:
        type: integer
        format: int64
    OrderId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: 同一租户和操作者重试同一请求时必须保持不变
      schema:
        type: string
        minLength: 1
        maxLength: 128