Calculadora de margemMargin calculatorCalculadora de margen

Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. É uma feature somente leitura + cálculo local: um único RPC (getMarginCalculator) traz o catálogo de preços por produto; toda a matemática (lucro, totais, margem) acontece em getters do State, no aparelho. O dado atravessa quatro representações, ligadas por mappers, com cache write-through:Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. It's a read-only + local-compute feature: a single RPC (getMarginCalculator) returns the per-product price catalog; all math (profit, totals, margin) happens in State getters, on-device. Data crosses four representations, linked by mappers, with cache write-through:Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox. Es una feature solo lectura + cálculo local: un único RPC (getMarginCalculator) trae el catálogo de precios por producto; toda la matemática (lucro, totales, margen) ocurre en getters del State, en el dispositivo. El dato atraviesa cuatro representaciones, unidas por mappers, con cache write-through:

• MarginCalculatorReplygRPC proto
  • toDTOMarginCalculatorDTODTO · Freezed
    • toEntityMarginCalculatorEntitydomain
      • toModelMarginCalculatorModelObjectBox
        • toEntityMarginCalculatorEntitydomain · cache
          • filter by accountMarginCalculatorNotifier + State
            • getters → UIMarginCalculatorPage

O mesmo catálogo 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. Aqui os campos são todos primitivos (String, int, double, List<String>): não há um único enum tipado na Entity, ao contrário da maioria das features. Muda pouquíssimo entre camadas — um rename no proto, a relação vira ToMany no Model, e o lastSyncAt é gerado no mapper.The same catalog exists in four near-identical representations across layers — Proto (gRPC wire) → DTO (Freezed) → Model (ObjectBox) → Entity (domain) — each boundary crossed by a mapper. Here every field is primitive (String, int, double, List<String>): there isn't a single typed enum in the Entity, unlike most features. Very little changes between layers — one proto rename, the relation becomes ToMany in the Model, and lastSyncAt is generated in the mapper.El mismo catálogo existe en cuatro representaciones casi idénticas a lo largo de las capas — Proto (wire gRPC) → DTO (Freezed) → Model (ObjectBox) → Entity (dominio) — cada frontera cruzada por un mapper. Aquí cada campo es primitivo (String, int, double, List<String>): no hay un solo enum tipado en la Entity, a diferencia de la mayoría de las features. Cambia poquísimo entre capas — un rename en el proto, la relación pasa a ToMany en el Model, y el lastSyncAt se genera en el mapper.

A lista chega num container MarginCalculator (lastSyncAt gerado no mapper + products[]); cada item é um MarginCalculatorProduct de 10 campos — nome, sticks por pack e os seis preços (custo, RRP, RRSP × stick/pack) + a lista de contas às quais o produto pertence. A seguir, na ordem: o proto, as estruturas de dados campo-a-campo por camada, e os mappers.The list arrives in a MarginCalculator container (lastSyncAt generated in the mapper + products[]); each item is a 10-field MarginCalculatorProduct — name, sticks per pack and the six prices (cost, RRP, RRSP × stick/pack) + the list of accounts the product belongs to. Next, in order: the proto, the field-by-field data structures per layer, and the mappers.La lista llega en un container MarginCalculator (lastSyncAt generado en el mapper + products[]); cada ítem es un MarginCalculatorProduct de 10 campos — nombre, sticks por pack y los seis precios (costo, RRP, RRSP × stick/pack) + la lista de cuentas a las que pertenece el producto. A continuación, en orden: el proto, las estructuras de datos campo a campo por capa, y los mappers.

Proto

MarginCalculatorConectaRep.proto · proto3 · package mn.bat.conectarep.streambridge. Um serviço (MarginCalculatorConectaRepService), um método unário:One service (MarginCalculatorConectaRepService), a single unary method:Un servicio (MarginCalculatorConectaRepService), 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 (ou o nome) primeiro diverge lendo Proto→Entity.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 (or name) first diverges reading Proto→Entity.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 el tipo (o el nombre) primero diverge leyendo Proto→Entity.

• MarginCalculator raiz 2 campos

  Campo	Proto	DTO	Model	Entity
  lastSyncAt	—	DateTime	DateTime	DateTime
  products	repeated MarginCalculatorProduct	List<…DTO>	ToMany<…Model>	List<…Entity>

  • MarginCalculatorProduct MarginCalculator.products[] 10 campos

    Campo	Proto	DTO	Model	Entity
    sfid	string	String	String @Unique	String
    accountSfids	accountSfid repeated string	List<String>	List<String>	List<String>
    name	string	String	String	String
    sticksPerPack	int32	int	int	int
    retailerCostPerStick	double	double	double	double
    retailerCostPerPack	double	double	double	double
    rrpPerStick	double	double	double	double
    rrpPerPack	double	double	double	double
    rrspPerStick	double	double	double	double
    rrspPerPack	double	double	double	double

Mappers

As conversões entre camadas, todas como extension (5 direções por tipo). Aqui o método DTO→Entity e Model→Entity chama-se toEntity() (não toDomain()):The conversions between layers, all as extensions (5 directions per type). Here the DTO→Entity and Model→Entity method is named toEntity() (not toDomain()):Las conversiones entre capas, todas como extension (5 direcciones por tipo). Aquí el método DTO→Entity y Model→Entity se llama toEntity() (no toDomain()):

MarginCalculatorRepositoryImpl implementaimplementsimplementa MarginCalculatorRepositoryInterface e injeta os 3 datasources (mock/local/remote) + ConnectivityService + a flag useMock + Ref. Método a método:and injects the 3 datasources (mock/local/remote) + ConnectivityService + the useMock flag + Ref. Method by method:e inyecta los 3 datasources (mock/local/remote) + ConnectivityService + la flag useMock + Ref. 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.

