chore: relocate backend into apps/api ahead of monorepo merge

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-27 00:12:54 +08:00 · 2026-08-24 12:20:40 +08:00
parent af44598df6
commit eaa6d2276a
388 changed files with 0 additions and 13998 deletions
@@ -0,0 +1,148 @@
+# Profile Controller Documentation (Admin)
+
+**File:** `controllers/admin/profile.controller.js`  
+**Base URL:** `/api/admin/profile`  
+**Guards:** `authenticate → requireAdmin() → adminLimiter`
+
+---
+
+## Table of Contents
+- [Get Profile](#get-profile)
+- [Update Profile](#update-profile)
+- [Upload Avatar](#upload-avatar)
+- [Delete Avatar](#delete-avatar)
+
+---
+
+## Notes
+
+- All endpoints are self-service — they operate on the **currently authenticated admin** (`req.user.user_id`).
+- `password`, `otp_code`, and `otp_expires_at` are always excluded from responses.
+- Avatar files are stored in S3 via `s3.service`. The old avatar is deleted before upload.
+
+---
+
+## Get Profile
+
+**`GET /api/admin/profile`**
+
+Returns the authenticated admin's full user record.
+
+### Response `200`
+```json
+{
+  "status": "success",
+  "message": "Profile retrieved.",
+  "data": {
+    "user_id": 1,
+    "email": "admin@example.com",
+    "is_active": true,
+    "is_verified": true,
+    "reg_type": "system",
+    "acc_type": "admin",
+    "personal_info": {
+      "name": {
+        "given_name": "Kenneth",
+        "middle_name": null,
+        "last_name": "Obsequio",
+        "extension_name": null,
+        "full_name": "Kenneth Obsequio"
+      },
+      "occupation": null,
+      "addresses": [],
+      "phone_number": [],
+      "date_of_birth": null,
+      "avatar": {
+        "url": "https://...",
+        "uuid": "storage-key",
+        "name": "avatar.jpg",
+        "mime_type": "image/jpeg",
+        "size": 204800
+      }
+    },
+    "createdAt": "2025-10-06T00:00:00.000Z",
+    "updatedAt": "2026-06-18T00:00:00.000Z"
+  }
+}
+```
+
+---
+
+## Update Profile
+
+**`PUT /api/admin/profile`**
+
+Deep-merges `personal_info` — top-level keys and `name` sub-keys are merged separately. Existing keys not present in the request body are preserved.
+
+### Request Body
+```json
+{
+  "personal_info": {
+    "name": {
+      "given_name": "Kenneth",
+      "last_name": "Obsequio"
+    },
+    "occupation": "Software Engineer",
+    "date_of_birth": "1995-05-15"
+  }
+}
+```
+
+### Response `200`
+```json
+{
+  "status": "success",
+  "message": "Profile updated.",
+  "data": { ... }
+}
+```
+
+---
+
+## Upload Avatar
+
+**`POST /api/admin/profile/avatar`**
+
+Uploads (or replaces) the admin's avatar via `multipart/form-data`.
+
+- Old avatar is deleted from S3 before uploading the new one.
+- Avatar metadata is stored in `personal_info.avatar`.
+
+### Request
+`Content-Type: multipart/form-data`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file` | file | **Yes** | Image file (handled by `avatar_upload.middleware`) |
+
+### Response `200`
+```json
+{
+  "status": "success",
+  "message": "Avatar updated.",
+  "data": { ... }
+}
+```
+
+### Error Responses
+| Status | Message |
+|--------|---------|
+| `400` | `No file provided.` |
+
+---
+
+## Delete Avatar
+
+**`DELETE /api/admin/profile/avatar`**
+
+Removes the admin's avatar from S3 and sets `personal_info.avatar` to `null`.
+
+### Response `200`
+```json
+{ "status": "success", "message": "Avatar removed." }
+```
+
+### Error Responses
+| Status | Message |
+|--------|---------|
+| `404` | `No avatar to remove.` |