RecompraBuybackRecompra

Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. A recompra tem leitura e escrita distintas. A leitura (recompras agendadas) usa um único RPC getBuybackCollection com cache write-through. A escrita não tem RPC próprio: passa pelo Dispatcher (DispatcherOrchestrator) como duas transações — solicitação e execução.Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. Buyback has distinct read and write sides. The read (scheduled buybacks) uses a single getBuybackCollection RPC with cache write-through. The write has no proto of its own: it goes through the Dispatcher (DispatcherOrchestrator) as two transactions — request and execution.Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. La recompra tiene lados lectura y escritura distintos. La lectura (recompras agendadas) usa un único RPC getBuybackCollection con cache write-through. La escritura no tiene proto propio: pasa por el Dispatcher (DispatcherOrchestrator) como dos transacciones — solicitud y ejecución.

Leitura — recompras agendadas (write-through)Read — scheduled buybacks (write-through)Lectura — recompras agendadas (write-through)

• BuybackCollectionReplygRPC proto
  • toDTOBuybackCollectionDTODTO · Freezed
    • toEntityBuybackCollectionEntitydomain
      • toModelBuybackCollectionModelObjectBox
        • toEntityBuybackCollectionEntitydomain · cache
          • watchBuybackCollectionNotifier + State
            • → UIBuybackCollectionPage

Escrita — via Dispatcher (duas transações)Write — via Dispatcher (two transactions)Escritura — vía Dispatcher (dos transacciones)

• Draft / Buyback + ActionUI state
  • build()Build…DispatcherPayloadUseCaserequest · execution
    • DispatcherEnvelopeSubmitBuyback…UseCase
      • dispatchDispatcherOrchestratorstore · tracking · retry
        • sendTransactiongRPC · SalesReturnSEN / SalesReturnUplift

O lado de leitura segue as quatro representações — Proto (wire gRPC) → DTO (Freezed) → Model (ObjectBox) → Entity (domínio) — ligadas por mappers, com cache write-through. Muda muito pouco entre camadas: o status vira enum tipado só na Entity, o upliftDate é parseado para DateTime? no Model, e as listas viram relações ToMany.The read side follows the four representations — Proto (gRPC wire) → DTO (Freezed) → Model (ObjectBox) → Entity (domain) — linked by mappers, with cache write-through. Very little changes across layers: status becomes a typed enum only in the Entity, upliftDate is parsed to DateTime? in the Model, and lists become ToMany relations.El lado de lectura sigue las cuatro representaciones — Proto (wire gRPC) → DTO (Freezed) → Model (ObjectBox) → Entity (dominio) — unidas por mappers, con cache write-through. Cambia muy poco entre capas: status pasa a enum tipado solo en la Entity, upliftDate se parsea a DateTime? en el Model, y las listas pasan a relaciones ToMany.

A resposta chega num container BuybackCollectionEntity (lastSyncAt gerado no mapper + accounts[]); cada conta é um BuybackAccount com uma lista de Buyback (9 campos) e seus BuybackItem. O lado de escrita não usa este proto — monta JSON no builder a partir de entities cruas (ver UseCases). A seguir: o proto de leitura, as estruturas campo-a-campo e os mappers.The response arrives in a BuybackCollectionEntity container (lastSyncAt generated in the mapper + accounts[]); each account is a BuybackAccount with a list of Buyback (9 fields) and their BuybackItem. The write side doesn't use this proto — it builds JSON in the builder from raw entities (see UseCases). Next: the read proto, the field-by-field structures and the mappers.La respuesta llega en un container BuybackCollectionEntity (lastSyncAt generado en el mapper + accounts[]); cada cuenta es un BuybackAccount con una lista de Buyback (9 campos) y sus BuybackItem. El lado de escritura no usa este proto — arma JSON en el builder desde entities crudas (ver UseCases). A continuación: el proto de lectura, las estructuras campo a campo y los mappers.

Proto

BuybackCollectionConectaRep.proto · proto3 · package mn.bat.conectarep.streambridge. Um serviço (BuybackCollectionConectaRepService), um método unário:One service (BuybackCollectionConectaRepService), a single unary method:Un servicio (BuybackCollectionConectaRepService), un método unario:

Estruturas de dadosData structuresEstructuras de datos

