paths:
  # ─── generateQRCodeLogin ──────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=generateQRCodeLogin&ver=v1":
    post:
      operationId: generateQRCodeLogin
      summary: Generate Google Authenticator QR code
      tags: [staffManagement]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "../components.yaml#/components/schemas/GenerateQRCodeLoginRequest"
            example:
              user_id: "usr_001"
              account_name: "admin@example.com"
      responses:
        "200":
          description: QR code result — DTO returned directly
          content:
            application/json:
              schema:
                $ref: "../components.yaml#/components/schemas/GenerateQRCodeLoginResponse"
              example:
                qr_png_b64: "iVBORw0KGgoAAAANSUhEUgAA..."
                secret_id: "secret_xyz"
        "400":
          $ref: "../components.yaml#/components/responses/ClientError"
        "500":
          $ref: "../components.yaml#/components/responses/ServerError"

  # ─── Enable2FA ────────────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=enable2FA&ver=v1":
    post:
      operationId: enable2FA
      summary: Enable 2FA with a TOTP secret
      tags: [staffManagement]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "../components.yaml#/components/schemas/EnrollKeyVaultRequest"
            example:
              user_id: "usr_001"
              secret_id: "secret_xyz"
              code: "123456"
      responses:
        "200":
          description: Enroll result — DTO returned directly
          content:
            application/json:
              schema:
                $ref: "../components.yaml#/components/schemas/EnrollKeyVaultResponse"
              example:
                valid: true
        "400":
          $ref: "../components.yaml#/components/responses/ClientError"
        "500":
          $ref: "../components.yaml#/components/responses/ServerError"

  # ─── ValidateCode ──────────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=validateCode&ver=v1":
    post:
      operationId: validateCode
      summary: Validate a TOTP / OTP code
      tags: [staffManagement]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "../components.yaml#/components/schemas/ValidateCodeRequest"
            example:
              user_id: "usr_001"
              code: "123456"
      responses:
        "200":
          description: Validation result — DTO returned directly
          content:
            application/json:
              schema:
                $ref: "../components.yaml#/components/schemas/ValidateCodeResponse"
              example:
                valid: true
        "400":
          $ref: "../components.yaml#/components/responses/ClientError"
        "500":
          $ref: "../components.yaml#/components/responses/ServerError"