JornadaJourneyJornada

Clean Architecture + Riverpod + Freezed + ObjectBox. A Jornada não tem proto de leitura próprio: a leitura é local (a última jornada gravada no ObjectBox) e a habilitação de campos vem do EMC; a única saída para a rede são as escritas, que vão pelo Dispatcher. Por isso, dois grafos: leitura (composição local) e escrita (transação).Clean Architecture + Riverpod + Freezed + ObjectBox. Journey has no read proto of its own: the read is local (the last journey stored in ObjectBox) and field enablement comes from the EMC; the only network output are the writes, which go through the Dispatcher. Hence two graphs: read (local composition) and write (transaction).Clean Architecture + Riverpod + Freezed + ObjectBox. La Jornada no tiene proto de lectura propio: la lectura es local (la última jornada grabada en ObjectBox) y la habilitación de campos viene del EMC; la única salida a la red son las escrituras, que van por el Dispatcher. De ahí dos grafos: lectura (composición local) y escritura (transacción).

Leitura — montagem no _load()Read — assembly in _load()Lectura — armado en _load()

• GetCurrentOdometerJourneyUseCaseexecute()
  • getLatestJourneyOdometerJourneyRepositorylocal-only
    • query order startedAt descOdometerJourneyLocalDataSourceObjectBox
      • toDomainOdometerJourneyEntity?+ journeyConfig (EMC) · repType
        • _loadJourneyNotifier + State
          • → UIJourneyPage

Escrita — iniciar / encerrar (odômetro)Write — start / finish (odometer)Escritura — iniciar / finalizar (odómetro)

• JourneyNotifierstartJourney / finishJourney
  • execute(...)Start/FinishOdometerJourneyUseCase
    • build(input)BuildOdometerJourney…UseCaseDispatcherEnvelope
      • submit(envelope)SubmitOdometerJourneyUseCase→ DispatcherOrchestrator
        • on SuccesssaveJourneyObjectBox local
          • invalidate + _loadJourneyState

As escritas são remote-first (§36): a transação é disparada primeiro e a jornada só é gravada localmente depois do sucesso. A placa (só no início, só BR) segue o mesmo padrão numa transação separada (Build/SubmitCarLicensePlateUseCase).Writes are remote-first (§36): the transaction fires first and the journey is only saved locally after success. The plate (start only, BR only) follows the same pattern in a separate transaction (Build/SubmitCarLicensePlateUseCase).Las escrituras son remote-first (§36): la transacción se dispara primero y la jornada se graba localmente solo tras el éxito. La matrícula (solo al inicio, solo BR) sigue el mismo patrón en una transacción separada (Build/SubmitCarLicensePlateUseCase).

A Jornada não tem proto nem DTO: não faz gRPC de leitura. Existe uma única estrutura persistida — OdometerJourney (Entity ↔ Model, ObjectBox local) — e dois inputs de escrita (payload inputs do Dispatcher) que carregam entities cruas. O JourneyState compõe a jornada atual (do cache local) com os campos habilitados (do EMC).Journey has no proto and no DTO: it does no read gRPC. There's a single persisted structure — OdometerJourney (Entity ↔ Model, local ObjectBox) — and two write inputs (Dispatcher payload inputs) carrying raw entities. JourneyState composes the current journey (from local cache) with the enabled fields (from the EMC).La Jornada no tiene proto ni DTO: no hace gRPC de lectura. Existe una única estructura persistida — OdometerJourney (Entity ↔ Model, ObjectBox local) — y dos inputs de escritura (payload inputs del Dispatcher) que llevan entities crudas. El JourneyState compone la jornada actual (del caché local) con los campos habilitados (del EMC).

Fontes de dadosData sourcesFuentes de datos

Cada campo do JourneyState e de onde vem — não há RPC de leitura próprio:Each JourneyState field and where it comes from — there's no screen-owned read RPC:Cada campo del JourneyState y de dónde viene — no hay RPC de lectura propio:

Estruturas de dadosData structuresEstructuras de datos

Um dropdown por estrutura. OdometerJourney é a única que persiste (Entity ↔ Model, sem DTO nem proto); os dois payload inputs são só Entity (entrada crua para os builders do Dispatcher, §36).One dropdown per structure. OdometerJourney is the only one that persists (Entity ↔ Model, no DTO or proto); the two payload inputs are Entity-only (raw input for the Dispatcher builders, §36).Un dropdown por estructura. OdometerJourney es la única que persiste (Entity ↔ Model, sin DTO ni proto); los dos payload inputs son solo Entity (entrada cruda para los builders del Dispatcher, §36).

