Notas do varejoRetail notesNotas del punto de venta

Clean Architecture + Riverpod + Freezed + ObjectBox. Há dois fluxos distintos: a leitura (cache do próprio aggregate de Notas) e a escrita (criar/editar/excluir, via Dispatcher).Clean Architecture + Riverpod + Freezed + ObjectBox. There are two distinct flows: the read (cache of the Notes aggregate itself) and the write (create/edit/delete, via the Dispatcher).Clean Architecture + Riverpod + Freezed + ObjectBox. Hay dos flujos distintos: la lectura (caché del propio aggregate de Notas) y la escritura (crear/editar/eliminar, vía Dispatcher).

Leitura · cache + remoto no refreshRead · cache + remote on refreshLectura · caché + remoto en el refresh

As notas têm proto e pipeline próprios (NoteConectaRep.proto). O GetNotesUseCase lê o cache do agregado de Notas e recorta por conta com getCachedNotesForAccount. O sync inicial (DataSyncType.notes) e o pull-to-refresh populam esse cache pelo getNotes. Da feature de Visitas o Notifier só tira a identificação do varejo (nome, código, código fiscal):Notes have their own proto and pipeline (NoteConectaRep.proto). GetNotesUseCase reads the Notes aggregate cache and slices it per account with getCachedNotesForAccount. The initial sync (DataSyncType.notes) and pull-to-refresh populate that cache through getNotes. From the Visits feature the Notifier only takes the retail identity (name, code, tax code):Las notas tienen proto y pipeline propios (NoteConectaRep.proto). El GetNotesUseCase lee el caché del aggregate de Notas y lo recorta por cuenta con getCachedNotesForAccount. El sync inicial (DataSyncType.notes) y el pull-to-refresh poblan ese caché mediante getNotes. De la feature de Visitas el Notifier solo toma la identificación del punto de venta (nombre, código, código fiscal):

• NotesModelObjectBox · cache
  • getCachedNotesNotesLocalDataSource
    • toDomainNotesEntity · notesForAccountdomain
      • getCachedNotesForAccountGetNotesUseCase
        • _loadNotesNotifier + NotesState
          • → UINotesPage

Escrita · criar/editar/excluir via DispatcherWrite · create/edit/delete via DispatcherEscritura · crear/editar/eliminar vía Dispatcher

A ação sai do editor/modal, o Notifier lê os arquivos como base64, monta o NotesDispatcherPayloadInput (entities cruas + isDeleted), o builder gera o envelope (DispatcherType.notes · NoteUploadAPI) e o submit despacha:The action leaves the editor/modal, the Notifier reads the files as base64, assembles the NotesDispatcherPayloadInput (raw entities + isDeleted), the builder produces the envelope (DispatcherType.notes · NoteUploadAPI) and submit dispatches:La acción sale del editor/modal, el Notifier lee los archivos como base64, arma el NotesDispatcherPayloadInput (entities crudas + isDeleted), el builder produce el sobre (DispatcherType.notes · NoteUploadAPI) y submit despacha:

• NoteEditorModalContent / NoteCardWidgetUI
  • submitNote / deleteNoteNotesNotifier
    • readAsBase64FileCaptureServiceanexos → base64
      • build(input)BuildNotesDispatcherPayloadUseCase→ DispatcherEnvelope
        • submit(envelope)SubmitNotesUseCase
          • dispatchDispatcherOrchestratorNoteUploadAPI · batchApi

