Pesquisa Técnica — Add Recommended Item

Contexto

Refinamento da task #193232 — endpoint POST api/payment/v2/{id}/add-recommended-item.

---

Código relevante encontrado

PaymentController

Path: coezzion-service-checkout/src/Checkout.API/Controllers/PaymentController.cs

Endpoints existentes relevantes:

Method	Route	Auth
GET	api/payment/v2/{id}	Sem auth + reCAPTCHA
PUT	api/payment	[Authorize(AuthenticationSchemes = "PaymentsScheme")] + Idempotency key
PUT	api/payment/v2/retry	[Authorize(AuthenticationSchemes = "PaymentsScheme")]
GET	api/payment/v2/status/{id}	[UseApiKey("venda_ai")]
POST	api/payment/check-payment-flow	[UseApiKey("internal")]

O controller usa IZZMediator para despachar todos os commands e queries.

CartController — ausência de add item

Path: coezzion-service-cart/src/Cart.API/Controllers/CartController.cs

Não existe endpoint de add item a cart existente. Itens só são adicionados na criação via POST api/cart com JWT Bearer. Padrão de ApiKey existente: [AllowAnonymous] + [UseApiKey("venda_ai")] no POST api/cart/assistant.

[UseApiKey] lê de IConfiguration["ApiKeys:{configKey}"] e valida o header x-api-key.

CartItemsModel

Path: coezzion-db-core/src/Core.OrgDB/Entities/CartItemsModel.cs

Campos: CartId, ProductId, Quantity, Size, UnitPrice, Discount (DiscountType enum), DiscountValue, GrossPrice, Total.

CartModel.AddItems

Path: coezzion-db-core/src/Core.OrgDB/Entities/CartModel.cs (linha ~199)

public void AddItems(ICollection<CartItemsModel> cartItems)
{
    foreach (var item in cartItems) CartItems.Add(item);
}

GetInfoBase — DTOs de retorno

Path: coezzion-service-checkout/src/Checkout.Domain/DTO/GetInfo/GetInfoBase.cs

Tipos confirmados para o DTO de retorno do novo endpoint:

Tipo	Campos
Values	Products, Discount, DiscountPix, Bonus, Subtotal, SubtotalWhenPix, Shipment, Total, TotalWhenPix
Product	Name, Size, Amount, FullPrice, Price, Total, Url
PaymentMethods	CreditCard, Pix, Boleto, Installments, IsTwoCreditCardsAllowed — recalcula parcelas com base no novo total

Autenticação PaymentsScheme

Esquema JWT customizado já usado em PUT api/payment (FinishOrder) e PUT api/payment/v2/retry. O zzlink já carrega o token desse scheme para operações de finalização — reutilizável para o add item.

ApiKey "internal"

Já existe no PaymentController ([UseApiKey("internal")] no POST api/payment/check-payment-flow). Será reusado na comunicação checkout→cart no novo endpoint da Cart API.

---

Decisões tomadas durante o refinamento

#	Questão	Decisão
1	Onde fica o endpoint?	PaymentController no checkout service
2	Route	POST api/payment/v2/{id}/add-recommended-item
3	Autenticação	[Authorize(AuthenticationSchemes = "PaymentsScheme")]
4	Contrato retorno 200	{ values, products, paymentMethods, recommendedItems } — reusa Values, List<Product>, PaymentMethods, List<RecommendedItemsInfoDTO> de GetInfoBase.cs
5	PaymentMethods recalculado?	Sim — parcelas sempre recalculadas com novo total quando valor do pedido muda
6	Cart API	Nova task separada; endpoint POST api/cart/{cartId}/items; auth [UseApiKey("internal")]
7	Ajuste Payment.Total	Síncrono no handler, após sucesso da Cart API
8	Auditoria alllogs	Log ao tentar + log do resultado; falhas também logadas
9	Janela de validade	Cart.DateCreated + 1 hora — mesma regra do GetInfo
10	Erro sem estoque	Repassa 400 com mensagem + loga na alllogs; sem tratativa adicional no checkout

---

Nova task identificada

Task — Cart API: Add Item a cart existente

• Novo endpoint: POST api/cart/{cartId}/items
• Auth: [UseApiKey("internal")]
• Responsabilidades: validar estoque (usando StoreId do cart), adicionar item, recalcular totais do cart
• Payload recebido: productId, size, discount, discountType, fullPrice, price
• Relacionada à task #193232
• Deve ser aberta como task separada e vinculada a #193232