Visita AdhocAdhoc VisitVisita Adhoc

Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. Um único fluxo remote-first de escrita-e-leitura: o botão dispara o provider, que chama o UseCase → Repository → RPC remoto getAdhocVisit. O reply vira AdhocVisitResultEntity (achatado) e o merge coordinator funde suas 15 listas em 11 datasources locais. Não há Local datasource nem Model próprios do agregado — ele é transiente e se dissolve nos caches de cada feature.Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. A single remote-first read-and-write flow: the button fires the provider, which calls the UseCase → Repository → remote RPC getAdhocVisit. The reply becomes an AdhocVisitResultEntity (flattened) and the merge coordinator merges its 15 lists into 11 local datasources. There is no Local datasource nor Model for the aggregate — it is transient and dissolves into each feature's caches.Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. Un único flujo remote-first de escritura-y-lectura: el botón dispara el provider, que llama al UseCase → Repository → RPC remoto getAdhocVisit. El reply se vuelve AdhocVisitResultEntity (aplanado) y el merge coordinator fusiona sus 15 listas en 11 datasources locales. No hay Local datasource ni Model propios del agregado — es transitorio y se disuelve en los cachés de cada feature.

• RetailCardWidget · ADHOCUI
  • create(retailName, accountSapCustomerId)AdhocVisitCreationprovider · family(accountSfid)
    • execute(accountSfid, geo?)CreateAdhocVisitUseCase
      • createAdhocVisitAdhocVisitRepositoryImplremote-first · sem fallback
        • getAdhocVisit (gRPC)AdhocVisitRemoteDataSourceAdhocVisitReply → DTO
          • toDomainAdhocVisitResultEntity15 listas achatadas
            • merge(result, accountSfid)AdhocVisitMergeCoordinator→ 11 caches ObjectBox

A Visita Adhoc é um agregado de fronteira transiente: existe em três representações — Proto (AdhocVisitReply, wire gRPC) → DTO (AdhocVisitResultDTO, Freezed) → Entity (AdhocVisitResultEntity, domínio) — ligadas por dois mappers. Não há Model ObjectBox nem JSON de mock para o agregado: ele nunca é persistido como uma unidade — cada uma de suas listas é fundida no cache da sua feature (a coluna Model de cada sub-estrutura vive no doc da feature dona).The Adhoc Visit is a transient boundary aggregate: it exists in three representations — Proto (AdhocVisitReply, gRPC wire) → DTO (AdhocVisitResultDTO, Freezed) → Entity (AdhocVisitResultEntity, domain) — linked by two mappers. There is no ObjectBox Model nor mock JSON for the aggregate: it is never persisted as one unit — each of its lists is merged into its own feature's cache (each sub-structure's Model column lives in that feature's doc).La Visita Adhoc es un agregado de frontera transitorio: existe en tres representaciones — Proto (AdhocVisitReply, wire gRPC) → DTO (AdhocVisitResultDTO, Freezed) → Entity (AdhocVisitResultEntity, dominio) — unidas por dos mappers. No hay Model ObjectBox ni JSON de mock para el agregado: nunca se persiste como una unidad — cada una de sus listas se fusiona en el caché de su feature (la columna Model de cada sub-estructura vive en el doc de esa feature).

O AdhocVisitReply tem 11 campos; três deles são mensagens-wrapper (AdhocSurveys, AdhocMerchandising, AdhocFinancialManagement) que o mapper achata — por isso o DTO/Entity terminam com 15 listas. O CallTask vem do TasksConectaRep.proto (mesma estrutura da feature Call Task). A seguir: o proto, as estruturas e os mappers.The AdhocVisitReply has 11 fields; three of them are wrapper messages (AdhocSurveys, AdhocMerchandising, AdhocFinancialManagement) that the mapper flattens — that's why the DTO/Entity end up with 15 lists. CallTask comes from TasksConectaRep.proto (same structure as the Call Task feature). Next: the proto, the structures and the mappers.El AdhocVisitReply tiene 11 campos; tres de ellos son mensajes-wrapper (AdhocSurveys, AdhocMerchandising, AdhocFinancialManagement) que el mapper aplana — por eso el DTO/Entity terminan con 15 listas. El CallTask viene de TasksConectaRep.proto (misma estructura que la feature Call Task). A continuación: el proto, las estructuras y los mappers.

