# Canonical token-aware Auction workflow.
# Client and Provider share list/details; command ids live in the body whenever
# another value is submitted. Application bidding is Socket.IO-only.

_fail400: &fail400
  description: Validation or business-rule failure
  content:
    application/json:
      schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
      examples:
        validation:
          value: { key: fail, message: "البيانات المرسلة غير صحيحة", status: 400 }

_unauth419: &unauthorized419
  description: Missing or invalid authenticated Client/Provider session
  content:
    application/json:
      schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
      examples:
        unauthorized:
          value: { key: unauthorized, message: "غير مصرح", status: 419 }

_notFound404: &notFound404
  description: Auction not found or not visible to the authenticated actor
  content:
    application/json:
      schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
      examples:
        missing:
          value: { key: notFound, message: "المزاد غير موجود", status: 404 }

_conflict409: &conflict409
  description: Stale state or idempotency conflict
  content:
    application/json:
      schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
      examples:
        conflict:
          value: { key: fail, message: "تم تغيير حالة المزاد، حدّث البيانات وحاول مرة أخرى", status: 409 }

_figma-create: &figma-create
  mobile:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26435&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
    nodeId: "9967:26435"
  web:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10766-119775&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
    nodeId: "10766:119775"

_figma-list: &figma-list
  mobile:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26383&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
    nodeId: "9967:26383"
  web:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118201&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
    nodeId: "10760:118201"

_figma-details: &figma-details
  mobile:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26743&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
    nodeId: "9967:26743"
  web:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118627&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
    nodeId: "10760:118627"

_figma-join: &figma-join
  mobile:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9489-5949&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
    nodeId: "9489:5949"
  web:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-111802&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
    nodeId: "10245:111802"

_figma-end: &figma-end
  mobile:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26417&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
    nodeId: "9967:26417"
  web:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118260&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
    nodeId: "10760:118260"

_figma-payment: &figma-payment
  mobile:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9530-17677&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
    nodeId: "9530:17677"
  web:
    url: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-110448&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
    nodeId: "10245:110448"

auctions:
  get:
    tags: [Shared Auctions]
    summary: List auctions for the authenticated Client or Provider
    description: |
      One role-aware endpoint. The bearer token selects the actor and allowed tabs.
      The `type` query value is required. Client values: `upcoming`, `current`,
      `finished`. Provider values: `pending`, `accepted`, `rejected`, `upcoming`,
      `current`, `finished`. List DTOs are card-sized;
      the API does not call the details endpoint per row.
      An approved Auction enters the Client `upcoming` tab when its dashboard-scheduled
      publication job becomes due. The deadline is the later of approval time and
      `startAt - auctionPublishBeforeStartHours`. At `startAt`, the start job changes
      the lifecycle status to `current` (the internal live workflow) and creates the
      persistent end job for `endAt`.

      <div class="figma-links"><span>Figma Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26383&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile — Auctions</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118201&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web — Auctions</a></div>
    x-figma: *figma-list
    operationId: listAuctionsByAuthenticatedRole
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - in: query
        name: type
        required: true
        description: Clients may use upcoming/current/finished; Providers may use all six values.
        schema:
          type: string
          enum: [pending, accepted, rejected, upcoming, current, finished]
        example: upcoming
      - in: query
        name: search
        schema: { type: string, maxLength: 200 }
      - in: query
        name: page
        schema: { type: integer, minimum: 1, default: 1 }
      - in: query
        name: limit
        schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    responses:
      '200':
        description: Role-filtered paginated Auction cards
        content:
          application/json:
            example:
              key: success
              message: "تم إرجاع المزادات بنجاح"
              status: 200
              data:
                - id: "64f001122334455667788990"
                  auctionNumber: 42
                  name: "مزاد أجهزة احترافية"
                  status: Upcoming
                  depositAmount: 100
                  openingPrice: 1000
                  startDate: "2026-08-10T12:00:00.000Z"
                  endDate: "2026-08-10T18:00:00.000Z"
                  durationHours: 6
                  participantsCount: 0
      '400': *fail400
      '419': *unauthorized419