A nota existe em quatro representações — Proto (wire gRPC) → DTO (Freezed) → Model (ObjectBox) → Entity (domínio) — ligadas por mappers, com cache write-through. A nota tem proto, DTO, Model e Entity próprios, no agregado Notes: NotesEntity carrega o lastSyncAt uma única vez e a lista de NoteEntity (§21). Cada nota carrega o accountSfid do varejo dono — no wire é o retailerId, o mesmo nome que o NoteUploadAPI já usa na escrita. O campo é opcional por semântica: vazio significa nota sem varejo, e o notesForAccount nunca a devolve num recorte por conta. É essa folga que deixa a estrutura pronta para notas não ligadas a varejo, sem tocar no contrato de Visitas — de onde Account.notes foi removido.A note exists in four representations — Proto (gRPC wire) → DTO (Freezed) → Model (ObjectBox) → Entity (domain) — linked by mappers, with cache write-through. The note has its own proto, DTO, Model and Entity, in the Notes aggregate: NotesEntity carries lastSyncAt once plus the list of NoteEntity (§21). Each note carries the owning retail's accountSfid — on the wire it is retailerId, the same name NoteUploadAPI already uses on the write side. The field is semantically optional: empty means a note with no retail, and notesForAccount never returns it in a per-account slice. That slack is what leaves the structure ready for notes not tied to a retail, without touching the Visits contract — where Account.notes was removed.Una nota existe en cuatro representaciones — Proto (wire gRPC) → DTO (Freezed) → Model (ObjectBox) → Entity (dominio) — unidas por mappers, con cache write-through. La nota tiene proto, DTO, Model y Entity propios, en el aggregate Notes: NotesEntity lleva el lastSyncAt una sola vez y la lista de NoteEntity (§21). Cada nota lleva el accountSfid del punto de venta dueño — en el wire es el retailerId, el mismo nombre que el NoteUploadAPI ya usa en la escritura. El campo es opcional por semántica: vacío significa nota sin punto de venta, y el notesForAccount nunca la devuelve en un recorte por cuenta. Esa holgura deja la estructura lista para notas no ligadas a un punto de venta, sin tocar el contrato de Visitas — de donde Account.notes fue eliminado.

A escrita (criar/editar/excluir) não usa nenhuma dessas quatro representações: o Notifier monta um NotesDispatcherPayloadInput com a NoteEntity crua + anexos em base64 e o builder serializa o JSON da transação (ver UseCases). A seguir, na ordem: o proto de origem, as estruturas campo-a-campo por camada, e os mappers. ¹ não se aplica aqui (os campos do proto não são optional).The write (create/edit/delete) uses none of these four representations: the Notifier assembles a NotesDispatcherPayloadInput with the raw NoteEntity + base64 attachments and the builder serializes the transaction JSON (see UseCases). Next, in order: the origin proto, the field-by-field structures per layer, and the mappers. ¹ doesn't apply here (the proto fields aren't optional).La escritura (crear/editar/eliminar) no usa ninguna de esas cuatro representaciones: el Notifier arma un NotesDispatcherPayloadInput con la NoteEntity cruda + adjuntos en base64 y el builder serializa el JSON de la transacción (ver UseCases). A continuación, en orden: el proto de origen, las estructuras campo a campo por capa, y los mappers. ¹ no aplica aquí (los campos del proto no son optional).

Proto

A nota vem do seu próprio proto — NoteConectaRep.proto · proto3. A escrita continua saindo pelo Dispatcher (ver UseCases), não por esse serviço.The note comes from its own proto — NoteConectaRep.proto · proto3. Writes still go out through the Dispatcher (see UseCases), not through this service.La nota viene de su propio proto — NoteConectaRep.proto · proto3. La escritura sigue saliendo por el Dispatcher (ver UseCases), no por este servicio.

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 em azul marca onde o tipo (ou nome) primeiro muda lendo Proto→DTO→Model→Entity.One dropdown per structure, nested by hierarchy. Each table has one column per layer — Proto · DTO · Model · Entity; the blue text marks where the type (or name) first changes reading Proto→DTO→Model→Entity.Un dropdown por estructura, anidados por jerarquía. Cada tabla tiene una columna por capa — Proto · DTO · Model · Entity; el texto en azul marca dónde primero cambia el tipo (o nombre) leyendo Proto→DTO→Model→Entity.

• Note NoteReply.noteList[] 7 camposfieldscampos

  Campo	Proto	DTO	Model	Entity
  id	string	String	noteId	String
  accountSfid	retailerId	String	String	String
  title	string	String	String	String
  text	textPreview	String	String	String
  createdAt	string	String?	DateTime?	DateTime?
  updatedAt	string	String?	DateTime?	DateTime?
  attachments	repeated NoteAttachment	List<…DTO>	ToMany<…Model>	List<…Entity>

  • NoteAttachment Note.attachments[] 3 camposfieldscampos

    Campo	Proto	DTO	Model	Entity
    fileUrl	string	String	String	String
    fileName	string	String	String	String
    fileType	string	String	String	String

