openapi.yaml

openapi: "3.1.0"

info:
  title: FoodFlow API
  description: |
    FoodFlow -- Food Delivery Platform REST API.

    **Base path:** `/api`. The production origin is the verified Railway API domain.

    **Conventions:**
    - All monetary values are in **VND**, represented as integers.
    - All datetime values use ISO 8601 `date-time` with timezone.
    - Successful web/admin/restaurant endpoints return `{ success: true, data, meta? }`.
    - List endpoints put the collection in `data` and pagination in `meta`.
    - Errors use the shared `ProblemDetail` schema (RFC 7807) and are not success-wrapped.
    - Idempotency is supported via `Idempotency-Key` header (UUID v4).
    - Inbound HMAC: SePay webhooks are verified with `x-sepay-signature`.
    - Outbound HMAC: generic outbound webhooks use `X-Signature-SHA256` when configured.

    **Versioning:** Batch 4 currently uses the `/api` base without a `/v1` prefix. A future version prefix requires an updated server contract and migration policy.
  version: "1.0.0"
  contact:
    name: FoodFlow Team
    email: support@foodflow.vn

servers:
  - url: https://replace-with-foodflow-api.up.railway.app/api
    description: Production placeholder; replace with the verified Railway public domain before publishing external client configuration
  - url: http://localhost:3001/api
    description: Local development

