docs: add topping category API descriptions (reject + get)

product-variant-assign-topping-description.md

@@ -0,0 +1,93 @@
+# Assign Topping To Product Variant API - Description
+
+This document is for **backoffice and chef users** integrating with the Menu Management API to assign a topping to a specific product variant.
+
+The Assign Topping To Product Variant API assigns one topping to one product variant identified by product id and variant SKU. The API validates variant and topping existence, persists the assignment transactionally, appends an outbox event (`product.variant.topping.assigned`), and returns assignment details. On success it returns **200 OK**.
+
+---
+
+## Endpoint
+
+| Method | Path | Content-Type |
+|--------|------|--------------|
+| `POST` | `/vendors/{vendorId}/products/{productId}/variants/{sku}/topping/{toppingId}/assign` | `application/json` |
+
+- **Base URL:** Use your environment base URL.
+- **Controller attributes:** `[ApiController]` and `[Route("vendors/{vendorId:long}/products/{productId:long}/variants")]`
+- **Action route:** `[HttpPost("{sku}/topping/{toppingId:long}/assign")]`
+- **Resolved endpoint path:** `/vendors/{vendorId}/products/{productId}/variants/{sku}/topping/{toppingId}/assign`
+- **Path parameters:** `vendorId` (long), `productId` (long), `sku` (string), `toppingId` (long).
+- **Request body:** none.
+
+---
+
+## Request
+
+This endpoint does not require a request body.
+
+### Path parameter reference
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `vendorId` | number | Yes | Vendor identifier used for topping lookup. |
+| `productId` | number | Yes | Product identifier used with SKU to find variant. |
+| `sku` | string | Yes | Product variant SKU. |
+| `toppingId` | number | Yes | Topping identifier to assign. |
+
+**Business rules:**
+- Product variant must exist for `(productId, sku)`; otherwise request fails with not found.
+- Topping must exist for `(vendorId, toppingId)`; otherwise request fails with not found.
+- Assignment is saved transactionally and outbox event `product.variant.topping.assigned` is emitted.
+
+---
+
+## Sample Request
+
+```http
+POST /vendors/100/products/501/variants/VAR-901/topping/12345/assign
+```
+
+### cURL example
+
+```bash
+curl -X POST "{baseUrl}/vendors/100/products/501/variants/VAR-901/topping/12345/assign" \
+  -H "Accept: application/json"
+```
+
+---
+
+## Responses
+
+### Success - 200 OK
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+```
+
+```json
+{
+  "sku": "VAR-901",
+  "toppingId": 12345,
+  "assignedAt": "2026-03-18T12:15:00Z"
+}
+```
+
+### Error - 404 / 400 / 409 / 500
+
+- **404:** Product variant or topping not found.
+- **400:** Validation error (for example invalid route parameter binding).
+- **409:** Concurrency conflict during transactional save.
+- **500:** Unexpected server error while assigning topping to product variant.
+
+---
+
+## Status codes summary
+
+| Code | Meaning |
+|------|---------|
+| **200** | Topping assigned to product variant successfully. |
+| **404** | Product variant or topping not found. |
+| **400** | Validation failure. |
+| **409** | Concurrency conflict. |
+| **500** | Server error. |

topping-activate-description.md

@@ -0,0 +1,109 @@
+# Activate Topping API - Description
+
+This document is for **backoffice and chef users** integrating with the Menu Management API to activate a topping for a vendor.
+
+The Activate Topping API activates a topping by vendor and topping id. If the topping is already active, the API returns the current topping response without applying changes. If activation is needed, it updates the record, appends an outbox event (`topping.activated`), and returns the updated topping payload. On success it returns **200 OK**.
+
+---
+
+## Endpoint
+
+| Method | Path | Content-Type |
+|--------|------|--------------|
+| `POST` | `/vendors/{vendorId}/toppings/{id}/activate` | `application/json` |
+
+- **Base URL:** Use your environment base URL.
+- **Controller attributes:** `[ApiController]` and `[Route("vendors/{vendorId:long}/toppings")]`
+- **Action route:** `[HttpPost("{id:long}/activate")]`
+- **Resolved endpoint path:** `/vendors/{vendorId}/toppings/{id}/activate`
+- **Path parameters:** `vendorId` (long), `id` (long).
+- **Note:** `vendorId` and `id` from route are applied as source of truth and override request body values.
+
+---
+
+## Request Body
+
+### Field reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | number | Yes | Topping id in payload. Route `id` is applied as source of truth. |
+| `vendorId` | number | Yes | Vendor id in payload. Route `vendorId` is applied as source of truth. |
+
+**Business rules:**
+- Topping must exist for `(id, vendorId)`; otherwise request fails with not found.
+- If `isActive` is already true, current topping response is returned immediately.
+- If inactive, topping is activated and saved transactionally.
+- Outbox event `topping.activated` is emitted when activation is applied.
+
+---
+
+## Sample Request
+
+```http
+POST /vendors/100/toppings/12345/activate
+Content-Type: application/json
+```
+
+```json
+{
+  "id": 12345,
+  "vendorId": 100
+}
+```
+
+### cURL example
+
+```bash
+curl -X POST "{baseUrl}/vendors/100/toppings/12345/activate" \
+  -H "Content-Type: application/json" \
+  -d '{"id":12345,"vendorId":100}'
+```
+
+---
+
+## Responses
+
+### Success - 200 OK
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+```
+
+```json
+{
+  "id": 12345,
+  "name": "Extra Cheese Premium",
+  "vendorId": 100,
+  "signature": "TOP-100-0012345",
+  "price": 30000,
+  "stock": 90,
+  "status": "Active",
+  "approvedBy": 7001,
+  "approvedAt": "2026-03-18T11:30:00Z",
+  "rejectedBy": null,
+  "rejectedAt": null,
+  "rejectionReason": null,
+  "isActive": true
+}
+```
+
+### Error - 400 / 404 / 409 / 500
+
+- **400:** Validation error (invalid payload).
+- **404:** Topping id not found for vendor.
+- **409:** Concurrency conflict during transactional save.
+- **500:** Unexpected server error while activating topping.
+
+---
+
+## Status codes summary
+
+| Code | Meaning |
+|------|---------|
+| **200** | Topping activated successfully (or already active). |
+| **400** | Validation failure. |
+| **404** | Topping not found. |
+| **409** | Concurrency conflict. |
+| **500** | Server error. |

