FAQ

Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. A tela tem duas frentes distintas: uma leitura do FAQ (um único RPC getFaq, com cache write-through) e uma escrita (a mensagem de suporte, que sai pelo Dispatcher). Os dois grafos:Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. The screen has two distinct fronts: a read of the FAQ (a single getFaq RPC, with cache write-through) and a write (the support message, sent through the Dispatcher). Both graphs:Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. La pantalla tiene dos frentes distintos: una lectura del FAQ (un único RPC getFaq, con cache write-through) y una escritura (el mensaje de soporte, que sale por el Dispatcher). Los dos grafos:

Leitura — FAQ (cache write-through)Read — FAQ (cache write-through)Lectura — FAQ (cache write-through)

• FaqReplygRPC proto
  • toFaqDTOFaqDTODTO · Freezed
    • toDomainFaqEntitydomain
      • toModelFaqModelObjectBox
        • toDomainFaqEntitydomain · cache
          • watchFaqNotifier + State
            • → UIFaqPage

Escrita — mensagem de suporte (Dispatcher)Write — support message (Dispatcher)Escritura — mensaje de soporte (Dispatcher)

• FaqPagesubmit
  • submitSupportMessageFaqNotifier
    • build(input)BuildHelpSupportDispatcherPayloadUseCase
      • DispatcherEnvelopeSubmitHelpSupportUseCase
        • dispatchDispatcherOrchestrator
          • gRPCSupportRequestAPIsendTransaction

O mesmo FAQ 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 em quase todas as camadas; muda pouquíssimo (o id dos itens é renomeado no Model, relações viram ToMany, e o lastSyncAt é gerado no mapper). O fetch é write-through: todo retorno é gravado no ObjectBox e a UI passa a ler do cache.The same FAQ 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 across almost all layers; very little changes (item id is renamed in the Model, relations become ToMany, and lastSyncAt is generated in the mapper). Fetch is write-through: every response is written to ObjectBox and the UI then reads from cache.El mismo FAQ 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 en casi todas las capas; cambia muy poco (el id de los ítems se renombra en el Model, las relaciones pasan a ToMany, y el lastSyncAt se genera en el mapper). El fetch es write-through: toda respuesta se graba en ObjectBox y la UI lee del caché.

Tudo chega num container Faq de 4 campos (contactCenter + faqs[] + supportSubjects[] + lastSyncAt), com duas sub-estruturas simples — FaqItem (pergunta/resposta) e SupportSubject (assunto do formulário). Diferente de Pedidos, não há nenhum enum de domínio: todos os campos são String em todas as camadas. A seguir, na ordem: o proto, as estruturas de dados campo-a-campo, e os mappers.Everything arrives in a 4-field Faq container (contactCenter + faqs[] + supportSubjects[] + lastSyncAt), with two simple sub-structures — FaqItem (question/answer) and SupportSubject (form subject). Unlike Orders, there is no domain enum at all: every field is a String across all layers. Next, in order: the proto, the field-by-field data structures, and the mappers.Todo llega en un container Faq de 4 campos (contactCenter + faqs[] + supportSubjects[] + lastSyncAt), con dos sub-estructuras simples — FaqItem (pregunta/respuesta) y SupportSubject (asunto del formulario). A diferencia de Pedidos, no hay ningún enum de dominio: todos los campos son String en todas las capas. A continuación, en orden: el proto, las estructuras de datos campo a campo, y los mappers.

Proto

FaqConectaRep.proto · proto3 · package mn.bat.conectarep.streambridge. Um serviço (FaqConectaRepService), um método unário:One service (FaqConectaRepService), a single unary method:Un servicio (FaqConectaRepService), 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/nome primeiro muda (rename do id no Model, relação ToMany no Model, lastSyncAt gerado no mapper). ¹ = optional 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/name first changes (id rename in the Model, ToMany relation in the Model, lastSyncAt generated in the mapper). ¹ = optional 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/nombre (rename del id en el Model, relación ToMany en el Model, lastSyncAt generado en el mapper). ¹ = optional en el proto.

