update api and add more features

docs/api_auth_controller_plan.md

@@ -0,0 +1,74 @@
+# `AuthController` plan
+
+## Scope
+- **Controller**: `app/Http/Controllers/Api/Auth/AuthController.php`
+- **Purpose**: JWT login, token refresh, current-user lookup, logout.
+- **Primary dependencies**:
+  - `App\Services\Auth\ApiLoginSecurityService` (rate limiting / IP blocking, attempt tracking, response builder)
+  - `PHPOpenSourceSaver\JWTAuth\Facades\JWTAuth` (token issuance/refresh/invalidation)
+  - `Illuminate\Support\Facades\Auth` (current user)
+
+## Routes
+- **Public (no `/v1`)**
+  - `POST /api/login` → `login`
+- **Versioned (`/v1`)**
+  - `POST /api/v1/login` → `login`
+- **Auth prefix (`/v1/auth`)**
+  - `POST /api/v1/auth/login` → `login`
+  - `POST /api/v1/auth/refresh` → `refresh` (middleware: `jwt.auth`)
+  - `POST /api/v1/auth/logout` → `logout` (middleware: `auth:api`)
+  - `GET /api/v1/auth/me` → `me` (middleware: `auth:api`)
+
+## Authentication & authorization
+- **`login`**: public; checks credentials, then issues JWT.
+- **`refresh`**: requires a valid JWT via `jwt.auth`.
+- **`me`/`logout`**: require `auth:api` (JWT/guarded user).
+
+## Request/validation expectations
+- **`login`**:
+  - Accepts JSON or form payload. Extracts `email`, `password`.
+  - Returns `400` if missing.
+  - Normalizes email to lowercase; looks up `User` by case-insensitive email.
+- **`refresh`**:
+  - Expects bearer token in request (handled by `JWTAuth::parseToken()`).
+- **`logout`**:
+  - Attempts JWT invalidation when bearer token looks like a JWT (3 dot-separated segments).
+  - Also deletes `currentAccessToken()` when supported (supports Sanctum-style tokens if present).
+
+## Response shapes
+- **`login` success**: `ApiLoginSecurityService::buildLoginResponse($user, $jwtToken)` (treat as canonical shape).
+- **`login` failures**:
+  - `400`: `{ status:false, message:"Email and password are required." }`
+  - `401`: `{ status:false, message:"Invalid email or password." }`
+  - `403`: `{ status:false, message:"Account suspended. Please reset your password." }`
+  - `429`: `{ status:false, message:"Too many failed attempts..." }`
+- **`refresh` success** (Base API shape):
+  - `{ status:true, message:"Token refreshed.", data:{ access_token, token_type:"bearer", expires_in } }`
+- **`me` success** (Base API shape):
+  - `{ status:true, message:"OK", data:{ id, firstname, lastname, email, class_section_id, class_section_name } }`
+- **`logout` success** (Base API shape):
+  - `{ status:true, message:"Logged out.", data:null }`
+
+## Side effects & security notes
+- Logs IP attempt / failed attempt / successful login via `ApiLoginSecurityService`.
+- Suspended users are rejected **after** verifying credentials (avoids email enumeration by response shape).
+
+## Error handling expectations
+- `refresh`: any exception becomes `401` via `respondError('Token refresh failed.', 401)`.
+- `logout`: JWT invalidation errors are intentionally ignored.
+
+## Test plan (feature)
+- **Login**
+  - Missing email/password → `400`.
+  - Unknown email → `401` and IP attempt logged.
+  - Wrong password → `401` and failed attempt handling invoked.
+  - Suspended user with correct password → `403`.
+  - Successful login returns expected response shape and includes token.
+  - IP blocked → `429`.
+- **Refresh**
+  - Valid token refresh returns new token + expires_in.
+  - Invalid/missing token returns `401`.
+- **Me/Logout**
+  - Requires auth; returns `401` unauthenticated.
+  - Logout returns success even if token invalidation fails.
+