Carrinho de comprasShopping cartCarrito de compras

Clean Architecture + Riverpod + Freezed + ObjectBox + gRPC. Ao contrário da Lista de pedidos (leitura), o carrinho é estado de escrita client-side: montado no aparelho, persistido só localmente por conta, e enviado como transação. Há duas frentes distintas — a máquina de estado do carrinho (leitura/mutação) e o envio (escrita remota via Dispatcher).Clean Architecture + Riverpod + Freezed + ObjectBox + gRPC. Unlike the read-only Order list, the cart is client-side write state: assembled on-device, persisted locally only per account, and sent as a transaction. There are two distinct fronts — the cart state machine (read/mutate) and submission (remote write via the Dispatcher).Clean Architecture + Riverpod + Freezed + ObjectBox + gRPC. A diferencia de la Lista de pedidos (lectura), el carrito es estado de escritura client-side: armado en el dispositivo, persistido solo localmente por cuenta, y enviado como transacción. Hay dos frentes — la máquina de estado del carrito (lectura/mutación) y el envío (escritura remota vía Dispatcher).

1 · Máquina de estado do carrinho (leitura + mutação)1 · Cart state machine (read + mutate)1 · Máquina de estado del carrito (lectura + mutación)

O cartProvider(accountSfid) é a fonte única do carrinho. Toda mutação vira um CartIntent que passa pelo CartOrchestrator; os totais, os bloqueios e a avaliação de promoção são providers derivados.The cartProvider(accountSfid) is the cart's single source of truth. Every mutation becomes a CartIntent routed through the CartOrchestrator; totals, locks and promotion evaluation are derived providers.El cartProvider(accountSfid) es la fuente única del carrito. Toda mutación se vuelve un CartIntent que pasa por el CartOrchestrator; totales, bloqueos y evaluación de promoción son providers derivados.

• CartIntentadd / remove / promo / payment…
  • Cart.applyCartOrchestrator.applyIntentmutate + evaluate + parcels
    • saveCartRepositoryObjectBox local-only
      • statecartProviderCartEntity? · keepAlive
        • watchcartTotals · cartLock · cartContextderived providers
          • → UIShowcase · Review · Payment

2 · Envio (escrita remota via Dispatcher)2 · Submission (remote write via Dispatcher)2 · Envío (escritura remota vía Dispatcher)

O OrderSubmission quebra o carrinho em splits, monta um envelope por split com o BuildOrderPlacementDispatcherPayloadUseCase e envia em paralelo (Future.wait). O contrato wire está documentado na transação Order Placement.The OrderSubmission breaks the cart into splits, builds one envelope per split with BuildOrderPlacementDispatcherPayloadUseCase and sends them in parallel (Future.wait). The wire contract is documented in the Order Placement transaction.El OrderSubmission divide el carrito en splits, arma un envelope por split con BuildOrderPlacementDispatcherPayloadUseCase y los envía en paralelo (Future.wait). El contrato wire está documentado en la transacción Order Placement.

• OrderPaymentFooterConfirmar
  • notifier.submitOrderSubmission.submitsplits + status + envelopes
    • buildBuildOrderPlacementDispatcherPayloadUseCaseDispatcherEnvelope
      • submitSubmitOrderUseCase → DispatcherOrchestratorsendTransaction
        • on all ACKCart.clear+ OrderConfirmation

Últimos pedidos é a exceção de leitura: usa o mesmo OrderRepository da Lista de pedidos (proto OrderConectaRep, RPC getOrderList) via GetOrdersForAccountUseCase / LoadOlderOrdersForAccountUseCase.Last orders is the read exception: it uses the Order list's OrderRepository (proto OrderConectaRep, RPC getOrderList) via GetOrdersForAccountUseCase / LoadOlderOrdersForAccountUseCase.Últimos pedidos es la excepción de lectura: usa el OrderRepository de la Lista de pedidos (proto OrderConectaRep, RPC getOrderList) vía GetOrdersForAccountUseCase / LoadOlderOrdersForAccountUseCase.