auction-create:
  post:
    tags: [Provider Auctions]
    summary: Create a productless Auction for admin review
    description: |
      Provider only. Images are validated by file signature. The server persists
      `Pending`, calculates `endDate = startDate + durationHours`, records history,
      and notifies an active super admin. Product association is not accepted.
      Financial fields are not accepted from the Provider. `vatPrice` and
      `appCommission` are initialized to null for later financial processing.

      <div class="figma-links"><span>Figma Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26435&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile — Create Auction</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10766-119775&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web — Create Auction</a></div>
    x-figma: *figma-create
    operationId: createAuctionWorkflow
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      description: Swagger fills all test values automatically; select at least one image before executing.
      content:
        multipart/form-data:
          schema:
            type: object
            required: [name, description, images, depositAmount, startDate, durationHours]
            additionalProperties: false
            properties:
              name: { type: string, minLength: 2, maxLength: 160, default: "مزاد أجهزة احترافية", example: "مزاد أجهزة احترافية" }
              description: { type: string, minLength: 2, maxLength: 3000, default: "وصف واضح للمزاد", example: "وصف واضح للمزاد" }
              images:
                type: array
                minItems: 1
                maxItems: 10
                items: { type: string, format: binary }
              depositAmount: { type: number, minimum: 0, default: 100, example: 100 }
              startDate:
                type: string
                format: date-time
                description: Must be a future ISO-8601 date-time, for example 2030-01-01T12:00:00Z. The server calculates endDate from this value and durationHours.
                default: "2030-01-01T12:00:00Z"
                example: "2030-01-01T12:00:00Z"
              durationHours: { type: integer, minimum: 5, maximum: 24, default: 6, example: 6 }
    responses:
      '200':
        description: Auction created as Pending
        content:
          application/json:
            example: { key: success, message: "تم إنشاء المزاد بنجاح", status: 200 }
      '400': *fail400
      '419': *unauthorized419

auction-details:
  get:
    tags: [Shared Auctions]
    summary: Get role-aware Auction details
    description: |
      Uses the authenticated role and Auction `id` query value. Client responses include own
      participation/result/payment state. Provider responses include moderation
      minimum and owner actions. A Client cannot open the Auction before its publication
      job is due. Backend authorization enforces every action.

      <div class="figma-links"><span>Figma Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26743&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile — Auction Details</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118627&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web — Auction Details</a></div>
    x-figma: *figma-details
    operationId: getAuctionWorkflowDetails
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - in: query
        name: id
        required: true
        schema: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
    responses:
      '200':
        description: Role-aware Auction operational profile
        content:
          application/json:
            example:
              key: success
              message: "تفاصيل المزاد"
              status: 200
              data:
                id: "64f001122334455667788990"
                name: "مزاد أجهزة احترافية"
                status: Upcoming
                depositAmount: 100
                openingPrice: 1000
                adminMinimumOpeningPrice: 800
                startDate: "2026-08-10T12:00:00.000Z"
                endDate: "2026-08-10T18:00:00.000Z"
                durationHours: 6
                participation: { isJoined: false, paymentStatus: null }
                allowedActions: [JOIN_AUCTION]
      '404': *notFound404
      '419': *unauthorized419

auction-update:
  put:
    tags: [Provider Auctions]
    summary: Set the opening price of an owned Accepted Auction
    description: |
      Provider only. The multipart body must contain exactly `id` and
      `openingPrice`. The Auction must be owned by the authenticated Provider,
      must still be Accepted, and must not have been published. A successful
      update publishes it immediately and changes its exposed status to Upcoming.
      `openingPrice` cannot be lower than `adminMinimumOpeningPrice`.

      <div class="figma-links"><span>Figma Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26435&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile — Configure Auction</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10766-119775&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web — Configure Auction</a></div>
    x-figma: *figma-create
    operationId: updateAuctionWorkflow
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [id, openingPrice]
            additionalProperties: false
            properties:
              id: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
              openingPrice:
                type: number
                minimum: 0
                example: 1000
                description: Provider opening price; must be at least adminMinimumOpeningPrice.
          example: { id: "64f001122334455667788990", openingPrice: 1000 }
    responses:
      '200':
        description: Auction updated; Accepted becomes Upcoming after configuration
        content:
          application/json:
            example:
              key: success
              message: "تم تحديث المزاد بنجاح"
              status: 200
              data: { id: "64f001122334455667788990", status: Upcoming, openingPrice: 1000, adminMinimumOpeningPrice: 800 }
      '400': *fail400
      '404': *notFound404
      '419': *unauthorized419

auction-join:
  post:
    tags: [Client Auctions]
    summary: Join an Upcoming Auction and pay its server-calculated deposit
    description: |
      Client only. Wallet payment is committed transactionally and idempotently.
      Online returns `202` with a pending AuctionPayment; participation is not
      activated until a verifiable gateway confirmation exists.

      <div class="figma-links"><span>Figma Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9489-5949&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile — Join Auction</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-111802&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web — Join Auction</a></div>
    x-figma: *figma-join
    operationId: joinAuctionWorkflow
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [auctionId, paymentMethod]
            additionalProperties: false
            properties:
              auctionId: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
              paymentMethod: { type: string, enum: [wallet, online] }
          examples:
            wallet: { value: { auctionId: "64f001122334455667788990", paymentMethod: wallet } }
            online: { value: { auctionId: "64f001122334455667788990", paymentMethod: online } }
    responses:
      '200': { description: Wallet deposit paid and participation confirmed }
      '202': { description: Online AuctionPayment created as pending; not joined yet }
      '400': *fail400
      '404': *notFound404
      '409': *conflict409
      '419': *unauthorized419