• Faq raiz 4 campos

  Campo	Proto	DTO	Model	Entity
  contactCenter	string	String	String	String
  faqs	repeated FaqItem	List<…DTO>	ToMany<…Model>	List<…Entity>
  supportSubjects	repeated SupportSubject	List<…DTO>	ToMany<…Model>	List<…Entity>
  lastSyncAt	—	DateTime?	DateTime	DateTime?

  O container é a própria FaqReply no proto (não há message "Faq" separada); vira FaqDTO / FaqModel / FaqEntity. No Model, lastSyncAt é não-nulo (@Property(type: date)).The container is FaqReply itself in the proto (there's no separate "Faq" message); it becomes FaqDTO / FaqModel / FaqEntity. In the Model, lastSyncAt is non-null (@Property(type: date)).El container es la propia FaqReply en el proto (no hay message "Faq" separada); pasa a FaqDTO / FaqModel / FaqEntity. En el Model, lastSyncAt es no-nulo (@Property(type: date)).

  • FaqItem Faq.faqs[] 3 campos

    Campo	Proto	DTO	Model	Entity
    id	string	String	faqItemId	String
    question	string	String	String	String
    answer	string	String	String	String

    id é renomeado para faqItemId no Model porque o ObjectBox reserva id para a chave @Id (int). O mapper reverte para id na volta à Entity.id is renamed to faqItemId in the Model because ObjectBox reserves id for the @Id key (int). The mapper reverts to id back in the Entity.id se renombra a faqItemId en el Model porque ObjectBox reserva id para la clave @Id (int). El mapper revierte a id al volver a la Entity.

  • SupportSubject Faq.supportSubjects[] 2 campos

    Campo	Proto	DTO	Model	Entity
    id	string	String	supportSubjectId	String
    subject	string	String	String	String

    Mesmo rename do id → supportSubjectId no Model, revertido no mapper de volta.Same id → supportSubjectId rename in the Model, reverted in the mapper on the way back.Mismo rename id → supportSubjectId en el Model, revertido en el mapper de vuelta.

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):

