Cart API: add and remove items

[Filipejqueiroga]

The cart is linked to the authenticated user and created automatically the first time they add an item. Each cart item holds a product reference and a quantity. All users (BUYER and SELLER) have access to the cart.

New entities

Cart

Cart
├── id (Long, PK)
└── owner (User, OneToOne, FK → users.id)

CartItem

CartItem
├── id (Long, PK)
├── cart (Cart, ManyToOne, FK → carts.id)
├── product (Product, ManyToOne, FK → products.id)
└── quantity (Integer, required, min = 1

Endpoints

Method	Route	Auth	Description
GET	/api/v1/cart	Required	Returns the user's cart with all items
POST	/api/v1/cart/items	Required	Adds a product or increments quantity if already present
PUT	/api/v1/cart/items/{productId}	Required	Updates the quantity of a cart item
DELETE	/api/v1/cart/items/{productId}	Required	Removes an item from the cart

Business rules

• The cart is created automatically on the first POST /api/v1/cart/items — no separate creation step
• POST /cart/items increments the quantity if the product is already in the cart
• Minimum cart item quantity is 1
• PUT /cart/items/{productId} with quantity 0 removes the item from the cart
• Adding a product that does not exist returns 404
• GET /cart returns each item with: product name, price, quantity, and subtotal (price × quantity)
• The response also includes the cart total (sum of all subtotals)

Acceptance criteria

• POST /api/v1/cart/items adds the product or increments its quantity if already present
• The cart is created automatically if it does not exist yet
• GET /api/v1/cart returns all items with product info, quantity, subtotal per item, and cart total
• PUT /api/v1/cart/items/{productId} correctly updates the quantity
• PUT /api/v1/cart/items/{productId} with quantity 0 removes the item
• DELETE /api/v1/cart/items/{productId} removes the item from the cart
• Adding a non-existent product returns 404
• All endpoints return 401 for unauthenticated requests