auction-cancel:
  post:
    tags: [Provider Auctions]
    summary: Cancel an owned Auction before it starts
    description: |
      Provider only. Allowed in Pending, Accepted, or Upcoming before start.
      Auction cancellation and all paid-deposit refunds commit in one transaction;
      each refund remains idempotent and has an independent financial record.
      affected Clients, Provider, and admin receive enriched notifications.

      <div class="figma-links"><span>Figma Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26743&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile — Auction Actions</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118627&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web — Auction Actions</a></div>
    x-figma: *figma-details
    operationId: cancelAuctionWorkflow
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [auctionId, reason]
            additionalProperties: false
            properties:
              auctionId: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
              reason: { type: string, minLength: 2, maxLength: 500 }
          example: { auctionId: "64f001122334455667788990", reason: "تعذر استكمال المزاد" }
    responses:
      '200': { description: Auction cancelled and all due refunds completed/replayed }
      '400': *fail400
      '404': *notFound404
      '409': *conflict409
      '419': *unauthorized419

auction-end:
  post:
    tags: [Provider Auctions]
    summary: Finalize an owned live Auction after its end time
    description: |
      Provider fallback for the server finalizer. It freezes the highest bid,
      refunds losing deposits, records `Finished`, and notifies the Provider and
      highest bidder. The winner is not final until Provider acceptance.

      <div class="figma-links"><span>Figma Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26417&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile — End Auction</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118260&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web — End Auction</a></div>
    x-figma: *figma-end
    operationId: endAuctionWorkflow
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [auctionId]
            additionalProperties: false
            properties:
              auctionId: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
    responses:
      '200': { description: Finalized or stable idempotent replay }
      '400': *fail400
      '404': *notFound404
      '419': *unauthorized419

auction-accept-winner:
  post:
    tags: [Provider Auctions]
    summary: Accept the frozen highest bid
    description: |
      Provider only. The backend computes `remainingAmount = winningBidAmount -
      depositAmount`, assigns the winner once, opens payment, records status
      history, and notifies the winner and admin.

      <div class="figma-links"><span>Figma Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26417&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile — Winner Decision</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118260&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web — Winner Decision</a></div>
    x-figma: *figma-end
    operationId: acceptAuctionWinnerWorkflow
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [auctionId]
            additionalProperties: false
            properties:
              auctionId: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
    responses:
      '200': { description: Winner accepted and payment is AwaitingPayment }
      '400': *fail400
      '404': *notFound404
      '409': *conflict409
      '419': *unauthorized419

auction-reject-winner:
  post:
    tags: [Provider Auctions]
    summary: Reject the frozen highest bid once
    description: |
      Provider only. Records WinnerRejected, reason, and deposit refund without
      auto-selecting a second winner. Notifies the bidder and admin.

      <div class="figma-links"><span>Figma Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26417&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile — Winner Decision</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118260&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web — Winner Decision</a></div>
    x-figma: *figma-end
    operationId: rejectAuctionWinnerWorkflow
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [auctionId, reason]
            additionalProperties: false
            properties:
              auctionId: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
              reason: { type: string, minLength: 2, maxLength: 500 }
          example: { auctionId: "64f001122334455667788990", reason: "قيمة العرض غير مناسبة" }
    responses:
      '200': { description: Highest bid rejected and held deposit refunded/replayed }
      '400': *fail400
      '404': *notFound404
      '409': *conflict409
      '419': *unauthorized419

auction-winner-payment:
  post:
    tags: [Client Auctions]
    summary: Pay the winner's server-calculated remaining amount
    description: |
      Winning Client only. Amount is never accepted from the request. Wallet
      settlement is transactional and idempotent. Online creates a pending
      AuctionPayment and cannot mark the Auction paid without gateway proof.
      A successful Wallet settlement creates exactly one productless Order linked
      by `auction`, using the Auction name and images as its immutable snapshot.

      <div class="figma-links"><span>Figma Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9530-17677&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile — Winner Payment</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-110448&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web — Winner Payment</a></div>
    x-figma: *figma-payment
    operationId: payAuctionWinnerWorkflow
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [auctionId, paymentMethod]
            additionalProperties: false
            properties:
              auctionId: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
              paymentMethod: { type: string, enum: [wallet, online] }
          examples:
            wallet: { value: { auctionId: "64f001122334455667788990", paymentMethod: wallet } }
            online: { value: { auctionId: "64f001122334455667788990", paymentMethod: online } }
    responses:
      '200': { description: Wallet payment committed, one Auction Order created, and Auction completed }
      '202': { description: Online AuctionPayment pending gateway confirmation }
      '400': *fail400
      '404': *notFound404
      '409': *conflict409
      '419': *unauthorized419

auctions-bids:
  get:
    tags: [Shared Auctions]
    summary: Get privacy-safe Auction bid history
    description: |
      Distinct supporting read. Bidder labels are anonymized; tokens, wallet data,
      phone, email, and idempotency keys are never returned.
    operationId: getAuctionBidHistory
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - in: query
        name: id
        required: true
        schema: { type: string, pattern: '^[a-fA-F0-9]{24}$' }
      - in: query
        name: page
        schema: { type: integer, minimum: 1, default: 1 }
      - in: query
        name: limit
        schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    responses:
      '200': { description: Privacy-safe bid page }
      '404': *notFound404