tags:
  - name: auth
    description: Authentication (register, login, refresh, logout, forgot/reset password, verify email, OTP)
  - name: users
    description: User profiles, address book, wallet
  - name: restaurants
    description: Restaurant discovery (nearby, search, detail, menu, reviews)
  - name: restaurant-profile
    description: Restaurant owner profile, opening hours, and special closure dates
  - name: menu
    description: Menu management (categories, items, options, availability) -- restaurant owner only
  - name: restaurant-staff
    description: Restaurant tenant staff invitations, permissions, and shift schedules
  - name: restaurant-reviews
    description: Restaurant tenant review inbox and merchant replies
  - name: orders
    description: Order lifecycle (place, status transitions, cancel, refund, assign driver, tracking)
  - name: drivers
    description: Driver operations (online/offline, location, earnings, trip history, withdrawals)
  - name: payments
    description: Wallet topup, payment methods, SePay webhook, refund, withdrawal
  - name: promotions
    description: Promotion CRUD, validation, overlap check, scheduler, audience targeting (admin)
  - name: notifications
    description: Push notifications (FCM), email templates (vi/en/ja), SMS
  - name: support
    description: Support tickets, replies, SLA, macros, bulk actions, CSAT (admin)
  - name: audit
    description: Audit log (search tsvector, export, retention) -- admin only
  - name: settings
    description: Platform settings and degraded integration state -- admin only
  - name: ai
    description: FoodFlow AI chatbot and service integration
  - name: analytics
    description: KPI aggregations, business dashboards, heat maps -- admin only
  - name: realtime
    description: Short-lived Supabase Realtime authorization for authenticated private channels
  - name: jobs
    description: Secured PostgreSQL outbox drain used for Railway recovery and approved worker invocations
  - name: health
    description: Public platform liveness and strict dependency readiness probes

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT bearer access token. Obtain via `POST /auth/login`; the signing algorithm follows the active JWT cutover phase.
    cronBearer:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: Exact server-side CRON_SECRET value. Never expose this credential to browser or mobile clients.
  parameters:
    PageParam:
      name: page
      in: query
      schema: { type: integer, minimum: 1, default: 1 }
      description: Page number (1-indexed)
    LimitParam:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      description: Items per page
    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: false
      schema: { type: string, format: uuid }
      description: UUID v4 for idempotent request deduplication

  schemas:
    # ── Shared ──

    SuccessEnvelope:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { description: "Endpoint-specific payload" }
        meta: { description: "Optional pagination or aggregation metadata" }
      required: [success, data]

    ProblemDetail:
      type: object
      properties:
        type:    { type: string, description: "URI to problem type documentation" }
        title:   { type: string, description: "Short human-readable summary" }
        status:  { type: integer, description: "HTTP status code" }
        detail:  { type: string, description: "Human-readable explanation" }
        instance: { type: string, description: "URI to the specific occurrence" }
        code:    { type: string, description: "Application-specific error code (e.g. AUTH_INVALID_CREDENTIALS)" }
      required: [type, title, status, detail]
      example:
        type: "about:blank"
        title: "Validation Error"
        status: 422
        detail: "Email is not valid"
        code: "VALIDATION_INVALID_EMAIL"

    HealthComponentStatus:
      type: object
      additionalProperties: false
      properties:
        status: { type: string, enum: [up, down] }
        latencyMs: { type: integer, minimum: 0 }
      required: [status, latencyMs]

    StorageHealthComponentStatus:
      type: object
      additionalProperties: false
      properties:
        provider: { type: string, enum: [minio, supabase] }
        status: { type: string, enum: [up, down] }
        latencyMs: { type: integer, minimum: 0 }
      required: [provider, status, latencyMs]

    HealthComponents:
      type: object
      additionalProperties: false
      properties:
        db: { $ref: '#/components/schemas/HealthComponentStatus' }
        redis: { $ref: '#/components/schemas/HealthComponentStatus' }
        storage: { $ref: '#/components/schemas/StorageHealthComponentStatus' }
      required: [db, redis, storage]

    HealthResponse:
      type: object
      additionalProperties: false
      properties:
        status: { type: string, enum: [ok, degraded] }
        uptime: { type: number, minimum: 0 }
        timestamp: { type: string, format: date-time }
        components: { $ref: '#/components/schemas/HealthComponents' }
      required: [status, uptime, timestamp, components]

    ReadinessResponse:
      type: object
      additionalProperties: false
      properties:
        status: { type: string, enum: [ready, not_ready] }
        ready: { type: boolean }
        timestamp: { type: string, format: date-time }
        components: { $ref: '#/components/schemas/HealthComponents' }
      required: [status, ready, timestamp, components]

    PaginationMeta:
      type: object
      properties:
        total:    { type: integer, description: "Total items across all pages" }
        page:     { type: integer, description: "Current page number" }
        limit:    { type: integer, description: "Items per page" }
        hasMore:  { type: boolean, description: "Whether more pages exist" }
      required: [total, page, limit, hasMore]

    RealtimeTokenRequest:
      type: object
      additionalProperties: false
      properties:
        orderId:
          type: string
          format: uuid
          description: Optional order scope; the actor must be an authorized participant or admin.
        restaurantId:
          type: string
          format: uuid
          description: Optional restaurant scope; the actor must have an active profile for this tenant.

    RealtimeTokenData:
      type: object
      additionalProperties: false
      properties:
        provider:
          type: string
          const: supabase
        token:
          type: string
          minLength: 1
          description: Five-minute Supabase-compatible JWT carrying explicit realtime_channels claims.
        expiresAt:
          type: string
          format: date-time
        channels:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            pattern: '^private:'
      required: [provider, token, expiresAt, channels]

    RealtimeTokenEnvelope:
      type: object
      additionalProperties: false
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/RealtimeTokenData'
      required: [success, data]

    JobDrainStats:
      type: object
      additionalProperties: false
      properties:
        claimed: { type: integer, minimum: 0 }
        completed: { type: integer, minimum: 0 }
        failed: { type: integer, minimum: 0 }
        retried: { type: integer, minimum: 0 }
      required: [claimed, completed, failed, retried]

    JobDrainEnvelope:
      type: object
      additionalProperties: false
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/JobDrainStats'
      required: [success, data]

    # ── Auth ──

    RegisterRequest:
      type: object
      properties:
        email:    { type: string, format: email }
        password: { type: string, minLength: 8, maxLength: 72, description: "Must include uppercase, lowercase, digit" }
        fullName: { type: string, minLength: 2, maxLength: 100 }
        phone:    { type: string, pattern: '^\+?[1-9]\d{6,14}$', description: "e.g. +84123456789" }
      required: [email, password, fullName]
      additionalProperties: false
      example:
        email: "nguyenvana@example.com"
        password: "REPLACE_WITH_STRONG_PASSWORD"
        fullName: "Nguyễn Văn A"
        phone: "+84987654321"

    LoginRequest:
      type: object
      properties:
        email:    { type: string, format: email }
        password: { type: string }
      required: [email, password]
      example:
        email: "customer1@foodflow.vn"
        password: "REPLACE_WITH_TEST_PASSWORD"

    RefreshRequest:
      type: object
      properties:
        refreshToken: { type: string }
      required: [refreshToken]
      example:
        refreshToken: "REPLACE_WITH_OPAQUE_REFRESH_TOKEN"

    LogoutRequest:
      type: object
      properties:
        refreshToken: { type: string }
      example:
        refreshToken: "REPLACE_WITH_OPAQUE_REFRESH_TOKEN"

    ForgotPasswordRequest:
      type: object
      properties:
        email: { type: string, format: email }
      required: [email]
      example:
        email: "nguyenvana@example.com"

    ResetPasswordRequest:
      type: object
      properties:
        token:    { type: string, description: "Reset token from email" }
        password: { type: string, minLength: 8, maxLength: 72 }
      required: [token, password]
      example:
        token: "REPLACE_WITH_RESET_TOKEN"
        password: "REPLACE_WITH_NEW_STRONG_PASSWORD"

    AuthResult:
      type: object
      properties:
        accessToken:  { type: string, description: "JWT access token (15 min TTL; algorithm follows the active backend cutover phase)" }
        refreshToken: { type: string, description: "Rotating refresh JWT (7 day TTL; invalidated through the server-side blocklist)" }
        expiresAt:    { type: string, format: date-time }
        user:
          $ref: "#/components/schemas/UserProfile"
      required: [accessToken, refreshToken, expiresAt, user]

    # ── Users ──

    UserProfile:
      type: object
      properties:
        id:        { type: string, format: uuid }
        email:     { type: string, format: email }
        fullName:  { type: string }
        phone:     { type: string }
        role:      { type: string, enum: [customer, driver, restaurant, admin] }
        avatarUrl: { type: string }
        isActive:  { type: boolean }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
      required: [id, email, fullName, role, isActive, createdAt, updatedAt]
      example:
        id: "550e8400-e29b-41d4-a716-446655440000"
        email: "nguyenvana@example.com"
        fullName: "Nguyễn Văn A"
        phone: "+84987654321"
        role: "customer"
        avatarUrl: "https://cdn.foodflow.vn/avatars/default.png"
        isActive: true
        createdAt: "2026-01-15T08:30:00Z"
        updatedAt: "2026-07-11T08:30:00Z"

    UpdateUserRequest:
      type: object
      properties:
        fullName:  { type: string, minLength: 1, maxLength: 100 }
        phone:     { type: string }
        avatarUrl: { type: string, format: uri }
      example:
        fullName: "Nguyễn Văn A (đã sửa)"
        phone: "+84988888888"

    AvatarUploadResponse:
      type: object
      properties:
        url: { type: string }
      required: [url]
      example:
        url: "https://cdn.foodflow.vn/avatars/550e8400-e29b-41d4-a716-446655440000.jpg"

    Address:
      type: object
      properties:
        id:        { type: string, format: uuid }
        label:     { type: string, description: "e.g. Nhà riêng, Công ty" }
        addressLine: { type: string }
        latitude:  { type: number, minimum: 3.8, maximum: 23.5 }
        longitude: { type: number, minimum: 102.0, maximum: 117.5 }
        isDefault: { type: boolean }
        createdAt: { type: string, format: date-time }
      required: [id, label, addressLine, latitude, longitude, isDefault, createdAt]
      example:
        id: "11111111-1111-4111-8111-111111111111"
        label: "Nhà riêng"
        addressLine: "123 Nguyễn Huệ, Quận 1, TP. Hồ Chí Minh"
        latitude: 10.7769
        longitude: 106.7009
        isDefault: true
        createdAt: "2026-07-06T00:00:00Z"

    CreateAddressRequest:
      type: object
      properties:
        label:       { type: string }
        addressLine: { type: string }
        latitude:    { type: number, minimum: 3.8, maximum: 23.5 }
        longitude:   { type: number, minimum: 102.0, maximum: 117.5 }
        isDefault:   { type: boolean, default: false }
      required: [label, addressLine, latitude, longitude]
      example:
        label: "Công ty"
        addressLine: "456 Lê Lợi, Quận 1, TP. Hồ Chí Minh"
        latitude: 10.7730
        longitude: 106.6984
        isDefault: false

    UpdateAddressRequest:
      type: object
      properties:
        label:       { type: string }
        addressLine: { type: string }
        latitude:    { type: number, minimum: 3.8, maximum: 23.5 }
        longitude:   { type: number, minimum: 102.0, maximum: 117.5 }
        isDefault:   { type: boolean }
      example:
        label: "Nhà mới"
        addressLine: "789 Võ Văn Kiệt, Quận 1, TP. Hồ Chí Minh"

    WalletSnapshot:
      type: object
      properties:
        balance:      { type: integer, description: "Available balance in VND" }
        transactions:
          type: array
          items: { $ref: "#/components/schemas/WalletTransaction" }
      required: [balance, transactions]
      example:
        balance: 350000
        transactions:
          - id: "22222222-2222-4222-8222-222222222222"
            amountDelta: 200000
            type: credit
            reason: order_refund
            refId: "11111111-1111-4111-8111-111111111111"
            createdAt: "2026-06-09T10:30:00Z"

    WalletTransaction:
      type: object
      properties:
        id: { type: string, format: uuid }
        amountDelta: { type: integer, description: "Signed wallet ledger delta in VND" }
        type: { type: string, enum: [credit, debit] }
        reason: { type: string, description: "Ledger reason such as order_refund, referral_bonus, or order_payment" }
        refId: { type: string, format: uuid, nullable: true }
        createdAt: { type: string, format: date-time }
      required: [id, amountDelta, type, reason, createdAt]
      example:
        id: "22222222-2222-4222-8222-222222222222"
        amountDelta: 200000
        type: credit
        reason: order_refund
        refId: "11111111-1111-4111-8111-111111111111"
        createdAt: "2026-06-09T10:30:00Z"

    # ── Restaurants ──

    RestaurantSummary:
      type: object
      properties:
        id:           { type: string, format: uuid }
        name:         { type: string }
        slug:         { type: string }
        logoUrl:      { type: string }
        coverUrl:     { type: string }
        cuisineTypes: { type: array, items: { type: string } }
        priceRange:   { type: string, enum: ["$", "$$", "$$$"] }
        rating:       { type: number }
        totalReviews: { type: integer }
        distanceKm:   { type: number, description: "Distance from query point (nearby only)" }
        isOpen:       { type: boolean }
        prepTimeAvg:  { type: integer, description: "Average preparation time in minutes" }
        minOrderAmount: { type: integer, description: "Minimum order amount in VND" }
      required: [id, name, slug, cuisineTypes, priceRange, rating, totalReviews, isOpen]
      example:
        id: "33333333-3333-4333-8333-333333333333"
        name: "Phở 24"
        slug: "pho-24"
        logoUrl: "https://cdn.foodflow.vn/restaurants/pho24-logo.png"
        coverUrl: "https://cdn.foodflow.vn/restaurants/pho24-cover.png"
        cuisineTypes: ["Phở", "Món Việt"]
        priceRange: "$$"
        rating: 4.5
        totalReviews: 128
        distanceKm: 1.2
        isOpen: true
        prepTimeAvg: 15
        minOrderAmount: 50000

    RestaurantOpeningHour:
      type: object
      properties:
        dayOfWeek: { type: integer, minimum: 0, maximum: 6, description: "0=Sunday, 6=Saturday" }
        openTime:  { type: string, pattern: "^\\d{2}:\\d{2}$", description: "HH:mm" }
        closeTime: { type: string, pattern: "^\\d{2}:\\d{2}$", description: "HH:mm" }
        isClosed:  { type: boolean }
      required: [dayOfWeek, openTime, closeTime, isClosed]

    RestaurantHolidayClosure:
      type: object
      properties:
        id: { type: string, format: uuid, readOnly: true }
        date: { type: string, format: date, description: "Full-day closure date in YYYY-MM-DD format" }
        reason: { type: string, nullable: true, maxLength: 200 }
      required: [date]

    RestaurantDetail:
      allOf:
        - $ref: "#/components/schemas/RestaurantSummary"
        - type: object
          properties:
            description: { type: string }
            addressLine: { type: string }
            city:        { type: string }
            district:    { type: string }
            phone:       { type: string }
            openingHours:
              type: array
              items: { $ref: "#/components/schemas/RestaurantOpeningHour" }

    RestaurantProfile:
      allOf:
        - $ref: "#/components/schemas/RestaurantDetail"
        - type: object
          properties:
            holidayClosures:
              type: array
              items: { $ref: "#/components/schemas/RestaurantHolidayClosure" }
            membership:
              type: object
              properties:
                id: { type: string, format: uuid }
                role: { type: string }
                permissions: { type: array, items: { type: string } }
                onboardingCompletedAt: { type: string, format: date-time, nullable: true }
              required: [id, role, permissions]

    UpdateRestaurantProfileRequest:
      type: object
      properties:
        name: { type: string, maxLength: 200 }
        description: { type: string, maxLength: 2000 }
        phone: { type: string, maxLength: 20 }
        addressLine: { type: string, maxLength: 300 }
        cuisineTypes: { type: array, items: { type: string } }
        logoUrl: { type: string, maxLength: 500 }
        coverUrl: { type: string, maxLength: 500 }
        minOrderAmount: { type: number, minimum: 0 }
        isOpen: { type: boolean }
        openingHours:
          type: array
          items: { $ref: "#/components/schemas/RestaurantOpeningHour" }
        holidayClosures:
          type: array
          description: Replaces the authenticated restaurant's full special closure list when provided.
          items: { $ref: "#/components/schemas/RestaurantHolidayClosure" }

    ImageUploadResult:
      type: object
      properties:
        url: { type: string, format: uri }
      required: [url]

    MenuCategory:
      type: object
      properties:
        id:       { type: string, format: uuid }
        name:     { type: string }
        sortOrder: { type: integer }
        items:
          type: array
          items: { $ref: "#/components/schemas/MenuItem" }
      required: [id, name, sortOrder, items]

    MenuItem:
      type: object
      properties:
        id:          { type: string, format: uuid }
        restaurantId: { type: string, format: uuid }
        name:        { type: string }
        description: { type: string }
        imageUrl:    { type: string }
        basePrice:   { type: integer, description: "VND" }
        isAvailable: { type: boolean }
        isPopular:   { type: boolean }
        options:
          type: array
          items: { $ref: "#/components/schemas/MenuItemOption" }
      required: [id, restaurantId, name, description, imageUrl, basePrice, isAvailable, isPopular, options]
      example:
        id: "44444444-4444-4444-8444-444444444444"
        restaurantId: "33333333-3333-4333-8333-333333333333"
        name: "Phở bò tái chín"
        description: "Phở bò với thịt tái và chín, kèm rau thơm"
        imageUrl: "https://cdn.foodflow.vn/menu/pho-bo-tai-chin.jpg"
        basePrice: 65000
        isAvailable: true
        isPopular: true
        options: []

    MenuItemOption:
      type: object
      properties:
        id:         { type: string, format: uuid }
        name:       { type: string }
        isRequired: { type: boolean }
        isMultiple: { type: boolean }
        values:
          type: array
          items:
            type: object
            properties:
              value:         { type: string }
              priceModifier: { type: integer, description: "Additional VND" }
            required: [value, priceModifier]
      required: [id, name, isRequired, isMultiple, values]
      example:
        id: "55555555-5555-4555-8555-555555555555"
        name: "Size"
        isRequired: true
        isMultiple: false
        values:
          - { value: "Nhỏ", priceModifier: 0 }
          - { value: "Vừa", priceModifier: 15000 }
          - { value: "Lớn", priceModifier: 25000 }

    Review:
      type: object
      properties:
        id:             { type: string, format: uuid }
        foodRating:     { type: integer, minimum: 1, maximum: 5 }
        deliveryRating: { type: integer, minimum: 1, maximum: 5 }
        comment:        { type: string }
        customerName:   { type: string }
        createdAt:      { type: string, format: date-time }
      required: [id, foodRating, deliveryRating, customerName, createdAt]
      example:
        id: "ffffffff-ffff-4fff-8fff-ffffffffffff"
        foodRating: 5
        deliveryRating: 4
        comment: "Phở ngon, nước dùng đậm đà"
        customerName: "Nguyễn Văn A"
        createdAt: "2026-06-08T12:00:00Z"

    # ── Orders ──

    PlaceOrderRequest:
      type: object
      properties:
        addressId:     { type: string, format: uuid }
        paymentMethod: { type: string, enum: [cash, wallet, sepay], default: cash, description: "Public payment method. Wallet payments debit the confirmed wallet ledger; no mock wallet request value is accepted." }
        promotionCode: { type: string }
        notes:         { type: string, maxLength: 500 }
      required: [addressId]
      example:
        addressId: "11111111-1111-4111-8111-111111111111"
        paymentMethod: "wallet"
        promotionCode: "WELCOME2026"
        notes: "Không hành, thêm ớt"

    DeliveryPricingResponse:
      type: object
      description: Configured checkout delivery pricing returned by the backend so clients do not invent local delivery-fee business rules.
      properties:
        baseDeliveryFeeVnd: { type: integer, minimum: 0, description: "Configured base delivery fee in VND" }
      required: [baseDeliveryFeeVnd]
      example:
        baseDeliveryFeeVnd: 15000

    OrderDetail:
      type: object
      properties:
        id:             { type: string, format: uuid }
        status:         { type: string, enum: [created, pending_payment, paid, restaurant_pending, restaurant_accepted, preparing, ready_for_pickup, driver_assigned, driver_arriving_restaurant, picked_up, delivering, delivered, completed, cancelled, refunded] }
        subtotal:       { type: integer, description: "VND" }
        deliveryFee:    { type: integer, description: "VND" }
        discount:       { type: integer, description: "VND" }
        total:          { type: integer, description: "VND" }
        paymentMethod:  { type: string, enum: [cash, wallet, sepay] }
        notes:          { type: string }
        items:
          type: array
          items:
            type: object
            properties:
              id:         { type: string, format: uuid }
              menuItemId: { type: string, format: uuid }
              name:       { type: string }
              nameSnapshot: { type: string }
              quantity:   { type: integer }
              unitPrice:  { type: integer, description: "VND" }
              price:      { type: integer, description: "Alias of unitPrice for legacy clients" }
              options:    { type: array, items: { type: string }, description: "Selected option values" }
              selectedOptions: { type: array, items: { type: object, additionalProperties: true }, description: "Persisted selected option JSON" }
              totalPrice: { type: integer, description: "VND" }
              lineTotal:  { type: integer, description: "VND" }
            required: [menuItemId, name, quantity, unitPrice, lineTotal]
        restaurant:
          type: object
          properties:
            id:   { type: string, format: uuid }
            name: { type: string }
        deliveryAddress:
          $ref: "#/components/schemas/Address"
        driver:
          type: object
          properties:
            id:       { type: string, format: uuid }
            fullName: { type: string }
            phone:    { type: string }
            rating:   { type: number }
            lat:      { type: number }
            lng:      { type: number }
        timeline:
          type: array
          items:
            type: object
            properties:
              status:    { type: string }
              timestamp: { type: string, format: date-time }
              note:      { type: string }
        createdAt:      { type: string, format: date-time }
        estimatedDelivery: { type: string, format: date-time }
      required: [id, status, subtotal, deliveryFee, total, paymentMethod, items, restaurant, createdAt]
      example:
        id: "66666666-6666-4666-8666-666666666666"
        status: "preparing"
        subtotal: 130000
        deliveryFee: 15000
        discount: 20000
        total: 125000
        paymentMethod: "wallet"
        notes: "Không hành, thêm ớt"
        items:
          - { menuItemId: "44444444-4444-4444-8444-444444444444", name: "Phở bò tái chín", nameSnapshot: "Phở bò tái chín", quantity: 2, unitPrice: 65000, price: 65000, selectedOptions: [{ groupName: "Size", optionName: "Lớn", price: 15000 }], lineTotal: 130000, totalPrice: 130000 }
        restaurant: { id: "33333333-3333-4333-8333-333333333333", name: "Phở 24" }
        deliveryAddress:

          id: "11111111-1111-4111-8111-111111111111"
          addressLine: "123 Nguyen Hue, Quan 1, TP. Ho Chi Minh"
          label: "Nhà riêng"
          street: "123 Nguyễn Huệ"
          ward: "Phường Bến Nghé"
          district: "Quận 1"
          city: "TP. Hồ Chí Minh"
          latitude: 10.7769
          longitude: 106.7009
          lat: 10.7769
          lng: 106.7009
          isDefault: true
          createdAt: "2026-07-06T00:00:00Z"
        createdAt: "2026-06-09T11:00:00Z"
        estimatedDelivery: "2026-06-09T11:35:00Z"
        timeline:
          - { status: "created", timestamp: "2026-06-09T11:00:00Z" }
          - { status: "paid", timestamp: "2026-06-09T11:00:05Z" }
          - { status: "restaurant_accepted", timestamp: "2026-06-09T11:02:00Z" }
          - { status: "preparing", timestamp: "2026-06-09T11:05:00Z" }

    OrderTrackingDriverLocation:
      type: object
      description: Last real GPS position recorded for the driver currently assigned to the order.
      properties:
        lat: { type: number, minimum: -90, maximum: 90 }
        lng: { type: number, minimum: -180, maximum: 180 }
        lastUpdated: { type: string, format: date-time }
      required: [lat, lng, lastUpdated]

    OrderTrackingResponse:
      type: object
      description: Order-participant-scoped tracking snapshot. Nullable fields remain null until real telemetry exists.
      properties:
        orderId: { type: string, format: uuid }
        status: { type: string, enum: [created, pending_payment, paid, restaurant_pending, restaurant_accepted, preparing, ready_for_pickup, driver_assigned, driver_arriving_restaurant, picked_up, delivering, delivered, completed, cancelled, refunded] }
        driverLocation:
          oneOf:
            - $ref: "#/components/schemas/OrderTrackingDriverLocation"
            - type: "null"
        etaMinutes: { type: [integer, "null"], minimum: 1 }
        routePolyline: { type: [string, "null"] }
        routePhase: { type: string, enum: [pickup, dropoff] }
      required: [orderId, status, driverLocation, etaMinutes, routePolyline, routePhase]

    RestaurantOrderChatMessage:
      type: object
      description: Persisted order-room message used by restaurant staff and assigned driver.
      properties:
        id: { type: string, format: uuid }
        senderType: { type: string, enum: [customer, driver, restaurant, ai, system] }
        senderId: { type: string, format: uuid, nullable: true }
        content: { type: string, minLength: 1, maxLength: 1000 }
        createdAt: { type: string, format: date-time }
      required: [id, senderType, content, createdAt]

    RestaurantOrderChatMessagesPayload:
      type: object
      properties:
        messages:
          type: array
          items: { $ref: "#/components/schemas/RestaurantOrderChatMessage" }
        canReply:
          type: boolean
          description: False until a driver is assigned to the order.
      required: [messages, canReply]

    CreateRestaurantOrderChatMessageRequest:
      type: object
      properties:
        content: { type: string, minLength: 1, maxLength: 1000 }
      required: [content]

    CancelOrderRequest:
      type: object
      properties:
        reason: { type: string, maxLength: 500 }
      example:
        reason: "Đổi ý, muốn đặt món khác"

    UpdateOrderStatusRequest:
      type: object
      properties:
        status: { type: string }
        note:   { type: string }
      required: [status]
      example:
        status: "preparing"
        note: "Bắt đầu chế biến món"

    AdminOrderStatusRequest:
      type: object
      properties:
        status: { type: string, description: "Target order status accepted by the backend order state machine." }
        note: { type: string }
      required: [status]

    RestaurantReviewRequest:
      type: object
      properties:
        notes: { type: string }
        reason: { type: string }

    RestaurantMenuAvailabilityRequest:
      type: object
      properties:
        available: { type: boolean }
      required: [available]

    KycReviewRequest:
      type: object
      additionalProperties: false
      properties:
        submissionId: { type: string, format: uuid }
        status: { type: string, enum: [approved, rejected] }
        reason: { type: string, minLength: 1, maxLength: 1000, description: "Required when status is rejected." }
      required: [submissionId, status]

    DriverKycUploadRequest:
      type: object
      additionalProperties: false
      properties:
        documentType: { type: string, enum: [idCardFront, idCardBack, driverLicense, vehicleRegistration] }
        contentType: { type: string, enum: [image/jpeg, image/png, image/webp] }
        sizeBytes: { type: integer, minimum: 1024, maximum: 4194304 }
      required: [documentType, contentType, sizeBytes]

    DriverKycUploadGrant:
      type: object
      additionalProperties: false
      description: Short-lived upload capability for one private KYC object. Clients must not derive or persist a public URL.
      properties:
        uploadUrl: { type: string, format: uri, description: "Provider-signed PUT URL. HTTPS is mandatory in release clients." }
        objectKey: { type: string, minLength: 1, maxLength: 512, description: "Opaque private object key returned unchanged in the final KYC submission." }
        headers:
          type: object
          description: Exact non-credential headers that the client must include in the signed PUT request.
          additionalProperties: { type: string }
      required: [uploadUrl, objectKey, headers]

    DriverKycDocumentObjects:
      type: object
      additionalProperties: false
      description: Private storage object keys owned by the authenticated driver; URI values are rejected.
      properties:
        idCardFront: { type: string, minLength: 1, maxLength: 512 }
        idCardBack: { type: string, minLength: 1, maxLength: 512 }
        driverLicense: { type: string, minLength: 1, maxLength: 512 }
        vehicleRegistration: { type: string, minLength: 1, maxLength: 512 }
      required: [idCardFront, idCardBack, driverLicense, vehicleRegistration]

    SubmitDriverKycRequest:
      type: object
      additionalProperties: false
      properties:
        licenseNumber: { type: string, minLength: 5, maxLength: 50, pattern: "^[A-Z0-9./-]+$" }
        vehicleType: { type: string, enum: [motorbike, car, bicycle] }
        vehiclePlate: { type: string, minLength: 5, maxLength: 20, pattern: "^[A-Z0-9.-]+$" }
        documents: { $ref: "#/components/schemas/DriverKycDocumentObjects" }
      required: [licenseNumber, vehicleType, vehiclePlate, documents]
      example:
        licenseNumber: "A1-123456789"
        vehicleType: "motorbike"
        vehiclePlate: "59-F1-12345"
        documents:
          idCardFront: "kyc/9c8a7a32-6f2d-4c7d-a40f-7de8629f84a9/1730000000000-0123456789abcdef01234567-idCardFront.jpg"
          idCardBack: "kyc/9c8a7a32-6f2d-4c7d-a40f-7de8629f84a9/1730000000001-0123456789abcdef01234567-idCardBack.jpg"
          driverLicense: "kyc/9c8a7a32-6f2d-4c7d-a40f-7de8629f84a9/1730000000002-0123456789abcdef01234567-driverLicense.jpg"
          vehicleRegistration: "kyc/9c8a7a32-6f2d-4c7d-a40f-7de8629f84a9/1730000000003-0123456789abcdef01234567-vehicleRegistration.jpg"

    DriverKycSubmissionReceipt:
      type: object
      additionalProperties: false
      properties:
        submissionId: { type: string, format: uuid }
        status: { type: string, enum: [pending] }
        submittedAt: { type: string, format: date-time }
      required: [submissionId, status, submittedAt]

    DriverKycLatestSubmission:
      type: object
      additionalProperties: false
      properties:
        id: { type: string, format: uuid }
        status: { type: string, enum: [pending, approved, rejected] }
        rejectionReason: { type: [string, "null"] }
        submittedAt: { type: string, format: date-time }
        reviewedAt: { type: [string, "null"], format: date-time }
      required: [id, status, rejectionReason, submittedAt, reviewedAt]

    DriverKycStatusResponse:
      type: object
      additionalProperties: false
      properties:
        isVerified: { type: boolean }
        status: { type: string, enum: [not_submitted, pending, approved, rejected] }
        licenseNumber: { type: [string, "null"] }
        vehicleType: { type: string, enum: [motorbike, car, bicycle] }
        vehiclePlate: { type: [string, "null"] }
        termsAcceptedAt: { type: [string, "null"], format: date-time }
        termsVersion: { type: [string, "null"] }
        latestSubmission:
          oneOf:
            - $ref: "#/components/schemas/DriverKycLatestSubmission"
            - type: "null"
        attemptsRemaining: { type: integer, minimum: 0 }
      required: [isVerified, status, licenseNumber, vehicleType, vehiclePlate, termsAcceptedAt, termsVersion, latestSubmission, attemptsRemaining]

    AdminKycSignedDocuments:
      type: object
      additionalProperties: false
      description: Five-minute signed read URLs generated only for authorized admin review.
      properties:
        idCardFront: { type: string, format: uri }
        idCardBack: { type: string, format: uri }
        driverLicense: { type: string, format: uri }
        vehicleRegistration: { type: string, format: uri }
      required: [idCardFront, idCardBack, driverLicense, vehicleRegistration]

    AdminKycSubmission:
      type: object
      additionalProperties: false
      properties:
        id: { type: string, format: uuid }
        status: { type: string, enum: [pending, approved, rejected] }
        rejectionReason: { type: [string, "null"] }
        reviewedById: { type: [string, "null"], format: uuid }
        reviewedAt: { type: [string, "null"], format: date-time }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        documentsAvailable: { type: boolean }
        documentUrls:
          oneOf:
            - $ref: "#/components/schemas/AdminKycSignedDocuments"
            - type: "null"
      required: [id, status, rejectionReason, reviewedById, reviewedAt, createdAt, updatedAt, documentsAvailable, documentUrls]

    AdminKycReviewResponse:
      type: object
      additionalProperties: false
      properties:
        id: { type: string, format: uuid }
        status: { type: string, enum: [approved, rejected] }
        rejectionReason: { type: [string, "null"] }
        reviewedById: { type: string, format: uuid }
        reviewedAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
      required: [id, status, rejectionReason, reviewedById, reviewedAt, updatedAt]

    CreateReviewRequest:
      type: object
      properties:
        foodRating:     { type: integer, minimum: 1, maximum: 5 }
        deliveryRating: { type: integer, minimum: 1, maximum: 5 }
        comment:        { type: string, maxLength: 500 }
      required: [foodRating, deliveryRating]
      example:
        foodRating: 5
        deliveryRating: 4
        comment: "Phở ngon, giao nhanh"

    # ── Drivers ──

    GoOnlineRequest:
      type: object
      properties:
        lat: { type: number, minimum: -90, maximum: 90 }
        lng: { type: number, minimum: -180, maximum: 180 }
      required: [lat, lng]
      example:
        lat: 10.7769
        lng: 106.7009

    DriverLocationUpdateRequest:
      type: object
      additionalProperties: false
      description: A fresh GPS sample captured by the authenticated driver's device. Speed is expressed in kilometres per hour.
      properties:
        lat: { type: number, minimum: -90, maximum: 90 }
        lng: { type: number, minimum: -180, maximum: 180 }
        bearing: { type: number, minimum: 0, exclusiveMaximum: 360 }
        speed: { type: number, minimum: 0, maximum: 150 }
        accuracy: { type: number, minimum: 0, maximum: 10000 }
        timestamp: { type: string, format: date-time }
      required: [lat, lng, timestamp]

    DriverLocationUpdateResponse:
      type: object
      properties:
        accepted: { type: boolean, const: true }
        orderId: { type: [string, "null"], format: uuid }
        timestamp: { type: string, format: date-time }
      required: [accepted, orderId, timestamp]

    DispatchOfferResponseRequest:
      type: object
      additionalProperties: false
      properties:
        offerToken:
          type: string
          format: uuid
          description: Single-use token delivered only on the authenticated driver's private realtime channel.
        decision: { type: string, enum: [accept, reject] }
      required: [offerToken, decision]

    DispatchOfferResolution:
      type: object
      properties:
        orderId: { type: string, format: uuid }
        decision: { type: string, enum: [accept, reject] }
        status: { type: string, enum: [assigned, rejected] }
      required: [orderId, decision, status]

    DriverEarningEntry:
      type: object
      description: One real payout ledger row joined to its completed order.
      properties:
        orderId: { type: string, format: uuid }
        orderCode: { type: string }
        restaurantName: { type: string }
        amount: { type: integer, description: "Net driver payout ledger amount in VND" }
        completedAt: { type: string, format: date-time }
      required: [orderId, orderCode, restaurantName, amount, completedAt]

    DriverEarnings:
      type: object
      description: Driver payout ledger totals for the requested `today`, `week`, or `month` period.
      properties:
        totalEarnings: { type: integer, description: "Net driver payout ledger amount in VND" }
        totalOrders: { type: integer, minimum: 0, description: "Distinct orders represented by the payout entries." }
        averagePerOrder: { type: integer, description: "Rounded VND average per distinct order." }
        entries:
          type: array
          items: { $ref: "#/components/schemas/DriverEarningEntry" }
      required: [totalEarnings, totalOrders, averagePerOrder, entries]
      example:
        totalEarnings: 350000
        totalOrders: 7
        averagePerOrder: 50000
        entries:
          - orderId: "66666666-6666-4666-8666-666666666666"
            orderCode: "FF-20260703-0001"
            restaurantName: "Pho 24"
            amount: 50000
            completedAt: "2026-07-03T08:30:00Z"

    DriverOrderItem:
      type: object
      properties:
        menuItemId: { type: string, format: uuid }
        name: { type: string }
        quantity: { type: integer, minimum: 1 }
        unitPrice: { type: integer, description: "VND" }
        totalPrice: { type: integer, description: "VND" }
        selectedOptions:
          description: Original selected option JSON persisted on the order item.
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              items: {}
            - type: string
            - type: number
            - type: boolean
            - type: "null"
      required: [menuItemId, name, quantity, unitPrice, totalPrice, selectedOptions]

    DriverOrderAddress:
      type: object
      properties:
        label: { type: string }
        address: { type: string }
        latitude: { type: number, minimum: -90, maximum: 90 }
        longitude: { type: number, minimum: -180, maximum: 180 }
      required: [label, address, latitude, longitude]

    DriverOrderStatusHistory:
      type: object
      properties:
        status: { type: string }
        timestamp: { type: string, format: date-time }
        note: { type: [string, "null"] }
      required: [status, timestamp, note]

    DriverOrder:
      type: object
      description: Order snapshot scoped to the authenticated driver. Coordinates are read from PostGIS; missing location rows return `404 ORDER_LOCATION_NOT_FOUND` instead of synthetic coordinates.
      properties:
        id: { type: string, format: uuid }
        userId: { type: string, format: uuid }
        restaurantId: { type: string, format: uuid }
        restaurantName: { type: string }
        restaurantLogoUrl: { type: [string, "null"] }
        restaurantPhone: { type: [string, "null"] }
        customerName: { type: string }
        customerPhone: { type: [string, "null"] }
        items:
          type: array
          items: { $ref: "#/components/schemas/DriverOrderItem" }
        subtotal: { type: integer, description: "VND" }
        deliveryFee: { type: integer, description: "VND" }
        discount: { type: integer, description: "VND" }
        total: { type: integer, description: "VND" }
        status: { type: string, enum: [driver_assigned, driver_arriving_restaurant, picked_up, delivering, delivered, completed, cancelled, refunded] }
        driverId: { type: [string, "null"], format: uuid }
        deliveryAddress: { $ref: "#/components/schemas/DriverOrderAddress" }
        paymentMethod: { type: string }
        note: { type: [string, "null"] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        statusHistory:
          type: array
          items: { $ref: "#/components/schemas/DriverOrderStatusHistory" }
        restaurantLatitude: { type: number, minimum: -90, maximum: 90 }
        restaurantLongitude: { type: number, minimum: -180, maximum: 180 }
        estimatedDeliveryTimeMinutes: { type: [integer, "null"], minimum: 1 }
        routePolyline: { type: [string, "null"] }
      required:
        - id
        - userId
        - restaurantId
        - restaurantName
        - restaurantLogoUrl
        - restaurantPhone
        - customerName
        - customerPhone
        - items
        - subtotal
        - deliveryFee
        - discount
        - total
        - status
        - driverId
        - deliveryAddress
        - paymentMethod
        - note
        - createdAt
        - updatedAt
        - statusHistory
        - restaurantLatitude
        - restaurantLongitude
        - estimatedDeliveryTimeMinutes
        - routePolyline

    DriverDailyEarning:
      type: object
      properties:
        date: { type: string, format: date }
        amount: { type: integer, description: "Net driver payout ledger amount in VND" }
        tripCount: { type: integer, minimum: 0 }
      required: [date, amount, tripCount]

    DriverEarningsSummary:
      type: object
      properties:
        period: { type: string, enum: [7d, 30d, 90d] }
        totalVnd: { type: integer, description: "Net driver payout ledger amount in VND" }
        tripCount: { type: integer, minimum: 0 }
        avgPerTrip: { type: integer, description: "VND" }
        byDay:
          type: array
          items: { $ref: "#/components/schemas/DriverDailyEarning" }
      required: [period, totalVnd, tripCount, avgPerTrip, byDay]

    DriverEarningsSummaryResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/DriverEarningsSummary" }
      required: [success, data]

    DriverRatingReview:
      type: object
      properties:
        id: { type: string, format: uuid }
        customerName: { type: string }
        customerAvatarUrl: { type: string, nullable: true }
        rating: { type: integer, minimum: 1, maximum: 5 }
        comment: { type: string, nullable: true }
        date: { type: string, format: date-time }
        orderId: { type: string, format: uuid }
        orderCode: { type: string }
      required: [id, customerName, customerAvatarUrl, rating, comment, date, orderId, orderCode]

    DriverRatingStats:
      type: object
      properties:
        average: { type: number, format: double, minimum: 0, maximum: 5 }
        totalReviews: { type: integer, minimum: 0 }
        distribution:
          type: object
          additionalProperties:
            type: integer
            minimum: 0
          example: { "1": 0, "2": 0, "3": 0, "4": 1, "5": 2 }
      required: [average, totalReviews, distribution]

    DriverRatings:
      type: object
      properties:
        reviews:
          type: array
          items: { $ref: "#/components/schemas/DriverRatingReview" }
        stats: { $ref: "#/components/schemas/DriverRatingStats" }
        hasMore: { type: boolean }
      required: [reviews, stats, hasMore]

    DriverRatingsResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/DriverRatings" }
      required: [success, data]

    DriverTripRoutePoint:
      type: object
      properties:
        lat: { type: number, format: double }
        lng: { type: number, format: double }
        timestamp: { type: string, format: date-time }
      required: [lat, lng, timestamp]

    DriverTripRouteSegment:
      type: object
      properties:
        distanceKm: { type: number, format: double, minimum: 0 }
        durationSeconds: { type: integer, minimum: 0 }
        instruction: { type: string }
        startIndex: { type: integer, minimum: 0 }
        endIndex: { type: integer, minimum: 0 }
      required: [distanceKm, durationSeconds, instruction, startIndex, endIndex]

    DriverTripRoute:
      type: object
      properties:
        tripId: { type: string, format: uuid }
        points:
          type: array
          items: { $ref: "#/components/schemas/DriverTripRoutePoint" }
        segments:
          type: array
          items: { $ref: "#/components/schemas/DriverTripRouteSegment" }
        totalDistanceKm: { type: number, format: double, minimum: 0 }
        totalDurationSeconds: { type: integer, minimum: 0 }
        avgSpeedKmh: { type: number, format: double, minimum: 0 }
        payout: { type: number, minimum: 0 }
      required: [tripId, points, segments, totalDistanceKm, totalDurationSeconds, avgSpeedKmh, payout]

    DriverTripRouteResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/DriverTripRoute" }
      required: [success, data]

    DriverHeatmapPoint:
      type: object
      properties:
        lat: { type: number, format: double }
        lng: { type: number, format: double }
        demandLevel: { type: integer, minimum: 0, maximum: 2, description: "0 low, 1 medium, 2 high" }
        orderCount: { type: integer, minimum: 0 }
        avgPayout: { type: integer, description: "Average delivery fee in VND" }
      required: [lat, lng, demandLevel, orderCount, avgPayout]
      example:
        lat: 10.7769
        lng: 106.7009
        demandLevel: 2
        orderCount: 12
        avgPayout: 32000

    DriverHeatmapResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data:
          type: array
          items: { $ref: "#/components/schemas/DriverHeatmapPoint" }
      required: [success, data]

    DriverBankAccount:
      type: object
      properties:
        id: { type: string, format: uuid }
        bankCode: { type: string, minLength: 2, maxLength: 32 }
        bankName: { type: string, minLength: 2, maxLength: 160 }
        accountNumber: { type: string, minLength: 4, maxLength: 32 }
        accountHolderName: { type: string, minLength: 2, maxLength: 160 }
        isDefault: { type: boolean }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
      required: [id, bankCode, bankName, accountNumber, accountHolderName, isDefault, createdAt, updatedAt]

    CreateDriverBankAccountRequest:
      type: object
      properties:
        bankCode: { type: string, minLength: 2, maxLength: 32, pattern: "^[A-Za-z0-9_-]+$" }
        bankName: { type: string, minLength: 2, maxLength: 160 }
        accountNumber: { type: string, pattern: "^[0-9]{4,32}$" }
        accountHolderName: { type: string, minLength: 2, maxLength: 160 }
      required: [bankCode, bankName, accountNumber, accountHolderName]

    DriverBankAccountsResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data:
          type: array
          items: { $ref: "#/components/schemas/DriverBankAccount" }
      required: [success, data]

    DriverBankAccountResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/DriverBankAccount" }
      required: [success, data]

    DeleteDriverBankAccountResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data:
          type: object
          properties:
            deleted: { type: boolean, const: true }
          required: [deleted]
      required: [success, data]

    DriverTipReport:
      type: object
      properties:
        id: { type: string, format: uuid }
        tripId: { type: string, format: uuid }
        amount: { type: integer, minimum: 1000, maximum: 500000, description: "Cash tip amount reported by driver in VND" }
        currency: { type: string, enum: [VND] }
        status: { type: string, enum: [reported] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
      required: [id, tripId, amount, currency, status, createdAt, updatedAt]

    DriverTipReportRequest:
      type: object
      properties:
        amount: { type: integer, minimum: 1000, maximum: 500000 }
      required: [amount]

    DriverTipReportResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/DriverTipReport" }
      required: [success, data]

    DriverIncentive:
      type: object
      properties:
        id: { type: string }
        title: { type: string }
        rewardAmount: { type: integer, minimum: 0, description: "VND" }
        progress: { type: integer, minimum: 0 }
        target: { type: integer, minimum: 0 }
        endsAt: { type: string, format: date-time }
      required: [id, title, rewardAmount, progress, target, endsAt]

    DriverIncentives:
      type: object
      properties:
        active:
          type: array
          items: { $ref: "#/components/schemas/DriverIncentive" }
        completed:
          type: array
          items: { $ref: "#/components/schemas/DriverIncentive" }
      required: [active, completed]

    DriverIncentivesResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/DriverIncentives" }
      required: [success, data]

    DriverAgreementAcceptance:
      type: object
      properties:
        termsAcceptedAt: { type: string, format: date-time }
        termsVersion: { type: string, minLength: 4, maxLength: 32 }
      required: [termsAcceptedAt, termsVersion]

    AcceptDriverAgreementRequest:
      type: object
      properties:
        termsVersion: { type: string, minLength: 4, maxLength: 32 }
      required: [termsVersion]
      example:
        termsVersion: "driver-terms-2026-07"

    DriverAgreementAcceptanceResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/DriverAgreementAcceptance" }
      required: [success, data]

    DriverTrip:
      type: object
      properties:
        orderId:  { type: string, format: uuid }
        status:   { type: string }
        earnings: { type: integer, description: "VND. Driver share of delivery fee" }
        distanceKm: { type: number }
        completedAt: { type: string, format: date-time }
      required: [orderId, status, earnings]
      example:
        orderId: "66666666-6666-4666-8666-666666666666"
        status: "completed"
        earnings: 12000
        distanceKm: 2.3
        completedAt: "2026-06-09T11:40:00Z"

    DriverWithdrawalRequest:
      type: object
      properties:
        amount:         { type: integer, minimum: 50000, maximum: 50000000, description: "VND" }
        bankCode:       { type: string }
        accountNumber:  { type: string }
        accountName:    { type: string }
      required: [amount, bankCode, accountNumber, accountName]
      example:
        amount: 5000000
        bankCode: "VCB"
        accountNumber: "0011001234567"
        accountName: "NGUYEN VAN B"

    # ── Restaurant staff ──

    StaffCapability:
      type: string
      enum: [orders, menu, reports, settings, staff, promotions]

    RestaurantStaffMember:
      type: object
      properties:
        id: { type: string, format: uuid }
        userId: { type: string, format: uuid }
        name: { type: string }
        email: { type: string, format: email }
        avatar: { type: string, format: uri, nullable: true }
        role: { type: string, enum: [owner, manager, kitchen, cashier, viewer] }
        permissions:
          type: array
          items: { $ref: "#/components/schemas/StaffCapability" }
        isActive: { type: boolean }
        joinedAt: { type: string, format: date-time }
      required: [id, userId, name, email, role, permissions, isActive, joinedAt]

    RestaurantStaffInvite:
      type: object
      properties:
        id: { type: string, format: uuid }
        email: { type: string, format: email }
        role: { type: string, enum: [manager, kitchen, cashier, viewer] }
        permissions:
          type: array
          items: { $ref: "#/components/schemas/StaffCapability" }
        status: { type: string, enum: [pending, accepted, expired, revoked] }
        expiresAt: { type: string, format: date-time }
        createdAt: { type: string, format: date-time }
      required: [id, email, role, permissions, status, expiresAt, createdAt]

    CreatedRestaurantStaffInvite:
      allOf:
        - $ref: "#/components/schemas/RestaurantStaffInvite"
        - type: object
          properties:
            token:
              type: string
              description: Returned once for delivery by an authorized invitation integration.
              readOnly: true
          required: [token]

    RestaurantStaffShift:
      type: object
      properties:
        id: { type: string, format: uuid }
        restaurantId: { type: string, format: uuid }
        restaurantProfileId: { type: string, format: uuid }
        startsAt: { type: string, format: date-time }
        endsAt: { type: string, format: date-time }
        status: { type: string, enum: [scheduled, completed, cancelled] }
        note: { type: string, maxLength: 300, nullable: true }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
      required: [id, restaurantId, restaurantProfileId, startsAt, endsAt, status, createdAt, updatedAt]

    RestaurantStaffOverview:
      type: object
      properties:
        staff:
          type: array
          items: { $ref: "#/components/schemas/RestaurantStaffMember" }
        invites:
          type: array
          items: { $ref: "#/components/schemas/RestaurantStaffInvite" }
        shifts:
          type: array
          items: { $ref: "#/components/schemas/RestaurantStaffShift" }
      required: [staff, invites, shifts]

    RestaurantStaffOverviewResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/RestaurantStaffOverview" }
      required: [success, data]

    RestaurantStaffMemberResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/RestaurantStaffMember" }
      required: [success, data]

    InviteRestaurantStaffRequest:
      type: object
      properties:
        emails:
          type: array
          minItems: 1
          maxItems: 20
          items: { type: string, format: email }
        role: { type: string, enum: [manager, kitchen, cashier, viewer] }
        permissions:
          type: array
          items: { $ref: "#/components/schemas/StaffCapability" }
      required: [emails, role]

    InviteRestaurantStaffResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data:
          type: object
          properties:
            invites:
              type: array
              items: { $ref: "#/components/schemas/CreatedRestaurantStaffInvite" }
          required: [invites]
      required: [success, data]

    UpdateRestaurantStaffRequest:
      type: object
      properties:
        role: { type: string, enum: [manager, kitchen, cashier, viewer] }
        permissions:
          type: array
          items: { $ref: "#/components/schemas/StaffCapability" }
        isActive: { type: boolean }

    CreateRestaurantStaffShiftRequest:
      type: object
      properties:
        restaurantProfileId: { type: string, format: uuid }
        startsAt: { type: string, format: date-time }
        endsAt: { type: string, format: date-time }
        note: { type: string, maxLength: 300 }
      required: [restaurantProfileId, startsAt, endsAt]

    UpdateRestaurantStaffShiftRequest:
      type: object
      properties:
        startsAt: { type: string, format: date-time }
        endsAt: { type: string, format: date-time }
        note: { type: string, maxLength: 300 }
        status: { type: string, enum: [scheduled, completed, cancelled] }

    RestaurantStaffShiftResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/RestaurantStaffShift" }
      required: [success, data]

    DeleteRestaurantStaffShiftResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data:
          type: object
          properties:
            deleted: { type: boolean, const: true }
          required: [deleted]
      required: [success, data]

    RestaurantReview:
      type: object
      additionalProperties: false
      properties:
        id: { type: string, format: uuid }
        orderId: { type: string, format: uuid }
        rating: { type: integer, minimum: 1, maximum: 5 }
        comment: { type: string }
        customerName: { type: string }
        customerInitial: { type: string, minLength: 0, maxLength: 2 }
        customerAvatar: { type: [string, "null"], format: uri }
        dishName: { type: string }
        dishId: { type: [string, "null"], format: uuid }
        photos:
          type: array
          items: { type: string, format: uri }
        reply: { type: [string, "null"] }
        repliedAt: { type: [string, "null"], format: date-time }
        createdAt: { type: string, format: date-time }
      required: [id, orderId, rating, comment, customerName, customerInitial, customerAvatar, dishName, dishId, photos, reply, repliedAt, createdAt]

    RestaurantReviewsPayload:
      type: object
      additionalProperties: false
      properties:
        reviews:
          type: array
          items: { $ref: "#/components/schemas/RestaurantReview" }
        distribution:
          type: object
          additionalProperties: { type: integer, minimum: 0 }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [reviews, distribution, meta]

    RestaurantReviewReplyRequest:
      type: object
      additionalProperties: false
      properties:
        reply: { type: string, minLength: 1, maxLength: 1000 }
      required: [reply]

    RestaurantReviewReplyResult:
      type: object
      properties:
        id: { type: string, format: uuid }
        reply: { type: string }
        replyAt: { type: string, format: date-time }
      required: [id, reply, replyAt]

    # ── Payments ──

    SepayWebhookPayload:
      type: object
      properties:
        id:              { type: integer, minimum: 1, description: "Stable SePay transaction id used for deduplication" }
        gateway:         { type: string, example: "Vietcombank" }
        transactionDate: { type: string, description: "Vietnam local time in YYYY-MM-DD HH:mm:ss format" }
        accountNumber:   { type: string }
        subAccount:      { type: string, description: "Matched virtual account, or an empty string" }
        code:            { type: [string, "null"], description: "Payment code extracted by SePay" }
        content:         { type: string }
        transferType:    { type: string, enum: [in, out] }
        description:     { type: string }
        transferAmount:  { type: integer, minimum: 1, description: "Positive VND amount" }
        accumulated:     { type: integer, minimum: 0 }
        referenceCode:   { type: string, description: "Bank transaction reference" }
      required: [id, gateway, transactionDate, accountNumber, code, content, transferType, transferAmount]
      example:
        id: 92704
        gateway: "Vietcombank"
        transactionDate: "2026-07-11 14:30:00"
        accountNumber: "0011001234567"
        subAccount: ""
        code: "FF-ORDERABC123"
        content: "FF-ORDERABC123 thanh toan"
        transferType: "in"
        description: "NGUYEN VAN A chuyen tien"
        transferAmount: 200000
        accumulated: 1000000
        referenceCode: "FT2607110001"

    PaymentIntent:
      type: object
      properties:
        id:             { type: string, format: uuid }
        orderId:        { type: string, format: uuid }
        amount:         { type: integer, description: "VND" }
        method:         { type: string, enum: [cash, wallet, sepay] }
        status:         { type: string, enum: [pending, completed, failed, refunded] }
        transactionRef: { type: string }
        paidAt:         { type: string, format: date-time }
        createdAt:      { type: string, format: date-time }
      required: [id, orderId, amount, method, status, createdAt]
      example:
        id: "77777777-7777-4777-8777-777777777777"
        orderId: "66666666-6666-4666-8666-666666666666"
        amount: 125000
        method: "wallet"
        status: "completed"
        transactionRef: "sepay-ref-abc123"
        paidAt: "2026-06-09T11:00:05Z"
        createdAt: "2026-06-09T11:00:00Z"

    # ── Promotions ──

    Promotion:
      type: object
      properties:
        id:            { type: string, format: uuid }
        code:          { type: string }
        name:          { type: string, maxLength: 150 }
        description:   { type: string }
        type:          { type: string, enum: [percentage, fixed, free_delivery, bogo, combo] }
        value:         { type: integer, description: "Percent (if percentage) or VND (if fixed)" }
        minOrderAmount: { type: integer, description: "Minimum order amount in VND" }
        maxDiscount:   { type: integer, description: "Max discount cap in VND" }
        usageLimit:    { type: integer }
        usageCount:    { type: integer }
        maxPerUser:    { type: integer, minimum: 1 }
        targeting:     { type: object, additionalProperties: true }
        status:        { type: string, enum: [draft, scheduled, active, paused, expired, archived] }
        startsAt:      { type: string, format: date-time }
        expiresAt:     { type: string, format: date-time }
        isActive:      { type: boolean }
        createdAt:     { type: string, format: date-time }
      required: [id, code, type, value, usageLimit, startsAt, expiresAt, isActive]
      example:
        id: "88888888-8888-4888-8888-888888888888"
        code: "WELCOME2026"
        type: "percentage"
        value: 20
        minOrderAmount: 100000
        maxDiscount: 50000
        usageLimit: 500
        usageCount: 23
        startsAt: "2026-06-01T00:00:00Z"
        expiresAt: "2026-07-01T00:00:00Z"
        isActive: true
        createdAt: "2026-06-01T00:00:00Z"

    RestaurantPromotion:
      type: object
      properties:
        id: { type: string, format: uuid }
        code: { type: string }
        name: { type: string }
        description: { type: string, nullable: true }
        type: { type: string, enum: [percent, fixed, bogof, combo] }
        discountValue: { type: number }
        minOrderVnd: { type: number }
        maxDiscountVnd: { type: number, nullable: true }
        appliesTo: { type: string, enum: [all, category, items] }
        categoryId: { type: string, format: uuid, nullable: true }
        itemIds: { type: array, items: { type: string, format: uuid } }
        target: { type: object, additionalProperties: true }
        schedule:
          type: object
          properties:
            validFrom: { type: string, format: date-time }
            validUntil: { type: string, format: date-time }
            recurring: { type: object, nullable: true, additionalProperties: true }
          required: [validFrom, validUntil]
        channels: { type: array, items: { type: string, enum: [in_app, push, email, sms] } }
        stackable: { type: boolean }
        maxUsage: { type: integer }
        perUserLimit: { type: integer }
        usageCount: { type: integer }
        status: { type: string, enum: [draft, scheduled, active, paused, expired, archived] }
        createdAt: { type: string, format: date-time }
        createdBy: { type: string }
      required: [id, code, name, type, discountValue, appliesTo, target, schedule, channels, stackable, perUserLimit, usageCount, status, createdAt, createdBy]

    RestaurantPromotionAnalytics:
      type: object
      properties:
        usageCount: { type: integer, minimum: 0 }
        revenueAttributed: { type: number, minimum: 0, description: "VND from orders that redeemed the promotion" }
        discountGiven: { type: number, minimum: 0, description: "VND discount cost from promotion usages" }
        redemptionRate: { type: number, minimum: 0, description: "Usage count divided by finite usage limit, percent" }
        roi: { type: number, description: "(revenueAttributed - discountGiven) / discountGiven, percent" }
        usageTimeline:
          type: array
          items:
            type: object
            properties:
              date: { type: string, format: date }
              count: { type: integer, minimum: 0 }
              revenueAttributed: { type: number, minimum: 0 }
              discountGiven: { type: number, minimum: 0 }
            required: [date, count, revenueAttributed, discountGiven]
      required: [usageCount, revenueAttributed, discountGiven, redemptionRate, roi, usageTimeline]

    AdminPromotionAnalytics:
      type: object
      description: Admin-wide promotion analytics derived from real `promotion_usage` and linked order totals.
      properties:
        redemptions: { type: integer, minimum: 0 }
        gmv: { type: number, minimum: 0, description: "Gross merchandise value from orders that redeemed the promotion." }
        discountCost: { type: number, minimum: 0, description: "Promotion discount cost in VND." }
        roi:
          type: [number, "null"]
          description: "(gmv - discountCost) / discountCost, null when discountCost is zero."
      required: [redemptions, gmv, discountCost, roi]

    RestaurantInsightSuggestionParams:
      type: object
      additionalProperties:
        oneOf:
          - type: string
          - type: number
          - type: boolean
          - type: "null"

    RestaurantInsightSuggestion:
      type: object
      description: Recommendation payload. Runtime responses carry i18n keys plus params; localized text is resolved by the client.
      properties:
        id: { type: string }
        type: { type: string, enum: [pricing, menu_mix, marketing, operations] }
        titleKey: { type: string, description: "Key under restaurant web `insights.suggestions` messages" }
        descriptionKey: { type: string, description: "Key under restaurant web `insights.suggestions` messages" }
        predictedImpactKey: { type: string, description: "Key under restaurant web `insights.suggestions` messages" }
        params: { $ref: "#/components/schemas/RestaurantInsightSuggestionParams" }
        actionable: { type: boolean }
      required: [id, type, titleKey, descriptionKey, predictedImpactKey, params, actionable]
      example:
        id: "menu-availability"
        type: "menu_mix"
        titleKey: "catalog.menuAvailability.title"
        descriptionKey: "catalog.menuAvailability.description"
        predictedImpactKey: "catalog.menuAvailability.impact"
        params: { count: 2 }
        actionable: true

    RestaurantPeakHour:
      type: object
      properties:
        day: { type: integer, minimum: 0, maximum: 6, description: "JavaScript day index, Sunday = 0" }
        hour: { type: integer, minimum: 0, maximum: 23 }
        orderCount: { type: integer, minimum: 0 }
      required: [day, hour, orderCount]

    RestaurantBestSeller:
      type: object
      properties:
        itemId: { type: string, format: uuid }
        name: { type: string }
        orderCount: { type: integer, minimum: 0 }
        revenueShare: { type: number, minimum: 0 }
        trendVsLastWeek: { type: number }
      required: [itemId, name, orderCount, revenueShare, trendVsLastWeek]

    RestaurantSlowMover:
      type: object
      properties:
        itemId: { type: string, format: uuid }
        name: { type: string }
        ordersInPeriod: { type: integer, minimum: 0 }
        period: { type: integer, minimum: 1 }
        pctDecline: { type: number, minimum: 0 }
        recommendation: { type: string, enum: [bundle, discount, remove] }
      required: [itemId, name, ordersInPeriod, period, pctDecline, recommendation]

    RestaurantRevenueForecastPoint:
      type: object
      properties:
        date: { type: string, format: date }
        predicted: { type: number, minimum: 0 }
        actual: { type: number, minimum: 0 }
        lower: { type: number, minimum: 0 }
        upper: { type: number, minimum: 0 }
      required: [date, predicted]

    RestaurantInsights:
      type: object
      properties:
        suggestions:
          type: array
          items: { $ref: "#/components/schemas/RestaurantInsightSuggestion" }
        peakHours:
          type: array
          items: { $ref: "#/components/schemas/RestaurantPeakHour" }
        bestSellers:
          type: array
          items: { $ref: "#/components/schemas/RestaurantBestSeller" }
        slowMovers:
          type: array
          items: { $ref: "#/components/schemas/RestaurantSlowMover" }
        forecast:
          type: array
          items: { $ref: "#/components/schemas/RestaurantRevenueForecastPoint" }
      required: [suggestions, peakHours, bestSellers, slowMovers, forecast]

    RestaurantInsightsEnvelope:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/RestaurantInsights" }
      required: [success, data]

    RestaurantPromotionListEnvelope:
      type: object
      properties:
        success: { type: boolean, const: true }
        data:
          type: object
          properties:
            promotions:
              type: array
              items: { $ref: "#/components/schemas/RestaurantPromotion" }
            total: { type: integer, minimum: 0 }
            analytics: { $ref: "#/components/schemas/RestaurantPromotionAnalytics" }
          required: [promotions, total, analytics]
      required: [success, data]

    RestaurantPromotionDetailEnvelope:
      type: object
      properties:
        success: { type: boolean, const: true }
        data:
          type: object
          properties:
            promotion: { $ref: "#/components/schemas/RestaurantPromotion" }
            analytics: { $ref: "#/components/schemas/RestaurantPromotionAnalytics" }
          required: [promotion, analytics]
      required: [success, data]

    CreatePromotionRequest:
      type: object
      properties:
        code:          { type: string, maxLength: 50 }
        name:          { type: string, maxLength: 150 }
        description:   { type: string, maxLength: 2000 }
        type:          { type: string, enum: [percentage, fixed, free_delivery, bogo, combo] }
        value:         { type: integer, description: "Percent or VND" }
        minOrderAmount: { type: integer, description: "VND" }
        maxDiscount:   { type: integer, description: "VND" }
        usageLimit:    { type: integer, minimum: 1 }
        maxPerUser:    { type: integer, minimum: 1 }
        targeting:     { type: object, additionalProperties: true }
        startsAt:      { type: string, format: date-time }
        expiresAt:     { type: string, format: date-time }
        isActive:      { type: boolean, default: true }
      required: [code, type, value, usageLimit, startsAt, expiresAt]
      example:
        code: "SUMMER2026"
        type: "fixed"
        value: 30000
        minOrderAmount: 150000
        maxDiscount: 30000
        usageLimit: 1000
        startsAt: "2026-07-01T00:00:00Z"
        expiresAt: "2026-08-31T23:59:59Z"
        isActive: true

    UpdatePromotionRequest:
      type: object
      properties:
        code:          { type: string, maxLength: 50 }
        name:          { type: string, maxLength: 150 }
        description:   { type: string, maxLength: 2000 }
        type:          { type: string, enum: [percentage, fixed, free_delivery, bogo, combo] }
        value:         { type: integer }
        minOrderAmount: { type: integer, description: "VND" }
        maxDiscount:   { type: integer, description: "VND" }
        usageLimit:    { type: integer, minimum: 1 }
        maxPerUser:    { type: integer, minimum: 1 }
        targeting:     { type: object, additionalProperties: true }
        startsAt:      { type: string, format: date-time }
        expiresAt:     { type: string, format: date-time }
        isActive:      { type: boolean }
      example:
        maxDiscount: 50000

    PromotionValidateRequest:
      type: object
      properties:
        code:          { type: string }
        restaurantId:  { type: string, format: uuid }
        subtotal:      { type: integer, description: "Order subtotal in VND before delivery fee and discount" }
      required: [code, restaurantId, subtotal]
      example:
        code: "WELCOME2026"
        restaurantId: "33333333-3333-4333-8333-333333333333"
        subtotal: 200000

    PromotionValidateResult:
      type: object
      properties:
        discountAmount: { type: integer, description: "VND" }
      required: [discountAmount]
      example:
        discountAmount: 40000

    CustomerPromotion:
      type: object
      properties:
        id:             { type: string, format: uuid }
        code:           { type: string }
        title:          { type: string }
        name:           { type: string }
        description:    { type: string }
        type:           { type: string, enum: [percentage, fixed, free_delivery, bogo, combo] }
        value:          { type: integer, description: "Raw promotion value" }
        discountPercent: { type: integer, nullable: true }
        percentOff:     { type: integer, nullable: true }
        fixedAmount:    { type: integer, nullable: true, description: "VND" }
        maxDiscount:    { type: integer, nullable: true, description: "VND" }
        minOrderAmount: { type: integer, description: "VND" }
        restaurantId:   { type: string, format: uuid, nullable: true }
        expiresAt:      { type: string, format: date-time }
        isUsed:         { type: boolean }
        status:         { type: string, enum: [available, used] }
        usedAt:         { type: string, format: date-time, nullable: true }
      required: [id, code, title, name, description, type, value, minOrderAmount, expiresAt, isUsed, status]
      example:
        id: "11111111-1111-4111-8111-111111111111"
        code: "WELCOME2026"
        title: "Welcome 2026"
        name: "Welcome 2026"
        description: "20% off your first FoodFlow order"
        type: "percentage"
        value: 20
        discountPercent: 20
        percentOff: 20
        maxDiscount: 50000
        minOrderAmount: 100000
        expiresAt: "2026-12-31T16:59:59.000Z"
        isUsed: false
        status: "available"

    # ── Notifications ──

    PromotionTargetingPreview:
      type: object
      properties:
        audience:
          type: string
          enum: [all, new, vip, lapsed, order_history]
        estimatedReach: { type: integer, minimum: 0 }
        breakdown:
          type: array
          items:
            type: object
            properties:
              key: { type: string, enum: [new, returning, lapsed] }
              count: { type: integer, minimum: 0 }
              pct: { type: integer, minimum: 0, maximum: 100 }
            required: [key, count, pct]
        updatedAt: { type: string, format: date-time }
      required: [audience, estimatedReach, breakdown, updatedAt]

    PromotionTargetingPreviewEnvelope:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { $ref: "#/components/schemas/PromotionTargetingPreview" }
      required: [success, data]

    PromotionBroadcastEnvelope:
      type: object
      properties:
        success: { type: boolean, const: true }
        data:
          type: object
          properties:
            targeted: { type: integer, minimum: 0 }
            sent: { type: integer, minimum: 0 }
          required: [targeted, sent]
      required: [success, data]

    Notification:
      type: object
      properties:
        id:        { type: string, format: uuid }
        title:     { type: string }
        body:      { type: string }
        type:      { type: string, description: "Backend notification event type such as order_update, promotion.broadcast, support.reply, or driver_alert" }
        isRead:    { type: boolean }
        data:      { type: object, description: "Arbitrary JSON payload persisted on the notification row" }
        deepLink:  { type: string, nullable: true, description: "Optional client navigation target when supplied by the event producer" }
        createdAt: { type: string, format: date-time }
      required: [id, title, body, type, isRead, createdAt]
      example:
        id: "99999999-9999-4999-8999-999999999999"
        title: "Đơn hàng #order-001 đang được chuẩn bị"
        body: "Nhà hàng Phở 24 đã nhận đơn và đang chế biến món ăn của bạn"
        type: "order_update"
        isRead: false
        data: { orderId: "66666666-6666-4666-8666-666666666666", event: "preparing" }
        deepLink: "/orders/66666666-6666-4666-8666-666666666666"
        createdAt: "2026-06-09T11:05:00Z"

    RegisterFcmTokenRequest:
      type: object
      properties:
        token:    { type: string, minLength: 20, maxLength: 500 }
        platform: { type: string, enum: [ios, android, web] }
        deviceId: { type: string, minLength: 1, maxLength: 200 }
        registrationId: { type: string, format: uuid }
      required: [token, platform, registrationId]
      example:
        token: "REPLACE_WITH_FCM_TOKEN"
        platform: "android"
        deviceId: "device-001"
        registrationId: "9165a90e-1e23-4f7a-8df6-5c7b1a5c4f10"

    LegacyRegisterFcmTokenRequest:
      type: object
      deprecated: true
      description: >-
        Temporary rolling-upgrade body for installed mobile clients. New
        clients must send registrationId; remove support only after enforcing
        a minimum mobile version.
      properties:
        token:    { type: string, minLength: 20, maxLength: 500 }
        platform: { type: string, enum: [ios, android, web] }
        deviceId: { type: string, minLength: 1, maxLength: 200 }
      required: [token, platform]

    UnregisterFcmTokenRequest:
      type: object
      properties:
        token: { type: string, minLength: 20, maxLength: 500 }
        registrationId: { type: string, format: uuid }
      required: [token, registrationId]

    # ── Support ──

    SupportTicket:
      type: object
      properties:
        id:            { type: string, format: uuid }
        subject:       { type: string }
        issueType:     { type: string, enum: [late_delivery, wrong_item, missing_item, driver_issue, refund_request, other] }
        priority:      { type: string, enum: [low, medium, high, critical] }
        status:        { type: string, enum: [open, in_progress, resolved, closed] }
        orderId:       { type: string, format: uuid }
        userId:        { type: string, format: uuid }
        assignedAdminId: { type: string, format: uuid }
        resolutionNotes: { type: string }
        csatScore:     { type: integer, minimum: 1, maximum: 5, description: "Customer satisfaction after resolution" }
        createdAt:     { type: string, format: date-time }
        updatedAt:     { type: string, format: date-time }
        replies:
          type: array
          items: { $ref: "#/components/schemas/TicketReply" }
      required: [id, subject, issueType, priority, status, userId, createdAt, updatedAt]
      example:
        id: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
        subject: "Đơn hàng giao thiếu món"
        issueType: "missing_item"
        priority: "medium"
        status: "in_progress"
        orderId: "66666666-6666-4666-8666-666666666666"
        userId: "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
        createdAt: "2026-06-09T12:00:00Z"
        updatedAt: "2026-06-09T12:30:00Z"
        replies: []

    TicketReply:
      type: object
      properties:
        id:        { type: string, format: uuid }
        ticketId:  { type: string, format: uuid }
        authorId:  { type: string, format: uuid }
        authorRole: { type: string, enum: [customer, admin] }
        body:      { type: string }
        createdAt: { type: string, format: date-time }
      required: [id, ticketId, authorId, body, createdAt]
      example:
        id: "cccccccc-cccc-4ccc-8ccc-cccccccccccc"
        ticketId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
        authorId: "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
        authorRole: "admin"
        body: "Chúng tôi đã kiểm tra và sẽ hoàn tiền cho món thiếu. Xin lỗi bạn vì sự bất tiện này."
        createdAt: "2026-06-09T12:30:00Z"

    SupportAgent:
      type: object
      properties:
        id: { type: string, format: uuid }
        fullName: { type: string }
        email: { type: string, format: email }
      required: [id, fullName, email]

    SupportMessagesPayload:
      type: object
      properties:
        messages:
          type: array
          items: { $ref: "#/components/schemas/TicketReply" }
      required: [messages]

    SupportMessageRequest:
      type: object
      properties:
        body: { type: string, minLength: 1 }
      required: [body]

    CreateTicketRequest:
      type: object
      properties:
        subject:   { type: string, maxLength: 200 }
        issueType: { type: string, enum: [late_delivery, wrong_item, missing_item, driver_issue, refund_request, other] }
        priority:  { type: string, enum: [low, medium, high, critical], default: medium }
        orderId:   { type: string, format: uuid }
        body:      { type: string }
      required: [subject, issueType]
      example:
        subject: "Đơn hàng giao thiếu món"
        issueType: "missing_item"
        priority: "medium"
        orderId: "66666666-6666-4666-8666-666666666666"
        body: "Tôi đặt 2 bát phở nhưng chỉ nhận được 1 bát."

    CreateReplyRequest:
      type: object
      properties:
        body: { type: string }
      required: [body]
      example:
        body: "Cảm ơn bạn đã phản hồi. Tôi sẽ kiểm tra ngay."

    UpdateTicketRequest:
      type: object
      properties:
        status:          { type: string, enum: [open, in_progress, resolved, closed] }
        assignedAdminId: { type: string, format: uuid }
        resolutionNotes: { type: string }
      example:
        status: "resolved"
        resolutionNotes: "Đã hoàn tiền món thiếu 65,000đ"

    SubmitCsatRequest:
      type: object
      properties:
        score:   { type: integer, minimum: 1, maximum: 5 }
        feedback: { type: string, maxLength: 500 }
      required: [score]
      example:
        score: 4
        feedback: "Xử lý nhanh, nhân viên lịch sự"

    # ── Audit ──

    AuditLogEntry:
      type: object
      properties:
        id:        { type: string, description: "Serialized bigint audit identifier" }
        adminId:   { type: string, format: uuid }
        admin:
          type: object
          properties:
            id:       { type: string, format: uuid }
            email:    { type: string, format: email }
            fullName: { type: string }
        action:       { type: string, description: "e.g. promotion.updated" }
        targetType:   { type: string, description: "e.g. promotion, restaurant" }
        targetId:     { type: string, format: uuid, nullable: true }
        oldValue:     { type: object, nullable: true, additionalProperties: true }
        newValue:     { type: object, nullable: true, additionalProperties: true }
        ipAddress:    { type: string }
        userAgent: { type: string }
        correlationId: { type: string, nullable: true }
        severity: { type: string }
        metadata: { type: object, nullable: true, additionalProperties: true }
        createdAt: { type: string, format: date-time }
      required: [id, adminId, action, targetType, ipAddress, createdAt]
      example:
        id: "42"
        adminId: "8e65cf48-5f95-4b8e-94cc-3e14062b6339"
        action: "promotion.updated"
        targetType: "promotion"
        targetId: "53e01a32-3918-4c47-b1df-b03338d97f11"
        oldValue: { isActive: false }
        newValue: { isActive: true }
        ipAddress: "192.168.1.1"
        userAgent: "Mozilla/5.0 ..."
        createdAt: "2026-06-09T14:00:00Z"

    # ── Analytics ──

    AdminExportJob:
      type: object
      properties:
        id: { type: string, format: uuid }
        type: { type: string, enum: [audit_logs, drivers, orders, promotions, restaurants, revenue, users] }
        resource: { type: string, enum: [audit_logs, drivers, orders, promotions, restaurants, revenue, users] }
        format: { type: string, enum: [csv, xlsx, parquet] }
        status: { type: string, enum: [queued, running, completed, failed, cancelled] }
        progress: { type: integer, minimum: 0, maximum: 100 }
        rowCount: { type: integer, minimum: 0 }
        totalRows: { type: integer, minimum: 0 }
        filterSummary:
          type: object
          additionalProperties: { type: string }
        requestedBy:
          type: object
          properties:
            id: { type: string, format: uuid }
            email: { type: string, format: email }
            fullName: { type: string }
        createdAt: { type: string, format: date-time }
        completedAt: { type: string, format: date-time }
        downloadUrl: { type: string }
        errorMessage: { type: string }
      required: [id, type, resource, format, status, progress, rowCount, totalRows, filterSummary, createdAt]

    AdminExportJobsPayload:
      type: object
      properties:
        jobs:
          type: array
          items: { $ref: "#/components/schemas/AdminExportJob" }
      required: [jobs]

    CreateAdminExportRequest:
      type: object
      properties:
        resource: { type: string, enum: [audit_logs, drivers, orders, promotions, restaurants, revenue, users] }
        type: { type: string, enum: [audit_logs, drivers, orders, promotions, restaurants, revenue, users], deprecated: true }
        format: { type: string, enum: [csv, xlsx], description: "Parquet is intentionally not accepted until a real parquet writer/storage pipeline exists." }
        period: { type: string, enum: [today, 7d, 30d, thisMonth, thisQuarter, custom] }
        dateFrom: { type: string, format: date }
        dateTo: { type: string, format: date }
        filters:
          type: object
          additionalProperties: true
      required: [format]

    AdminSettingValue:
      type: object
      additionalProperties: true

    AdminSettingsSectionResponse:
      type: object
      properties:
        section: { type: string, enum: [general, branding, compliance, integrations] }
        settings: { $ref: "#/components/schemas/AdminSettingValue" }
        updatedAt: { type: string, format: date-time, nullable: true }
      required: [section, settings, updatedAt]

    AdminSettingsPayload:
      type: object
      properties:
        sections:
          type: object
          properties:
            general: { $ref: "#/components/schemas/AdminSettingsSectionResponse" }
            branding: { $ref: "#/components/schemas/AdminSettingsSectionResponse" }
            compliance: { $ref: "#/components/schemas/AdminSettingsSectionResponse" }
            integrations: { $ref: "#/components/schemas/AdminSettingsSectionResponse" }
      required: [sections]

    AiMonitorStatus:
      type: string
      enum: [online, degraded, not_configured]

    AdminAiMonitorOverview:
      type: object
      properties:
        instance:
          type: object
          properties:
            status: { $ref: "#/components/schemas/AiMonitorStatus" }
            dashboardUrl: { type: string, nullable: true }
            degradedReason: { type: string, nullable: true }
            provider: { type: string, enum: [deepseek] }
            model: { type: string }
            telemetry:
              type: object
              properties:
                status: { type: string, enum: [live, awaiting_requests, unavailable] }
                lastRequestAt: { type: string, format: date-time, nullable: true }
                lastSuccessfulRequestAt: { type: string, format: date-time, nullable: true }
                lastFailureCode: { type: string, nullable: true }
              required: [status, lastRequestAt, lastSuccessfulRequestAt, lastFailureCode]
          required: [status, dashboardUrl, degradedReason, provider, model, telemetry]
        stats: { $ref: "#/components/schemas/AdminAiMonitorStats" }
      required: [instance, stats]

    AdminAiMonitorStats:
      type: object
      properties:
        totalConversations: { type: integer, nullable: true }
        selfResolved: { type: integer, nullable: true }
        escalated: { type: integer, nullable: true }
        resolutionRate: { type: number, nullable: true }
        costTodayUsd: { type: number, nullable: true }
        budgetTodayUsd: { type: number, nullable: true }
        inputTokens: { type: integer, nullable: true }
        outputTokens: { type: integer, nullable: true }
        requests: { type: integer, nullable: true }
        failedRequests: { type: integer, nullable: true }
        averageLatencyMs: { type: integer, nullable: true }
      required:
        - totalConversations
        - selfResolved
        - escalated
        - resolutionRate
        - costTodayUsd
        - budgetTodayUsd
        - inputTokens
        - outputTokens
        - requests
        - failedRequests
        - averageLatencyMs

    AiChatRequest:
      type: object
      properties:
        message: { type: string, minLength: 1, maxLength: 4000 }
        sessionId: { type: string, format: uuid, description: "An active AI-support session owned by the authenticated caller." }
        orderId: { type: string, maxLength: 36, pattern: "^(?:FD\\d{10}|F[DF]-?\\d{3,10}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$", description: "A customer-scoped order UUID or FoodFlow order code; ownership is resolved before grounding." }
      required: [message]

    AiChatReply:
      type: object
      properties:
        reply: { type: string }
        sessionId: { type: string, format: uuid }
        action: { type: string, enum: [answered, escalated] }
        escalated: { type: boolean }
        severity: { type: string }
        language: { type: string, enum: [vi, en, ja] }
        grounded: { type: boolean, description: "True when the reply used verified backend tool context." }
        toolCalls:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                enum:
                  - getOrderStatus
                  - getDriverLocation
                  - getRestaurantStatus
                  - getRefundEligibility
                  - createSupportTicket
                  - getRecommendedFoods
                  - notifyAdmin
              args:
                type: object
                additionalProperties: true
            required: [name, args]
      required: [reply, sessionId, action, language]

    AiChatHistoryMessage:
      type: object
      properties:
        id: { type: string }
        role: { type: string, enum: [user, assistant] }
        content: { type: string }
        createdAt: { type: string, format: date-time }
      required: [id, role, content, createdAt]

    AiChatHistory:
      type: object
      properties:
        sessionId: { type: string, nullable: true, format: uuid }
        messages:
          type: array
          maxItems: 50
          items: { $ref: "#/components/schemas/AiChatHistoryMessage" }
      required: [sessionId, messages]

    DashboardKpi:
      type: object
      properties:
        totalOrders:         { type: integer }
        totalRevenue:        { type: integer, description: "VND" }
        totalUsers:          { type: integer }
        activeDrivers:       { type: integer }
        activeRestaurants:   { type: integer }
        avgOrderValue:       { type: integer, description: "VND" }
        cancellationRate:    { type: number }
        periodStart:         { type: string, format: date-time }
        periodEnd:           { type: string, format: date-time }
      required: [totalOrders, totalRevenue, totalUsers, activeDrivers, activeRestaurants]
      example:
        totalOrders: 1234
        totalRevenue: 156780000
        totalUsers: 8920
        activeDrivers: 45
        activeRestaurants: 67
        avgOrderValue: 127000
        cancellationRate: 0.035
        periodStart: "2026-06-01T00:00:00Z"
        periodEnd: "2026-06-09T23:59:59Z"

    AdminKpiCard:
      type: object
      description: One admin dashboard KPI card returned by the database-backed `/admin/kpis` endpoint.
      properties:
        key: { type: string, example: revenue }
        label: { type: string, example: Revenue }
        value: { type: number }
        formattedValue: { type: string, example: "₫12,450,000" }
        delta: { type: number, description: "Ratio versus the previous period, e.g. 0.12 for +12%." }
        sparkline:
          type: array
          items: { type: number }
        drillDownHref: { type: string, example: "/analytics" }
      required: [key, label, value, formattedValue, delta, sparkline, drillDownHref]

    AdminKpisResponse:
      type: object
      properties:
        kpis:
          type: array
          items: { $ref: "#/components/schemas/AdminKpiCard" }
      required: [kpis]

    AdminRecentOrder:
      type: object
      description: Recent order card used by the admin realtime order feed.
      properties:
        id: { type: string, format: uuid }
        orderCode: { type: string }
        status: { type: string }
        total: { type: number, description: "VND" }
        customer:
          type: object
          properties:
            name: { type: string }
          required: [name]
        restaurant:
          type: object
          properties:
            name: { type: string }
          required: [name]
        driver:
          oneOf:
            - type: object
              properties:
                name: { type: string }
              required: [name]
            - type: "null"
        placedAt: { type: string, format: date-time }
      required: [id, orderCode, status, total, customer, restaurant, driver, placedAt]

    AdminRecentOrdersResponse:
      type: object
      properties:
        orders:
          type: array
          items: { $ref: "#/components/schemas/AdminRecentOrder" }
      required: [orders]

    RevenueChartPoint:
      type: object
      properties:
        date:    { type: string, format: date }
        revenue: { type: integer, description: "VND" }
        orders:  { type: integer }
      required: [date, revenue, orders]
      example:
        date: "2026-06-09"
        revenue: 18250000
        orders: 145

    AdminOrderStatusPoint:
      type: object
      properties:
        date: { type: string, format: date }
        pending: { type: integer, minimum: 0 }
        confirmed: { type: integer, minimum: 0 }
        delivering: { type: integer, minimum: 0 }
        completed: { type: integer, minimum: 0 }
        cancelled: { type: integer, minimum: 0 }
      required: [date, pending, confirmed, delivering, completed, cancelled]

    AdminTopRestaurantPoint:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        rating: { type: number }
        revenue: { type: number, description: "VND" }
        orderCount: { type: integer, minimum: 0 }
      required: [id, name, rating, revenue, orderCount]

    AdminRetentionCohort:
      type: object
      description: Daily first-order customer cohort derived from real orders, with retention counted only when a cohort customer places another order after the cohort date inside the requested window.
      properties:
        date: { type: string, format: date }
        newCustomers: { type: integer, minimum: 0 }
        retainedCustomers: { type: integer, minimum: 0 }
        retentionRate: { type: number, minimum: 0, maximum: 100 }
      required: [date, newCustomers, retainedCustomers, retentionRate]

    AdminDriverOnlinePoint:
      type: object
      properties:
        hour: { type: integer, minimum: 0, maximum: 23 }
        count: { type: integer, minimum: 0 }
      required: [hour, count]

    AdminOrderHeatmapCell:
      type: object
      properties:
        day: { type: integer, minimum: 0, maximum: 6, description: "Monday=0, Sunday=6" }
        hour: { type: integer, minimum: 0, maximum: 23 }
        count: { type: integer, minimum: 0 }
      required: [day, hour, count]

    AdminChartsResponse:
      type: object
      properties:
        revenue:
          type: array
          items:
            type: object
            properties:
              date: { type: string, format: date }
              revenue: { type: number, description: "VND" }
              prevRevenue: { type: number, description: "Previous period VND aligned by day offset" }
            required: [date, revenue, prevRevenue]
        orderStatus:
          type: array
          items: { $ref: "#/components/schemas/AdminOrderStatusPoint" }
        driverOnline:
          type: array
          items: { $ref: "#/components/schemas/AdminDriverOnlinePoint" }
        topRestaurants:
          type: array
          items: { $ref: "#/components/schemas/AdminTopRestaurantPoint" }
        retention:
          type: array
          items: { $ref: "#/components/schemas/AdminRetentionCohort" }
        heatmap:
          type: array
          items: { $ref: "#/components/schemas/AdminOrderHeatmapCell" }
      required: [revenue, orderStatus, driverOnline, topRestaurants, retention, heatmap]

    RestaurantKpi:
      type: object
      properties:
        restaurantId:    { type: string, format: uuid }
        restaurantName:  { type: string }
        totalOrders:     { type: integer }
        totalRevenue:    { type: integer, description: "VND" }
        avgPrepTimeMin:  { type: number }
        rating:          { type: number }
        topItems:
          type: array
          items:
            type: object
            properties:
              itemName:   { type: string }
              orderCount: { type: integer }
              revenue:    { type: integer, description: "VND" }
      required: [restaurantId, restaurantName, totalOrders, totalRevenue]
      example:
        restaurantId: "33333333-3333-4333-8333-333333333333"
        restaurantName: "Phở 24"
        totalOrders: 345
        totalRevenue: 42150000
        avgPrepTimeMin: 14.5
        rating: 4.5
        topItems:
          - { itemName: "Phở bò tái chín", orderCount: 210, revenue: 13650000 }
          - { itemName: "Phở gà", orderCount: 89, revenue: 5785000 }

    HeatmapPoint:
      type: object
      properties:
        districtCode: { type: string, description: "Restaurant district/city bucket for dispatch demand heatmaps." }
        lat:         { type: number }
        lng:         { type: number }
        orderCount:  { type: integer }
        weight:      { type: number, description: "0.0 - 1.0 intensity" }
      required: [lat, lng, orderCount]
      example:
        lat: 10.7769
        lng: 106.7009
        orderCount: 45
        weight: 0.85

    AdminDriver:
      type: object
      properties:
        id: { type: string, format: uuid, description: Driver user ID }
        profileId: { type: string, format: uuid }
        name: { type: string }
        email: { type: string, format: email }
        phone: { type: string, nullable: true }
        rating: { type: number, minimum: 0, maximum: 5 }
        totalDeliveries: { type: integer, minimum: 0 }
        status: { type: string, enum: [online, offline, delivering] }
        vehicleType: { type: string, enum: [motorbike, car, bicycle] }
        vehiclePlate: { type: string, nullable: true }
        isVerified: { type: boolean }
        isActive: { type: boolean }
        createdAt: { type: string, format: date-time }
      required:
        - id
        - profileId
        - name
        - email
        - phone
        - rating
        - totalDeliveries
        - status
        - vehicleType
        - vehiclePlate
        - isVerified
        - isActive
        - createdAt

    AdminDriverLocation:
      type: object
      description: Live nationwide Vietnam admin map location enriched from Redis driver presence and database-backed driver profile/order state.
      properties:
        id: { type: string, format: uuid, description: Driver user ID, example: 4d2b9fb7-8aa4-49f5-96f9-77d931f8f5a1 }
        driverId: { type: string, format: uuid, description: Driver user ID, example: 4d2b9fb7-8aa4-49f5-96f9-77d931f8f5a1 }
        name: { type: string, example: Nguyen Van Tai }
        rating: { type: number, minimum: 0, maximum: 5, example: 4.8 }
        status: { type: string, enum: [online, offline, free, delivering, busy] }
        lat: { type: number, format: double, example: 10.7769 }
        lng: { type: number, format: double, example: 106.7009 }
        currentOrder: { type: string, nullable: true, description: Active order code or ID when driver has an active order. }
        vehicleType: { type: string, nullable: true, example: motorbike }
        vehiclePlate: { type: string, nullable: true, example: 59A1-12345 }
        lastSeenAt: { type: string, format: date-time }
      required:
        - id
        - driverId
        - name
        - rating
        - status
        - lat
        - lng
        - lastSeenAt

    # ── Paged responses ──

    PaginatedUsers:
      type: object
      properties:
        data: { type: array, items: { $ref: "#/components/schemas/UserProfile" } }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [data, meta]
    PaginatedRestaurants:
      type: object
      properties:
        data: { type: array, items: { $ref: "#/components/schemas/RestaurantSummary" } }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [data, meta]
    PaginatedOrders:
      type: object
      properties:
        data: { type: array, items: { $ref: "#/components/schemas/OrderDetail" } }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [data, meta]
    PaginatedNotifications:
      type: object
      properties:
        notifications: { type: array, items: { $ref: "#/components/schemas/Notification" } }
        unreadCount: { type: integer, minimum: 0 }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [notifications, unreadCount, meta]
    PaginatedAuditLogs:
      type: object
      properties:
        data: { type: array, items: { $ref: "#/components/schemas/AuditLogEntry" } }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [data, meta]
    PaginatedPromotions:
      type: object
      properties:
        data: { type: array, items: { $ref: "#/components/schemas/Promotion" } }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [data, meta]
    PaginatedSupportTickets:
      type: object
      properties:
        data: { type: array, items: { $ref: "#/components/schemas/SupportTicket" } }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [data, meta]
    PaginatedDriverTrips:
      type: object
      properties:
        data: { type: array, items: { $ref: "#/components/schemas/DriverTrip" } }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [data, meta]
    PaginatedAdminDrivers:
      type: object
      properties:
        success: { type: boolean, const: true }
        data: { type: array, items: { $ref: "#/components/schemas/AdminDriver" } }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [success, data, meta]
    AdminDriverLocationsResponse:
      type: object
      properties:
        success: { type: boolean, const: true }
        data:
          type: array
          items: { $ref: "#/components/schemas/AdminDriverLocation" }
      required: [success, data]
    PaginatedReviews:
      type: object
      properties:
        data: { type: array, items: { $ref: "#/components/schemas/Review" } }
        meta: { $ref: "#/components/schemas/PaginationMeta" }
      required: [data, meta]

paths:

  /healthz:
    get:
      tags: [health]
      operationId: getApiHealth
      summary: Report API liveness and dependency state
      description: Database and Redis failures return 503. A storage-only outage is reported as degraded with 200 so the platform does not restart an otherwise live instance.
      security: []
      responses:
        "200":
          description: API is live; all components are up or only storage is degraded
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HealthResponse' }
        "503":
          description: A dependency required for API liveness is down
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HealthResponse' }

  /readyz:
    get:
      tags: [health]
      operationId: getApiReadiness
      summary: Report strict readiness for production traffic
      description: Returns 200 only when database, Redis, and the explicitly configured storage provider are all reachable. Any dependency failure returns 503 and not_ready.
      security: []
      responses:
        "200":
          description: Every configured dependency is ready
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReadinessResponse' }
        "503":
          description: At least one configured dependency is not ready
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReadinessResponse' }

  /realtime/token:
    post:
      tags: [realtime]
      operationId: issueRealtimeToken
      summary: Issue a short-lived Supabase Realtime token for authorized private channels
      description: Verifies the authenticated actor's requested order and restaurant scopes before signing a five-minute Supabase JWT with an explicit private channel allowlist.
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeTokenRequest'
      responses:
        "200":
          description: Supabase token and explicit channel allowlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeTokenEnvelope'
        "401":
          description: Missing, invalid, expired, or inactive user access token
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProblemDetail' }
        "403":
          description: Requested order or restaurant channel is outside the authenticated actor's scope
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProblemDetail' }
        "500":
          description: Supabase realtime signing is not configured
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProblemDetail' }

  /jobs/drain:
    get:
      tags: [jobs]
      operationId: drainPostgresJobsFromCron
      summary: Drain due PostgreSQL outbox jobs from an authenticated recovery invocation
      description: Claims and executes due PostgreSQL outbox jobs up to the bounded limit. This server-to-server route requires the exact CRON_SECRET bearer value.
      security:
        - cronBearer: []
      parameters:
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
      responses:
        "200":
          description: Drain execution statistics
          content:
            application/json:
              schema: { $ref: '#/components/schemas/JobDrainEnvelope' }
        "401":
          description: Missing or invalid CRON_SECRET bearer value
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProblemDetail' }
    post:
      tags: [jobs]
      operationId: drainPostgresJobsFromWorker
      summary: Drain due PostgreSQL outbox jobs from an approved worker invocation
      description: Provides the same bounded drain contract for an approved secure worker call and rejects browser or user access tokens.
      security:
        - cronBearer: []
      parameters:
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
      responses:
        "200":
          description: Drain execution statistics
          content:
            application/json:
              schema: { $ref: '#/components/schemas/JobDrainEnvelope' }
        "401":
          description: Missing or invalid CRON_SECRET bearer value
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProblemDetail' }

  # ═══════════════════════════════════════════════
  # AUTH
  # ═══════════════════════════════════════════════

  /auth/register:
    post:
      tags: [auth]
      summary: Register a new user
      description: Creates a customer account using the public registration contract. Driver, restaurant, and admin accounts must be created through controlled onboarding or invitation flows.
      operationId: auth_register
      x-foo-actor: public
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RegisterRequest" }
      responses:
        "201": { description: "User registered", content: { application/json: { schema: { $ref: "#/components/schemas/AuthResult" } } } }
        "409": { description: "Email already exists", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "422": { description: "Validation error", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /auth/login:
    post:
      tags: [auth]
      summary: Login with email and password
      description: Authenticates a user with email and password and returns access and refresh tokens.
      operationId: auth_login
      x-foo-actor: public
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/LoginRequest" }
      responses:
        "200": { description: "Login successful", content: { application/json: { schema: { $ref: "#/components/schemas/AuthResult" } } } }
        "401": { description: "Invalid credentials", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "423": { description: "Account locked", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "429": { description: "Rate limited", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /auth/refresh:
    post:
      tags: [auth]
      summary: Refresh access token
      description: Exchanges a valid refresh token for a new access token without changing the user locale.
      operationId: auth_refresh
      x-foo-actor: public
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RefreshRequest" }
      responses:
        "200": { description: "Tokens refreshed", content: { application/json: { schema: { $ref: "#/components/schemas/AuthResult" } } } }
        "401": { description: "Invalid or expired refresh token", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /auth/logout:
    post:
      tags: [auth]
      summary: Logout (invalidate refresh token)
      description: Invalidates the caller's refresh token so it can no longer be used for session renewal.
      operationId: auth_logout
      x-foo-actor: user
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/LogoutRequest" }
      responses:
        "200": { description: "Logged out", content: { application/json: { schema: { type: object, properties: { message: { type: string } } } } } }

  /auth/forgot-password:
    post:
      tags: [auth]
      summary: Request password reset email
      description: Starts the password reset flow and always returns a neutral success response to avoid account enumeration.
      operationId: auth_forgotPassword
      x-foo-actor: public
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ForgotPasswordRequest" }
      responses:
        "200": { description: "Reset email sent (always 200 to prevent email enumeration)", content: { application/json: { schema: { type: object, properties: { message: { type: string } } } } } }

  /auth/reset-password:
    post:
      tags: [auth]
      summary: Reset password with token
      description: Applies a password reset token and stores the new password after token validation.
      operationId: auth_resetPassword
      x-foo-actor: public
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ResetPasswordRequest" }
      responses:
        "200": { description: "Password reset successful", content: { application/json: { schema: { type: object, properties: { message: { type: string } } } } } }
        "400": { description: "Invalid or expired token", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /.well-known/jwks.json:
    get:
      tags: [auth]
      summary: JWKS endpoint for Ed25519 public keys
      description: Publishes public signing keys used by clients or services that verify FoodFlow JWTs.
      operationId: auth_jwks
      x-foo-actor: public
      security: []
      responses:
        "200":
          description: JWKS document
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      type: object
                      properties:
                        kty: { type: string }
                        crv: { type: string }
                        x:   { type: string }
                        kid: { type: string }
                        use: { type: string }
                        alg: { type: string }

  # ═══════════════════════════════════════════════
  # USERS
  # ═══════════════════════════════════════════════

  /users/me:
    get:
      tags: [users]
      summary: Get current user profile
      description: Returns the authenticated user's profile fields and preferences.
      operationId: users_getProfile
      x-foo-actor: user
      responses:
        "200": { description: "User profile", content: { application/json: { schema: { $ref: "#/components/schemas/UserProfile" } } } }
        "401": { description: "Unauthenticated", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    patch:
      tags: [users]
      summary: Update current user profile
      description: Updates editable profile fields for the authenticated user.
      operationId: users_updateProfile
      x-foo-actor: user
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateUserRequest" }
      responses:
        "200": { description: "Profile updated", content: { application/json: { schema: { $ref: "#/components/schemas/UserProfile" } } } }
        "401": { description: "Unauthenticated", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "422": { description: "Validation error", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /users/me/avatar:
    post:
      tags: [users]
      summary: Upload avatar image
      description: Uploads and validates an avatar image for the authenticated user.
      operationId: users_uploadAvatar
      x-foo-actor: user
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
              required: [file]
      responses:
        "200": { description: "Avatar uploaded", content: { application/json: { schema: { $ref: "#/components/schemas/AvatarUploadResponse" } } } }
        "400": { description: "Invalid file", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /users/addresses:
    get:
      tags: [users]
      summary: List saved addresses
      description: Lists saved delivery addresses belonging to the authenticated user.
      operationId: users_listAddresses
      x-foo-actor: user
      responses:
        "200": { description: "Address list", content: { application/json: { schema: { type: array, items: { $ref: "#/components/schemas/Address" } } } } }
    post:
      tags: [users]
      summary: Add a new address
      description: Creates a new saved delivery address for the authenticated user.
      operationId: users_createAddress
      x-foo-actor: user
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateAddressRequest" }
      responses:
        "201": { description: "Address created", content: { application/json: { schema: { $ref: "#/components/schemas/Address" } } } }
        "422": { description: "Validation error", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /users/addresses/{addressId}:
    put:
      tags: [users]
      summary: Update an address
      description: Updates one saved delivery address when it belongs to the authenticated user.
      operationId: users_updateAddress
      x-foo-actor: user
      parameters:
        - name: addressId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateAddressRequest" }
      responses:
        "200": { description: "Address updated", content: { application/json: { schema: { $ref: "#/components/schemas/Address" } } } }
        "404": { description: "Address not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    delete:
      tags: [users]
      summary: Delete an address
      description: Deletes one saved delivery address owned by the authenticated user.
      operationId: users_deleteAddress
      x-foo-actor: user
      parameters:
        - name: addressId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Address deleted" }
        "404": { description: "Address not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /users/wallet:
    get:
      tags: [users]
      summary: Get wallet balance and transactions
      description: Returns the authenticated user's wallet balance and recent wallet transactions.
      operationId: users_getWallet
      x-foo-actor: user
      responses:
        "200": { description: "Wallet snapshot", content: { application/json: { schema: { $ref: "#/components/schemas/WalletSnapshot" } } } }

  # ═══════════════════════════════════════════════
  # RESTAURANTS (public discovery)
  # ═══════════════════════════════════════════════

  /restaurants/nearby:
    get:
      tags: [restaurants]
      summary: Find restaurants near a location (PostGIS)
      description: Searches active restaurants near the provided coordinates using PostGIS distance filters.
      operationId: restaurants_nearby
      x-foo-actor: public
      security: []
      parameters:
        - name: lat
          in: query
          required: true
          schema: { type: number }
        - name: lng
          in: query
          required: true
          schema: { type: number }
        - name: radius
          in: query
          schema: { type: integer, default: 5 }
          description: Radius in km
        - name: cuisine
          in: query
          schema: { type: string }
          description: Filter by cuisine type
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Nearby restaurants", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedRestaurants" } } } }

  /restaurants/search:
    get:
      tags: [restaurants]
      summary: Search restaurants by keyword
      description: Searches active restaurants by keyword with pagination for customer discovery.
      operationId: restaurants_search
      x-foo-actor: public
      security: []
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
          description: Search keyword
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Search results", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedRestaurants" } } } }

  /restaurants/{restaurantId}:
    get:
      tags: [restaurants]
      summary: Get restaurant detail
      description: Returns public detail for one active restaurant.
      operationId: restaurants_getDetail
      x-foo-actor: public
      security: []
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Restaurant detail", content: { application/json: { schema: { $ref: "#/components/schemas/RestaurantDetail" } } } }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurants/{restaurantId}/menu:
    get:
      tags: [restaurants]
      summary: Get restaurant menu (categories + items)
      description: Returns visible menu categories and available items for one active restaurant.
      operationId: restaurants_getMenu
      x-foo-actor: public
      security: []
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Restaurant menu", content: { application/json: { schema: { type: object, properties: { categories: { type: array, items: { $ref: "#/components/schemas/MenuCategory" } } } } } } }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurants/{restaurantId}/reviews:
    get:
      tags: [restaurants]
      summary: Get restaurant reviews
      description: Lists public customer reviews for one restaurant with pagination.
      operationId: restaurants_getReviews
      x-foo-actor: public
      security: []
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Restaurant reviews", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedReviews" } } } }

  # ═══════════════════════════════════════════════
  # MENU (restaurant owner)
  # ═══════════════════════════════════════════════

  /restaurant/profile:
    get:
      tags: [restaurant-profile]
      summary: Get restaurant owner profile
      description: Returns the authenticated restaurant tenant profile, opening hours, persisted holiday closures, and membership metadata.
      operationId: restaurant_profile_get
      x-foo-actor: restaurant_owner
      responses:
        "200":
          description: "Restaurant profile"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/RestaurantProfile" }
        "403": { description: "Restaurant profile unavailable", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    patch:
      tags: [restaurant-profile]
      summary: Update restaurant owner profile
      description: Updates editable restaurant profile fields. When `openingHours` or `holidayClosures` are provided, the submitted arrays replace the existing tenant-scoped rows.
      operationId: restaurant_profile_update
      x-foo-actor: restaurant_owner
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateRestaurantProfileRequest" }
      responses:
        "200":
          description: "Updated restaurant profile"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/RestaurantProfile" }
        "400": { description: "Invalid opening hours or duplicate holiday closure date", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "403": { description: "Restaurant profile unavailable", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/profile/upload:
    post:
      tags: [restaurant-profile]
      summary: Upload a restaurant profile image
      description: Uploads a logo or cover image for the authenticated restaurant tenant through the shared storage service.
      operationId: restaurant_profile_uploadImage
      x-foo-actor: restaurant_owner
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file: { type: string, format: binary }
              required: [file]
      responses:
        "201":
          description: "Uploaded image URL"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/ImageUploadResult" }
        "400": { description: "Missing or invalid image", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/reviews:
    get:
      tags: [restaurant-reviews]
      summary: List reviews for the authenticated restaurant
      description: Returns only reviews owned by the authenticated restaurant tenant, including the stable fields consumed by the Restaurant dashboard.
      operationId: restaurantReviews_list
      x-foo-actor: restaurant_owner
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
        - name: rating
          in: query
          schema: { type: integer, minimum: 1, maximum: 5 }
      responses:
        "200":
          description: "Tenant-scoped restaurant reviews"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/RestaurantReviewsPayload" }
        "403": { description: "Restaurant profile unavailable", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/reviews/{id}/reply:
    post:
      tags: [restaurant-reviews]
      summary: Reply to a tenant-owned review
      description: Creates or edits the merchant reply for a review owned by the authenticated restaurant. Existing replies can be edited only during the 24-hour edit window.
      operationId: restaurantReviews_reply
      x-foo-actor: restaurant_owner
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RestaurantReviewReplyRequest" }
      responses:
        "201":
          description: "Review reply saved"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/RestaurantReviewReplyResult" }
        "400": { description: "Reply edit window closed or invalid reply", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "403": { description: "Review belongs to another restaurant tenant", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Review not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/staff:
    get:
      tags: [restaurant-staff]
      summary: List restaurant staff, pending invitations, and shifts
      description: Returns staff resources scoped to the authenticated restaurant tenant.
      operationId: restaurantStaff_list
      x-foo-actor: restaurant_owner
      responses:
        "200": { description: "Restaurant staff overview", content: { application/json: { schema: { $ref: "#/components/schemas/RestaurantStaffOverviewResponse" } } } }
        "403": { description: "Restaurant profile unavailable", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/staff/invite:
    post:
      tags: [restaurant-staff]
      summary: Create pending staff invitations
      description: Creates tenant-scoped invitation records. It does not claim email delivery unless a delivery integration consumes the returned one-time token.
      operationId: restaurantStaff_invite
      x-foo-actor: restaurant_owner
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/InviteRestaurantStaffRequest" }
      responses:
        "201": { description: "Pending invitations created", content: { application/json: { schema: { $ref: "#/components/schemas/InviteRestaurantStaffResponse" } } } }
        "400": { description: "Invalid emails, role, or permissions", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "403": { description: "Staff management permission required", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/staff/{profileId}:
    patch:
      tags: [restaurant-staff]
      summary: Update a restaurant staff member
      description: Updates role, permissions, or active state within the authenticated restaurant tenant. Owner escalation is forbidden.
      operationId: restaurantStaff_update
      x-foo-actor: restaurant_owner
      parameters:
        - name: profileId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateRestaurantStaffRequest" }
      responses:
        "200": { description: "Updated staff member", content: { application/json: { schema: { $ref: "#/components/schemas/RestaurantStaffMemberResponse" } } } }
        "403": { description: "Owner or manager boundary violation", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Staff member not found in tenant", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/staff/shifts:
    post:
      tags: [restaurant-staff]
      summary: Create a staff shift
      description: Creates a non-overlapping shift for an active staff member in the authenticated restaurant tenant.
      operationId: restaurantStaff_createShift
      x-foo-actor: restaurant_owner
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateRestaurantStaffShiftRequest" }
      responses:
        "201": { description: "Shift created", content: { application/json: { schema: { $ref: "#/components/schemas/RestaurantStaffShiftResponse" } } } }
        "403": { description: "Staff management permission required", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Staff member not found in tenant", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "409": { description: "Shift overlaps or ends before it starts", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/staff/shifts/{shiftId}:
    patch:
      tags: [restaurant-staff]
      summary: Update a staff shift
      description: Updates time, note, or status for a shift owned by the authenticated restaurant tenant.
      operationId: restaurantStaff_updateShift
      x-foo-actor: restaurant_owner
      parameters:
        - name: shiftId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateRestaurantStaffShiftRequest" }
      responses:
        "200": { description: "Shift updated", content: { application/json: { schema: { $ref: "#/components/schemas/RestaurantStaffShiftResponse" } } } }
        "404": { description: "Shift not found in tenant", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "409": { description: "Shift overlaps or ends before it starts", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    delete:
      tags: [restaurant-staff]
      summary: Delete a staff shift
      description: Deletes a shift only when it belongs to the authenticated restaurant tenant.
      operationId: restaurantStaff_deleteShift
      x-foo-actor: restaurant_owner
      parameters:
        - name: shiftId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Shift deleted", content: { application/json: { schema: { $ref: "#/components/schemas/DeleteRestaurantStaffShiftResponse" } } } }
        "404": { description: "Shift not found in tenant", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/menu:
    get:
      tags: [menu]
      summary: Get my restaurant's full menu
      description: Returns the authenticated restaurant tenant's menu categories and menu items.
      operationId: menu_getMenu
      x-foo-actor: restaurant_owner
      responses:
        "200": { description: "Full menu", content: { application/json: { schema: { type: object, properties: { categories: { type: array, items: { $ref: "#/components/schemas/MenuCategory" } } } } } } }

  /restaurant/menu/categories:
    post:
      tags: [menu]
      summary: Create a menu category
      description: Creates a menu category owned by the authenticated restaurant tenant.
      operationId: menu_createCategory
      x-foo-actor: restaurant_owner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, minLength: 1, maxLength: 100 }
                sortOrder: { type: integer, default: 0 }
              required: [name]
              example:
                name: "Món chính"
                sortOrder: 1
      responses:
        "201": { description: "Category created", content: { application/json: { schema: { $ref: "#/components/schemas/MenuCategory" } } } }

  /restaurant/menu/categories/{categoryId}:
    patch:
      tags: [menu]
      summary: Update a menu category
      description: Updates category metadata after verifying the category belongs to the authenticated restaurant.
      operationId: menu_updateCategory
      x-foo-actor: restaurant_owner
      parameters:
        - name: categoryId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, minLength: 1, maxLength: 100 }
                sortOrder: { type: integer }
      responses:
        "200": { description: "Category updated" }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    delete:
      tags: [menu]
      summary: Delete a menu category
      description: Deletes a tenant-owned menu category when backend validation allows removal.
      operationId: menu_deleteCategory
      x-foo-actor: restaurant_owner
      parameters:
        - name: categoryId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Category deleted" }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/menu/items:
    post:
      tags: [menu]
      summary: Create a menu item
      description: Creates a menu item, options, and pricing under a tenant-owned category.
      operationId: menu_createItem
      x-foo-actor: restaurant_owner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                categoryId: { type: string, format: uuid }
                name: { type: string, minLength: 1, maxLength: 200 }
                description: { type: string }
                imageUrl: { type: string }
                basePrice: { type: integer, description: "VND" }
                isAvailable: { type: boolean, default: true }
                isPopular: { type: boolean, default: false }
                options:
                  type: array
                  items:
                    type: object
                    properties:
                      name: { type: string }
                      isRequired: { type: boolean, default: false }
                      isMultiple: { type: boolean, default: false }
                      values:
                        type: array
                        items:
                          type: object
                          properties:
                            value: { type: string }
                            priceModifier: { type: integer, description: "VND" }
                          required: [value]
                    required: [name]
              required: [categoryId, name, basePrice]
              example:
                categoryId: "dddddddd-dddd-4ddd-8ddd-dddddddddddd"
                name: "Bún bò Huế đặc biệt"
                description: "Bún bò Huế chuẩn vị, cay nồng"
                basePrice: 55000
                options:
                  - name: "Size"
                    values:
                      - { value: "Vừa", priceModifier: 0 }
                      - { value: "Lớn", priceModifier: 20000 }
      responses:
        "201": { description: "Menu item created", content: { application/json: { schema: { $ref: "#/components/schemas/MenuItem" } } } }
        "422": { description: "Validation error", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/menu/items/{itemId}:
    patch:
      tags: [menu]
      summary: Update a menu item
      description: Updates a tenant-owned menu item and rejects changes for items outside the restaurant.
      operationId: menu_updateItem
      x-foo-actor: restaurant_owner
      parameters:
        - name: itemId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, minLength: 1, maxLength: 200 }
                description: { type: string }
                imageUrl: { type: string }
                basePrice: { type: integer, description: "VND" }
                isAvailable: { type: boolean }
                isPopular: { type: boolean }
                categoryId: { type: string, format: uuid }
      responses:
        "200": { description: "Menu item updated" }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    delete:
      tags: [menu]
      summary: Delete a menu item
      description: Deletes a tenant-owned menu item when backend validation allows removal.
      operationId: menu_deleteItem
      x-foo-actor: restaurant_owner
      parameters:
        - name: itemId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Menu item deleted" }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/menu/items/{itemId}/toggle:
    patch:
      tags: [menu]
      summary: Toggle item availability
      description: Toggles availability for a tenant-owned menu item without changing other menu fields.
      operationId: menu_toggleItem
      x-foo-actor: restaurant_owner
      parameters:
        - name: itemId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Item toggled" }

  # ═══════════════════════════════════════════════
  # ORDERS
  # ═══════════════════════════════════════════════

  /orders:
    post:
      tags: [orders]
      summary: Place a new order
      description: Places an order from the authenticated customer's current cart using an idempotency key for duplicate protection.
      operationId: orders_place
      x-foo-actor: user
      parameters:
        - $ref: "#/components/parameters/IdempotencyKeyHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PlaceOrderRequest" }
      responses:
        "201": { description: "Order placed", content: { application/json: { schema: { $ref: "#/components/schemas/OrderDetail" } } } }
        "400": { description: "Cart empty / restaurant closed / below min order", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "409": { description: "Duplicate (idempotency key)", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    get:
      tags: [orders]
      summary: Get customer's order history
      description: Lists orders owned by the authenticated customer with optional status filtering and pagination.
      operationId: orders_getMyOrders
      x-foo-actor: user
      parameters:
        - name: status
          in: query
          schema: { type: string }
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "My orders", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedOrders" } } } }

  /orders/delivery-pricing:
    get:
      tags: [orders]
      summary: Get configured delivery pricing
      description: Returns the backend-configured delivery base fee for checkout preview UI. Clients must use this endpoint instead of local free-delivery thresholds or hardcoded fees; order placement remains authoritative.
      operationId: orders_getDeliveryPricing
      x-foo-actor: user
      responses:
        "200": { description: "Configured delivery pricing", content: { application/json: { schema: { $ref: "#/components/schemas/DeliveryPricingResponse" } } } }
        "503": { description: "Delivery pricing not configured", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /orders/{orderId}:
    get:
      tags: [orders]
      summary: Get order detail
      description: Returns one order when it belongs to the authenticated customer.
      operationId: orders_getDetail
      x-foo-actor: user
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Order detail", content: { application/json: { schema: { $ref: "#/components/schemas/OrderDetail" } } } }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /orders/{orderId}/tracking:
    get:
      tags: [orders]
      summary: Get the current order tracking snapshot
      description: Returns an accessible order's status plus real assigned-driver GPS, cached or persisted ETA, and route data. Customers, assigned drivers, active restaurant staff for the order tenant, and admins may read the snapshot. Telemetry fields remain null until recorded and are never replaced with synthetic coordinates.
      operationId: orders_getTracking
      x-foo-actor: user
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Current tracking snapshot", content: { application/json: { schema: { $ref: "#/components/schemas/OrderTrackingResponse" } } } }
        "401": { description: "Authentication required", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "403": { description: "Order participant role required", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Order not found for this actor", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /orders/{orderId}/cancel:
    post:
      tags: [orders]
      summary: Cancel an order
      description: Cancels a customer-owned order only when the current order status still allows cancellation.
      operationId: orders_cancel
      x-foo-actor: user
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CancelOrderRequest" }
      responses:
        "200": { description: "Order cancelled", content: { application/json: { schema: { $ref: "#/components/schemas/OrderDetail" } } } }
        "400": { description: "Order cannot be cancelled at this stage", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /orders/{orderId}/review:
    post:
      tags: [orders]
      summary: Submit a review for a completed order
      description: Creates a review for a completed customer order that has not already been reviewed.
      operationId: orders_submitReview
      x-foo-actor: user
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateReviewRequest" }
      responses:
        "200": { description: "Review submitted", content: { application/json: { schema: { $ref: "#/components/schemas/Review" } } } }
        "400": { description: "Order not completed or already reviewed", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/orders:
    get:
      tags: [orders]
      summary: Get restaurant's incoming orders
      description: Lists orders scoped to the authenticated restaurant, optionally filtered by order status.
      operationId: orders_getRestaurantOrders
      x-foo-actor: restaurant_owner
      parameters:
        - name: status
          in: query
          schema: { type: string }
      responses:
        "200": { description: "Restaurant orders", content: { application/json: { schema: { type: array, items: { $ref: "#/components/schemas/OrderDetail" } } } } }

  /restaurant/orders/{orderId}/status:
    patch:
      tags: [orders]
      summary: Update order status (restaurant)
      description: Applies a validated restaurant-side order status transition for an order owned by the current tenant.
      operationId: orders_updateRestaurantStatus
      x-foo-actor: restaurant_owner
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateOrderStatusRequest" }
      responses:
        "200": { description: "Status updated", content: { application/json: { schema: { $ref: "#/components/schemas/OrderDetail" } } } }
        "400": { description: "Invalid transition", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/orders/{orderId}/messages:
    get:
      tags: [orders]
      summary: Get restaurant-driver order chat messages
      description: Returns persisted chat messages after verifying the order belongs to the current restaurant.
      operationId: orders_getRestaurantOrderMessages
      x-foo-actor: restaurant_owner
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: "Order chat messages"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/RestaurantOrderChatMessagesPayload" }
        "404": { description: "Order not found for restaurant", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    post:
      tags: [orders]
      summary: Create a restaurant-driver order chat message
      description: Persists a restaurant message and broadcasts `/events` `order:message_created` to subscribers. Returns a problem detail when no driver is assigned.
      operationId: orders_createRestaurantOrderMessage
      x-foo-actor: restaurant_owner
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateRestaurantOrderChatMessageRequest" }
      responses:
        "201":
          description: "Message created"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/RestaurantOrderChatMessage" }
        "400": { description: "Driver not assigned or invalid content", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Order not found for restaurant", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /restaurant/insights:
    get:
      tags: [analytics]
      summary: Get restaurant menu and operations insights
      description: Returns tenant-scoped insights calculated from real completed orders and menu item state. Suggestion copy is represented by i18n keys plus params so web clients render the active locale.
      operationId: restaurant_getInsights
      x-foo-actor: restaurant_owner
      responses:
        "200":
          description: Tenant-scoped restaurant insights
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RestaurantInsightsEnvelope" }
        "403":
          description: The authenticated user cannot access a restaurant tenant
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProblemDetail" }

  /restaurant/promotions:
    get:
      tags: [promotions]
      summary: List restaurant promotions with aggregate analytics
      description: Returns tenant-scoped promotions plus aggregate analytics calculated from confirmed promotion usages and order totals.
      operationId: restaurant_listPromotions
      x-foo-actor: restaurant_owner
      parameters:
        - name: status
          in: query
          schema: { type: string, enum: [draft, scheduled, active, paused, expired, archived] }
        - name: search
          in: query
          schema: { type: string }
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        "200":
          description: Tenant-scoped promotions and aggregate analytics from confirmed redemptions
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RestaurantPromotionListEnvelope" }

  /restaurant/promotions/{promotionId}:
    get:
      tags: [promotions]
      summary: Get restaurant promotion detail with real analytics
      description: Returns one tenant-scoped promotion plus usage, attributed revenue, discount cost, redemption rate, ROI, and daily usage timeline.
      operationId: restaurant_getPromotion
      x-foo-actor: restaurant_owner
      parameters:
        - name: promotionId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Tenant-scoped promotion detail and analytics from confirmed redemptions
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RestaurantPromotionDetailEnvelope" }
        "404":
          description: Promotion not found for the authenticated restaurant
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProblemDetail" }

  /restaurant/promotions/targeting-preview:
    get:
      tags: [promotions]
      summary: Preview a promotion audience from successful restaurant orders
      description: Calculates audience reach from tenant-scoped successful order history without using hard-coded reach estimates.
      operationId: restaurant_previewPromotionTargeting
      x-foo-actor: restaurant_owner
      parameters:
        - name: audience
          in: query
          required: true
          schema: { type: string, enum: [all, new, vip, lapsed, segment, order_history] }
        - name: minOrderCount
          in: query
          schema: { type: integer, minimum: 1 }
        - name: lastOrderWithinDays
          in: query
          schema: { type: integer, minimum: 1, maximum: 365, default: 30 }
        - name: segmentId
          in: query
          description: Reserved for persisted customer segments; unsupported segments return a problem detail.
          schema: { type: string }
      responses:
        "200":
          description: Audience reach calculated from successful order history
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PromotionTargetingPreviewEnvelope" }
        "400":
          description: Invalid or unsupported targeting parameters
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProblemDetail" }

  /restaurant/promotions/{promotionId}/broadcast:
    post:
      tags: [promotions]
      summary: Broadcast a promotion to its tenant-scoped target audience
      description: Resolves the promotion's tenant-scoped audience and creates notifications for active customers.
      operationId: restaurant_broadcastPromotion
      x-foo-actor: restaurant_owner
      parameters:
        - name: promotionId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Broadcast result for active target customers
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PromotionBroadcastEnvelope" }
        "400":
          description: The promotion target is not currently supported
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProblemDetail" }
        "404":
          description: Promotion not found for the authenticated restaurant
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProblemDetail" }

  /driver/orders/{orderId}/status:
    patch:
      tags: [orders]
      summary: Update order status (driver)
      description: Applies a validated driver-side order status transition for an assigned delivery order.
      operationId: orders_updateDriverStatus
      x-foo-actor: driver
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateOrderStatusRequest" }
      responses:
        "200": { description: "Status updated", content: { application/json: { schema: { $ref: "#/components/schemas/OrderDetail" } } } }
        "400": { description: "Invalid transition", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  # ═══════════════════════════════════════════════
  # DRIVERS
  # ═══════════════════════════════════════════════

  /driver/online:
    post:
      tags: [drivers]
      summary: Go online (start accepting orders)
      description: Marks the authenticated driver online and records their latest service location.
      operationId: drivers_goOnline
      x-foo-actor: driver
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/GoOnlineRequest" }
      responses:
        "200": { description: "Now online", content: { application/json: { schema: { type: object, properties: { isOnline: { type: boolean }, lat: { type: number }, lng: { type: number } } } } } }

  /driver/offline:
    post:
      tags: [drivers]
      summary: Go offline
      description: Marks the authenticated driver offline so dispatch no longer offers new orders.
      operationId: drivers_goOffline
      x-foo-actor: driver
      responses:
        "200": { description: "Now offline", content: { application/json: { schema: { type: object, properties: { isOnline: { type: boolean } } } } } }

  /driver/location:
    post:
      tags: [drivers]
      summary: Submit a live driver GPS sample
      description: Reuses the authenticated tracking pipeline and rejects stale, future, out-of-bounds, implausibly fast, or teleporting samples before updating Redis/PostGIS and publishing authorized realtime order/admin events.
      operationId: tracking_updateDriverLocation
      x-foo-actor: driver
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DriverLocationUpdateRequest" }
      responses:
        "201":
          description: Location sample accepted
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DriverLocationUpdateResponse" }
        "422":
          description: Location rejected as stale, future, invalid, outside the service area, or physically implausible
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProblemDetail" }

  /driver/dispatch/offers/{orderId}/respond:
    post:
      tags: [drivers]
      summary: Resolve a short-lived dispatch offer
      description: Accepts or rejects the authenticated driver's persisted offer exactly once. The API stores only a SHA-256 token hash, enforces expiry and driver ownership, atomically claims assignment, and never relies on an in-memory WebSocket callback.
      operationId: dispatch_respondToOffer
      x-foo-actor: driver
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DispatchOfferResponseRequest" }
      responses:
        "200":
          description: Offer resolved
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DispatchOfferResolution" }
        "409":
          description: Offer token is invalid, expired, already resolved, or the order/driver can no longer be assigned
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProblemDetail" }

  /driver/orders/active:
    get:
      tags: [drivers]
      summary: Get authenticated driver's active order
      description: Returns the newest active order assigned to the authenticated driver, or `null` when no active assignment exists. Order and address coordinates come from PostGIS; missing location rows return `404 ORDER_LOCATION_NOT_FOUND`.
      operationId: drivers_getActiveOrder
      x-foo-actor: driver
      responses:
        "200":
          description: Active order or null
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/DriverOrder"
                  - type: "null"
        "404": { description: "Order location not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/orders/history:
    get:
      tags: [drivers]
      summary: List authenticated driver's completed order history
      description: Returns terminal orders assigned to the authenticated driver. Empty arrays are valid; API failures must not be treated as empty history by clients.
      operationId: drivers_getOrderHistory
      x-foo-actor: driver
      parameters:
        - name: fromDate
          in: query
          schema: { type: string, format: date-time }
        - name: toDate
          in: query
          schema: { type: string, format: date-time }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 50, default: 20 }
      responses:
        "200":
          description: Driver order history
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/DriverOrder" }
        "404": { description: "Order location not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/bank-accounts:
    get:
      tags: [drivers]
      summary: List driver bank accounts
      description: Lists payout bank accounts owned by the authenticated driver. Empty arrays are valid.
      operationId: drivers_listBankAccounts
      x-foo-actor: driver
      responses:
        "200": { description: "Driver bank accounts", content: { application/json: { schema: { $ref: "#/components/schemas/DriverBankAccountsResponse" } } } }
    post:
      tags: [drivers]
      summary: Create driver bank account
      description: Adds a payout bank account for the authenticated driver. The first account becomes default.
      operationId: drivers_createBankAccount
      x-foo-actor: driver
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateDriverBankAccountRequest" }
      responses:
        "201": { description: "Driver bank account created", content: { application/json: { schema: { $ref: "#/components/schemas/DriverBankAccountResponse" } } } }
        "400": { description: "Duplicate or invalid bank account", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Driver profile not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/bank-accounts/{accountId}/default:
    patch:
      tags: [drivers]
      summary: Set default driver bank account
      description: Marks one owned payout bank account as default and clears the previous default.
      operationId: drivers_setDefaultBankAccount
      x-foo-actor: driver
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Default bank account", content: { application/json: { schema: { $ref: "#/components/schemas/DriverBankAccountResponse" } } } }
        "404": { description: "Bank account not found for driver", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/bank-accounts/{accountId}:
    delete:
      tags: [drivers]
      summary: Delete driver bank account
      description: Deletes one owned payout bank account. If the deleted account was default, the newest remaining account becomes default.
      operationId: drivers_deleteBankAccount
      x-foo-actor: driver
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Deleted", content: { application/json: { schema: { $ref: "#/components/schemas/DeleteDriverBankAccountResponse" } } } }
        "404": { description: "Bank account not found for driver", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/trips/{tripId}/tip-report:
    post:
      tags: [drivers]
      summary: Report cash tip for a completed trip
      description: Stores a driver-reported cash tip for audit/reconciliation only. This does not automatically change payout ledger settlement.
      operationId: drivers_reportTripCashTip
      x-foo-actor: driver
      parameters:
        - name: tripId
          in: path
          required: true
          schema: { type: string }
          description: Order UUID or order code.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DriverTipReportRequest" }
      responses:
        "201": { description: "Tip report saved", content: { application/json: { schema: { $ref: "#/components/schemas/DriverTipReportResponse" } } } }
        "400": { description: "Trip not completed or invalid amount", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Trip not found for driver", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/earnings:
    get:
      tags: [drivers]
      summary: Get driver payout ledger earnings
      description: Returns payout ledger totals and entries for the authenticated driver over the requested `today`, `week`, or `month` period. Empty `entries` means no settled driver payout rows exist for the period.
      operationId: drivers_getEarnings
      x-foo-actor: driver
      parameters:
        - name: period
          in: query
          schema: { type: string, enum: [today, week, month], default: today }
      responses:
        "200": { description: "Earnings", content: { application/json: { schema: { $ref: "#/components/schemas/DriverEarnings" } } } }
        "400": { description: "Invalid earnings period", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/earnings/summary:
    get:
      tags: [drivers]
      summary: Get chart-ready driver earnings summary
      description: Returns continuous day buckets from driver payout ledger data. Days without trips are returned with zero amounts.
      operationId: drivers_getEarningsSummary
      x-foo-actor: driver
      parameters:
        - name: period
          in: query
          schema: { type: string, enum: [7d, 30d, 90d], default: 7d }
      responses:
        "200": { description: "Earnings summary", content: { application/json: { schema: { $ref: "#/components/schemas/DriverEarningsSummaryResponse" } } } }

  /driver/ratings:
    get:
      tags: [drivers]
      summary: Get driver rating history
      description: Returns visible delivery reviews for the authenticated driver and derives rating stats from Review rows. Empty arrays are valid; no runtime sample reviews are generated.
      operationId: drivers_getRatings
      x-foo-actor: driver
      parameters:
        - name: star
          in: query
          schema: { type: integer, minimum: 1, maximum: 5 }
      responses:
        "200": { description: "Rating history", content: { application/json: { schema: { $ref: "#/components/schemas/DriverRatingsResponse" } } } }

  /driver/trips/{tripId}/route:
    get:
      tags: [drivers]
      summary: Get driver trip route
      description: Returns real telemetry or persisted route geometry for a trip owned by the authenticated driver. Empty arrays are valid when no route data has been recorded; no runtime sample route is generated.
      operationId: drivers_getTripRoute
      x-foo-actor: driver
      parameters:
        - name: tripId
          in: path
          required: true
          schema: { type: string }
          description: Order UUID or order code.
      responses:
        "200": { description: "Trip route", content: { application/json: { schema: { $ref: "#/components/schemas/DriverTripRouteResponse" } } } }
        "404": { description: "Trip not found for driver", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/heatmap:
    get:
      tags: [drivers]
      summary: Get nearby driver demand heatmap
      description: Returns real order-density points near the authenticated driver's current map center. Empty arrays are valid; no runtime sample data is generated.
      operationId: drivers_getHeatmap
      x-foo-actor: driver
      parameters:
        - name: lat
          in: query
          required: true
          schema: { type: number, minimum: -90, maximum: 90 }
        - name: lng
          in: query
          required: true
          schema: { type: number, minimum: -180, maximum: 180 }
        - name: radius
          in: query
          schema: { type: number, minimum: 0.1, maximum: 25, default: 5 }
        - name: window
          in: query
          schema: { type: string, enum: [now, 1h, 3h, today], default: now }
      responses:
        "200": { description: "Demand points", content: { application/json: { schema: { $ref: "#/components/schemas/DriverHeatmapResponse" } } } }
        "400": { description: "Invalid coordinates", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/incentives:
    get:
      tags: [drivers]
      summary: Get driver incentives
      description: Returns active and completed driver incentive campaigns from persisted driver incentive campaign records. Progress is computed from the authenticated driver's delivered tasks in each campaign window; empty arrays mean no persisted campaigns match, not fabricated sample data.
      operationId: drivers_getIncentives
      x-foo-actor: driver
      responses:
        "200": { description: "Driver incentives", content: { application/json: { schema: { $ref: "#/components/schemas/DriverIncentivesResponse" } } } }

  /driver/trips:
    get:
      tags: [drivers]
      summary: Get driver trip history
      description: Lists completed and historical trips for the authenticated driver with optional date filters.
      operationId: drivers_getTrips
      x-foo-actor: driver
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
        - name: fromDate
          in: query
          schema: { type: string, format: date-time }
        - name: toDate
          in: query
          schema: { type: string, format: date-time }
      responses:
        "200": { description: "Trip history", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedDriverTrips" } } } }

  /driver/onboarding/agreement:
    post:
      tags: [drivers]
      summary: Accept driver onboarding terms
      description: Persists the authenticated driver's terms version and acceptance timestamp before KYC submission.
      operationId: drivers_acceptOnboardingAgreement
      x-foo-actor: driver
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AcceptDriverAgreementRequest" }
      responses:
        "201": { description: "Agreement accepted", content: { application/json: { schema: { $ref: "#/components/schemas/DriverAgreementAcceptanceResponse" } } } }
        "400": { description: "Invalid terms version", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Driver profile not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/kyc/uploads:
    post:
      tags: [drivers]
      summary: Create a private KYC upload grant
      description: Validates ownership prerequisites and returns a provider-signed upload capability for exactly one private driver document. The grant never returns a public asset URL.
      operationId: drivers_createKycUploadGrant
      x-foo-actor: driver
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DriverKycUploadRequest" }
      responses:
        "201": { description: "Private upload grant", content: { application/json: { schema: { $ref: "#/components/schemas/DriverKycUploadGrant" } } } }
        "400": { description: "Terms, file metadata, retry eligibility, or private storage configuration is invalid", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "409": { description: "Driver is already verified or already has a pending submission", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Driver profile not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "503": { description: "Private storage signing is temporarily unavailable", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/kyc:
    post:
      tags: [drivers]
      summary: Submit KYC documents
      description: Validates four authenticated-driver-owned private objects, image metadata and signatures, then atomically creates one pending KYC submission and updates vehicle information. Public URLs and duplicate object keys are rejected.
      operationId: drivers_submitKyc
      x-foo-actor: driver
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SubmitDriverKycRequest" }
      responses:
        "201": { description: "KYC submitted", content: { application/json: { schema: { $ref: "#/components/schemas/DriverKycSubmissionReceipt" } } } }
        "400": { description: "Terms, identifiers, object ownership, image metadata, or signatures are invalid", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "409": { description: "Driver is verified, has a pending submission, or exhausted automatic retries", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Driver profile or private document not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/kyc/status:
    get:
      tags: [drivers]
      summary: Check KYC verification status
      description: Returns the authenticated driver's current KYC verification status and submitted vehicle details.
      operationId: drivers_kycStatus
      x-foo-actor: driver
      responses:
        "200": { description: "KYC status", content: { application/json: { schema: { $ref: "#/components/schemas/DriverKycStatusResponse" } } } }
        "404": { description: "Driver profile not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /driver/withdrawals:
    post:
      tags: [drivers]
      summary: Request earnings withdrawal
      description: Creates a withdrawal request against the authenticated driver's available earnings balance.
      operationId: drivers_requestWithdrawal
      x-foo-actor: driver
      parameters:
        - $ref: "#/components/parameters/IdempotencyKeyHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DriverWithdrawalRequest" }
      responses:
        "201": { description: "Withdrawal requested", content: { application/json: { schema: { type: object, properties: { withdrawalId: { type: string, format: uuid }, amount: { type: integer }, status: { type: string }, createdAt: { type: string, format: date-time } } } } } }
        "400": { description: "Insufficient balance", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    get:
      tags: [drivers]
      summary: Get withdrawal history
      description: Lists withdrawal requests created by the authenticated driver.
      operationId: drivers_getWithdrawals
      x-foo-actor: driver
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Withdrawal history", content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { type: object, properties: { id: { type: string, format: uuid }, amount: { type: integer }, bankCode: { type: string }, accountNumber: { type: string }, status: { type: string, enum: [pending, processing, completed, rejected] }, createdAt: { type: string, format: date-time } } } }, meta: { $ref: "#/components/schemas/PaginationMeta" } } } } } }

  # ═══════════════════════════════════════════════
  # PAYMENTS
  # ═══════════════════════════════════════════════

  /payments/intents:
    get:
      tags: [payments]
      summary: List payment intents (admin)
      description: Lists payment intents for admin review with optional status filtering and pagination.
      operationId: payments_listIntents
      x-foo-actor: admin
      parameters:
        - name: status
          in: query
          schema: { type: string, enum: [pending, completed, failed, refunded] }
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Payment intents", content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: "#/components/schemas/PaymentIntent" } }, meta: { $ref: "#/components/schemas/PaginationMeta" } } } } } }

  /payments/intents/{intentId}/refund:
    post:
      tags: [payments]
      summary: Refund a payment
      description: Creates a refund for one payment intent after validating refund eligibility and amount.
      operationId: payments_refund
      x-foo-actor: admin
      parameters:
        - name: intentId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason: { type: string }
                amount: { type: integer, description: "VND. Defaults to full amount" }
      responses:
        "200": { description: "Refunded", content: { application/json: { schema: { $ref: "#/components/schemas/PaymentIntent" } } } }
        "400": { description: "Already refunded / invalid", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  # ═══════════════════════════════════════════════
  # WEBHOOKS
  # ═══════════════════════════════════════════════

  /webhooks/sepay/payment-success:
    post:
      tags: [payments]
      summary: SePay payment success webhook (inbound HMAC verified)
      description: Processes an inbound SePay payment-success webhook after HMAC signature verification.
      operationId: webhooks_sepayPaymentSuccess
      x-foo-actor: service
      security: []
      parameters:
        - name: x-sepay-signature
          in: header
          required: true
          schema: { type: string }
          description: HMAC-SHA256 signature in `sha256={hex}` format
        - name: x-sepay-timestamp
          in: header
          required: true
          schema: { type: string, pattern: "^[0-9]{10}$" }
          description: Unix timestamp included in the signed `{timestamp}.{raw_body}` message
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SepayWebhookPayload" }
      responses:
        "200":
          description: "Accepted; exact response required by SePay. Non-payable signed transfers are durably audited as ignored or manual review."
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [success]
                properties:
                  success: { type: boolean, const: true }
              example: { success: true }
        "400": { description: "Invalid/stale signature or malformed payload", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "503": { description: "A concurrent receipt is still processing or a durable claim could not be acquired; SePay should retry", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  # ═══════════════════════════════════════════════
  # PROMOTIONS
  # ═══════════════════════════════════════════════

  /promotions/available:
    get:
      tags: [promotions]
      summary: List promotions available to the authenticated customer
      description: Returns active, time-valid promotions filtered by usage limit, first-order rules, and the authenticated customer's per-user redemption count.
      operationId: promotions_listAvailable
      x-foo-actor: user
      responses:
        "200":
          description: Customer-scoped available promotions
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/CustomerPromotion" }

  /promotions/my:
    get:
      tags: [promotions]
      summary: List promotions used by the authenticated customer
      description: Returns a deduplicated promotion redemption history scoped to the authenticated customer.
      operationId: promotions_listMine
      x-foo-actor: user
      responses:
        "200":
          description: Customer-scoped used promotion history
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/CustomerPromotion" }

  /promotions/validate:
    post:
      tags: [promotions]
      summary: Validate a promotion code
      description: Validates whether a promotion code can apply to the authenticated customer's order context.
      operationId: promotions_validate
      x-foo-actor: user
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PromotionValidateRequest" }
      responses:
        "200": { description: "Validation result", content: { application/json: { schema: { $ref: "#/components/schemas/PromotionValidateResult" } } } }
        "404": { description: "Code not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /promotions/{promotionCode}:
    get:
      tags: [promotions]
      summary: Get promotion by code
      description: Returns a promotion by code when it is visible and accessible to the authenticated user.
      operationId: promotions_getByCode
      x-foo-actor: user
      parameters:
        - name: promotionCode
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: "Promotion detail", content: { application/json: { schema: { $ref: "#/components/schemas/Promotion" } } } }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  # ═══════════════════════════════════════════════
  # NOTIFICATIONS
  # ═══════════════════════════════════════════════

  /notifications:
    get:
      tags: [notifications]
      summary: Get user notifications
      description: Lists notifications addressed to the authenticated user with pagination.
      operationId: notifications_list
      x-foo-actor: user
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Notifications", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedNotifications" } } } }

  /notifications/{notificationId}/read:
    patch:
      tags: [notifications]
      summary: Mark a notification as read
      description: Marks one notification as read when it belongs to the authenticated user.
      operationId: notifications_markRead
      x-foo-actor: user
      parameters:
        - name: notificationId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Marked as read" }

  /notifications/read-all:
    patch:
      tags: [notifications]
      summary: Mark all notifications as read
      description: Marks every unread notification for the authenticated user as read.
      operationId: notifications_markAllRead
      x-foo-actor: user
      responses:
        "200": { description: "All marked as read" }

  /notifications/fcm-token:
    post:
      tags: [notifications]
      summary: Register FCM push token
      description: >-
        Registers or updates an FCM push token for the authenticated user's
        device. New clients must send registrationId; the legacy body is a
        temporary rolling-upgrade adapter.
      operationId: notifications_registerFcmToken
      x-foo-actor: user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/RegisterFcmTokenRequest"
                - $ref: "#/components/schemas/LegacyRegisterFcmTokenRequest"
      responses:
        "201": { description: "Token registered" }
        "400": { description: "Invalid token, platform, or device ID" }

    delete:
      tags: [notifications]
      summary: Unregister FCM push token
      description: >-
        Idempotently revokes one device registration by its opaque token and
        registrationId capability. Authentication is not required so a device
        can retry cleanup after local logout or session expiry; the capability
        can revoke only that exact registration.
      operationId: notifications_unregisterFcmToken
      x-foo-actor: public
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UnregisterFcmTokenRequest" }
      responses:
        "200": { description: "Token unregistered" }
        "400": { description: "Invalid token" }
        "429": { description: "Cleanup rate limit exceeded" }

  /notifications/fcm-token/{token}:
    delete:
      deprecated: true
      tags: [notifications]
      summary: Unregister an FCM token (legacy authenticated client)
      description: >-
        Temporary rolling-upgrade route for installed clients that do not yet
        persist a registrationId. New clients use DELETE /notifications/fcm-token.
      operationId: notifications_unregisterLegacyFcmToken
      x-foo-actor: user
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string, minLength: 20, maxLength: 500 }
      responses:
        "200": { description: "Token unregistered" }
        "400": { description: "Invalid token" }

  # ═══════════════════════════════════════════════
  # SUPPORT (admin)
  # ═══════════════════════════════════════════════

  /support/tickets:
    post:
      tags: [support]
      summary: Create a support ticket (user)
      description: Creates a customer support ticket for the authenticated user.
      operationId: support_createTicket
      x-foo-actor: user
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateTicketRequest" }
      responses:
        "201": { description: "Ticket created", content: { application/json: { schema: { $ref: "#/components/schemas/SupportTicket" } } } }

  /support/tickets/{ticketId}:
    get:
      tags: [support]
      summary: Get ticket detail
      description: Returns one support ticket when it belongs to the authenticated user.
      operationId: support_getTicket
      x-foo-actor: user
      parameters:
        - name: ticketId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Ticket detail", content: { application/json: { schema: { $ref: "#/components/schemas/SupportTicket" } } } }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /support/tickets/{ticketId}/replies:
    post:
      tags: [support]
      summary: Add reply to a ticket
      description: Adds a user reply to an existing support ticket owned by the authenticated user.
      operationId: support_addReply
      x-foo-actor: user
      parameters:
        - name: ticketId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateReplyRequest" }
      responses:
        "201": { description: "Reply added", content: { application/json: { schema: { $ref: "#/components/schemas/TicketReply" } } } }

  /support/tickets/{ticketId}/csat:
    post:
      tags: [support]
      summary: Submit CSAT (customer satisfaction) score
      description: Records a customer satisfaction score for a resolved support ticket.
      operationId: support_submitCsat
      x-foo-actor: user
      parameters:
        - name: ticketId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SubmitCsatRequest" }
      responses:
        "200": { description: "CSAT submitted" }
        "400": { description: "Ticket not resolved", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/support-tickets:
    get:
      tags: [support]
      summary: List support tickets (admin)
      description: Lists support tickets with admin-only filters and pagination for queue management.
      operationId: support_adminListTickets
      x-foo-actor: admin
      parameters:
        - name: status
          in: query
          schema: { type: string, enum: [open, in_progress, resolved, closed] }
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Tickets", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedSupportTickets" } } } }

  /admin/support-tickets/{ticketId}:
    get:
      tags: [support]
      summary: Get one support ticket
      description: Returns one support ticket with user, assigned admin, order, messages, CSAT, and computed SLA deadline.
      operationId: support_adminGetTicket
      x-foo-actor: admin
      parameters:
        - name: ticketId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Support ticket", content: { application/json: { schema: { $ref: "#/components/schemas/SupportTicket" } } } }
        "404": { description: "Support ticket not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    patch:
      tags: [support]
      summary: Update ticket (assign, change status, resolve) -- admin
      description: Applies an admin ticket update such as assignment, status change, priority change, or resolution metadata.
      operationId: support_adminUpdateTicket
      x-foo-actor: admin
      parameters:
        - name: ticketId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateTicketRequest" }
      responses:
        "200": { description: "Ticket updated", content: { application/json: { schema: { $ref: "#/components/schemas/SupportTicket" } } } }

  /admin/support-tickets/{ticketId}/messages:
    get:
      tags: [support]
      summary: Get support ticket messages
      description: Returns real persisted support ticket messages in chronological order.
      operationId: support_adminGetMessages
      x-foo-actor: admin
      parameters:
        - name: ticketId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Ticket messages", content: { application/json: { schema: { $ref: "#/components/schemas/SupportMessagesPayload" } } } }
        "404": { description: "Support ticket not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/support-tickets/{ticketId}/replies:
    post:
      tags: [support]
      summary: Add a public support reply
      description: Persists a public admin reply, moves the ticket into progress when applicable, and creates a user notification.
      operationId: support_adminReply
      x-foo-actor: admin
      parameters:
        - name: ticketId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SupportMessageRequest" }
      responses:
        "201": { description: "Reply created", content: { application/json: { schema: { $ref: "#/components/schemas/TicketReply" } } } }
        "404": { description: "Support ticket not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/support-tickets/bulk:
    post:
      tags: [support]
      summary: Bulk action on tickets
      description: Applies one admin action to multiple support tickets after validating the selected ticket IDs.
      operationId: support_bulkAction
      x-foo-actor: admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids: { type: array, items: { type: string, format: uuid } }
                action: { type: string, enum: [assign, status, priority, tag] }
                value: { type: string }
              required: [ids, action, value]
              example:
                ids: ["aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "abababab-abab-4bab-8bab-abababababab"]
                action: "status"
                value: "resolved"
      responses:
        "200": { description: "Bulk action executed", content: { application/json: { schema: { type: object, properties: { updated: { type: integer } }, required: [updated] } } } }

  /admin/support-agents:
    get:
      tags: [support]
      summary: List active admin support agents
      description: Returns active admin users available for ticket assignment.
      operationId: support_adminListAgents
      x-foo-actor: admin
      responses:
        "200": { description: "Support agents", content: { application/json: { schema: { type: array, items: { $ref: "#/components/schemas/SupportAgent" } } } } }

  # ═══════════════════════════════════════════════
  # AUDIT (admin)
  # ═══════════════════════════════════════════════

  /admin/audit-logs:
    get:
      tags: [audit]
      summary: List audit logs
      description: Searches audit logs with pagination and filters for actor, action, and timestamp range.
      operationId: audit_list
      x-foo-actor: admin
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
        - { name: actor, in: query, schema: { type: string }, description: "Admin UUID, email, or name" }
        - { name: action, in: query, schema: { type: string } }
        - { name: dateFrom, in: query, schema: { type: string, format: date-time } }
        - { name: dateTo, in: query, schema: { type: string, format: date-time } }
      responses:
        "200": { description: "Audit logs", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedAuditLogs" } } } }

  /admin/audit-logs/export:
    get:
      tags: [audit]
      summary: Export filtered audit logs as CSV
      description: Streams a CSV export of audit logs matching the same filters as the audit list endpoint.
      operationId: audit_export
      x-foo-actor: admin
      parameters:
        - { name: actor, in: query, schema: { type: string }, description: "Admin UUID, email, or name" }
        - { name: action, in: query, schema: { type: string } }
        - { name: dateFrom, in: query, schema: { type: string, format: date-time } }
        - { name: dateTo, in: query, schema: { type: string, format: date-time } }
      responses:
        "200": { description: "UTF-8 CSV download", content: { text/csv: { schema: { type: string, format: binary } } } }

  # ═══════════════════════════════════════════════
  # ANALYTICS (admin)
  # ═══════════════════════════════════════════════

  /admin/exports:
    get:
      tags: [audit]
      summary: List admin export jobs
      description: Returns recent export jobs backed by `AdminExportJob`; `processing` query values are mapped to `running` for one compatibility cycle.
      operationId: admin_exports_list
      x-foo-actor: admin
      parameters:
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 30 } }
        - { name: status, in: query, schema: { type: string, enum: [all, queued, running, completed, failed, cancelled, processing] }, description: "`processing` is a temporary alias for `running`." }
      responses:
        "200":
          description: "Export jobs"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AdminExportJobsPayload" }
    post:
      tags: [audit]
      summary: Create an admin export job
      description: Creates a canonical CSV or XLSX export job from real database rows. Parquet is not accepted until a real writer/storage pipeline exists.
      operationId: admin_exports_create
      x-foo-actor: admin
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateAdminExportRequest" }
      responses:
        "201":
          description: "Export job created"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AdminExportJob" }
        "400": { description: "Unsupported resource, format, or date", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/exports/{id}/download:
    get:
      tags: [audit]
      summary: Download a completed CSV or XLSX export
      description: Streams the generated UTF-8 CSV or XLSX workbook for a completed export job. Parquet or incomplete jobs return a problem detail.
      operationId: admin_exports_download
      x-foo-actor: admin
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200":
          description: "CSV or XLSX download"
          content:
            text/csv: { schema: { type: string, format: binary } }
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: { schema: { type: string, format: binary } }
        "400": { description: "Export job is not ready or not downloadable", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Export job not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/export-jobs:
    get:
      tags: [audit]
      summary: List admin export jobs (legacy alias)
      description: Deprecated alias for `GET /admin/exports`, kept for one compatibility cycle.
      operationId: admin_exportJobs_listLegacy
      deprecated: true
      x-foo-actor: admin
      parameters:
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 30 } }
        - { name: status, in: query, schema: { type: string, enum: [all, queued, running, completed, failed, cancelled, processing] } }
      responses:
        "200":
          description: "Export jobs"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AdminExportJobsPayload" }

  /admin/reports/jobs:
    get:
      tags: [audit]
      summary: List report export jobs (legacy alias)
      description: Deprecated alias for `GET /admin/exports`, kept for existing report pages during the Batch 4 transition.
      operationId: admin_reports_listLegacy
      deprecated: true
      x-foo-actor: admin
      parameters:
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
      responses:
        "200":
          description: "Export jobs"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AdminExportJobsPayload" }

  /admin/reports/generate:
    post:
      tags: [audit]
      summary: Create a report export job (legacy alias)
      description: Deprecated alias for `POST /admin/exports`, accepting the same request contract.
      operationId: admin_reports_generateLegacy
      deprecated: true
      x-foo-actor: admin
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateAdminExportRequest" }
      responses:
        "201":
          description: "Export job created"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AdminExportJob" }

  /admin/settings:
    get:
      tags: [settings]
      summary: Get all platform settings sections
      description: Returns merged platform settings with defaults and degraded integration state. Sensitive values are redacted.
      operationId: admin_settings_getAll
      x-foo-actor: admin
      responses:
        "200":
          description: "Platform settings"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AdminSettingsPayload" }
    patch:
      tags: [settings]
      summary: Update one or more platform settings sections
      description: Merges supplied section patches into `PlatformSetting` records and returns redacted settings.
      operationId: admin_settings_updateAll
      x-foo-actor: admin
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AdminSettingValue" }
      responses:
        "200":
          description: "Updated platform settings"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AdminSettingsPayload" }

  /admin/settings/{section}:
    get:
      tags: [settings]
      summary: Get a platform settings section
      description: Returns one settings section merged with defaults. Unsupported sections return a problem detail.
      operationId: admin_settings_getSection
      x-foo-actor: admin
      parameters:
        - { name: section, in: path, required: true, schema: { type: string, enum: [general, branding, compliance, integrations] } }
      responses:
        "200":
          description: "Platform settings section"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AdminSettingsSectionResponse" }
        "400": { description: "Unsupported section", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    patch:
      tags: [settings]
      summary: Update a platform settings section
      description: Merges a patch into one settings section and tracks the admin user that made the update.
      operationId: admin_settings_updateSection
      x-foo-actor: admin
      parameters:
        - { name: section, in: path, required: true, schema: { type: string, enum: [general, branding, compliance, integrations] } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AdminSettingValue" }
      responses:
        "200":
          description: "Updated platform settings section"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AdminSettingsSectionResponse" }
        "400": { description: "Unsupported section", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/ai-monitor:
    get:
      tags: [ai]
      summary: Get AI chatbot monitor overview
      description: Returns DeepSeek configuration plus DB-backed conversations, escalations, actual provider token/latency telemetry, and provider status. Cost stays null until an approved billing source is connected.
      operationId: admin_aiMonitor_getOverview
      x-foo-actor: admin
      responses:
        "200":
          description: "AI monitor overview"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AdminAiMonitorOverview" }

  /ai/chat:
    post:
      tags: [ai]
      summary: Create one chatbot reply
      description: Runs the role-scoped FoodFlow chatbot pipeline once through DeepSeek and returns a safety-filtered answered or escalated state. Requested sessions are ownership-checked before any memory read. Provider/context failures fail closed with HTTP 503; no fallback assistant reply is returned.
      operationId: ai_chat_create
      x-foo-actor: user
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AiChatRequest" }
      responses:
        "200":
          description: "Chatbot reply"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AiChatReply" }
        "400": { description: "Missing/overlong/unsafe message, malformed UUID, or session/order mismatch", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Requested AI session or customer-scoped order was not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "503": { description: "Provider unconfigured, unavailable, or grounded context unavailable", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /ai/history:
    get:
      tags: [ai]
      summary: Get the authenticated user's persisted AI chat history
      description: Returns at most fifty turns belonging to the caller only. Omit sessionId to select the caller's latest active AI-support session.
      operationId: ai_chat_getHistory
      x-foo-actor: user
      parameters:
        - in: query
          name: sessionId
          required: false
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: "User-scoped AI chat history"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SuccessEnvelope"
                  - type: object
                    properties:
                      data: { $ref: "#/components/schemas/AiChatHistory" }
        "400": { description: "Invalid session ID", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /ai/stream:
    post:
      tags: [ai]
      summary: Stream a chatbot reply as server-sent events
      description: Streams thinking/response/escalated/done events from the same safety-filtered chatbot service. It does not synthesize word tokens; failures emit an allow-listed public error code and no assistant fallback.
      operationId: ai_chat_stream
      x-foo-actor: user
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AiChatRequest" }
      responses:
        "200": { description: "SSE stream with thinking/response/escalated/done or error events", content: { text/event-stream: { schema: { type: string } } } }
        "400": { description: "Missing/overlong/unsafe message or malformed UUID", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/kpis:
    get:
      tags: [analytics]
      summary: Get admin KPI cards
      description: Returns database-backed KPI cards for the selected period and previous-period comparison.
      operationId: analytics_adminKpis
      x-foo-actor: admin
      parameters:
        - name: period
          in: query
          schema: { type: string, default: today }
        - name: compare
          in: query
          schema: { type: string, default: yesterday }
      responses:
        "200": { description: "Admin KPI cards", content: { application/json: { schema: { $ref: "#/components/schemas/AdminKpisResponse" } } } }

  /admin/charts:
    get:
      tags: [analytics]
      summary: Get admin analytics chart data
      description: Returns revenue, order funnel, driver-online, restaurant ranking, order heatmap, and database-backed customer retention cohorts for the requested rolling window.
      operationId: analytics_adminCharts
      x-foo-actor: admin
      parameters:
        - name: period
          in: query
          schema: { type: string, default: "30d" }
      responses:
        "200": { description: "Admin analytics charts", content: { application/json: { schema: { $ref: "#/components/schemas/AdminChartsResponse" } } } }

  /admin/dashboard:
    get:
      tags: [analytics]
      summary: Get admin dashboard KPIs
      description: Returns platform KPI totals and comparisons for the admin dashboard.
      operationId: analytics_dashboard
      x-foo-actor: admin
      responses:
        "200": { description: "Dashboard KPIs", content: { application/json: { schema: { $ref: "#/components/schemas/DashboardKpi" } } } }

  /admin/dashboard/top-restaurants:
    get:
      tags: [analytics]
      summary: Top restaurants by revenue
      description: Returns the highest-revenue restaurants for the requested rolling day window.
      operationId: analytics_topRestaurants
      x-foo-actor: admin
      parameters:
        - name: days
          in: query
          schema: { type: integer, default: 7 }
      responses:
        "200": { description: "Top restaurants", content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: "#/components/schemas/RestaurantKpi" } } } } } } }

  /admin/dashboard/revenue-chart:
    get:
      tags: [analytics]
      summary: Revenue trend chart data
      description: Returns daily revenue points for admin dashboard trend charts.
      operationId: analytics_revenueChart
      x-foo-actor: admin
      parameters:
        - name: days
          in: query
          schema: { type: integer, default: 7 }
      responses:
        "200": { description: "Revenue chart points", content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: "#/components/schemas/RevenueChartPoint" } } } } } } }

  /admin/dashboard/heatmap:
    get:
      tags: [analytics]
      summary: Dashboard order density heatmap
      description: Returns day/hour order-density cells for the admin dashboard heatmap. Use `/admin/dispatch/heatmap` for map coordinates.
      operationId: analytics_heatmap
      x-foo-actor: admin
      parameters:
        - name: days
          in: query
          schema: { type: integer, minimum: 1, maximum: 365, default: 30 }
      responses:
        "200": { description: "Dashboard heatmap cells", content: { application/json: { schema: { type: array, items: { $ref: "#/components/schemas/AdminOrderHeatmapCell" } } } } }

  /admin/dispatch/heatmap:
    get:
      tags: [analytics]
      summary: Dispatch demand map heatmap
      description: Returns real order density by restaurant district/city bucket with centroid coordinates for the admin dispatch map. The `since` query must be an ISO date-time; clients should not send natural-language placeholders.
      operationId: analytics_dispatchHeatmap
      x-foo-actor: admin
      parameters:
        - name: since
          in: query
          required: true
          schema: { type: string, format: date-time }
      responses:
        "200": { description: "Dispatch map heatmap points", content: { application/json: { schema: { type: array, items: { $ref: "#/components/schemas/HeatmapPoint" } } } } }
        "400": { description: "Invalid or missing since query", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/restaurants/{restaurantId}/kpi:
    get:
      tags: [analytics]
      summary: Get per-restaurant KPI
      description: Returns KPI metrics for one restaurant selected by an admin.
      operationId: analytics_restaurantKpi
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: period
          in: query
          schema: { type: string, default: "7d" }
      responses:
        "200": { description: "Restaurant KPI", content: { application/json: { schema: { $ref: "#/components/schemas/RestaurantKpi" } } } }

  # ═══════════════════════════════════════════════
  # ADMIN USER & RESTAURANT MANAGEMENT
  # ═══════════════════════════════════════════════

  /admin/drivers:
    get:
      tags: [drivers]
      summary: List driver accounts for administration
      description: Returns database-backed driver identity, vehicle, verification and derived availability state. Tracking coordinates remain on `/admin/online-drivers`.
      operationId: admin_listDrivers
      x-foo-actor: admin
      parameters:
        - name: search
          in: query
          description: Match driver name, email, phone, or vehicle plate.
          schema: { type: string, maxLength: 100 }
        - name: status
          in: query
          schema: { type: string, enum: [online, offline, delivering] }
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Paginated driver accounts
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PaginatedAdminDrivers" }
        "400": { description: Invalid query parameters, content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "401": { description: Authentication required, content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "403": { description: Admin role required, content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/online-drivers:
    get:
      tags: [drivers]
      summary: List live online driver map positions
      description: Returns Redis-backed active driver coordinates across Vietnam, filtered to the Vietnam map bounds and enriched with database-backed driver identity, vehicle profile and active order state for the admin map.
      operationId: admin_listOnlineDriverLocations
      x-foo-actor: admin
      responses:
        "200":
          description: Online driver locations for the admin map
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AdminDriverLocationsResponse" }
        "401": { description: Authentication required, content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "403": { description: Admin role required, content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/users:
    get:
      tags: [analytics]
      summary: List all users (admin)
      description: Lists platform users with optional role filter and pagination for admin management.
      operationId: admin_listUsers
      x-foo-actor: admin
      parameters:
        - name: role
          in: query
          schema: { type: string, enum: [customer, driver, restaurant, admin] }
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "User list", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedUsers" } } } }

  /admin/users/{userId}:
    get:
      tags: [analytics]
      summary: Get one user for admin review
      description: Returns one user with customer, driver, and restaurant profile details. Password hashes are omitted by the backend.
      operationId: admin_getUser
      x-foo-actor: admin
      parameters:
        - name: userId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "User detail", content: { application/json: { schema: { type: object, additionalProperties: true } } } }
        "404": { description: "User not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/users/{userId}/wallet:
    get:
      tags: [analytics]
      summary: Get one user's wallet ledger
      description: Returns the confirmed balance derived from real wallet transactions and the latest wallet ledger rows.
      operationId: admin_getUserWallet
      x-foo-actor: admin
      parameters:
        - name: userId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: "Wallet ledger"
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance: { type: number }
                  transactions:
                    type: array
                    items: { type: object, additionalProperties: true }
                required: [balance, transactions]
        "404": { description: "User not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/users/{userId}/vouchers:
    get:
      tags: [analytics]
      summary: Get voucher and promotion usage for one user
      description: Returns currently usable persisted promotions and real promotion usage history for the user. Empty arrays mean no matching persisted promotions/usages; no placeholder voucher rows are synthesized.
      operationId: admin_getUserVouchers
      x-foo-actor: admin
      parameters:
        - name: userId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: "User voucher and promotion usage summary"
          content:
            application/json:
              schema:
                type: object
                properties:
                  owned:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, format: uuid }
                        promotionId: { type: string, format: uuid }
                        code: { type: string }
                        description: { type: string }
                        discountType: { type: string, enum: [percentage, fixed, free_delivery, bogo, combo] }
                        discountValue: { type: number }
                        minOrder: { type: number }
                        maxDiscount: { type: number }
                        validUntil: { type: string, format: date-time }
                        usedAt: { type: string, format: date-time, nullable: true }
                        orderCode: { type: string, nullable: true }
                      required: [id, promotionId, code, description, discountType, discountValue, minOrder, maxDiscount, validUntil, usedAt]
                  used:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, format: uuid }
                        promotionId: { type: string, format: uuid }
                        code: { type: string }
                        description: { type: string }
                        discountType: { type: string, enum: [percentage, fixed, free_delivery, bogo, combo] }
                        discountValue: { type: number }
                        minOrder: { type: number }
                        maxDiscount: { type: number }
                        validUntil: { type: string, format: date-time }
                        usedAt: { type: string, format: date-time, nullable: true }
                        orderCode: { type: string, nullable: true }
                      required: [id, promotionId, code, description, discountType, discountValue, minOrder, maxDiscount, validUntil, usedAt]
                  totalSaved: { type: number }
                required: [owned, used, totalSaved]
        "404": { description: "User not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/users/{userId}/refunds:
    get:
      tags: [analytics]
      summary: Get refunded payments for one user
      description: Returns real refunded payment rows linked to the user's customer orders.
      operationId: admin_getUserRefunds
      x-foo-actor: admin
      parameters:
        - name: userId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Refunded payments", content: { application/json: { schema: { type: array, items: { type: object, additionalProperties: true } } } } }
        "404": { description: "User not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/users/{userId}/kyc:
    get:
      tags: [drivers]
      summary: Get driver KYC submissions for one user
      description: Returns an explicit unavailable reason for non-driver users or real driver KYC submissions with five-minute signed private-document read URLs for authorized admin review. Raw object keys are never returned.
      operationId: admin_getUserKyc
      x-foo-actor: admin
      parameters:
        - name: userId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: "KYC payload"
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    additionalProperties: false
                    properties:
                      available: { type: boolean, const: false }
                      reason: { type: string, enum: [NOT_A_DRIVER] }
                    required: [available, reason]
                  - type: object
                    additionalProperties: false
                    properties:
                      available: { type: boolean, const: true }
                      submissions:
                        type: array
                        items: { $ref: "#/components/schemas/AdminKycSubmission" }
                    required: [available, submissions]
        "404": { description: "User not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/users/{userId}/kyc/review:
    post:
      tags: [drivers]
      summary: Review one driver KYC submission
      description: Approves or rejects a real KYC submission and records the reviewing admin.
      operationId: admin_reviewUserKyc
      x-foo-actor: admin
      parameters:
        - name: userId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/KycReviewRequest" }
      responses:
        "201": { description: "KYC review saved without private object keys", content: { application/json: { schema: { $ref: "#/components/schemas/AdminKycReviewResponse" } } } }
        "400": { description: "Rejection reason or private document manifest is invalid", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "409": { description: "KYC submission was already reviewed", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "KYC submission not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/users/{userId}/status:
    patch:
      tags: [analytics]
      summary: Toggle user active status
      description: Enables or disables one user account after admin authorization.
      operationId: admin_toggleUserStatus
      x-foo-actor: admin
      parameters:
        - name: userId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isActive: { type: boolean }
              required: [isActive]
      responses:
        "200": { description: "Status updated" }

  /admin/restaurants:
    get:
      tags: [analytics]
      summary: List all restaurants (admin)
      description: Lists restaurants with pagination for admin review and lifecycle management.
      operationId: admin_listRestaurants
      x-foo-actor: admin
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Restaurant list", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedRestaurants" } } } }

  /admin/restaurants/{restaurantId}:
    get:
      tags: [analytics]
      summary: Get one restaurant for admin review
      description: Returns one restaurant with opening hours and owner profile relations for admin detail pages.
      operationId: admin_getRestaurant
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Restaurant detail", content: { application/json: { schema: { type: object, additionalProperties: true } } } }
        "404": { description: "Restaurant not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/restaurants/{restaurantId}/overview:
    get:
      tags: [analytics]
      summary: Get restaurant operational overview
      description: Returns real aggregate order, revenue, rating, menu, and staff counts for one restaurant.
      operationId: admin_getRestaurantOverview
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: "Restaurant overview"
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalOrders: { type: integer, minimum: 0 }
                  completedOrders: { type: integer, minimum: 0 }
                  revenue: { type: number, minimum: 0 }
                  rating: { type: number, minimum: 0, maximum: 5 }
                  reviewCount: { type: integer, minimum: 0 }
                  menuItems: { type: integer, minimum: 0 }
                  activeStaff: { type: integer, minimum: 0 }
                required: [totalOrders, completedOrders, revenue, rating, reviewCount, menuItems, activeStaff]
        "404": { description: "Restaurant not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/restaurants/{restaurantId}/menu:
    get:
      tags: [restaurants]
      summary: Get restaurant menu for admin review
      description: Returns real menu categories, items, options, and option values for one restaurant.
      operationId: admin_getRestaurantMenu
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Restaurant menu", content: { application/json: { schema: { type: array, items: { type: object, additionalProperties: true } } } } }
        "404": { description: "Restaurant not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/restaurants/{restaurantId}/menu/{itemId}:
    patch:
      tags: [restaurants]
      summary: Update one restaurant menu item's availability
      description: Updates the real menu item availability after verifying it belongs to the selected restaurant.
      operationId: admin_updateRestaurantMenuItem
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: itemId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RestaurantMenuAvailabilityRequest" }
      responses:
        "200": { description: "Menu item updated", content: { application/json: { schema: { type: object, additionalProperties: true } } } }
        "404": { description: "Menu item not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/restaurants/{restaurantId}/orders:
    get:
      tags: [analytics]
      summary: List orders for one restaurant as admin
      description: Returns real orders for one restaurant with pagination.
      operationId: admin_getRestaurantOrders
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Restaurant orders", content: { application/json: { schema: { type: object, properties: { orders: { type: array, items: { $ref: "#/components/schemas/OrderDetail" } }, meta: { $ref: "#/components/schemas/PaginationMeta" } }, required: [orders, meta] } } } }
        "404": { description: "Restaurant not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/restaurants/{restaurantId}/reviews:
    get:
      tags: [restaurants]
      summary: List reviews for one restaurant as admin
      description: Returns real review rows for one restaurant with pagination.
      operationId: admin_getRestaurantReviews
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Restaurant reviews", content: { application/json: { schema: { type: object, properties: { reviews: { type: array, items: { type: object, additionalProperties: true } }, meta: { $ref: "#/components/schemas/PaginationMeta" } }, required: [reviews, meta] } } } }
        "404": { description: "Restaurant not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/restaurants/{restaurantId}/finance:
    get:
      tags: [analytics]
      summary: Get restaurant finance summary
      description: Returns real gross, commission, net, and completed order count for one restaurant.
      operationId: admin_getRestaurantFinance
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: "Restaurant finance"
          content:
            application/json:
              schema:
                type: object
                properties:
                  gross: { type: number, minimum: 0 }
                  commission: { type: number, minimum: 0 }
                  net: { type: number }
                  orderCount: { type: integer, minimum: 0 }
                required: [gross, commission, net, orderCount]
        "404": { description: "Restaurant not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/restaurants/{restaurantId}/approve:
    post:
      tags: [restaurants]
      summary: Approve one restaurant
      description: Approves a pending restaurant, records admin notes, sets it active, and emits an audit log.
      operationId: admin_approveRestaurant
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RestaurantReviewRequest" }
      responses:
        "201": { description: "Restaurant approved", content: { application/json: { schema: { type: object, additionalProperties: true } } } }
        "404": { description: "Restaurant not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/restaurants/{restaurantId}/reject:
    post:
      tags: [restaurants]
      summary: Reject one restaurant
      description: Rejects a pending restaurant, records admin notes or reason, and emits an audit log.
      operationId: admin_rejectRestaurant
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RestaurantReviewRequest" }
      responses:
        "201": { description: "Restaurant rejected", content: { application/json: { schema: { type: object, additionalProperties: true } } } }
        "404": { description: "Restaurant not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/restaurants/{restaurantId}/status:
    patch:
      tags: [analytics]
      summary: Toggle restaurant active status
      description: Enables or disables one restaurant after admin authorization.
      operationId: admin_toggleRestaurantStatus
      x-foo-actor: admin
      parameters:
        - name: restaurantId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isActive: { type: boolean }
              required: [isActive]
      responses:
        "200": { description: "Status updated" }

  /admin/promotions:
    get:
      tags: [promotions]
      summary: List all promotions (admin)
      description: Lists platform promotions with pagination and optional active-state filtering.
      operationId: admin_listPromotions
      x-foo-actor: admin
      parameters:
        - name: isActive
          in: query
          schema: { type: boolean }
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Promotions", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedPromotions" } } } }
    post:
      tags: [promotions]
      summary: Create a promotion (admin)
      description: Creates a platform promotion and validates uniqueness of the promotion code.
      operationId: admin_createPromotion
      x-foo-actor: admin
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreatePromotionRequest" }
      responses:
        "201": { description: "Promotion created", content: { application/json: { schema: { $ref: "#/components/schemas/Promotion" } } } }
        "409": { description: "Code already exists", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/promotions/{promotionId}:
    get:
      tags: [promotions]
      summary: Get one promotion (admin)
      description: Returns one platform promotion with its promotion items for the admin detail page.
      operationId: admin_getPromotion
      x-foo-actor: admin
      parameters:
        - name: promotionId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Promotion", content: { application/json: { schema: { $ref: "#/components/schemas/Promotion" } } } }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    patch:
      tags: [promotions]
      summary: Update a promotion (admin)
      description: Updates a platform promotion selected by an admin.
      operationId: admin_updatePromotion
      x-foo-actor: admin
      parameters:
        - name: promotionId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdatePromotionRequest" }
      responses:
        "200": { description: "Promotion updated", content: { application/json: { schema: { $ref: "#/components/schemas/Promotion" } } } }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
    delete:
      tags: [promotions]
      summary: Delete a promotion (admin)
      description: Deletes a platform promotion selected by an admin when backend validation allows removal.
      operationId: admin_deletePromotion
      x-foo-actor: admin
      parameters:
        - name: promotionId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Promotion deleted" }
        "404": { description: "Not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/promotions/{promotionId}/toggle:
    patch:
      tags: [promotions]
      summary: Toggle promotion active state
      description: Toggles whether one platform promotion is active.
      operationId: admin_togglePromotion
      x-foo-actor: admin
      parameters:
        - name: promotionId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Promotion toggled" }

  /admin/promotions/{promotionId}/analytics:
    get:
      tags: [promotions]
      summary: Get admin promotion analytics
      description: Returns real promotion redemption count, GMV, discount cost, and ROI from promotion usage rows.
      operationId: admin_getPromotionAnalytics
      x-foo-actor: admin
      parameters:
        - name: promotionId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Promotion analytics", content: { application/json: { schema: { $ref: "#/components/schemas/AdminPromotionAnalytics" } } } }
        "404": { description: "Promotion not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/orders/recent:
    get:
      tags: [analytics]
      summary: Recent orders for admin realtime feed
      description: Returns the most recent orders used to hydrate the admin realtime order panel before socket events arrive.
      operationId: admin_recentOrders
      x-foo-actor: admin
      parameters:
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        "200": { description: "Recent orders", content: { application/json: { schema: { $ref: "#/components/schemas/AdminRecentOrdersResponse" } } } }

  /admin/orders:
    get:
      tags: [analytics]
      summary: List all orders (admin)
      description: Lists platform orders with pagination and optional status filtering for admin operations.
      operationId: admin_listOrders
      x-foo-actor: admin
      parameters:
        - name: status
          in: query
          schema: { type: string }
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200": { description: "Orders", content: { application/json: { schema: { $ref: "#/components/schemas/PaginatedOrders" } } } }

  /admin/orders/{orderId}:
    get:
      tags: [analytics]
      summary: Get one order for admin review
      description: Returns a serialized order with customer, restaurant, driver, address, items, payment, delivery task, and status history details.
      operationId: admin_getOrder
      x-foo-actor: admin
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: "Order detail", content: { application/json: { schema: { $ref: "#/components/schemas/OrderDetail" } } } }
        "404": { description: "Order not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }

  /admin/orders/{orderId}/status:
    patch:
      tags: [analytics]
      summary: Update one order status as admin
      description: Applies an admin order status transition through the backend order state machine and audit logging.
      operationId: admin_updateOrderStatus
      x-foo-actor: admin
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AdminOrderStatusRequest" }
      responses:
        "200": { description: "Order status updated", content: { application/json: { schema: { $ref: "#/components/schemas/OrderDetail" } } } }
        "400": { description: "Invalid transition", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }
        "404": { description: "Order not found", content: { application/json: { schema: { $ref: "#/components/schemas/ProblemDetail" } } } }