Gestão financeiraFinancial managementGestión financiera

Clean Architecture + Riverpod + Freezed + ObjectBox. São dois fluxos distintos: a leitura, que enche um agregado único no cache e serve as quatro telas a partir dele, e a escrita do comprovante de pagamento, que sai direto pelo Dispatcher sem gravar nada local.Clean Architecture + Riverpod + Freezed + ObjectBox. There are two distinct flows: the read, which fills a single aggregate in cache and serves all four screens from it, and the write of the proof of payment, which goes straight out through the Dispatcher without persisting anything locally.Clean Architecture + Riverpod + Freezed + ObjectBox. Hay dos flujos distintos: la lectura, que llena un agregado único en el caché y sirve las cuatro pantallas desde ahí, y la escritura del comprobante de pago, que sale directo por el Dispatcher sin grabar nada local.

Leitura · um agregado, quatro telasRead · one aggregate, four screensLectura · un agregado, cuatro pantallas

Um único RPC traz todos os títulos, bancos, pagamentos e notas de crédito do mercado — não há request por varejo. O retorno é gravado em FinancialManagementModel (linha única, write-through) e daí em diante cada tela recorta o que precisa em memória: por accountSfid no hub, por sfid nos detalhes. O locationHierarchySfid é resolvido dentro do repository a partir do currentResourceProvider.A single RPC brings every debit item, bank, payment and credit note in the market — there is no per-retail request. The response is written into FinancialManagementModel (single row, write-through) and from then on each screen slices what it needs in memory: by accountSfid on the hub, by sfid on the details. The locationHierarchySfid is resolved inside the repository from currentResourceProvider.Un único RPC trae todos los documentos, bancos, pagos y notas de crédito del mercado — no hay request por punto de venta. La respuesta se graba en FinancialManagementModel (fila única, write-through) y de ahí en adelante cada pantalla recorta lo que necesita en memoria: por accountSfid en el hub, por sfid en los detalles. El locationHierarchySfid se resuelve dentro del repository a partir de currentResourceProvider.

• FinancialManagementConectaRepServicegetFinancialManagement · gRPC
  • toDTOFinancialManagementRemoteDataSource
    • toDomain + saveFinancialManagementFinancialManagementRepositoryImplwrite-through · fallback pro cache
      • put (linha única)FinancialManagementModelObjectBox · 8 boxes
        • getCached*GetFinancialManagementUseCase+ GetDebitOpenItemsForAccount · GetCreditNotesForAccount
          • recorte por accountFinancialManagementNotifier
            • → UIFinancialManagementPage
          • getCachedDebitOpenItemBySfidDebitOpenItemDetailNotifier+ Order · Visit · PaymentRegisters
            • → UIDebitOpenItemDetailPage
          • getCachedCreditNoteBySfidCreditNoteDetailNotifier+ Retail · Orders (gate de link)
            • → UICreditNoteDetailPage

A nota fiscal fica fora dessa cadeia: ela não existe no proto de gestão financeira. O InvoiceDetailNotifier lê o cache de pedidos (GetOrdersUseCase.getCachedBySfid) e trabalha sobre order.invoice — por isso o link para a nota fiscal só existe quando o pedido está no cache local.The invoice sits outside that chain: it doesn't exist in the financial management proto. InvoiceDetailNotifier reads the orders cache (GetOrdersUseCase.getCachedBySfid) and works over order.invoice — which is why the invoice link only exists when the order is in the local cache.La factura queda fuera de esa cadena: no existe en el proto de gestión financiera. El InvoiceDetailNotifier lee el caché de pedidos (GetOrdersUseCase.getCachedBySfid) y trabaja sobre order.invoice — por eso el link a la factura solo existe cuando el pedido está en el caché local.

• OrdersModelObjectBox · cache de pedidos
  • getCachedBySfid + getCachedGetOrdersUseCase
    • order.invoice (BusinessFailure se ausente)InvoiceDetailNotifier
      • → UIInvoiceDetailPage

Escrita · comprovante de pagamentoWrite · proof of paymentEscritura · comprobante de pago

