ready to test

Testing Signed-off-by: Kenneth Obsequio <k80308392@gmail.com>
2026-09-27 00:12:54 +08:00 · 2026-06-22 10:06:58 +08:00
parent bf48c95467
commit 439bb33f77
189 changed files with 17559 additions and 686 deletions
@@ -0,0 +1,171 @@
+# Categories Controller Documentation
+
+**File:** `controllers/admin/categories.controller.js`  
+**Base URL:** `/api/admin/categories`  
+**Guards:** `authenticate → requireAdmin() → adminLimiter`
+
+---
+
+## Table of Contents
+- [Get All Categories](#get-all-categories)
+- [Get Single Category](#get-single-category)
+- [Create Category](#create-category)
+- [Update Category](#update-category)
+- [Archive Category](#archive-category)
+- [Restore Category](#restore-category)
+
+---
+
+## Notes
+
+- `slug` is auto-generated from `name` on create and update: lowercased, trimmed, non-alphanumeric runs replaced with `-`.
+- `slug` and `name` must be **unique** across all categories (including archived ones).
+- `paranoid: false` is used on GET All and GET One, so archived categories are visible.
+
+---
+
+## Get All Categories
+
+**`GET /api/admin/categories`**
+
+Returns all categories ordered alphabetically by name. Includes archived rows.
+
+### Response `200`
+```json
+{
+  "status": "success",
+  "message": "Categories retrieved.",
+  "data": [
+    {
+      "id": 1,
+      "name": "Business",
+      "slug": "business",
+      "description": "Business courses",
+      "is_active": true,
+      "createdAt": "2026-01-01T00:00:00.000Z",
+      "updatedAt": "2026-01-01T00:00:00.000Z",
+      "deletedAt": null
+    }
+  ]
+}
+```
+
+---
+
+## Get Single Category
+
+**`GET /api/admin/categories/:id`**
+
+Returns one category. Includes archived.
+
+### Response `200`
+```json
+{
+  "status": "success",
+  "message": "Category retrieved.",
+  "data": { "id": 1, "name": "Business", "slug": "business", ... }
+}
+```
+
+### Error Responses
+| Status | Message |
+|--------|---------|
+| `404` | `Category not found.` |
+
+---
+
+## Create Category
+
+**`POST /api/admin/categories`**
+
+### Request Body
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | **Yes** | Display name. Must be unique. |
+| `description` | string | No | Optional description. |
+| `is_active` | boolean | No | Default: `true` |
+
+### Response `201`
+```json
+{
+  "status": "success",
+  "message": "Category created.",
+  "data": { "id": 2, "name": "Design", "slug": "design", "is_active": true, ... }
+}
+```
+
+### Error Responses
+| Status | Message |
+|--------|---------|
+| `400` | `name is required.` |
+| `409` | `A category with that name already exists.` |
+
+---
+
+## Update Category
+
+**`PUT /api/admin/categories/:id`**
+
+Full update. Only non-`null`/`undefined` fields are changed. `slug` is re-generated if `name` changes.
+
+### Request Body
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | No | New display name. |
+| `description` | string | No | |
+| `is_active` | boolean | No | |
+
+### Response `200`
+```json
+{
+  "status": "success",
+  "message": "Category updated.",
+  "data": { ... }
+}
+```
+
+### Error Responses
+| Status | Message |
+|--------|---------|
+| `404` | `Category not found.` |
+| `409` | `A category with that name already exists.` |
+
+---
+
+## Archive Category
+
+**`DELETE /api/admin/categories/:id`**
+
+Soft-deletes the category (`deletedAt` set).
+
+### Response `200`
+```json
+{ "status": "success", "message": "Category archived." }
+```
+
+### Error Responses
+| Status | Message |
+|--------|---------|
+| `404` | `Category not found.` |
+
+---
+
+## Restore Category
+
+**`POST /api/admin/categories/:id/restore`**
+
+Restores a soft-deleted category.
+
+### Response `200`
+```json
+{
+  "status": "success",
+  "message": "Category restored.",
+  "data": { ... }
+}
+```
+
+### Error Responses
+| Status | Message |
+|--------|---------|
+| `404` | `Category not found.` |