O carrinho não tem proto nem DTO — é estado de escrita nascido no aparelho, não um dado que chega do backend. Existe em duas representações ligadas por um mapper: Entity (domínio, fonte da verdade em runtime) e Model (ObjectBox, persistência local). O CartRepository grava/lê por accountSfid — cada varejo tem, no máximo, um carrinho salvo. Só no envio o carrinho vira JSON de wire, e isso mora no builder do Dispatcher (ver Order Placement), não aqui.The cart has no proto and no DTO — it is write state born on-device, not data arriving from the backend. It exists in two representations linked by a mapper: Entity (domain, runtime source of truth) and Model (ObjectBox, local persistence). The CartRepository reads/writes by accountSfid — each retail has at most one saved cart. Only at submission does the cart become wire JSON, and that lives in the Dispatcher builder (see Order Placement), not here.El carrito no tiene proto ni DTO — es estado de escritura nacido en el dispositivo, no un dato que llega del backend. Existe en dos representaciones unidas por un mapper: Entity (dominio, fuente de verdad en runtime) y Model (ObjectBox, persistencia local). El CartRepository lee/graba por accountSfid — cada punto de venta tiene como máximo un carrito guardado. Solo en el envío el carrito se vuelve JSON de wire, y eso vive en el builder del Dispatcher (ver Order Placement), no aquí.

A raiz é o Cart (11 campos), com itens, promoções aplicadas, spot promotions aplicadas e o pagamento. Os enums só existem tipados na Entity; no Model trafegam como String. As relações viram ToMany no Model. O sub-objeto de pagamento (CartPayment) é achatado no Model (método vira String; as parcelas sobem para uma ToMany no CartModel). Campos avaliados em runtime (replenishments, promotionLink) não têm caixa própria no ObjectBox. A seguir: as estruturas campo-a-campo, os value objects só-domínio da avaliação, e os mappers.The root is Cart (11 fields), with items, applied promotions, applied spot promotions and payment. Enums are only typed in the Entity; in the Model they travel as String. Relations become ToMany in the Model. The payment sub-object (CartPayment) is flattened in the Model (method becomes a String; parcels lift into a ToMany on CartModel). Runtime-evaluated fields (replenishments, promotionLink) have no ObjectBox box of their own. Next: the field-by-field structures, the domain-only evaluation value objects, and the mappers.La raíz es Cart (11 campos), con ítems, promociones aplicadas, spot promotions aplicadas y el pago. Los enums solo están tipados en la Entity; en el Model viajan como String. Las relaciones pasan a ToMany en el Model. El sub-objeto de pago (CartPayment) está aplanado en el Model (método pasa a String; las cuotas suben a una ToMany en el CartModel). Campos evaluados en runtime (replenishments, promotionLink) no tienen caja propia en ObjectBox. A continuación: las estructuras campo a campo, los value objects solo-dominio de la evaluación, y los mappers.

Estruturas de dadosData structuresEstructuras de datos

Um dropdown por estrutura, aninhados pela hierarquia. Duas colunas de camada — Model · Entity (Entity última). O delta (texto accent) marca onde o tipo diverge: enum tipado → Entity; relação → ToMany no Model.One dropdown per structure, nested by hierarchy. Two layer columns — Model · Entity (Entity last). The delta (accent text) marks where the type diverges: typed enum → Entity; relation → ToMany in the Model.Un dropdown por estructura, anidados por jerarquía. Dos columnas de capa — Model · Entity (Entity última). El delta (texto accent) marca dónde diverge el tipo: enum tipado → Entity; relación → ToMany en el Model.