Proto

AdhocVisitConectaRep.proto · proto3 · package mn.bat.conectarep.streambridge. Um único RPC unário que agrega toda a visita:A single unary RPC that aggregates the whole visit:Un único RPC unario que agrega toda la visita:

Estruturas de dadosData structuresEstructuras de datos

Um dropdown por estrutura. Como o agregado não é persistido, a tabela tem três colunas de camada — Proto (AdhocVisitReply) · DTO · Entity; o texto azul marca onde o dado primeiro muda (o achatamento das mensagens-wrapper acontece no toDTO, no Proto→DTO). Cada linha aponta o doc da feature onde vive o Model daquela lista.One dropdown per structure. Since the aggregate is not persisted, the table has three layer columns — Proto (AdhocVisitReply) · DTO · Entity; the blue text marks where the data first changes (the flattening of the wrapper messages happens in toDTO, at Proto→DTO). Each row points to the feature doc where that list's Model lives.Un dropdown por estructura. Como el agregado no se persiste, la tabla tiene tres columnas de capa — Proto (AdhocVisitReply) · DTO · Entity; el texto azul marca dónde primero cambia el dato (el aplanamiento de los wrappers ocurre en toDTO, en Proto→DTO). Cada fila apunta al doc de la feature donde vive el Model de esa lista.

• AdhocVisitRequest request 5 camposfieldscampos

  Campo	Proto	DTO	Entity
  username	string	— (montado no datasource a partir do ResourceEntity)— (built in the datasource from the ResourceEntity)— (armado en el datasource desde el ResourceEntity)
  accountSfid	string	— (parâmetro do UseCase)— (UseCase parameter)— (parámetro del UseCase)
  repSfid	string	resource.sfid
  geoLatitude	double¹	— (posição do device)— (device position)— (posición del device)
  geoLongitude	double¹	— (posição do device)— (device position)— (posición del device)

• AdhocVisitResult AdhocVisitReply → DTO/Entity 15 listaslistslistas

  Campo	Proto (Reply)	DTO	Entity
  visits	repeated Visit	List<VisitDTO>	List<VisitEntity>
  callTasks	repeated CallTask	List<CallTaskDTO>	List<CallTaskEntity>
  surveys	surveys.surveys	List<SurveyDTO>	List<SurveyEntity>
  stockControl	repeated Stock	List<StockDTO>	List<StockEntity>
  promotions	repeated Promotion	List<PromotionDTO>	List<PromotionEntity>
  promotionSpots	repeated SpotPromotion	List<SpotPromotionDTO>	List<SpotPromotionEntity>
  orders	repeated Order	List<OrderDTO>	List<OrderEntity>
  merchandisingAssets	merchandising.assets	List<MerchandisingAssetDTO>	List<MerchandisingAssetEntity>
  merchandisingServiceOrders	merchandising.serviceOrders	List<MerchandisingServiceOrderDTO>	List<MerchandisingServiceOrderEntity>
  marginCalculator	repeated MarginCalculatorProduct	List<MarginCalculatorProductDTO>	List<MarginCalculatorProductEntity>
  debitOpenItems	financialManagement.debitOpenItems	List<DebitOpenItemDTO>	List<DebitOpenItemEntity>
  banks	financialManagement.banks	List<BankDTO>	List<BankEntity>
  payments	financialManagement.payments	List<PaymentDTO>	List<PaymentEntity>
  creditNotes	financialManagement.creditNotes	List<CreditNoteDTO>	List<CreditNoteEntity>
  productCatalog	repeated Product	List<ProductDTO>	List<ProductEntity>

Mappers

O adhoc_visit_result_mapper.dart tem 2 direções (o agregado não tem Model, então não há toModel/Model→Entity); cada lista delega ao mapper da sua feature.The adhoc_visit_result_mapper.dart has 2 directions (the aggregate has no Model, so no toModel/Model→Entity); each list delegates to its feature's mapper.El adhoc_visit_result_mapper.dart tiene 2 direcciones (el agregado no tiene Model, así que no hay toModel/Model→Entity); cada lista delega al mapper de su feature.