A feature não tem enums de domínio — todos os campos do modelo são primitivos. O único enum é de UI: a aba ativa da tela. Não trafega no wire nem é persistido.The feature has no domain enums — every model field is primitive. The only enum is a UI one: the screen's active tab. It doesn't travel on the wire and isn't persisted.La feature no tiene enums de dominio — todos los campos del modelo son primitivos. El único enum es de UI: la pestaña activa de la pantalla. No viaja en el wire ni se persiste.

Dois UseCases, ambos em usecases/margin_calculator/. O container é compartilhado por conta — cada produto declara a lista de contas (accountSfids) a que pertence — então o notifier consome a variante por conta.Two UseCases, both in usecases/margin_calculator/. The container is shared per account — each product declares the list of accounts (accountSfids) it belongs to — so the notifier consumes the per-account variant.Dos UseCases, ambos en usecases/margin_calculator/. El container es compartido por cuenta — cada producto declara la lista de cuentas (accountSfids) a la que pertenece — así el notifier consume la variante por cuenta.

O MarginCalculatorNotifier (@riverpod, family por visitSfid, with AsyncGuard<MarginCalculatorState>) é o cérebro da tela. O build({visitSfid}) observa os UseCases, resolve a visita pelo sfid (getCachedBySfid) para descobrir o varejo, e busca o catálogo daquela conta. O State (MarginCalculatorState, Freezed) é a fonte única de verdade: guarda os produtos, a seleção, a aba e os quatro campos digitados — e todo o cálculo vive em getters do State, recomputado a cada dígito.The MarginCalculatorNotifier (@riverpod, family by visitSfid, with AsyncGuard<MarginCalculatorState>) is the screen's brain. build({visitSfid}) watches the UseCases, resolves the visit by sfid (getCachedBySfid) to find the retailer, and fetches that account's catalog. The State (MarginCalculatorState, Freezed) is the single source of truth: it holds the products, selection, tab and the four typed fields — and all math lives in State getters, recomputed on every keystroke.El MarginCalculatorNotifier (@riverpod, family por visitSfid, with AsyncGuard<MarginCalculatorState>) es el cerebro de la pantalla. build({visitSfid}) observa los UseCases, resuelve la visita por sfid (getCachedBySfid) para hallar el punto de venta, y busca el catálogo de esa cuenta. El State (MarginCalculatorState, Freezed) es la fuente única de verdad: guarda los productos, la selección, la pestaña y los cuatro campos digitados — y toda la matemática vive en getters del State, recalculada en cada tecla.

MétodosMethodsMétodos

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

A MarginCalculatorPage (ConsumerWidget, recebe só o visitSfid) observa o marginCalculatorProvider(visitSfid:) e monta os widgets filhos. Loading e erro são globais (asyncState.when); o conteúdo existe só no ramo data. Cada card filho é auto-suficiente (lê o provider e retorna SizedBox.shrink() se o State for nulo). Árvore de composição:MarginCalculatorPage (ConsumerWidget, takes only visitSfid) watches marginCalculatorProvider(visitSfid:) and composes the child widgets. Loading and error are global (asyncState.when); content exists only in the data branch. Each child card is self-sufficient (reads the provider and returns SizedBox.shrink() if State is null). Composition tree:MarginCalculatorPage (ConsumerWidget, recibe solo el visitSfid) observa el marginCalculatorProvider(visitSfid:) y compone los widgets hijos. Loading y error son globales (asyncState.when); el contenido existe solo en la rama data. Cada card hijo es autosuficiente (lee el provider y retorna SizedBox.shrink() si el State es nulo). Árbol de composición:

• MarginCalculatorPage
  • AppPageShell displayBackButton · bg=background
    • CustomLoadingIndicator loading
    • FailureStateView error → invalidate
    • CustomPullToRefresh data → refresh()
      • DataLoadInfo state.lastSyncAt
      • MarginCalculatorHeader ícone + título
      • MarginCalculatorProductDropdown CustomDropdown.single → selectProduct
        • ConectaModal picker de produto (aberto pelo CustomDropdown)
      • MarginCalculatorTabBar Stick (azul) / Pack (verde) → selectTab
      • MarginCalculatorInputValuesCard ConsumerStatefulWidget · controllers espelham o State
        • CustomInput preço → updateActualSellingPriceForActiveTab
        • CustomInput qtd packs → updateQtyPacksForActiveTab
      • MarginCalculatorBankableCard RRSP/Actual por unidade + total; stick: callouts pack→stick + conversão
      • MarginCalculatorCombinedTotalsCard header roxo · stick+pack+total
      • MarginCalculatorIncidenceCard header laranja · margem % (value.toStringAsFixed(2))

O MarginCalculatorInputValuesCard mantém dois TextEditingController e os re-sincroniza com o State quando a aba ou o produto muda (_syncControllersIfNeeded), para os valores de cada aba não vazarem entre si. Valores monetários usam CurrencyUtils.formatAmountOnly; a margem % usa toStringAsFixed(2) por ser percentual, não moeda.The MarginCalculatorInputValuesCard keeps two TextEditingControllers and re-syncs them with State when tab or product changes (_syncControllersIfNeeded), so each tab's values don't bleed across. Money uses CurrencyUtils.formatAmountOnly; margin % uses toStringAsFixed(2) since it's a percentage, not currency.El MarginCalculatorInputValuesCard mantiene dos TextEditingController y los re-sincroniza con el State cuando cambia la pestaña o el producto (_syncControllersIfNeeded), para que los valores de cada pestaña no se filtren entre sí. Los valores monetarios usan CurrencyUtils.formatAmountOnly; el margen % usa toStringAsFixed(2) por ser porcentaje, no moneda.