• Cart raiz 11 campos

  Campo	Model	Entity
  accountSfid	String	String
  cartHash	String	String
  deliveryDate	String	String
  payment	flat (paymentMethod + parcels)	CartPaymentEntity
  items	ToMany<CartItemModel>	List<CartItemEntity>
  appliedPromotions	ToMany<…Model>	List<AppliedPromotionEntity>
  appliedSpotPromotions	ToMany<…Model>	List<AppliedSpotPromotionEntity>
  isFoldCart	bool	bool
  isPromptOrder	bool	bool
  orderId	String	String
  replenishments	—	List<OrderLockEntity>

  • CartItem Cart.items[] 6 campos

    Campo	Model	Entity
    productSfid	String	String
    quantity	double	double
    type	String	CartItemType
    promotionLink	flat (int fields)	CartItemPromotionLink?
    batchAllocations	ToMany<…Model>	List<…Entity>
    orderLineItemSfid	String?	String?

    • CartItemPromotionLink CartItem.promotionLink 4 campos

      Campo	Model	Entity
      promotionId	int	int
      isSpotPromotion	bool	bool
      rewardIndex	int?	int?
      rewardDetailIndex	int?	int?

    • CartItemBatchAllocation CartItem.batchAllocations[] 2 campos

      Campo	Model	Entity
      batchId	String	String
      quantity	double	double

  • CartPayment Cart.payment · achatado no Model 3 campos

    Campo	Model	Entity
    method	String (CartModel.paymentMethod)	String
    parcels	ToMany<ParcelModel> (no CartModel)	List<ParcelEntity>
    creditNote	flat (sfid + value)	CartCreditNoteEntity?

    • Parcel CartPayment.parcels[] 9 campos

      Campo	Model	Entity
      parcelSfid	String	String
      price	double	double
      percentage	double	double
      dueDate	DateTime?	DateTime?
      paymentMethod	String	String
      creditDays	double	double
      internalPixKey	String	String
      bankPixKey	String	String
      wasEdited	bool	bool

    • CartCreditNote CartPayment.creditNote 2 campos

      Campo	Model	Entity
      sfid	String	String
      value	double	double

  • AppliedPromotion Cart.appliedPromotions[] 6 campos

    Campo	Model	Entity
    promotionId	int	int
    isApplied	bool	bool
    achievedLevel	int	int
    selectedReward	flat (int fields)	RewardSelection?
    isAvailable	bool	bool
    isTargetAchieved	bool	bool

  • AppliedSpotPromotion Cart.appliedSpotPromotions[] 2 campos

    Campo	Model	Entity
    spotPromotionId	int	int
    isApplied	bool	bool

Value objects de avaliação (só domínio)Evaluation value objects (domain-only)Value objects de evaluación (solo dominio)

Não persistem, não têm proto/mapper — são calculados a cada mutação pelo CartOrchestrator e expostos por providers derivados:These do not persist and have no proto/mapper — they are computed on every mutation by the CartOrchestrator and exposed by derived providers:No persisten, no tienen proto/mapper — se calculan en cada mutación por el CartOrchestrator y se exponen por providers derivados:

Mappers

Só duas direções (sem proto/DTO), como extension. Há ainda um mapper especial de edição:Only two directions (no proto/DTO), as extensions. There is also a special edit mapper:Solo dos direcciones (sin proto/DTO), como extension. Hay además un mapper especial de edición:

CartRepositoryImpl implementaimplementsimplementa CartRepositoryInterface e injeta apenas o CartLocalDataSource. É local-only — não há mock nem remote: o carrinho é escrita client-side, o envio ao backend é responsabilidade do Dispatcher.and injects only CartLocalDataSource. It is local-only — no mock, no remote: the cart is client-side write state; sending to the backend is the Dispatcher's job.e inyecta solo CartLocalDataSource. Es local-only — sin mock ni remote: el carrito es escritura client-side; el envío al backend es responsabilidad del Dispatcher.

Um só datasource — nada de mock/remote (o carrinho nunca é buscado do backend).A single datasource — no mock/remote (the cart is never fetched from the backend).Un solo datasource — sin mock/remote (el carrito nunca se busca del backend).

Um dropdown por enum, todos os valores, um por linha. Códigos de wire ficam crus.One dropdown per enum, all values, one per line. Wire codes stay raw.Un dropdown por enum, todos los valores, uno por línea. Los códigos de wire quedan crudos.

A lógica não vive na Page nem no Notifier: fica em UseCases puros orquestrados pelo CartOrchestrator (o motor do carrinho) mais os UseCases de gate e envio.Logic lives neither in the Page nor the Notifier: it sits in pure UseCases orchestrated by the CartOrchestrator (the cart engine) plus the gate and submission UseCases.La lógica no vive en la Page ni en el Notifier: está en UseCases puros orquestados por el CartOrchestrator (el motor del carrito) más los UseCases de gate y envío.

