very first commit

docs/API_CHANGES_REQUIRED.md

@@ -0,0 +1,168 @@
+# Backend API Changes Required
+
+## Cart Quantity Support
+
+### 1. Add Quantity to Cart Items
+
+**Current GET /cart Response:**
+```json
+[
+  {
+    "itemID": 123,
+    "name": "Product Name",
+    "price": 100,
+    "currency": "RUB",
+    ...other item fields
+  }
+]
+```
+
+**NEW Required Response:**
+```json
+[
+  {
+    "itemID": 123,
+    "name": "Product Name",
+    "price": 100,
+    "currency": "RUB",
+    "quantity": 2,  // <-- ADD THIS FIELD
+    ...other item fields
+  }
+]
+```
+
+### 2. POST /cart - Add Item to Cart
+
+**Current Request:**
+```json
+{
+  "itemID": 123
+}
+```
+
+**NEW Request (with optional quantity):**
+```json
+{
+  "itemID": 123,
+  "quantity": 1  // Optional, defaults to 1 if not provided
+}
+```
+
+**Behavior:**
+- If item already exists in cart, **increment** the quantity by the provided amount
+- If item doesn't exist, add it with the specified quantity
+
+### 3. PATCH /cart - Update Item Quantity (NEW ENDPOINT)
+
+**Request:**
+```json
+{
+  "itemID": 123,
+  "quantity": 5  // New quantity value (not increment, but absolute value)
+}
+```
+
+**Response:**
+```json
+{
+  "message": "Cart updated successfully"
+}
+```
+
+**Behavior:**
+- Set the quantity to the exact value provided
+- If quantity is 0 or negative, remove the item from cart
+
+### 4. Payment Endpoints - Include Quantity
+
+**POST /payment/create**
+
+Update the items array to include quantity:
+
+**Current:**
+```json
+{
+  "amount": 1000,
+  "currency": "RUB",
+  "items": [
+    {
+      "itemID": 123,
+      "price": 500,
+      "name": "Product Name"
+    }
+  ]
+}
+```
+
+**NEW:**
+```json
+{
+  "amount": 1000,
+  "currency": "RUB",
+  "items": [
+    {
+      "itemID": 123,
+      "price": 500,
+      "name": "Product Name",
+      "quantity": 2  // <-- ADD THIS FIELD
+    }
+  ]
+}
+```
+
+### 5. Email Purchase Confirmation
+
+**POST /purchase-email**
+
+Update items to include quantity:
+
+**NEW:**
+```json
+{
+  "email": "user@example.com",
+  "telegramUserId": "123456",
+  "items": [
+    {
+      "itemID": 123,
+      "name": "Product Name",
+      "price": 500,
+      "currency": "RUB",
+      "quantity": 2  // <-- ADD THIS FIELD
+    }
+  ]
+}
+```
+
+## Future: Filters & Sorting (To Be Discussed)
+
+### GET /category/{categoryID}
+
+Add query parameters for filtering and sorting:
+
+**Proposed Query Parameters:**
+- `sort`: Sort order (e.g., `price_asc`, `price_desc`, `rating_desc`, `name_asc`)
+- `minPrice`: Minimum price filter
+- `maxPrice`: Maximum price filter
+- `minRating`: Minimum rating filter (1-5)
+- `count`: Number of items per page (already exists)
+- `skip`: Offset for pagination (already exists)
+
+**Example:**
+```
+GET /category/5?sort=price_asc&minPrice=100&maxPrice=500&minRating=4&count=20&skip=0
+```
+
+**Response:** Same as current (array of items)
+
+---
+
+## Summary
+
+**Required NOW:**
+1. Add `quantity` field to cart item responses
+2. Support `quantity` parameter in POST /cart
+3. Create new PATCH /cart endpoint for updating quantities
+4. Include `quantity` in payment and email endpoints
+
+**Future (After Discussion):**
+- Sorting and filtering query parameters for category items endpoint