paths:
  # ─── CreateStaffUser ──────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=createStaffUser&ver=v1":
    post:
      operationId: createStaffUser
      summary: Create a staff user
      description: |
        Permission: **OWNER only**

        - `username` must be pre-generated via `GenerateStaffUsername` and passed by the client.
        - Password is auto-generated by the system (min 12, max 24 chars; ≥1 uppercase, lowercase, number, special char).
        - New account defaults: `status = Active`, `2FA = Not Configured`.
        - System sends credentials to staff email **asynchronously** — email failure does not roll back the account.
      tags: [staffManagement]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "../components.yaml#/components/schemas/CreateStaffUserRequest"
            example:
              first_name: "Jane"
              last_name: "Doe"
              second_last_name: ""
              email: "jane.doe@nova.com"
              phone: "+5219981234567"
              role: "ADMIN"
              username: "nova.jdoe.43"
      responses:
        "200":
          description: Staff user created — DTO returned directly
          content:
            application/json:
              schema:
                $ref: "../components.yaml#/components/schemas/CreateStaffUserResponse"
              example:
                user_id: "usr_staff_001"
                username: "nova.jdoe.43"
                role: "ADMIN"
        "400":
          $ref: "../components.yaml#/components/responses/ClientError"
        "403":
          $ref: "../components.yaml#/components/responses/ClientError"
        "500":
          $ref: "../components.yaml#/components/responses/ServerError"

  # ─── GenerateStaffUsername ────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=generateStaffUsername&ver=v1":
    post:
      operationId: generateStaffUsername
      summary: Generate a preview username for a staff account
      description: |
        Permission: **OWNER only**

        - Returns a username preview in format `nova.{initial}{lastname}.{XX}` (lowercase).
        - Does **not** persist to DB — uniqueness is only guaranteed at `CreateStaffUser` time.
        - Call before submitting `CreateStaffUser`. Client may call again ("Re-generate") to get a new value.
      tags: [staffManagement]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "../components.yaml#/components/schemas/GenerateStaffUsernameRequest"
            example:
              first_name: "Jane"
              last_name: "Doe"
      responses:
        "200":
          description: Generated username preview — DTO returned directly
          content:
            application/json:
              schema:
                $ref: "../components.yaml#/components/schemas/GenerateStaffUsernameResponse"
              example:
                username: "nova.jdoe.43"
        "400":
          $ref: "../components.yaml#/components/responses/ClientError"
        "403":
          $ref: "../components.yaml#/components/responses/ClientError"
        "500":
          $ref: "../components.yaml#/components/responses/ServerError"

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

        - Default sort: `full_name ASC`.
        - Sortable: `full_name`, `created_at`.
        - `search` resets all filters and sort to default (debounce 500ms or Enter).
        - Supports infinity loading; 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/ListStaffRequest"
            example:
              search: ""
              role: "ADMIN"
              statuses: ["active", "inactive"]
              sort_by: "full_name"
              sort_dir: "asc"
              limit: 20
              offset: 0
      responses:
        "200":
          description: Paginated list of staff users — DTO returned directly
          content:
            application/json:
              schema:
                $ref: "../components.yaml#/components/schemas/ListStaffUsersResponse"
              example:
                items:
                  - user_id: "usr_staff_001"
                    full_name: "Jane Doe"
                    username: "nova.jdoe.43"
                    email: "jane.doe@nova.com"
                    phone: "+5219981234567"
                    role: "ADMIN"
                    status: "active"
                    last_login: "21/05/2026 08:00"
                    created_date: "01/01/2026 09:00"
                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"

  # ─── GetStaffInfo ─────────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=getStaffInfo&ver=v1":
    post:
      operationId: getStaffInfo
      summary: Get staff user detail by ID
      description: |
        Permission: **ADMIN, OWNER**

        Returns the full profile of a single staff account identified by `staff_id`.
        - `status` maps DB values: `ACTIVE` → `active`, `INACTIVE` → `inactive`, `DEACTIVATED` → `deactivated`.
        - `lock_status` is present only when the account is currently locked (password lock or OTP lock).
        - `last_login` is `"-"` if the staff has never logged in.
      tags: [staffManagement]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "../components.yaml#/components/schemas/GetStaffInfoRequest"
            example:
              staff_id: "6643f1a2b4c5d60012e34abc"
      responses:
        "200":
          description: Staff detail — DTO returned directly
          content:
            application/json:
              schema:
                $ref: "../components.yaml#/components/schemas/GetStaffInfoResponse"
              example:
                user_id: "6643f1a2b4c5d60012e34abc"
                first_name: "Jane"
                last_name: "Doe"
                second_last_name: ""
                username: "nova.jdoe.43"
                email: "jane.doe@nova.com"
                phone: "+5219981234567"
                role: "ADMIN"
                status: "active"
                two_fa_status: "VERIFIED"
                must_change_password: false
                failed_login_attempts: 0
                last_login: "21/05/2026 08:00"
                created_at: "01/01/2026 09:00"
                created_by: "6643f1a2b4c5d60012e34001"
        "400":
          $ref: "../components.yaml#/components/responses/ClientError"
        "403":
          $ref: "../components.yaml#/components/responses/ClientError"
        "404":
          $ref: "../components.yaml#/components/responses/ClientError"
        "500":
          $ref: "../components.yaml#/components/responses/ServerError"