openapi: 3.0.3
info:
  title: Platform Self-operated Analytics Sync Commands
  version: 1.0.0
paths:
  /api/platform/v1/last-leg/self-operated-analytics/sync-tasks:
    post:
      operationId: requestSelfoperatedAnalyticsSyncTask
      summary: 创建人工采集、复查、重建或恢复任务
      description: >-
        仅平台账号且须 platform:self-operated-analytics:sync 权限。命令先持久化，
        不在 HTTP 请求内运行历史采集。collectionMode 默认 OFF；VALIDATION 仅用于持久预算内的样本暂存，
        BUSINESS 允许 production 以及受控人工执行的 test，均要求真实出口取得服务端核验的人工独占许可。TEST 不自动计划、历史复查或创建两个月首采；仅执行人工命令及合法派生任务。
        TEST BUSINESS 人工根创建时冻结服务端 requestBudget/timeBudgetSeconds 为根会话请求总上限和截止时间；子任务及重试共用持久预算，续授权或重启不清零。
        请求上限或截止后不得继续出网，保留停止原因并终止未完成任务；不将截断结果作为完整版本发布。最后一个合法请求返回的完整数据允许完成纯本地校验和发布。
        出库来源时间及业务时间统一 Asia/Shanghai；首次正式目标固定为 E0 前两个滚动月。
        BACKFILL 单片不超过一天。RETRY 使用 taskNo 和非空 reason 恢复原分仓逻辑任务，
        保留半归并屏障及旧尝试，拒绝验证会话复活、账号共享任务伪装单仓、有效执行租约及上游未齐；
        requestKey 同键异载荷拒绝。成功受理只表示排队，不表示采集或发布成功。
        WAREHOUSE_DISCOVERY 仅允许 VALIDATION，只接受 requestKey/action，不要求已知仓码；
        真实账号根最多一页10条、一次HTTP、60秒，读取后SAMPLE_DONE，不进入出库、详情、库存或正式发布。
        普通 VALIDATION 冻结命令指定的单仓，每根独立最多300秒/40HTTP，账号预算、冷却与间隔仍共享。
      security:
        - bearerAuth: []
      x-required-authorities:
        - platform:self-operated-analytics:sync
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncCommand'
      responses:
        '200':
          description: 平台 ApiResponse 包络，成功 code 为字符串 200；返回稳定业务任务号与 ACCEPTED
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    type: object
                    properties:
                      taskNo: { type: string }
                      warehouseCode: { type: string, nullable: true, description: 目录发现无仓库主体，其他命令为指定仓码 }
                      status: { type: string, enum: [ACCEPTED] }
        '401': { description: 未认证 }
        '403': { description: 非平台身份或无独立写权限 }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
  schemas:
    SyncCommand:
      type: object
      required: [requestKey, action]
      oneOf:
        - properties:
            action: { type: string, enum: [WAREHOUSE_DISCOVERY] }
          not:
            anyOf:
              - required: [warehouseCode]
              - required: [taskNo]
              - required: [sourceFrom]
              - required: [sourceUntil]
              - required: [customerCode]
              - required: [deliveryNo]
              - required: [reason]
        - required: [warehouseCode]
          properties:
            action: { type: string, enum: [INVENTORY, BACKFILL, RECHECK, REBUILD, RETRY, VALIDATION] }
      properties:
        requestKey: { type: string, minLength: 1, maxLength: 100 }
        warehouseCode: { type: string, minLength: 1, maxLength: 64 }
        action: { type: string, enum: [INVENTORY, BACKFILL, RECHECK, REBUILD, RETRY, VALIDATION, WAREHOUSE_DISCOVERY] }
        taskNo: { type: string, minLength: 1, maxLength: 64, description: RETRY 必填，原始分仓业务任务号 }
        reason: { type: string, minLength: 1, maxLength: 500, description: RETRY 必填，随操作人和原任务审计保存 }
        sourceFrom: { type: string, example: '2026-10-11T00:00:00' }
        sourceUntil: { type: string, example: '2026-10-12T00:00:00' }
        customerCode: { type: string, maxLength: 64, description: RECHECK 必填 }
        deliveryNo: { type: string, maxLength: 128, description: RECHECK 必填 }