Um dropdown por estrutura, aninhados pela hierarquia. Cada tabela tem uma coluna por camada — Proto · DTO · Model · Entity; o texto accent marca onde o tipo primeiro muda (enum na Entity, parse de data no Model, relação ToMany no Model, rename no Proto).One dropdown per structure, nested by hierarchy. Each table has one column per layer — Proto · DTO · Model · Entity; the accent text marks where the type first changes (enum in the Entity, date parse in the Model, ToMany relation in the Model, rename in the Proto).Un dropdown por estructura, anidados por jerarquía. Cada tabla tiene una columna por capa — Proto · DTO · Model · Entity; el texto accent marca dónde primero cambia el tipo (enum en la Entity, parse de fecha en el Model, relación ToMany en el Model, rename en el Proto).

• BuybackCollection raiz 2 campos2 fields2 campos

  Campo	Proto	DTO	Model	Entity
  lastSyncAt	—	DateTime	DateTime	DateTime
  accounts	repeated BuybackAccount buybackCollection	List<…DTO>	ToMany<…Model>	List<…Entity>

  • BuybackAccount BuybackCollection.accounts[] 2 campos2 fields2 campos

    Campo	Proto	DTO	Model	Entity
    accountSfid	string	String	String	String
    buybacks	repeated Buyback	List<…DTO>	ToMany<…Model>	List<…Entity>

    • Buyback BuybackAccount.buybacks[] 9 campos9 fields9 campos

      Campo	Proto	DTO	Model	Entity
      sfid	string	String	String	String
      name	string	String	String	String
      status	string	String	String	BuybackStatus
      upliftDate	string	String	DateTime?	DateTime?
      totalItemsQuantity	double	double	double	double
      canAccept	bool	bool	bool	bool
      canReject	bool	bool	bool	bool
      canReschedule	bool	bool	bool	bool
      items	repeated BuybackItem	List<…DTO>	ToMany<…Model>	List<…Entity>

      • BuybackItem Buyback.items[] 3 campos3 fields3 campos

        Campo	Proto	DTO	Model	Entity
        productName	string	String	String	String
        uom	string	String	String	String
        quantity	double	double	double	double

Mappers

As conversões entre as camadas, todas como extension (5 direções por tipo). Aqui o método DTO→Entity e Model→Entity chama-se toEntity() (não toDomain):The conversions between layers, all as extensions (5 directions per type). Here the DTO→Entity and Model→Entity method is toEntity() (not toDomain):Las conversiones entre capas, todas como extension (5 direcciones por tipo). Aquí el método DTO→Entity y Model→Entity se llama toEntity() (no toDomain):

BuybackCollectionRepositoryImpl implementaimplementsimplementa BuybackCollectionRepositoryInterface e injeta os 3 datasources (mock/local/remote) + ConnectivityService + a flag useMock + Ref. É só do lado de leitura — a escrita vive no Dispatcher. Método a método:and injects the 3 datasources (mock/local/remote) + ConnectivityService + the useMock flag + Ref. It's read-only — writes live in the Dispatcher. Method by method:e inyecta los 3 datasources (mock/local/remote) + ConnectivityService + la flag useMock + Ref. Es solo del lado de lectura — la escritura vive en el Dispatcher. Método a método:

Um card por datasource (dropdown). No corpo: método, envio, retorno, fluxo de uso e tratamento de erro.One card per datasource (dropdown). In the body: method, what it sends, return, usage flow and error handling.Un card por datasource (dropdown). En el cuerpo: método, envío, retorno, flujo de uso y manejo de errores.

O status só existe tipado na Entity; em DTO/Model/Proto trafega como String. Lista completa de valores:The status is only typed in the Entity; in DTO/Model/Proto it travels as String. Full value list:El status solo está tipado en la Entity; en DTO/Model/Proto viaja como String. Lista completa de valores:

Um dropdown por UseCase. Os de leitura delegam ao repository; os de escrita seguem o padrão Dispatcher (§36): um builder puro que monta o DispatcherEnvelope a partir de um {X}DispatcherPayloadInput cru, e um submit que despacha pelo orchestrator.One dropdown per UseCase. Read ones delegate to the repository; write ones follow the Dispatcher pattern (§36): a pure builder that assembles the DispatcherEnvelope from a raw {X}DispatcherPayloadInput, and a submit that dispatches via the orchestrator.Un dropdown por UseCase. Los de lectura delegan al repository; los de escritura siguen el patrón Dispatcher (§36): un builder puro que arma el DispatcherEnvelope desde un {X}DispatcherPayloadInput crudo, y un submit que despacha vía el orchestrator.

