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

openapi: 3.0.3
info:
  title: 柏悦头程订单 API
  description: 业务成功和失败均使用 HTTP 200；仅响应体 code 为字符串 "200" 时表示成功，其他 code 表示失败。
  version: 1.1.0
security:
  - bearerAuth: []
paths:
  /api/merchant/v1/orders/first-leg:
    get:
      summary: 客户端入库订单聚合列表
      description: 按当前登录租户分页返回订单、货物汇总、收货方快照及头程入仓编码，需要 merchant:order:list 权限。
      parameters:
        - {name: keyword, in: query, required: false, schema: {type: string, maxLength: 64}}
        - {name: orderNo, in: query, required: false, schema: {type: string, maxLength: 64}}
        - {name: receivingWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: channelName, in: query, required: false, schema: {type: string, maxLength: 128}}
        - {name: customerContact, in: query, required: false, description: 客户名称、联系人或手机号, schema: {type: string, maxLength: 128}}
        - {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: status, in: query, required: false, schema: {type: string}}
        - {name: operationStatus, in: query, required: false, description: 操作状态，优先于兼容参数 status, schema: {type: string}}
        - {name: destinationType, in: query, required: false, schema: {type: string, maxLength: 32}}
        - {name: destinationWarehouseId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
        - {name: createdFrom, in: query, required: false, schema: {type: string, format: date-time}}
        - {name: createdTo, in: query, required: false, schema: {type: string, format: date-time}}
        - {name: page, in: query, required: false, schema: {type: integer, minimum: 1, default: 1}}
        - {name: size, in: query, required: false, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
      responses:
        '200':
          description: 成功或业务失败，响应体 code 为字符串 200 时成功
          content:
            application/json:
              schema: {type: object}
    post:
      summary: 创建订单草稿
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: {type: object}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
  /api/merchant/v1/orders/first-leg/{id}/submit:
    post:
      summary: 提交订单
      parameters:
        - $ref: '#/components/parameters/OrderId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
  /api/platform/v1/orders/first-leg:
    get:
      summary: 平台分页查询头程订单
      description: tenantId 省略时查询全部客户租户订单，传入时仅查询指定租户。
      parameters:
        - name: tenantId
          in: query
          required: false
          description: 可选的目标租户筛选
          schema: {type: integer, format: int64, minimum: 1}
      responses:
        '200': {description: 查询成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:list 权限和平台身份}
    post:
      summary: 平台代客创建订单草稿
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: {type: object}
      responses:
        '200': {description: 成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:create 权限}
  /api/platform/v1/orders/first-leg/tenant-counts:
    get:
      summary: 批量查询客户运单数
      description: 按客户租户 ID 返回真实头程运单数量，最多 200 个租户。
      parameters:
        - name: tenantIds
          in: query
          required: true
          schema: {type: array, maxItems: 200, items: {type: integer, format: int64}}
      responses:
        '200': {description: 查询成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:list 权限}
  /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: 成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:submit 权限}
  /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: 成功或业务失败，按响应体 code 判断}
        '403': {description: 需要 platform:order:edit 权限}
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}