FaqRepositoryImpl implementaimplementsimplementa FaqRepositoryInterface e injeta os 3 datasources (mock/local/remote) + ConnectivityService + a flag useMockData + Ref. É só leitura — a escrita da mensagem de suporte não passa por aqui (vai pelo Dispatcher). Método a método:and injects the 3 datasources (mock/local/remote) + ConnectivityService + the useMockData flag + Ref. It is read-only — the support message write does not go through here (it goes through the Dispatcher). Method by method:e inyecta los 3 datasources (mock/local/remote) + ConnectivityService + la flag useMockData + Ref. Es solo lectura — la escritura del mensaje de soporte no pasa por aquí (va por 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 modelo de dados do FAQ não tem nenhum enum de domínio — os campos são todos String/primitivo, sem status nem tipos tipados. O único enum da feature é de estado de UI, no State do Notifier (não trafega no wire):The FAQ data model has no domain enum at all — fields are all String/primitive, no typed status or types. The feature's only enum is a UI-state one, in the Notifier's State (it does not travel on the wire):El modelo de datos del FAQ no tiene ningún enum de dominio — los campos son todos String/primitivo, sin estado ni tipos tipados. El único enum de la feature es de estado de UI, en el State del Notifier (no viaja en el wire):

Um dropdown por UseCase. O de leitura delega ao repository; os dois de escrita compõem a transação de suporte (builder puro + submit pelo Dispatcher). Todos os providers são keepAlive.One dropdown per UseCase. The read one delegates to the repository; the two write ones compose the support transaction (pure builder + submit through the Dispatcher). All providers are keepAlive.Un dropdown por UseCase. El de lectura delega al repository; los dos de escritura componen la transacción de soporte (builder puro + submit por el Dispatcher). Todos los providers son keepAlive.

O FaqNotifier (@riverpod, with AsyncGuard<FaqState>) é o cérebro da tela. O build() observa os 3 UseCases (leitura + builder + submit) e retorna _load(). O State (FaqState, Freezed) é a fonte única de verdade da page: guarda o FAQ (AsyncValue<FaqEntity>) e o estado de cliente (cards abertos, assunto escolhido, texto da descrição, estado do envio). O Notifier concentra toda a lógica de escrita — a page só chama métodos dele.The FaqNotifier (@riverpod, with AsyncGuard<FaqState>) is the screen's brain. build() watches the 3 UseCases (read + builder + submit) and returns _load(). The State (FaqState, Freezed) is the page's single source of truth: it holds the FAQ (AsyncValue<FaqEntity>) and the client state (open cards, chosen subject, description text, submission status). The Notifier owns all write logic — the page only calls its methods.El FaqNotifier (@riverpod, with AsyncGuard<FaqState>) es el cerebro de la pantalla. build() observa los 3 UseCases (lectura + builder + submit) y retorna _load(). El State (FaqState, Freezed) es la fuente única de verdad de la page: guarda el FAQ (AsyncValue<FaqEntity>) y el estado de cliente (tarjetas abiertas, asunto elegido, texto de la descripción, estado del envío). El Notifier concentra toda la lógica de escritura — la page solo llama a sus métodos.

MétodosMethodsMétodos

State disponível para a PageState available to the PageState disponible para la Page

A FaqPage (ConsumerWidget) observa o faqProvider, monta os widgets filhos e escuta a transição do envio (ref.listen) para disparar o ConectaNotice (verde no sucesso, vermelho na falha) e resetar o status. Loading e erro são globais (faqAsync.when). Árvore de composição:FaqPage (ConsumerWidget) watches faqProvider, composes the child widgets and listens to the submission transition (ref.listen) to fire the ConectaNotice (green on success, red on failure) and reset the status. Loading and error are global (faqAsync.when). Composition tree:FaqPage (ConsumerWidget) observa faqProvider, compone los widgets hijos y escucha la transición del envío (ref.listen) para disparar el ConectaNotice (verde en éxito, rojo en fallo) y resetear el status. Loading y error son globales (faqAsync.when). Árbol de composición:

• FaqPage
  • AppPageShell displayBackButton
    • CustomLoadingIndicator loading
    • FailureStateView error → invalidate(faqProvider)
    • CustomPullToRefresh data → refresh()
      • DataLoadInfo lastSyncAt
      • FaqHelpHeaderWidget ícone + título "Ajuda"
      • FaqSectionTitleWidget título "FAQ"
      • FaqListWidget
        • CustomEmptyState lista vazia
        • FaqCardWidget expansível · chevron ↓/↑ · branco quando aberto → toggleExpand
      • FaqSectionTitleWidget título "Suporte"
      • SupportIntroWidget contactCenter + intro
      • SupportSubjectFieldWidget → selectSubject
        • SupportSubjectPickerModalContent modal · ConectaModal → backWithResult(subject.id)
      • SupportDescriptionFieldWidget CustomInput multilinha → updateDescription
      • SupportSubmitButtonWidget CustomButton.filled · enable/loading → submitSupportMessage

O FaqCardWidget é o componente expansível canônico: chevron para baixo fechado / cima aberto e fundo branco quando expandido, com animação de tamanho + fade. O modal de assunto retorna o id via AppRouter.backWithResult.The FaqCardWidget is the canonical expandable component: chevron down closed / up open and a white background when expanded, with a size + fade animation. The subject modal returns the id via AppRouter.backWithResult.El FaqCardWidget es el componente expandible canónico: chevron abajo cerrado / arriba abierto y fondo blanco al expandirse, con animación de tamaño + fade. El modal de asunto devuelve el id vía AppRouter.backWithResult.