A única escrita da feature. O widget só aciona o método do Notifier; o Notifier reúne as entities cruas (título, pedido, visita, representante), resolve os base64 dos arquivos e o relógio (submittedAt), e o builder faz toda a construção wire. Não há registro local: o envelope vai ao Dispatcher e a falha volta como Failure para o widget mostrar o aviso.The feature's only write. The widget merely calls the Notifier's method; the Notifier gathers the raw entities (debit item, order, visit, rep), resolves the files' base64 and the clock (submittedAt), and the builder does all the wire construction. There is no local register: the envelope goes to the Dispatcher and a failure comes back as a Failure for the widget to show the notice.La única escritura de la feature. El widget solo llama al método del Notifier; el Notifier reúne las entities crudas (documento, pedido, visita, representante), resuelve los base64 de los archivos y el reloj (submittedAt), y el builder hace toda la construcción wire. No hay registro local: el envelope va al Dispatcher y la falla vuelve como Failure para que el widget muestre el aviso.

• DebitOpenItemDetailProofOfPaymentWidgetUI · Enviar comprovante
  • submitProofOfPayment()DebitOpenItemDetailNotifiercurrentResourceProvider · readAsBase64 · DateTimeUtils.now()
    • build(input)BuildFinancialProofPaymentDispatcherPayloadUseCaseFinancialProofPaymentDispatcherPayloadInput
      • submit(envelope)SubmitFinancialProofPaymentUseCase
        • dispatchFinancialProofPaymentAPIDispatcherOrchestrator · batchApi
          • Success → limpa arquivos · Error → ConectaNoticeDebitOpenItemDetailStatesem persistência local

O mesmo dado financeiro 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 dos campos se mantêm em todas as camadas; muda pouco (enums tipados, datas parseadas, relações, campos vazios virando nulos). O fetch é write-through: todo retorno é gravado no ObjectBox e as quatro telas passam a ler do cache.The same financial 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. Field names stay the same across layers; little changes (typed enums, parsed dates, relations, empty fields becoming null). Fetch is write-through: every response is written to ObjectBox and the four screens then read from cache.El mismo dato financiero 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 de los campos se mantienen en todas las capas; cambia poco (enums tipados, fechas parseadas, relaciones, campos vacíos que se vuelven nulos). El fetch es write-through: toda respuesta se graba en ObjectBox y las cuatro pantallas leen del caché.

