openapi: "3.0.3"
info:
  title: Nova Web Admin API
  version: "v1.0"
  description: |
    Open API for Nova web admin — `staffManagement` controller.

    **Routing**: query params `ctrl`, `api`, `ver`
    **Auth**: Guest (no JWT required for these endpoints)

    ### Success
    HTTP `200` — server returns the DTO object **directly** (no wrapper envelope).

    ```json
    {
      "user_id": "abc123",
      "role": "ADMIN"
    }
    ```

    ### Error
    HTTP `4XX` / `5XX` — JSON body:
    ```json
    {
      "code": 180206,
      "message": "Invalid username or password",
      "details": [{ "source": "username", "issue": "invalid credentials" }]
    }
    ```
    `code` is composed by `serviceCode*10000 + pkgCode*100 + clientErrCode`.
    - `serviceCode`: `10` = system, `18` = Nova
    - `pkgCode`: `2` = staff package (`PkgErr_Staff`)
    - `clientErrCode`: specific error code (`00` for base, `01`-`99` for specific errors)
    - Base codes for web admin: `sysErrCode = 100200`, `pkgErrCode = 180200`

    #### System errors (`1002ZZ`)
    | Code | Description |
    |------|-------------|
    | `100201` | Database connection error |
    | `100202` | Database query error |
    | `100203` | Unknown internal server error |
    | `100204` | Timeout calling external service |
    | `100205` | Internal data parse / unmarshal error |

    #### Nova business errors (`1802ZZ`)
    | Code | Description |
    |------|-------------|
    | `180206` | Invalid username or password |
    | `180207` | Account disabled (`is_active = false`) |
    | `180208` | Account locked (too many failed attempts) |
    | `180209` | Must change password before continuing |
    | `180210` | Invalid or expired OTP code |
    | `180211` | `secret_id` not found or does not belong to user |
    | `180212` | Duplicate `request_id` (replay attack detected) |
    | `180213` | User not found |
    | `180214` | Insufficient permissions (forbidden) |
    | `180215` | Invalid request data (validation failed) |
    | `180216` | Phone number already exists |
    | `180217` | Username already exists |
    | `180218` | Email already linked to another staff account |
    | `180219` | OTP session expired (5-minute intermediate window) |
    | `180220` | Account blocked — too many failed OTP attempts (requires admin unblock) |
    | `180221` | User account is permanently deactivated |

servers:
  - url: https://s3dommv4yh.execute-api.mx-central-1.amazonaws.com/default/dev-omni-nova-client-web
    description: Cloud Development Server Base URL of the Lambda / API Gateway endpoint