topping-approve-chef-description.md

@@ -0,0 +1,112 @@
+# Approve Topping API (Chef Users) - Description
+
+This document is for **chef users** integrating with the Menu Management API to approve a pending (LQA) topping for a vendor.
+
+The Approve Topping API approves the pending topping version for the given topping id and vendor. If an active base version exists, it is deleted and replaced by the approved pending version. The API appends an outbox event (`topping.approved`) and returns the approved topping payload. On success it returns **200 OK**.
+
+---
+
+## Endpoint
+
+| Method | Path | Content-Type |
+|--------|------|--------------|
+| `POST` | `/vendors/{vendorId}/toppings/{id}/approve` | `application/json` |
+
+- **Base URL:** Use your environment base URL.
+- **Controller attributes:** `[ApiController]` and `[Route("vendors/{vendorId:long}/toppings")]`
+- **Action route:** `[HttpPost("{id:long}/approve")]`
+- **Resolved endpoint path:** `/vendors/{vendorId}/toppings/{id}/approve`
+- **Path parameters:** `vendorId` (long), `id` (long).
+- **Note:** `vendorId` and `id` from route are applied as source of truth and override request body values.
+
+---
+
+## Request Body
+
+### Field reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | number | Yes | Topping id in payload. Route `id` is applied as source of truth. |
+| `vendorId` | number | Yes | Vendor id in payload. Route `vendorId` is applied as source of truth. |
+| `agentUserId` | number | Yes | Chef/backoffice user id performing approval. |
+
+**Business rules:**
+- System loads LQA records by `(vendorId, id)`.
+- At least one record must exist; otherwise request fails with not found.
+- A **Pending** LQA topping must exist for approval.
+- If an **Active** base topping exists, it is deleted during the same transaction.
+- Approved pending topping is updated and outbox event `topping.approved` is emitted.
+
+---
+
+## Sample Request
+
+```http
+POST /vendors/100/toppings/12345/approve
+Content-Type: application/json
+```
+
+```json
+{
+  "id": 12345,
+  "vendorId": 100,
+  "agentUserId": 7001
+}
+```
+
+### cURL example
+
+```bash
+curl -X POST "{baseUrl}/vendors/100/toppings/12345/approve" \
+  -H "Content-Type: application/json" \
+  -d '{"id":12345,"vendorId":100,"agentUserId":7001}'
+```
+
+---
+
+## Responses
+
+### Success - 200 OK
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+```
+
+```json
+{
+  "id": 12345,
+  "name": "Extra Cheese Premium",
+  "vendorId": 100,
+  "signature": "TOP-100-0012345",
+  "price": 30000,
+  "stock": 90,
+  "status": "Active",
+  "approvedBy": 7001,
+  "approvedAt": "2026-03-18T11:30:00Z",
+  "rejectedBy": null,
+  "rejectedAt": null,
+  "rejectionReason": null,
+  "isActive": true
+}
+```
+
+### Error - 400 / 404 / 409 / 500
+
+- **400:** Validation error (invalid payload).
+- **404:** Topping id not found for vendor, or pending LQA topping not found.
+- **409:** Concurrency conflict during transactional save.
+- **500:** Unexpected server error while approving topping.
+
+---
+
+## Status codes summary
+
+| Code | Meaning |
+|------|---------|
+| **200** | Topping approved successfully. |
+| **400** | Validation failure. |
+| **404** | Topping or pending LQA record not found. |
+| **409** | Concurrency conflict. |
+| **500** | Server error. |