Conecta Você

Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. Há dois fluxos distintos: a leitura das aprovações (um RPC, com cache write-through) e a escrita das decisões (aprovar/rejeitar via Dispatcher, duas transações por decisão).Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. There are two distinct flows: the read of the approvals (one RPC, cache write-through) and the write of the decisions (approve/reject via the Dispatcher, two transactions per decision).Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. Hay dos flujos distintos: la lectura de las aprobaciones (un RPC, con cache write-through) y la escritura de las decisiones (aprobar/rechazar vía Dispatcher, dos transacciones por decisión).

Leitura · cache + remotoRead · cache + remoteLectura · caché + remoto

Um único RPC (getConectaVoce) traz os varejos com pendências e os motivos de rejeição. O dado atravessa quatro representações ligadas por mappers, e todo fetch grava no ObjectBox. O detalhe (por varejo) lê só do cache:A single RPC (getConectaVoce) brings the retails with pending items and the reject reasons. Data crosses four representations linked by mappers, and every fetch writes to ObjectBox. The detail (per retail) reads cache-only:Un único RPC (getConectaVoce) trae los puntos de venta con pendientes y los motivos de rechazo. El dato atraviesa cuatro representaciones unidas por mappers, y todo fetch graba en ObjectBox. El detalle (por punto de venta) lee solo del caché:

• ConectaVoceReplygRPC proto
  • toConectaVoceApprovalsDTOConectaVoceApprovalsDTODTO · Freezed
    • toDomainConectaVoceApprovalsEntitydomain
      • toModelConectaVoceApprovalsModelObjectBox
        • toDomainConectaVoceApprovalsEntitydomain · cache
          • watchConectaVoceApprovalsNotifier + State
            • → UIConectaVoceApprovalsPage
              • getCachedAccountByCodeConectaVoceApprovalDetailNotifier→ Detail / Request pages

Escrita · decisão via DispatcherWrite · decision via DispatcherEscritura · decisión vía Dispatcher

Aprovar/rejeitar dispara pelo Dispatcher (gRPC dedicado) duas transações em sequência: primeiro a ação (CVRequestAction), depois o relatório (CVRequestActionReport). Se a primeira falha, a segunda não sai. Ao final, a pendência é removida do cache:Approve/reject fires through the Dispatcher (dedicated gRPC) two transactions in sequence: first the action (CVRequestAction), then the report (CVRequestActionReport). If the first fails, the second doesn't go out. At the end, the pending item is removed from cache:Aprobar/rechazar dispara por el Dispatcher (gRPC dedicado) dos transacciones en secuencia: primero la acción (CVRequestAction), luego el reporte (CVRequestActionReport). Si la primera falla, la segunda no sale. Al final, el pendiente se quita del caché:

• ConectaVoceActionButtonBarWidgetUI
  • confirmAndSubmit…ConectaVoceApprovalDetailNotifierapprove / reject
    • executeSubmitConectaVoceRequestActionUseCase
      • build(input)Build…RequestAction + …Report PayloadUseCase→ 2× DispatcherEnvelope
        • dispatch ×2DispatcherOrchestratorgRPC dispatcher
          • on successremovePendingActionFromCache→ reload state

O dado existe em quatro representações quase idênticas ao longo das camadas — Proto (wire gRPC) → DTO (Freezed) → Model (ObjectBox) → Entity (domínio) — e cada fronteira é atravessada por um mapper. Os nomes se mantêm; muda muito pouco (enums tipados só na Entity, data como DateTime no Model, relações ToMany no Model). O fetch é write-through: todo retorno é gravado no ObjectBox e a UI lê do cache.The data exists in four near-identical representations across the layers — Proto (gRPC wire) → DTO (Freezed) → Model (ObjectBox) → Entity (domain) — and each boundary is crossed by a mapper. Names stay the same; very little changes (enums typed only in the Entity, date typed as DateTime in the Model, ToMany relations in the Model). Fetch is write-through: every response is written to ObjectBox and the UI reads from cache.El dato existe en cuatro representaciones casi idénticas a lo largo de las capas — Proto (wire gRPC) → DTO (Freezed) → Model (ObjectBox) → Entity (dominio) — y cada frontera se cruza con un mapper. Los nombres se mantienen; cambia muy poco (enums tipados solo en la Entity, fecha como DateTime en el Model, relaciones ToMany en el Model). El fetch es write-through: toda respuesta se graba en ObjectBox y la UI lee del caché.