Tudo chega num agregado único, FinancialManagementEntity: lastSyncAt (gerado no mapper de fronteira, o backend não envia), a flag isProofOfPaymentMandatory e quatro listas irmãs — títulos em aberto (18 campos cada), bancos (com agências), pagamentos e notas de crédito (com origem e pedidos aplicados). No ObjectBox ele vira uma linha única com quatro ToMany, e gravar significa limpar as oito boxes e regravar tudo. Os enums só existem tipados na Entity; em Proto/DTO/Model trafegam como String. A seguir, na ordem: o proto que transporta tudo, as estruturas de dados campo-a-campo por camada, os mappers que ligam as camadas e o resumo dos deltas.Everything arrives in a single aggregate, FinancialManagementEntity: lastSyncAt (generated in the boundary mapper — the backend doesn't send it), the isProofOfPaymentMandatory flag and four sibling lists — open debit items (18 fields each), banks (with branches), payments and credit notes (with origin and applied orders). In ObjectBox it becomes a single row with four ToMany, and saving means clearing the eight boxes and rewriting everything. Enums are only typed in the Entity; in Proto/DTO/Model they travel as String. Next, in order: the proto that carries it all, the field-by-field data structures per layer, the mappers that link the layers and the delta summary.Todo llega en un agregado único, FinancialManagementEntity: lastSyncAt (generado en el mapper de frontera, el backend no lo envía), la flag isProofOfPaymentMandatory y cuatro listas hermanas — documentos abiertos (18 campos cada uno), bancos (con sucursales), pagos y notas de crédito (con origen y pedidos aplicados). En ObjectBox se vuelve una fila única con cuatro ToMany, y grabar significa limpiar las ocho boxes y regrabar todo. Los enums solo están tipados en la Entity; en Proto/DTO/Model viajan como String. A continuación, en orden: el proto que transporta todo, las estructuras de datos campo a campo por capa, los mappers que unen las capas y el resumen de los deltas.

Proto

FinancialManagementConectaRep.proto · proto3 · package mn.bat.conectarep.streambridge. Um serviço (FinancialManagementConectaRepService) com três métodos unários — um de leitura do agregado e dois do link de pagamento:One service (FinancialManagementConectaRepService) with three unary methods — one reading the aggregate and two for the payment link:Un servicio (FinancialManagementConectaRepService) con tres métodos unarios — uno de lectura del agregado y dos del link de pago:

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; o texto em destaque marca onde o tipo primeiro muda (vazio→nulo no DTO, relação ToMany/ToOne e data parseada no Model, enum tipado na Entity). ¹ = optional no proto.One dropdown per structure, nested by hierarchy (lines link parent and children). Each table has one column per layer — Proto · DTO · Model · Entity; the highlighted text marks where the type first changes (empty→null in the DTO, ToMany/ToOne relation and parsed date in the Model, typed enum in the Entity). ¹ = optional in the proto.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; el texto destacado marca dónde primero cambia el tipo (vacío→nulo en el DTO, relación ToMany/ToOne y fecha parseada en el Model, enum tipado en la Entity). ¹ = optional en el proto.

• FinancialManagement raiz · linha única no ObjectBoxsingle ObjectBox rowfila única en ObjectBox 6 camposfieldscampos

  Campo	Proto	DTO	Model	Entity
  lastSyncAt	—	DateTime	DateTime	DateTime
  debitOpenItems	repeated DebitOpenItem	List<…DTO>	ToMany<…Model>	List<…Entity>
  banks	repeated Bank	List<…DTO>	ToMany<…Model>	List<…Entity>
  payments	repeated Payment	List<…DTO>	ToMany<…Model>	List<…Entity>
  creditNotes	repeated CreditNote	List<…DTO>	ToMany<…Model>	List<…Entity>
  isProofOfPaymentMandatory	bool	bool	bool	bool

  • DebitOpenItem debitOpenItems[] 18 camposfieldscampos

    Campo	Proto	DTO	Model	Entity
    debitOpenItemSfid	string	String	String	String
    accountSfid	string	String	String	String
    name	string	String	String	String
    price	double	double	double	double
    status	string	String	String	DebitOpenItemStatus
    type	string	String	String	String
    overdue	bool	bool	bool	bool
    date	string	String	DateTime?	DateTime
    invoiceSfid	string	String?	String?	String?
    openDays	int32	int	int	int
    inDispute	bool	bool	bool	bool
    creditPeriod¹	double	double?	double?	double?
    orderSfid	string	String	String	String
    resourceType	string	String	String	ResourceType
    invoiceNumber	string	String?	String?	String?
    invoiceName	string	String?	String?	String?
    paymentLinkStatus	string	String	String	PaymentLinkStatus
    deliveryStatus	string	String	String	DeliveryStatus

  • Bank banks[] 3 camposfieldscampos

    Campo	Proto	DTO	Model	Entity
    sfid	string	String	String	String
    name	string	String	String	String
    branches	repeated BankBranch	List<…DTO>	ToMany<…Model>	List<…Entity>

    • BankBranch bank.branches[] 2 camposfieldscampos

      Campo	Proto	DTO	Model	Entity
      sfid	string	String	String	String
      name	string	String	String	String

  • Payment payments[] · espelho do backend, só leiturabackend mirror, read onlyespejo del backend, solo lectura 10 camposfieldscampos

    Campo	Proto	DTO	Model	Entity
    sfid	string	String	String	String
    debitOpenItemSfid	string	String	String	String
    accountSfid	string	String	String	String
    invoiceSfid	string	String	String	String
    paymentMethod	string	String	String	String
    collectionReference	string	String	String	String
    payedAmount	double	double	double	double
    paymentDate	string	String	DateTime?	DateTime
    status	string	String	String	String
    paymentSource	string	String	String	PaymentSource

  • CreditNote creditNotes[] 10 camposfieldscampos

    Campo	Proto	DTO	Model	Entity
    sfid	string	String	String	String
    retailerId	string	String	String	String
    referenceNumber	string	String	String	String
    amount	double	double	double	double
    date	string	String	DateTime?	DateTime
    isUsed	bool	bool	bool	bool
    availableAmount	double	double	double	double
    creditNoteType	string	String	String	CreditNoteType
    origin¹	CreditNoteOrigin	…DTO?	2 × ToOne	…Entity?
    appliedOrders	repeated CreditNoteOrderReference	List<…DTO>	ToMany<…Model>	List<…Entity>

    • CreditNoteOrigin creditNote.origin · achatado no Modelflattened in the Modelachatado en el Model 2 camposfieldscampos

      Campo	Proto	DTO	Model	Entity
      cnap¹	CreditNoteCnapOrigin	…DTO?	ToOne cnapOrigin	…Entity?
      salesReturn¹	CreditNoteOrderReference	…DTO?	ToOne salesReturnOrigin	…Entity?

      • CreditNoteCnapOrigin origin.cnap · excedente de pagamentopayment overpaymentexcedente de pago 7 camposfieldscampos

        Campo	Proto	DTO	Model	Entity
        dpiName	string	String	String	String
        totalDue	double	double	double	double
        totalPaid	double	double	double	double
        difference	double	double	double	double
        paymentMethod	string	String	String	String
        orderSfid	string	String	String	String
        invoiceName	string	String	String	String

      • CreditNoteOrderReference origin.salesReturn eandy appliedOrders[] 7 camposfieldscampos

        Campo	Proto	DTO	Model	Entity
        orderSfid	string	String	String	String
        invoiceName	string	String	String	String
        poNumber	string	String	String	String
        retailerPoNumber	string	String	String	String
        source	string	String	String	String
        resource	string	String	String	String
        paymentMethod	string	String	String	String

        Toda navegação de referência de pedido — tanto em origin.salesReturn quanto em cada item de appliedOrders — é feita por orderSfid, nunca por um sfid de nota fiscal. O invoiceName serve apenas de rótulo do card.All order-reference navigation — both in origin.salesReturn and in each appliedOrders item — is done by orderSfid, never by an invoice sfid. invoiceName is only the card's label.Toda navegación de referencia de pedido — tanto en origin.salesReturn como en cada ítem de appliedOrders — se hace por orderSfid, nunca por un sfid de factura. El invoiceName sirve solo de etiqueta del card.

A mesma classe de Model (CreditNoteOrderReferenceModel) serve os dois papéis — o ToOne da origem por devolução e o ToMany dos pedidos aplicados. E não existe CreditNoteOriginModel: o wrapper é reconstruído no caminho de volta apenas quando um dos dois lados tem alvo.The same Model class (CreditNoteOrderReferenceModel) serves both roles — the sales-return origin's ToOne and the applied orders' ToMany. And there is no CreditNoteOriginModel: the wrapper is rebuilt on the way back only when one of the two sides has a target.La misma clase de Model (CreditNoteOrderReferenceModel) sirve a los dos papeles — el ToOne del origen por devolución y el ToMany de los pedidos aplicados. Y no existe CreditNoteOriginModel: el wrapper se reconstruye en el camino de vuelta solo cuando uno de los dos lados tiene destino.

Estruturas do link de pagamento (transientes)Payment link structures (transient)Estructuras del link de pago (transitorias)

As três estruturas dos RPCs de link de pagamento não são persistidas — não existe Model para nenhuma delas, e o único efeito no cache é a marcação de pendente nos títulos envolvidos.The three structures of the payment link RPCs are not persisted — no Model exists for any of them, and the only cache effect is marking the involved debit items as pending.Las tres estructuras de los RPC de link de pago no se persisten — no existe Model para ninguna, y el único efecto en el caché es marcar los documentos involucrados como pendiente.

• PaymentLinkBank getBankList 4 camposfieldscampos

  Campo	Proto	DTO	Model	Entity
  bankName	string	String	—	String
  bankIconBase64	string	String	—	String
  isCompany	bool	bool	—	bool
  transactionLimit	double	double	—	double

• PaymentLinkItem createPaymentLink · request 4 camposfieldscampos

  Campo	Proto	DTO	Model	Entity
  debitOpenItemSfid	string	—	—	String
  paymentAmount	double	—	—	double
  invoiceLegalNumber	string	—	—	String
  orderSfid	string	—	—	String

• PaymentLink createPaymentLink · reply 4 camposfieldscampos

  Campo	Proto	DTO	Model	Entity
  url	string	String	—	String
  bankOrderId	string	String	—	String
  bankName	string	String	—	String
  htmlResponse	string	—	—	—

PaymentLinkItemEntity é uma entity de request: não tem DTO nem Model, e é mapeada direto para o proto por toProto() — o único mapper Entity→Proto desta camada.PaymentLinkItemEntity is a request entity: it has no DTO and no Model, and is mapped straight to the proto by toProto() — this layer's only Entity→Proto mapper.PaymentLinkItemEntity es una entity de request: no tiene DTO ni Model, y se mapea directo al proto por toProto() — el único mapper Entity→Proto de esta capa.

Mappers

Nove arquivos em data/mappers/financial_management/. As cinco direções canônicas existem para todas as estruturas persistidas; o link de pagamento tem só as direções que usa.Nine files in data/mappers/financial_management/. The five canonical directions exist for every persisted structure; the payment link only has the directions it uses.Nueve archivos en data/mappers/financial_management/. Las cinco direcciones canónicas existen para todas las estructuras persistidas; el link de pago solo tiene las direcciones que usa.

FinancialManagementRepositoryImpl implementaimplementsimplementa FinancialManagementRepositoryInterface e injeta os 3 datasources (mock/local/remote) + ConnectivityService + a flag useMockData + Ref. São 11 métodos em quatro grupos: fetch do agregado, leitura de cache, mutação local e link de pagamento. Método a método:and injects the 3 datasources (mock/local/remote) + ConnectivityService + the useMockData flag + Ref. There are 11 methods in four groups: aggregate fetch, cache read, local mutation and payment link. Method by method:e inyecta los 3 datasources (mock/local/remote) + ConnectivityService + la flag useMockData + Ref. Son 11 métodos en cuatro grupos: fetch del agregado, lectura de caché, mutación local y link de pago. Método a método:

Um dropdown por método — assinatura, retorno e comportamento. O getFinancialManagement() traz a árvore de decisão de fonte dentro do próprio detalhe.One dropdown per method — signature, return and behavior. getFinancialManagement() carries the source decision tree inside its own detail.Un dropdown por método — firma, retorno y comportamiento. getFinancialManagement() trae el árbol de decisión de fuente dentro de su propio detalle.

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. Cada um vive em core/enums/ e leva os labels numa extension …Ux, nunca espalhados em widgets. Lista completa de valores:Enums are only typed in the Entity layer; in DTO/Model/Proto they travel as String. Each lives under core/enums/ and carries its labels in a …Ux extension, never scattered across widgets. Full value list:Los enums solo están tipados en la capa Entity; en DTO/Model/Proto viajan como String. Cada uno vive en core/enums/ y lleva los labels en una extension …Ux, nunca dispersos en widgets. Lista completa de valores:

Um dropdown por UseCase; dentro, cada método com assinatura, o que retorna e uso. Todos os providers são keepAlive. Os de leitura delegam ao repository sem lógica extra, exceto os dois que filtram por relação; o par do dispatcher é a única escrita.One dropdown per UseCase; inside, each method with its signature, what it returns and use. Every provider is keepAlive. The read ones delegate to the repository with no extra logic, except the two that filter by relation; the dispatcher pair is the only write.Un dropdown por UseCase; dentro, cada método con su firma, qué devuelve y uso. Todos los providers son keepAlive. Los de lectura delegan al repository sin lógica extra, excepto los dos que filtran por relación; el par del dispatcher es la única escritura.

UseCases emprestados de outras features, que as quatro telas consomem sem serem donas: GetOrdersUseCase (o pedido ligado ao título e a nota fiscal inteira), GetVisitsUseCase (a visita do varejo, de onde saem nome, código SAP e perfil de crédito), GetRetailsUseCase (o mesmo, quando não há visita), GetPaymentRegistersUseCase (pagamentos criados no aparelho) e GetEndMarketConfigurationUseCase (os módulos habilitados no mercado).UseCases borrowed from other features, which the four screens consume without owning: GetOrdersUseCase (the debit item's linked order and the whole invoice), GetVisitsUseCase (the retail's visit, source of name, SAP code and credit profile), GetRetailsUseCase (the same, when there is no visit), GetPaymentRegistersUseCase (payments created on the device) and GetEndMarketConfigurationUseCase (the market's enabled modules).UseCases prestados de otras features, que las cuatro pantallas consumen sin ser dueñas: GetOrdersUseCase (el pedido ligado al documento y la factura completa), GetVisitsUseCase (la visita del punto de venta, de donde salen nombre, código SAP y perfil de crédito), GetRetailsUseCase (lo mismo, cuando no hay visita), GetPaymentRegistersUseCase (pagos creados en el dispositivo) y GetEndMarketConfigurationUseCase (los módulos habilitados en el mercado).

São quatro Notifiers, um por tela, todos @riverpod em família e todos recebendo apenas identificadores — nunca uma entity pela rota (§17). Cada State Freezed é a fonte única de verdade da sua Page: guarda o dado do domínio e todo o estado de cliente, e expõe em getters tudo o que a UI precisa decidir. Nenhum widget calcula nada.There are four Notifiers, one per screen, all @riverpod families and all receiving identifiers only — never an entity through the route (§17). Each Freezed State is its Page's single source of truth: it holds the domain data and all the client state, and exposes in getters everything the UI needs to decide. No widget computes anything.Son cuatro Notifiers, uno por pantalla, todos @riverpod en familia y todos recibiendo solo identificadores — nunca una entity por la ruta (§17). Cada State Freezed es la fuente única de verdad de su Page: guarda el dato del dominio y todo el estado de cliente, y expone en getters todo lo que la UI necesita decidir. Ningún widget calcula nada.

Métodos · FinancialManagementNotifierMethods · FinancialManagementNotifierMétodos · FinancialManagementNotifier

Métodos · DebitOpenItemDetailNotifierMethods · DebitOpenItemDetailNotifierMétodos · DebitOpenItemDetailNotifier

Métodos · InvoiceDetailNotifier e CreditNoteDetailNotifierMethods · InvoiceDetailNotifier and CreditNoteDetailNotifierMétodos · InvoiceDetailNotifier y CreditNoteDetailNotifier

States disponíveis para as PagesStates available to the PagesStates disponibles para las Pages

Quatro ConsumerWidget, cada um observando o seu provider e montando os filhos. Loading e erro são globais em todas (asyncState.when); o conteúdo existe só no ramo data. A visibilidade de cada bloco vive dentro do widget filho, com SizedBox.shrink() no início — as Pages não decidem (§27). Árvores de composição, com os modais aninhados sob quem os abre:Four ConsumerWidget, each watching its provider and composing the children. Loading and error are global on all of them (asyncState.when); content exists only in the data branch. Each block's visibility lives inside the child widget, with an early SizedBox.shrink() — the Pages don't decide (§27). Composition trees, with the modals nested under whoever opens them:Cuatro ConsumerWidget, cada uno observando su provider y armando los hijos. Loading y error son globales en todas (asyncState.when); el contenido existe solo en la rama data. La visibilidad de cada bloque vive dentro del widget hijo, con SizedBox.shrink() al inicio — las Pages no deciden (§27). Árboles de composición, con los modales anidados bajo quien los abre:

Hub — FinancialManagementPageHub — FinancialManagementPageHub — FinancialManagementPage

• FinancialManagementPage accountSfid + origin
  • AppPageShell displayBackButton · background
    • CustomLoadingIndicator loading
    • FailureStateView error → invalidate
    • Stack data
      • CustomPullToRefresh → refresh() · padding reserva o rodapé fixo
        • DataLoadInfo state.lastSyncAt (visita + financeiro)
        • AccountHeaderCard nome · código SAP · selo de inadimplência
        • FinancialManagementCreditSectionWidget shrink se módulo retail_credit_details ausente
          • FinancialManagementCreditInfoCard 3 colunas: limite · disponível · dias
        • FinancialManagementTabBarWidget shrink se !showTabBar ou < 2 abas → selectTab
        • FinancialManagementDebitsTabContent aba Débitos
          • FinancialManagementTabContentHeader totais + ConectaFilterButton (isActive: hasActiveFilters)
            • FinancialManagementTotalsBarWidget N em aberto + CustomText.currency(debitsOpenTotal)
            • FinancialManagementFiltersModalContent modal · ConectaModalScaffold (rodapé fixo)
              • _StatusFilterSection shrink se detail filter_status ausente · pílulas de DebitOpenItemStatus.selectable
              • _DateRangeFilterSection shrink se detail filter_date_range ausente · 2 campos de data
              • _DatePickerModalContent modal aninhado · CustomCalendar → backWithResult<DateTime> (clampado)
              • _FooterButtons Limpar (outlined, só com filtro) + Aplicar (filled) → applyFilters / clearFilters
          • FinancialManagementDebitOpenItemsList
            • FinancialManagementDebitOpenItemsEmpty CustomEmptyState · texto muda com hasActiveFilters
            • FinancialManagementDebitOpenItemCard → goToDebitOpenItemDetail(origin) · volta → reloadAfterPayment(keepSelection: true)
              • FinancialManagementStatusPill status + pílula de link de pagamento
              • CustomCheckbox só se debitShowsCheckbox → toggleDebitSelection
              • CustomText.currency item.price
        • FinancialManagementCreditNotesTabContent aba Notas de crédito · CustomEmptyState se vazia
          • FinancialManagementTabContentHeader N disponíveis + creditNotesAvailableTotal (sem filtro)
          • FinancialManagementCreditNoteRow folio · valor · data → goToCreditNoteDetail (só se módulo credit_note_detail visível)
        • FinancialManagementDebitOpenItemsSectionWidget ramo SEM tab bar · shrink se módulo debit_open_item_list ausente
          • FinancialManagementDebitOpenItemsHeader título + ConectaFilterButton → mesmo modal de filtros
          • FinancialManagementDebitOpenItemsList a mesma lista de cima
      • FinancialManagementStickyFooterWidget CustomSummaryBar · visible: paymentSelectionEnabled && selectedDebitsCount > 0
        • CustomSummaryDebitsList expandido: selectedPaymentDebits
        • VisitNotStartedModalContent modal do VisitStartGuard, quando origin.requiresStartedVisit
        • → goToPaymentCreation semeia paymentDraftProvider · volta paid? → reloadAfterPayment()

Dois cabeçalhos coexistem por desenho: o …TabContentHeader (com abas) e o …DebitOpenItemsHeader (sem abas) têm layouts diferentes, mas abrem o mesmo modal de filtros. O modal não devolve valor: escreve direto no Notifier e fecha.Two headers coexist by design: …TabContentHeader (with tabs) and …DebitOpenItemsHeader (without tabs) have different layouts but open the same filters modal. The modal returns no value: it writes straight into the Notifier and closes.Dos encabezados coexisten por diseño: el …TabContentHeader (con pestañas) y el …DebitOpenItemsHeader (sin pestañas) tienen layouts distintos, pero abren el mismo modal de filtros. El modal no devuelve valor: escribe directo en el Notifier y cierra.

Detalhe do título — DebitOpenItemDetailPageDebit item detail — DebitOpenItemDetailPageDetalle del documento — DebitOpenItemDetailPage

• DebitOpenItemDetailPage debitOpenItemSfid + origin
  • AppPageShell displayBackButton · background
    • CustomLoadingIndicator loading
    • FailureStateView error → invalidate
    • SingleChildScrollView data · sem pull-to-refresh
      • DataLoadInfo state.lastSyncAt (agregado financeiro)
      • AccountHeaderCard displayAccountName · displayAccountSapId · accountIsOverdue
      • DebitOpenItemDetailInvoiceCardWidget sempre visível
        • FinancialManagementStatusPill status do título
        • CustomText.currency debit.price
        • _buildInfoGrid Número (link) · Nº fatura · Dias em aberto · Status · Em disputa
        • → goToInvoiceDetail só se invoiceDetailOrder != null · texto simples caso contrário
      • DebitOpenItemDetailPayButtonWidget shrink se !canCreatePayment
        • VisitNotStartedModalContent modal do VisitStartGuard, quando requiresStartedVisitToPay
        • → goToPaymentCreation semeia 1 PaymentDebitEntity · volta paid? → reloadPayments()
      • DebitOpenItemDetailPaymentsWidget shrink se !isPaymentCreationEnabled
        • CustomEmptyState se !hasPayments
        • _PaymentCard registros locais: método · valor · datas · nº transação · banco · agência · status
        • _PaymentCard pagamentos do backend: método · valor · data · nº transação · status
        • _OriginPill Link de pagamento vs Manual
      • DebitOpenItemDetailProofOfPaymentWidget shrink se !isProofOfPaymentEnabled
        • _ProofPaymentButton Tirar foto → captureProofOfPaymentImage(camera)
        • _ProofPaymentButton Anexar → pickProofOfPaymentDocument()
        • CustomFileThumbnail onRemove → remove…Photo / remove…Attachment
        • CustomButton Enviar comprovante → submitProofOfPayment() → ConectaNotice

Detalhe da nota fiscal — InvoiceDetailPageInvoice detail — InvoiceDetailPageDetalle de la factura — InvoiceDetailPage

• InvoiceDetailPage orderSfid
  • AppPageShell displayBackButton
    • CustomLoadingIndicator loading
    • InvoiceDetailNotFoundWidget error is BusinessFailure → CustomErrorState
    • FailureStateView qualquer outro erro → invalidate
    • SingleChildScrollView data · tela folha, sem navegação de saída
      • DataLoadInfo state.lastSyncAt (container de pedidos)
      • InvoiceDetailTitleWidget ícone + Fatura
      • AccountHeaderCard order.accountName · order.accountSapId
      • InvoiceDetailNumberPillWidget displayInvoiceLegalNumber
      • InvoiceDetailInfoGridWidget 6 InvoiceDetailLabelValueWidget
      • InvoiceDetailPaymentSectionWidget sempre visível
        • _buildPaymentRow order.payments: forma · CustomText.currency · vencimento
        • _buildPlaceholderRow sem parcelas: displayTotal + order.deliveryDate
      • InvoiceDetailItemsSectionWidget shrink se nonEmptyPaidCategories vazio · agrupado por categoria
      • InvoiceDetailFreeOfChargeSectionWidget shrink se freeOfChargeLineItems vazio · SKU + qtd
      • InvoiceDetailTotalSectionWidget subtotal · desconto · taxa · imposto · total (CurrencyUtils.format)

Detalhe da nota de crédito — CreditNoteDetailPageCredit note detail — CreditNoteDetailPageDetalle de la nota de crédito — CreditNoteDetailPage

• CreditNoteDetailPage creditNoteSfid
  • AppPageShell displayBackButton · background
    • CustomLoadingIndicator loading
    • FailureStateView error → refresh() (não invalidate)
    • CustomPullToRefresh data → refresh()
      • DataLoadInfo state.lastSyncAt (agregado financeiro)
      • AccountHeaderCard accountName em maiúsculas · accountCustomerCode
      • CreditNoteDetailHeaderCardWidget
        • FinancialManagementStatusPill Disponível / Utilizada (widget importado do hub)
        • CustomText.currency amount e effectiveAvailableAmount
        • _buildField Folio · Data · Tipo (creditNoteType.labelKey)
      • _buildOriginSection título por tipo (originSectionLabelKey)
        • CustomEmptyState se !hasOrigin
        • CreditNoteDetailSummaryCardWidget CNAP: DPI · nº fatura · total devido · total pago · diferença · forma
          • CreditNoteDetailFieldRowWidget label / valor · travessão se vazio
          • CustomButton Ver detalhes → goToInvoiceDetail (só se canOpenOrder)
          • unavailableMessage texto cinza quando o pedido não está em cache
        • CreditNoteDetailSummaryCardWidget devolução: nº fatura · nº PO · PO do varejo · origem · recurso · forma
      • _buildAppliedSection shrink se !hasAppliedOrders && !isUsed
        • CustomEmptyState usada mas sem faturas aplicadas
        • CreditNoteDetailSummaryCardWidget um card por fatura aplicada → goToInvoiceDetail

Nenhuma das quatro telas usa Navigator direto — toda navegação passa pelo AppRouter (§16). Todo valor monetário sai de CustomText.currency (renderização) ou CurrencyUtils.format (quando o destino é uma String), com o mercado vindo do currentMarketProvider; não há formatação manual em lugar nenhum (§15). A única formatação numérica feita em widget é a contagem de dias de crédito, que não é dinheiro.None of the four screens uses Navigator directly — all navigation goes through AppRouter (§16). Every monetary value comes from CustomText.currency (rendering) or CurrencyUtils.format (when the destination is a String), with the market read from currentMarketProvider; there is no manual formatting anywhere (§15). The only numeric formatting done in a widget is the credit days count, which is not money.Ninguna de las cuatro pantallas usa Navigator directo — toda navegación pasa por el AppRouter (§16). Todo valor monetario sale de CustomText.currency (renderización) o CurrencyUtils.format (cuando el destino es un String), con el mercado viniendo del currentMarketProvider; no hay formateo manual en ninguna parte (§15). El único formateo numérico hecho en widget es el conteo de días de crédito, que no es dinero.