NoteEntity tem ainda o getter hasAttachments (attachments.isNotEmpty). Defaults dos Freezed: title/text = "", attachments = lista vazia; datas nulas.NoteEntity also has the hasAttachments getter (attachments.isNotEmpty). Freezed defaults: title/text = "", attachments = empty list; dates null.NoteEntity tiene además el getter hasAttachments (attachments.isNotEmpty). Defaults de Freezed: title/text = "", attachments = lista vacía; fechas nulas.

Mappers

As cinco direções, para Note e NoteAttachment (extensions em note_mapper.dart / note_attachment_mapper.dart). As notas entram no fluxo por dentro do mapper de AccountData.The five directions, for Note and NoteAttachment (extensions in note_mapper.dart / note_attachment_mapper.dart). Notes enter the flow through the AccountData mapper.Las cinco direcciones, para Note y NoteAttachment (extensions en note_mapper.dart / note_attachment_mapper.dart). Las notas entran al flujo dentro del mapper de AccountData.

As Notas têm o seu NotesRepositoryImpl, com as 3 operações do padrão: getNotes (cache + fallback remoto), getCachedNotes e getCachedNotesForAccount (§28-A). O locationHierarchySfid é resolvido aqui, via currentResourceProvider (§25). A escrita das notas não passa por este repository — vai pelo Dispatcher (ver UseCases).Notes have their own NotesRepositoryImpl, with the 3 standard operations: getNotes (cache + remote fallback), getCachedNotes and getCachedNotesForAccount (§28-A). locationHierarchySfid is resolved here, via currentResourceProvider (§25). Note writes do not go through this repository — they go via the Dispatcher (see UseCases).Las Notas tienen su propio NotesRepositoryImpl, con las 3 operaciones del patrón: getNotes (caché + fallback remoto), getCachedNotes y getCachedNotesForAccount (§28-A). El locationHierarchySfid se resuelve aquí, vía currentResourceProvider (§25). La escritura de las notas no pasa por este repository — va por el Dispatcher (ver UseCases).

Um dropdown por método — assinatura, retorno e comportamento. As Notas usam estes três.One dropdown per method — signature, return and behavior. Notes use these three.Un dropdown por método — firma, retorno y comportamiento. Las Notas usan estos tres.

As Notas têm os 3 datasources próprios: mock (JSON de asset), local (ObjectBox) e remoto (gRPC). Os boxes são exclusivos — NotesModel, NoteModel e NoteAttachmentModel. A escrita das notas não usa datasource: sai pelo Dispatcher.Notes have their own 3 datasources: mock (asset JSON), local (ObjectBox) and remote (gRPC). The boxes are exclusive — NotesModel, NoteModel and NoteAttachmentModel. Note writes use no datasource: they go via the Dispatcher.Las Notas tienen sus 3 datasources propios: mock (JSON de asset), local (ObjectBox) y remoto (gRPC). Los boxes son exclusivos — NotesModel, NoteModel y NoteAttachmentModel. La escritura de las notas no usa datasource: sale por el Dispatcher.

As Notas não têm enum de dado próprio (a nota é texto livre). Os enums relevantes são o de gating (a ferramenta na grade) e o de transação (o canal de escrita), além dos enums de captura de arquivo reusados no editor.Notes have no data enum of their own (a note is free text). The relevant enums are the gating one (the tool in the grid) and the transaction one (the write channel), plus the file-capture enums reused in the editor.Las Notas no tienen enum de dato propio (la nota es texto libre). Los enums relevantes son el de gating (la herramienta en la grilla) y el de transacción (el canal de escritura), además de los enums de captura de archivo reutilizados en el editor.

Um dropdown por UseCase; dentro, cada método com assinatura, o que retorna e uso.One dropdown per UseCase; inside, each method with its signature, what it returns and use.Un dropdown por UseCase; dentro, cada método con su firma, qué devuelve y uso.

LeituraReadLectura

EscritaWriteEscritura