A lista chega num container ConectaVoceApprovals (lastSyncAt gerado no mapper + accounts[] + rejectReasons[]); cada item é um ConectaVoceAccount (o varejo) com uma lista de ConectaVocePendingAction (cada cadastro a aprovar). Os enums só existem tipados na Entity; em Proto/DTO/Model trafegam como String. A seguir, na ordem: o proto, as estruturas de dados campo-a-campo por camada, e os mappers.The list arrives in a ConectaVoceApprovals container (lastSyncAt generated in the mapper + accounts[] + rejectReasons[]); each item is a ConectaVoceAccount (the retail) with a list of ConectaVocePendingAction (each registration to approve). Enums are only typed in the Entity; in Proto/DTO/Model they travel as String. Next, in order: the proto, the field-by-field data structures per layer, and the mappers.La lista llega en un container ConectaVoceApprovals (lastSyncAt generado en el mapper + accounts[] + rejectReasons[]); cada ítem es un ConectaVoceAccount (el punto de venta) con una lista de ConectaVocePendingAction (cada registro a aprobar). Los enums solo están tipados en la Entity; en Proto/DTO/Model viajan como String. A continuación, en orden: el proto, las estructuras de datos campo a campo por capa, y los mappers.

Proto

ConectaVoceConectaRep.proto · proto3 · package mn.bat.conectarep.streambridge. Um serviço (ConectaVoceConectaRepService), um método unário de leitura. A escrita (aprovar/rejeitar) não usa este proto — sai pelo Dispatcher (ver UseCases).One service (ConectaVoceConectaRepService), a single unary read method. Writes (approve/reject) don't use this proto — they go through the Dispatcher (see UseCases).Un servicio (ConectaVoceConectaRepService), un método unario de lectura. La escritura (aprobar/rechazar) no usa este proto — sale por el Dispatcher (ver UseCases).

Estruturas de dadosData structuresEstructuras de datos

Um dropdown por estrutura, aninhados pela hierarquia (as linhas ligam pai e filhos). Cada tabela tem uma coluna por camada — Proto · DTO · Model · Entity; as células com borda marcam onde o tipo primeiro muda (relação ToMany no Model, enum na Entity, data como DateTime no Model, rename no Model). O container não tem proto próprio — vem de ConectaVoceReply + lastSyncAt gerado no mapper.One dropdown per structure, nested by hierarchy (lines link parent and children). Each table has one column per layer — Proto · DTO · Model · Entity; bordered cells mark where the type first changes (ToMany relation in the Model, enum in the Entity, date typed as DateTime in the Model, rename in the Model). The container has no proto of its own — it comes from ConectaVoceReply + lastSyncAt generated in the mapper.Un dropdown por estructura, anidados por jerarquía (las líneas unen padre e hijos). Cada tabla tiene una columna por capa — Proto · DTO · Model · Entity; las celdas con borde marcan dónde primero cambia el tipo (relación ToMany en el Model, enum en la Entity, fecha como DateTime en el Model, rename en el Model). El container no tiene proto propio — viene de ConectaVoceReply + lastSyncAt generado en el mapper.

• ConectaVoceApprovals raiz · container 3 campos3 fields3 campos

  Campo	Proto	DTO	Model	Entity
  lastSyncAt	—	DateTime	DateTime	DateTime
  accounts	repeated ConectaVoceAccount	List<…DTO>	ToMany<…Model>	List<…Entity>
  rejectReasons	repeated string	List<String>	List<String>	List<String>

  • ConectaVoceAccount ConectaVoceApprovals.accounts[] 5 campos5 fields5 campos

    Campo	Proto	DTO	Model	Entity
    accountCode	string	String	String	String
    accountName	string	String	String	String
    accountAddress	string	String	String	String
    totalOfPendingActions	int32	int	int	int
    pendingActions	repeated ConectaVocePendingAction	List<…DTO>	ToMany<…Model>	List<…Entity>

    • ConectaVocePendingAction ConectaVoceAccount.pendingActions[] 8 campos8 fields8 campos

      Campo	Proto	DTO	Model	Entity
      id	string	String	actionId	String
      action	string	String	String	ConectaVocePendingActionType
      name	string	String	String	String
      role	string	String	String	ClerkProgramLayer
      phone	string	String	String	String
      email	string	String	String	String
      taxId	string	String	String	String
      birthdate	string	String?	DateTime?	DateTime?

Mappers

As conversões entre as camadas, todas como extension (5 direções por tipo):The conversions between layers, all as extensions (5 directions per type):Las conversiones entre capas, todas como extension (5 direcciones por tipo):

ConectaVoceApprovalsRepositoryImpl implementaimplementsimplementa ConectaVoceApprovalsRepositoryInterface e injeta os 3 datasources (mock/local/remote) + ConnectivityService + a flag useMockData + Ref. Além da leitura, é o dono da mutação de cache pós-decisão. Método a método:and injects the 3 datasources (mock/local/remote) + ConnectivityService + the useMockData flag + Ref. Beyond the read, it owns the post-decision cache mutation. Method by method:e inyecta los 3 datasources (mock/local/remote) + ConnectivityService + la flag useMockData + Ref. Además de la lectura, es dueño de la mutación de caché post-decisión. 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.