• OdometerJourney persistida (local)persisted (local)persistida (local) 11 camposfieldscampos

  Campo	Model	Entity
  id	@Id int	—
  uuid	@Index String	String
  reconId	String	String
  status	String	OdometerJourneyStatus
  odometerStart	int	int
  odometerEnd	int?	int?
  startedAt	DateTime	DateTime
  endedAt	DateTime?	DateTime?
  startLatitude	double	double
  startLongitude	double	double
  endLatitude	double?	double?
  endLongitude	double?	double?

  id existe só no Model (chave ObjectBox), reaproveitado no save (busca por uuid). startedAt/endedAt são @Property(type: date) — não há parse de String. status é gravado como .name ("open"/"closed") e lido de volta com byName.id exists only in the Model (ObjectBox key), reused on save (lookup by uuid). startedAt/endedAt are @Property(type: date) — no String parse. status is stored as .name ("open"/"closed") and read back with byName.id existe solo en el Model (clave ObjectBox), reutilizado en el save (búsqueda por uuid). startedAt/endedAt son @Property(type: date) — sin parse de String. status se graba como .name ("open"/"closed") y se lee con byName.

• OdometerJourneyDispatcherPayloadInput entrada de escritawrite inputentrada de escritura 2 camposfieldscampos

  Campo	Entity
  journey	OdometerJourneyEntity
  resource	ResourceEntity

  Input cru (§36): a jornada e o representante como estão no domínio. Toda construção wire — arrays Odometer/ReconStatus, formatação de data, vanId (resource.locationSfid), Status (wireValue) — mora no build() do builder.A raw input (§36): the journey and the rep as they are in the domain. All wire construction — Odometer/ReconStatus arrays, date formatting, vanId (resource.locationSfid), Status (wireValue) — lives in the builder's build().Input crudo (§36): la jornada y el representante como están en el dominio. Toda construcción wire — arrays Odometer/ReconStatus, formateo de fecha, vanId (resource.locationSfid), Status (wireValue) — vive en el build() del builder.

• CarLicensePlateDispatcherPayloadInput entrada de escrita · BRwrite input · BRentrada de escritura · BR 4 camposfieldscampos

  Campo	Entity	default
  carLicensePlate	String	—
  resource	ResourceEntity	—
  submittedAt	DateTime	—
  isTradePlate	bool	false

  Compartilhado com Settings. O Notifier injeta submittedAt: DateTimeUtils.now(); a normalização da placa, resourceSfid/username e a data ficam no build() do builder.Shared with Settings. The Notifier injects submittedAt: DateTimeUtils.now(); plate normalization, resourceSfid/username and the date live in the builder's build().Compartido con Settings. El Notifier inyecta submittedAt: DateTimeUtils.now(); la normalización de la matrícula, resourceSfid/username y la fecha viven en el build() del builder.

Mappers