O CartOrchestrator apoia-se em ~20 UseCases pequenos em usecases/cart/ (pricing, meio-pack, parcelas, splits, lock rules, credit note, aprovação…) e no motor de promoções (usecases/promotion/). Cada mutação é composição pura desses UseCases.The CartOrchestrator leans on ~20 small UseCases in usecases/cart/ (pricing, half-pack, parcels, splits, lock rules, credit note, approval…) and the promotion engine (usecases/promotion/). Each mutation is a pure composition of these.El CartOrchestrator se apoya en ~20 UseCases pequeños en usecases/cart/ (pricing, medio-pack, cuotas, splits, lock rules, credit note, aprobación…) y el motor de promociones (usecases/promotion/). Cada mutación es composición pura de estos.

O carrinho é estado cross-page, então mora em Providers (não em Notifier de página — CLAUDE.md §33). As 5 telas têm cada uma seu Notifier de página, que só compõe o State a partir dos providers de cart + catálogo.The cart is cross-page state, so it lives in Providers (not a page Notifier — CLAUDE.md §33). The 5 screens each have their own page Notifier, which only composes State from the cart + catalog providers.El carrito es estado cross-page, por eso vive en Providers (no en Notifier de página — CLAUDE.md §33). Las 5 pantallas tienen cada una su Notifier de página, que solo compone el State desde los providers de cart + catálogo.

Providers transversais do carrinhoCross-page cart providersProviders transversales del carrito

Notifiers de páginaPage notifiersNotifiers de página

State disponível para as PagesState available to the PagesState disponible para las Pages

Cinco Pages, todas em AppPageShell com pull-to-refresh e rodapé/barra fixa. Modais aninhados sob o widget que os abre.Five Pages, all in AppPageShell with pull-to-refresh and a sticky footer/bar. Modals nested under the widget that opens them.Cinco Pages, todas en AppPageShell con pull-to-refresh y pie/barra fija. Modales anidados bajo el widget que los abre.

• ProductShowcasePage visitSfid
  • DataLoadInfo · AccountHeaderCard · OrderPlacementDeliveryPill
  • ProductShowcaseTabsWidget
  • ProductShowcaseFiltersWidget
  • ProductShowcasePromotionsSectionWidget
  • ProductShowcaseProductsSectionWidget loadMore ao rolar
  • ProductShowcaseStickyFooterWidget CustomSummaryBar → goToCartReview
    • ProductShowcaseSummaryModalContent resumo do carrinho (expandido)
    • OrderPlacementClearCartConfirmModalContent confirmar limpar
• CartReviewPage accountSfid · listen cart→back se esvaziou
  • DataLoadInfo · AccountHeaderCard · OrderPlacementCheckoutStepper(cart) · DeliveryPill
  • CartReviewPromotionsSectionWidget
  • CartReviewYourRequestSectionWidget
  • CartReviewBonusSectionWidget
  • CartReviewTotalsWidget · CartReviewLockWarningWidget
  • CartReviewFooterWidget Limpar / Pagamento (gate cartToPayment)
    • OrderPlacementClearCartConfirmModalContent
• OrderPaymentPage accountSfid · listen cart→back
  • DataLoadInfo · AccountHeaderCard · Stepper(payment) · DeliveryPill
  • OrderPaymentSplitBlockWidget × nº de splits
  • OrderPaymentDetailsSectionWidget
  • OrderPaymentFooterWidget Voltar / Confirmar (gate paymentToSubmit)
    • OrderSubmissionProgressModalContent progresso por split; onStart → notifier.submit; sucesso → goToOrderConfirmation
• OrderConfirmationPage accountSfid · PopScope canPop:false
  • DataLoadInfo · AccountHeaderCard · Stepper(finish)
  • OrderConfirmationSplitBlockWidget × pedido enviado
  • OrderConfirmationFooterWidget Continuar → visit detail (create) / root (edit)
• LastOrdersPage accountSfid
  • DataLoadInfo · LastOrdersHeaderWidget
  • LastOrdersListWidget
    • LastOrdersLoadOlderWidget carregar mais antigos