Os enums só existem tipados na camada Entity; em DTO/Model/Proto trafegam como String. Lista completa de valores:Enums are only typed in the Entity layer; in DTO/Model/Proto they travel as String. Full value list:Los enums solo están tipados en la Entity; en DTO/Model/Proto viajan como String. Lista completa de valores:

Um dropdown por UseCase. O de leitura delega ao repository; os de escrita montam e despacham as transações (padrão DispatcherPayloadBuilder, §36). Todos os providers são keepAlive.One dropdown per UseCase. The read one delegates to the repository; the write ones build and dispatch the transactions (DispatcherPayloadBuilder pattern, §36). All providers are keepAlive.Un dropdown por UseCase. El de lectura delega al repository; los de escritura arman y despachan las transacciones (patrón DispatcherPayloadBuilder, §36). Todos los providers son keepAlive.

São três Notifiers, um por área. Cada State (Freezed) é a fonte única de verdade da sua page — agrupamento e seleção são getters do State, não lógica na page.There are three Notifiers, one per area. Each State (Freezed) is its page's single source of truth — grouping and selection are State getters, not page logic.Son tres Notifiers, uno por área. Cada State (Freezed) es la fuente única de verdad de su page — agrupamiento y selección son getters del State, no lógica en la page.

MétodosMethodsMétodos

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

Quatro pages (ConsumerWidget), cada uma com AppPageShell (displayBackButton, sem drawer) e loading/erro globais via .when. Árvore de composição:Four pages (ConsumerWidget), each with AppPageShell (displayBackButton, no drawer) and global loading/error via .when. Composition tree:Cuatro pages (ConsumerWidget), cada una con AppPageShell (displayBackButton, sin drawer) y loading/error globales vía .when. Árbol de composición:

• ConectaVoceHubPage watch conectaVoceHubProvider
  • AppPageShell
    • ConectaVoceHubHeaderWidget DataLoadInfo + título
    • ConectaVoceHubWelcomeWidget headline + prompt
    • ConectaVoceHubActionsWidget MenuActionGrid
      • Aprovações → goToConectaVoceApprovals
      • Desempenho do território if showTerritoryPerformance → launchTerritoryPerformance (URL externa)
• ConectaVoceApprovalsPage watch conectaVoceApprovalsProvider
  • AppPageShell → CustomPullToRefresh → refresh()
    • DataLoadInfo
    • ConectaVoceApprovalsTitleRow
    • _ConectaVoceApprovalsListSection
      • CustomEmptyState !hasAccounts
      • ConectaVoceAccountCardWidget por varejo → goToConectaVoceApprovalDetail
• ConectaVoceApprovalDetailPage watch conectaVoceApprovalDetailProvider(accountCode)
  • AppPageShell → Column
    • Expanded → SingleChildScrollView
      • ConectaVoceApprovalsTitleRow
      • ConectaVoceAccountCardWidget onTap null
      • _InclusionSection / _EditionSection early-return se vazio
        • ConectaVocePendingActionRowWidget CustomRadio → select · linha → goToConectaVoceApprovalRequestDetail
    • ConectaVoceApprovalActionBarWidget enabled = hasSelection
      • ConectaVoceActionButtonBarWidget Rejeitar (outlined) · Aprovar (filled)
        • confirmAndSubmitConectaVoceApproval → ConectaVoceConfirmActionModalContent (aprovar: confirmar · rejeitar: dropdown de motivo) → approve/reject; volta se sem itens
• ConectaVoceApprovalRequestDetailPage reusa o detail provider(accountCode)
  • AppPageShell → SingleChildScrollView
    • ConectaVoceApprovalsTitleRow
    • ConectaVoceReadOnlyFieldWidget ×6 nome · cargo · telefone · e-mail · CPF · nascimento (formatados)
    • ConectaVoceRequestDetailActionBarWidget enabled = true
      • ConectaVoceActionButtonBarWidget → confirmAndSubmit… → volta após decidir

A entrada é a Home: o módulo de Ações mapeia ModuleDetailType.homeModuleConectaVoce → AppRouter.goToConectaVoceHub (EMC-driven, ver Mercados).The entry is Home: the Actions module maps ModuleDetailType.homeModuleConectaVoce → AppRouter.goToConectaVoceHub (EMC-driven, see Markets).La entrada es el Home: el módulo de Acciones mapea ModuleDetailType.homeModuleConectaVoce → AppRouter.goToConectaVoceHub (EMC-driven, ver Mercados).