O AdhocVisitRepositoryImpl tem um único método. Apesar do nome "create", é uma operação remote-first de leitura-e-cache: busca o reply no servidor e o funde nos caches locais. Não há caminho de fallback para cache — sem varejo no reply, falha.The AdhocVisitRepositoryImpl has a single method. Despite the "create" name, it is a remote-first read-and-cache operation: it fetches the reply from the server and merges it into the local caches. There is no cache fallback path — with no visit in the reply, it fails.El AdhocVisitRepositoryImpl tiene un único método. A pesar del nombre "create", es una operación remote-first de lectura-y-caché: busca el reply en el servidor y lo fusiona en los cachés locales. No hay camino de fallback a caché — sin visita en el reply, falla.

Só dois datasources próprios: Remote (o RPC) e Mock (stub vazio). Não há Local datasource nem JSON de mock do agregado — a persistência acontece nos 11 datasources locais das outras features, pelo merge coordinator (seção 08).Only two datasources of its own: Remote (the RPC) and Mock (empty stub). There is no Local datasource nor mock JSON for the aggregate — persistence happens in the 11 local datasources of the other features, via the merge coordinator (section 08).Solo dos datasources propios: Remote (el RPC) y Mock (stub vacío). No hay Local datasource ni JSON de mock del agregado — la persistencia ocurre en los 11 datasources locales de las otras features, vía el merge coordinator (sección 08).

A Visita Adhoc é orquestrada por um provider cross-page (não um Notifier de tela): o AdhocVisitCreation, family por accountSfid e keepAlive, vive em presentation/shared/providers/visits/ porque é consumido pelos cards da Lista de varejos. O build devolve o State inicial; o método create conduz o fluxo.The Adhoc Visit is orchestrated by a cross-page provider (not a screen Notifier): AdhocVisitCreation, family by accountSfid and keepAlive, lives in presentation/shared/providers/visits/ because the Retails list cards consume it. build returns the initial State; the create method drives the flow.La Visita Adhoc es orquestada por un provider cross-page (no un Notifier de pantalla): el AdhocVisitCreation, family por accountSfid y keepAlive, vive en presentation/shared/providers/visits/ porque las tarjetas de la Lista de puntos de venta lo consumen. El build devuelve el State inicial; el método create conduce el flujo.

MétodosMethodsMétodos

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

Sem page própria — a superfície é o card do varejo (na Lista de varejos) e o modal de confirmação.No page of its own — the surface is the retail card (in the Retails list) and the confirmation modal.Sin page propia — la superficie es la tarjeta del punto (en la Lista de puntos de venta) y el modal de confirmación.

• RetailsPage Lista de varejos (host)Retails list (host)Lista de puntos de venta (host)
  • RetailCardWidget observa adhocVisitCreationProvider(accountSfid:)watches adhocVisitCreationProvider(accountSfid:)observa adhocVisitCreationProvider(accountSfid:)
    • _RetailActionBadge · ADHOC visível só se isAdhocVisitCreationAvailable; loading na fase creatingvisible only if isAdhocVisitCreationAvailable; loading in the creating phasevisible solo si isAdhocVisitCreationAvailable; loading en la fase creating
    • CreateAdhocVisitModalContent modal · confirma → provider.create(retailName, accountSapCustomerId)modal · confirm → provider.create(retailName, accountSapCustomerId)modal · confirmar → provider.create(retailName, accountSapCustomerId)

A RetailsPage passa o onAdhocTap que abre o CreateAdhocVisitModalContent via ConectaModal.show; ao confirmar, chama ref.read(adhocVisitCreationProvider(...).notifier).create(...). Abrir modal e navegar ficam no widget; o disparo é o método do provider (§39).The RetailsPage passes the onAdhocTap that opens CreateAdhocVisitModalContent via ConectaModal.show; on confirm it calls ref.read(adhocVisitCreationProvider(...).notifier).create(...). Opening the modal and navigating stay in the widget; the trigger is the provider method (§39).La RetailsPage pasa el onAdhocTap que abre el CreateAdhocVisitModalContent vía ConectaModal.show; al confirmar llama ref.read(adhocVisitCreationProvider(...).notifier).create(...). Abrir el modal y navegar quedan en el widget; el disparo es el método del provider (§39).