paths:
  # ─── CreateClientUser ─────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=createClientUser&ver=v1":
    post:
      operationId: createClientUser
      summary: Create a client user
      description: |
        Permission: **ADMIN, OWNER**

        - `role` is always set to `CLIENT` by the server, not taken from the request.
        - `phone` must be unique in the system.
        - After creation, the client can log in via the mobile app immediately.
      tags: [staffManagement]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "../components.yaml#/components/schemas/CreateClientUserRequest"
            example:
              first_name: "Juan"
              last_name: "Doe"
              second_last_name: "García"
              phone: "5219981234567"
              email: "juan.doe@example.com"
              country: "MEX"
              address: "Av. Insurgentes Sur 1234, CDMX"
      responses:
        "200":
          description: Client user created — DTO returned directly
          content:
            application/json:
              schema:
                $ref: "../components.yaml#/components/schemas/CreateClientUserResponse"
              example:
                user_id: "usr_client_001"
                username: "juan.doe"
                role: "CLIENT"
        "400":
          $ref: "../components.yaml#/components/responses/ClientError"
        "403":
          $ref: "../components.yaml#/components/responses/ClientError"
        "500":
          $ref: "../components.yaml#/components/responses/ServerError"

  # ─── ListClientUsers ──────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=listClientUsers&ver=v1":
    post:
      operationId: listClientUsers
      summary: List client users
      description: |
        Permission: **ADMIN, OWNER**

        - Default sort: `created_at DESC`.
        - Sortable: `created_at`.
        - Supports infinity loading: last batch when returned count < `limit`.
        - `search` resets filters and sort to default when active.
        - Send empty `statuses` to select "All".
        - Returns `items: []`, `total: 0` when no data found.
      tags: [staffManagement]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "../components.yaml#/components/schemas/ListClientRequest"
            example:
              search: ""
              statuses: ["active", "inactive"]
              sort_by: "created_at"
              sort_dir: "desc"
              limit: 20
              offset: 0
      responses:
        "200":
          description: Paginated list of client users — DTO returned directly
          content:
            application/json:
              schema:
                $ref: "../components.yaml#/components/schemas/ListClientUsersResponse"
              example:
                items:
                  - user_id: "usr_client_001"
                    username: "juan.doe"
                    full_name: "Juan Doe García"
                    phone: "5219981234567"
                    email: "juan.doe@example.com"
                    address: "Av. Insurgentes Sur 1234, CDMX"
                    created_date: "21/05/2026 08:30"
                    status: "active"
                total: 1
                limit: 20
                offset: 0
        "400":
          $ref: "../components.yaml#/components/responses/ClientError"
        "403":
          $ref: "../components.yaml#/components/responses/ClientError"
        "500":
          $ref: "../components.yaml#/components/responses/ServerError"