O NotesNotifier (@riverpod, family por accountSfid) é o cérebro da tela. O build() é magro (resolve UseCases/serviço, registra o onDispose de limpeza de arquivos e chama guardedBuild(() => _load(...)) — via mixin AsyncGuard). O State (NotesState, Freezed) é a fonte única de verdade: guarda as notas do backend, o overlay otimista e o lastSyncAt, e expõe o getter displayItems que combina tudo.The NotesNotifier (@riverpod, family by accountSfid) is the screen's brain. build() is thin (resolves UseCases/service, registers the file-cleanup onDispose and calls guardedBuild(() => _load(...)) — via the AsyncGuard mixin). The State (NotesState, Freezed) is the single source of truth: it holds the backend notes, the optimistic overlay and lastSyncAt, and exposes the displayItems getter that merges everything.El NotesNotifier (@riverpod, family por accountSfid) es el cerebro de la pantalla. build() es magro (resuelve UseCases/servicio, registra el onDispose de limpieza de archivos y llama guardedBuild(() => _load(...)) — vía el mixin AsyncGuard). El State (NotesState, Freezed) es la fuente única de verdad: guarda las notas del backend, el overlay optimista y lastSyncAt, y expone el getter displayItems que combina todo.

MétodosMethodsMétodos

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

A NotesPage (ConsumerWidget) recebe só o accountSfid (§17), observa notesProvider(accountSfid:) e monta os widgets numa coluna rolável com pull-to-refresh. Loading e erro são globais (asyncState.when); erro → FailureStateView com retry via ref.invalidate. Árvore de composição:NotesPage (ConsumerWidget) takes only accountSfid (§17), watches notesProvider(accountSfid:) and composes the widgets in a scrollable column with pull-to-refresh. Loading and error are global (asyncState.when); error → FailureStateView with retry via ref.invalidate. Composition tree:NotesPage (ConsumerWidget) recibe solo accountSfid (§17), observa notesProvider(accountSfid:) y compone los widgets en una columna desplazable con pull-to-refresh. Loading y error son globales (asyncState.when); error → FailureStateView con retry vía ref.invalidate. Árbol de composición:

• NotesPage
  • AppPageShell displayBackButton
    • CustomLoadingIndicator loading
    • FailureStateView error → ref.invalidate
    • _NotesBody → CustomPullToRefresh → Column data
      • DataLoadInfo state.lastSyncAt
      • AccountHeaderCard shared · código · nome
      • NotesListWidget
        • CustomText título "Notas"
        • CustomEmptyState se sem notas
        • NoteCardWidget por nota · data + editar + excluir + título + texto + anexos
          • CustomFileThumbnail.remote anexo do backend (URL)
          • CustomFileThumbnail anexo local otimista
          • NoteEditorModalContent modal editar (widgets/modals/) → NoteEditorResult → submitNote
          • ConectaModal.showConfirmation confirmar exclusão → deleteNote
        • CustomAddButton + "Nova nota"
          • NoteEditorModalContent modal criar → NoteEditorResult → submitNote

Editor (NoteEditorModalContent, ConsumerStatefulWidget): dois campos (CustomInput título máx. 80 · texto máx. 1000, 3–6 linhas), uma linha de três botões (câmera · galeria · arquivo) e as miniaturas (anexos existentes só leitura + arquivos locais removíveis). "Salvar" ativa com título, texto ou anexo. Usa uma sessão de captura própria; ao fechar sem salvar, faz cleanupSession. Retorna NoteEditorResult via AppRouter.backWithResult. Feedback de envio via ConectaNotice (§30). Modais/navegação ficam no widget (precisam de BuildContext); o envio mora no Notifier (§39).Editor (NoteEditorModalContent, ConsumerStatefulWidget): two fields (CustomInput title max 80 · text max 1000, 3–6 lines), a row of three buttons (camera · gallery · file) and the thumbnails (existing read-only attachments + removable local files). "Save" enables with title, text or attachment. Uses its own capture session; on closing without saving, it runs cleanupSession. Returns NoteEditorResult via AppRouter.backWithResult. Submit feedback via ConectaNotice (§30). Modals/navigation stay in the widget (they need BuildContext); the submit lives in the Notifier (§39).Editor (NoteEditorModalContent, ConsumerStatefulWidget): dos campos (CustomInput título máx. 80 · texto máx. 1000, 3–6 líneas), una fila de tres botones (cámara · galería · archivo) y las miniaturas (adjuntos existentes de solo lectura + archivos locales removibles). "Guardar" se habilita con título, texto o adjunto. Usa su propia sesión de captura; al cerrar sin guardar, ejecuta cleanupSession. Devuelve NoteEditorResult vía AppRouter.backWithResult. Feedback de envío vía ConectaNotice (§30). Modales/navegación quedan en el widget (necesitan BuildContext); el envío vive en el Notifier (§39).