A feature tem quatro Notifiers de page — um por tela — mais um Provider cross-page que guarda o rascunho da solicitação (§33). Todos recebem só o visitSfid e re-buscam via UseCases; o contexto da visita vem do visitContextProvider.The feature has four page Notifiers — one per screen — plus a cross-page Provider holding the request draft (§33). All take only the visitSfid and re-fetch via UseCases; the visit context comes from visitContextProvider.La feature tiene cuatro Notifiers de page — uno por pantalla — más un Provider cross-page que guarda el borrador de la solicitud (§33). Todos reciben solo el visitSfid y re-buscan vía UseCases; el contexto de la visita viene de visitContextProvider.

NotifiersNotifiersNotifiers

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

Quatro pages, todas ConsumerWidget sobre AppPageShell (com displayBackButton), com loading/erro globais via asyncState.when. Árvores de composição (modais aninhados sob quem os abre):Four pages, all ConsumerWidget over AppPageShell (with displayBackButton), with global loading/error via asyncState.when. Composition trees (modals nested under what opens them):Cuatro pages, todas ConsumerWidget sobre AppPageShell (con displayBackButton), con loading/error globales vía asyncState.when. Árboles de composición (modales anidados bajo quien los abre):

BuybackMenuPage

• BuybackMenuPage
  • AppPageShell back button · data → CustomPullToRefresh
    • CustomLoadingIndicator loading
    • FailureStateView error → invalidate
    • DataLoadInfo lastSyncAt
    • AccountHeaderCard
    • BuybackMenuHeaderWidget
    • BuybackMenuActionsWidget MenuActionGrid
      • Solicitar → goToBuybackRequest
      • Coleta → goToBuybackCollection

BuybackRequestPage → BuybackRequestSummaryPage

• BuybackRequestPage
  • AppPageShell
    • DataLoadInfo · AccountHeaderCard · BuybackRequestHeaderWidget
    • BuybackRequestCategoriesWidget abas → setActiveCategory
    • BuybackRequestFiltersWidget marca + busca → setBrandFilter / setSearchQuery
    • BuybackRequestProductsSectionWidget
      • BuybackRequestProductCard
        • BuybackRequestQuantityControl → BuybackRequest.setQuantity
    • BuybackRequestFooterWidget CustomSummaryBar (itens + total) → goToBuybackRequestSummary
      • BuybackRequestSummaryTableWidget conteúdo expandido
• BuybackRequestSummaryPage
  • AppPageShell
    • DataLoadInfo · AccountHeaderCard · BuybackRequestSummaryHeaderWidget
    • BuybackRequestSummaryProductsWidget itens do rascunho
    • BuybackRequestSummaryFooterWidget quantidades/categoria · data · motivo · Confirmar
      • CustomCalendarModalContent modal · data de coleta → setCollectionDate
      • CustomDropdown<BuybackReasonEntity> → setReasonCode
      • BuybackRequestConfirmModalContent modal · confirma → submit() → SalesReturnSEN

BuybackCollectionPage

• BuybackCollectionPage
  • AppPageShell back button · no drawer
    • NestedScrollView
      • DataLoadInfo · AccountHeaderCard · BuybackCollectionTitleRow
      • BuybackCollectionTabBarWidget all/open/executed/rescheduled → selectTab
      • BuybackCollectionColumnHeaderWidget
      • TabBarView → _BuybackListSection
        • CustomEmptyState tab vazia
        • BuybackCollectionCardWidget expansível (itens) · CustomRadio → toggleSelection
          • SwipeToRevealReschedule canReschedule → CustomCalendarModalContent → rescheduleBuyback → SalesReturnUplift (RS)
    • BuybackCollectionActionButtonsWidget Rejeitar / Aceitar (enable = hasSelection)
      • BuybackExecutionConfirmModalContent modal · confirma → accept/rejectSelected → SalesReturnUplift (F/R)