paths:
  # ─── Auth ─────────────────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=login&ver=v1":
    $ref: "./paths/auth.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3Dlogin%26ver%3Dv1"

  "/?ctrl=staffManagementCtl&api=validate2FACode&ver=v1":
    $ref: "./paths/auth.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3Dvalidate2FACode%26ver%3Dv1"

  # ─── Google Auth / 2FA Setup ──────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=generateQRCodeLogin&ver=v1":
    $ref: "./paths/google_auth.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3DgenerateQRCodeLogin%26ver%3Dv1"

  "/?ctrl=staffManagementCtl&api=enable2FA&ver=v1":
    $ref: "./paths/google_auth.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3Denable2FA%26ver%3Dv1"

  # ─── Client User ──────────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=createClientUser&ver=v1":
    $ref: "./paths/client_user.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3DcreateClientUser%26ver%3Dv1"

  "/?ctrl=staffManagementCtl&api=listClientUsers&ver=v1":
    $ref: "./paths/client_user.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3DlistClientUsers%26ver%3Dv1"

  # ─── Staff User ───────────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=createStaffUser&ver=v1":
    $ref: "./paths/staff_user.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3DcreateStaffUser%26ver%3Dv1"

  "/?ctrl=staffManagementCtl&api=generateStaffUsername&ver=v1":
    $ref: "./paths/staff_user.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3DgenerateStaffUsername%26ver%3Dv1"

  "/?ctrl=staffManagementCtl&api=listStaffUsers&ver=v1":
    $ref: "./paths/staff_user.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3DlistStaffUsers%26ver%3Dv1"

  "/?ctrl=staffManagementCtl&api=getStaffInfo&ver=v1":
    $ref: "./paths/staff_user.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3DgetStaffInfo%26ver%3Dv1"

  # ─── Station ──────────────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=createStation&ver=v1":
    $ref: "./paths/station.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3DcreateStation%26ver%3Dv1"

  # ─── Config ───────────────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=getConfig&ver=v1":
    $ref: "./paths/config.yaml#/paths/~1%3Fctrl%3DstaffManagementCtl%26api%3DgetConfig%26ver%3Dv1"

  # ─── Session ──────────────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=initSession&ver=v1":
    post:
      operationId: initSession
      summary: Initialize a tracking session for staff
      description: |
        Generates a unique `tracking_id` for the current staff session.
        The `tracking_id` uses the Nova prefix and is backed by the database sequence.
      tags: [staffManagement]
      responses:
        "200":
          description: Session initialized — tracking ID returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InitSessionResponse"
              example:
                tracking_id: "NOVA-000001"
        "401":
          $ref: "#/components/responses/ClientError"
        "500":
          $ref: "#/components/responses/ServerError"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  # ─── Reusable responses ───────────────────────────────────────────────────
  responses:
    ClientError:
      description: |
        Client error (HTTP 4XX). Invalid request, missing params, validation
        failure, or auth error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
          example:
            code: 180215
            message: "Invalid request data (validation failed)"
            details:
              - source: "username"
                issue: "required"
    ServerError:
      description: Internal server error (HTTP 5XX).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
          example:
            code: 100203
            message: "Unknown internal server error"
            details: []

  schemas:
    # ── Base ──────────────────────────────────────────────────────────────────
    ApiError:
      $ref: "./components.yaml#/components/schemas/ApiError"

    # ── Session ───────────────────────────────────────────────────────────────
    InitSessionResponse:
      $ref: "./components.yaml#/components/schemas/InitSessionResponse"

    # ── Auth ──────────────────────────────────────────────────────────────────
    LoginRequest:
      $ref: "./components.yaml#/components/schemas/LoginRequest"

    LoginResponse:
      $ref: "./components.yaml#/components/schemas/LoginResponse"

    VerifyOTPRequest:
      $ref: "./components.yaml#/components/schemas/VerifyOTPRequest"

    VerifyOTPResponse:
      $ref: "./components.yaml#/components/schemas/VerifyOTPResponse"

    # ── Google Auth / 2FA Setup ───────────────────────────────────────────────
    GenerateQRCodeLoginRequest:
      $ref: "./components.yaml#/components/schemas/GenerateQRCodeLoginRequest"

    GenerateQRCodeLoginResponse:
      $ref: "./components.yaml#/components/schemas/GenerateQRCodeLoginResponse"

    EnrollKeyVaultRequest:
      $ref: "./components.yaml#/components/schemas/EnrollKeyVaultRequest"

    EnrollKeyVaultResponse:
      $ref: "./components.yaml#/components/schemas/EnrollKeyVaultResponse"

    # ── Client User ───────────────────────────────────────────────────────────
    CreateClientUserRequest:
      $ref: "./components.yaml#/components/schemas/CreateClientUserRequest"

    CreateClientUserResponse:
      $ref: "./components.yaml#/components/schemas/CreateClientUserResponse"

    ClientUserItem:
      $ref: "./components.yaml#/components/schemas/ClientUserItem"

    ListClientRequest:
      $ref: "./components.yaml#/components/schemas/ListClientRequest"

    ListClientUsersResponse:
      $ref: "./components.yaml#/components/schemas/ListClientUsersResponse"

    # ── Staff User ────────────────────────────────────────────────────────────
    CreateStaffUserRequest:
      $ref: "./components.yaml#/components/schemas/CreateStaffUserRequest"

    CreateStaffUserResponse:
      $ref: "./components.yaml#/components/schemas/CreateStaffUserResponse"

    GenerateStaffUsernameRequest:
      $ref: "./components.yaml#/components/schemas/GenerateStaffUsernameRequest"

    GenerateStaffUsernameResponse:
      $ref: "./components.yaml#/components/schemas/GenerateStaffUsernameResponse"

    StaffUserItem:
      $ref: "./components.yaml#/components/schemas/StaffUserItem"

    ListStaffRequest:
      $ref: "./components.yaml#/components/schemas/ListStaffRequest"

    ListStaffUsersResponse:
      $ref: "./components.yaml#/components/schemas/ListStaffUsersResponse"

    # ── Station ──────────────────────────────────────────────────────────────
    CreateStationAddressRequest:
      $ref: "./components.yaml#/components/schemas/CreateStationAddressRequest"

    CreateStationRequest:
      $ref: "./components.yaml#/components/schemas/CreateStationRequest"

    CreateStationResponse:
      $ref: "./components.yaml#/components/schemas/CreateStationResponse"

    # ── Config ────────────────────────────────────────────────────────────────
    GetConfigResponse:
      $ref: "./components.yaml#/components/schemas/GetConfigResponse"
    GetStaffInfoRequest:
      $ref: "./components.yaml#/components/schemas/GetStaffInfoRequest"

    GetStaffInfoResponse:
      $ref: "./components.yaml#/components/schemas/GetStaffInfoResponse"