Só OdometerJourney tem mapper — duas direções (sem JSON/Proto/DTO, é local puro):Only OdometerJourney has a mapper — two directions (no JSON/Proto/DTO, it's local-only):Solo OdometerJourney tiene mapper — dos direcciones (sin JSON/Proto/DTO, es local puro):

O OdometerJourneyRepositoryImpl (implements OdometerJourneyRepositoryInterface) injeta só o datasource local — é local puro, sem rede, sem mock nem remote. A escrita para a rede não passa por aqui: acontece nos UseCases de escrita via Dispatcher. Método a método:OdometerJourneyRepositoryImpl (implements OdometerJourneyRepositoryInterface) injects only the local datasource — it's local-only, no network, no mock or remote. The network write doesn't go through here: it happens in the write UseCases via the Dispatcher. Method by method:El OdometerJourneyRepositoryImpl (implements OdometerJourneyRepositoryInterface) inyecta solo el datasource local — es local puro, sin red, sin mock ni remote. La escritura a la red no pasa por aquí: ocurre en los UseCases de escritura vía Dispatcher. Método a método:

Um único datasource: o local (ObjectBox). Não há mock nem remote de leitura — a saída para a rede é o Dispatcher (documentado nos UseCases de escrita).A single datasource: the local one (ObjectBox). There's no mock or remote read — the network output is the Dispatcher (documented in the write UseCases).Un único datasource: el local (ObjectBox). No hay mock ni remote de lectura — la salida a la red es el Dispatcher (documentado en los UseCases de escritura).

Um dropdown por enum, todos os valores.One dropdown per enum, all values.Un dropdown por enum, todos los valores.

Um dropdown por UseCase, com tipos de retorno exatos. Leitura (1) + escrita de odômetro (start/finish + builder + submit) + escrita de placa (builder + submit + save local).One dropdown per UseCase, with exact return types. Read (1) + odometer write (start/finish + builder + submit) + plate write (builder + submit + local save).Un dropdown por UseCase, con tipos de retorno exactos. Lectura (1) + escritura de odómetro (start/finish + builder + submit) + escritura de matrícula (builder + submit + save local).

O JourneyNotifier (@riverpod, FutureOr<JourneyState> build()) monta a tela. O build() é magro e retorna _load(), que lê a jornada atual e resolve os campos habilitados via journeyConfig.visibleFieldsFor(repType). As chamadas de escrita (§39) partem do Notifier. Não há refresh() de pull-to-refresh; a leitura é reexecutada invalidando o currentOdometerJourneyProvider (provider dependente, não self — §37).The JourneyNotifier (@riverpod, FutureOr<JourneyState> build()) assembles the screen. build() is thin and returns _load(), which reads the current journey and resolves the enabled fields via journeyConfig.visibleFieldsFor(repType). Write calls (§39) originate in the Notifier. There's no pull-to-refresh refresh(); the read is re-run by invalidating currentOdometerJourneyProvider (a dependent provider, not self — §37).El JourneyNotifier (@riverpod, FutureOr<JourneyState> build()) arma la pantalla. El build() es magro y retorna _load(), que lee la jornada actual y resuelve los campos habilitados vía journeyConfig.visibleFieldsFor(repType). Las llamadas de escritura (§39) parten del Notifier. No hay refresh() de pull-to-refresh; la lectura se reejecuta invalidando el currentOdometerJourneyProvider (provider dependiente, no self — §37).

MétodosMethodsMétodos

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

A JourneyPage (ConsumerStatefulWidget) observa o journeyProvider e é embrulhada num PopScope(canPop: false). Loading e erro são globais (stateAsync.when); o formulário existe só no ramo data. O envio de escrita é disparado pelo Notifier (§39); o widget só orquestra modal/navegação. Árvore de composição:JourneyPage (ConsumerStatefulWidget) watches journeyProvider and is wrapped in a PopScope(canPop: false). Loading and error are global (stateAsync.when); the form exists only in the data branch. The write submit is fired by the Notifier (§39); the widget only orchestrates modal/navigation. Composition tree:La JourneyPage (ConsumerStatefulWidget) observa el journeyProvider y está envuelta en un PopScope(canPop: false). Loading y error son globales (stateAsync.when); el formulario existe solo en la rama data. El envío de escritura lo dispara el Notifier (§39); el widget solo orquesta modal/navegación. Árbol de composición:

• JourneyPage PopScope canPop:false
  • AppPageShell no back · no drawer
    • CustomLoadingIndicator loading
    • FailureStateView error → invalidate(journeyProvider)
    • SingleChildScrollView data · _buildForm
      • CustomText greeting (GreetingUtils)
      • _JourneyClock Timer 1s · time+date
      • CustomText title + subtitle (start/finish)
      • CustomText referenceOdometer (se houver)
      • CustomInput odometer · numeric · digitsOnly
      • CustomInput plate · showField(carLicensePlate) · uppercase · max 7
      • CustomButton start/finish · onSubmit → notifier
        • CarPlateSubmissionFailedModalContent plateSubmissionFailed → continue/cancel

O encerrar começa fora desta page, na Home: a EndJourneyPill (widget compartilhado) abre a EndJourneyModalContent (em home/widgets/modals, mostra os pendentes do dia); confirmar chama AppRouter.goToJourney, que abre esta page em modo fim.Finishing starts outside this page, on Home: the EndJourneyPill (shared widget) opens EndJourneyModalContent (in home/widgets/modals, showing the day's pending items); confirming calls AppRouter.goToJourney, which opens this page in finish mode.El finalizar comienza fuera de esta page, en el Home: la EndJourneyPill (widget compartido) abre la EndJourneyModalContent (en home/widgets/modals, muestra los pendientes del día); confirmar llama a AppRouter.goToJourney, que abre esta page en modo fin.