Feature · Contagem de estoqueFeature · Stock countFeature · Conteo de stock

Contagem de estoqueStock countConteo de stock

A ferramenta que o representante de vendas usa dentro de uma visita para registrar quanto produto o varejo ainda tem — duas quantidades por item, na unidade de medida Alta e na Baixa. A lista de produtos vem do cache do catálogo, filtrada por categoria e por família de marca; cada cartão ainda mostra uma grade com as últimas quatro contagens. As quantidades são digitadas na tela e enviadas ao backend pelo Dispatcher, sem nunca serem gravadas no aparelho. The tool a sales rep uses inside a visit to record how much product the retail still has — two quantities per item, in the High unit of measure and in the Low one. The product list comes from the catalog cache, filtered by category and brand family; each card also shows a grid of the last four counts. The quantities are typed on screen and sent to the backend through the Dispatcher, never written to the device. La herramienta que el representante de ventas usa dentro de una visita para registrar cuánto producto le queda al punto de venta — dos cantidades por ítem, en la unidad de medida Alta y en la Baja. La lista de productos viene del caché del catálogo, filtrada por categoría y por familia de marca; cada tarjeta muestra además una grilla con los últimos cuatro conteos. Las cantidades se escriben en la pantalla y se envían al backend por el Dispatcher, sin grabarse nunca en el dispositivo.

PúblicoAudiencePúblico

Representante · QA · Suporte · DevRep · QA · Support · DevRepresentante · QA · Soporte · Dev

Onde ficaWhereDónde

Detalhe da visita → Ferramentas · e o encerramento de visita (BR/ZA)Visit detail → Tools · and visit end (BR/ZA)Detalle de la visita → Herramientas · y el cierre de visita (BR/ZA)

RelacionadoRelatedRelacionado

Visit Detail · Price Check · LocationStockUploadAPI (serviceName)

AtualizadoUpdatedActualizado

04/08/20262026-08-04

Disponível emAvailable inDisponible en BR CL ZA

O que é e para que serveWhat it is and what it's forQué es y para qué sirve

A Contagem de estoque é um levantamento de campo: durante a visita, o representante de vendas percorre a lista de produtos e anota, produto por produto, quanto ainda existe em estoque naquele varejo. São duas colunas de entrada por produto, nomeadas pela unidade de medida: Alta (a embalagem maior — caixa, pacote fechado) e Baixa (a unidade menor em que o mesmo produto também é contado). Stock count is a field survey: during the visit, the sales rep walks the product list and records, product by product, how much is still in stock at that retail. There are two input columns per product, named after the unit of measure: High (the larger pack — case, sealed carton) and Low (the smaller unit the same product is also counted in). El Conteo de stock es un levantamiento de campo: durante la visita, el representante de ventas recorre la lista de productos y anota, producto por producto, cuánto queda en stock en ese punto de venta. Hay dos columnas de entrada por producto, nombradas por la unidad de medida: Alta (el envase mayor — caja, paquete cerrado) y Baja (la unidad menor en la que el mismo producto también se cuenta).

Quais produtos aparecem?Which products show up?¿Qué productos aparecen?

Os do catálogo do mercado marcados pelo backend como disponíveis para contagem de estoque. A lista é a mesma para todos os varejos — apesar do texto do estado vazio prometer o contrário, ela não é recortada por varejo (ver Pendências).The ones in the market catalog flagged by the backend as available for stock count. The list is the same for every retail — despite what the empty-state copy promises, it is not sliced per retail (see Pending items).Los del catálogo del mercado marcados por el backend como disponibles para conteo de stock. La lista es la misma para todos los puntos de venta — a pesar de lo que promete el texto del estado vacío, no se recorta por punto de venta (ver Pendientes).

O que se digita?What do you type?¿Qué se escribe?

Só números inteiros. Cada produto tem dois campos independentes; pode-se preencher um, o outro ou os dois. Campo vazio significa "não contado" e o produto simplesmente não entra no envio.Whole numbers only. Each product has two independent fields; you may fill one, the other or both. An empty field means "not counted" and the product simply doesn't go into the submission.Solo números enteros. Cada producto tiene dos campos independientes; se puede completar uno, el otro o los dos. Un campo vacío significa "no contado" y el producto simplemente no entra en el envío.

O que acontece ao enviar?What happens on submit?¿Qué pasa al enviar?

O app confirma num modal, monta uma linha por produto contado e manda tudo num único envio ao backend. Com sucesso, avisa em verde, apaga as contagens e volta para a visita.The app asks for confirmation in a modal, builds one row per counted product and sends everything in a single submission. On success it shows a green notice, wipes the counts and returns to the visit.La app confirma en un modal, arma una fila por producto contado y manda todo en un único envío al backend. Con éxito avisa en verde, borra los conteos y vuelve a la visita.

Duas coisas diferentes chamadas "estoque"Two different things called "stock"Dos cosas distintas llamadas "stock" Esta tela mede o estoque do varejo, na prateleira. Ela não tem nada a ver com o controle de estoque da van — o saldo que o representante carrega no veículo e que alimenta o pedido pronta-entrega, descrito em Prompt. São dois subsistemas separados, que só compartilham a palavra: a contagem de estoque não lê nem atualiza o saldo da van. A grade de histórico que aparece em cada cartão vem do catálogo de produtos, não do saldo da van. This screen measures the retail's stock, on the shelf. It has nothing to do with van stock control — the balance the rep carries in the vehicle that feeds prompt-delivery orders, described in Prompt. They are two separate subsystems that only share the word: stock count neither reads nor updates the van balance. The history grid on each card comes from the product catalog, not from the van balance. Esta pantalla mide el stock del punto de venta, en la estantería. No tiene nada que ver con el control de stock de la van — el saldo que el representante lleva en el vehículo y que alimenta el pedido de entrega inmediata, descrito en Prompt. Son dos subsistemas separados que solo comparten la palabra: el conteo de stock no lee ni actualiza el saldo de la van. La grilla de historial de cada tarjeta viene del catálogo de productos, no del saldo de la van.

Como acessarHow to openCómo acceder

Caminho principal: a grade de ferramentas da visitaMain path: the visit tools gridCamino principal: la grilla de herramientas de la visitaAbra o Detalhe da visita, desça até Ferramentas e toque no tile da contagem de estoque. Esse é o acesso disponível nos três mercados. Não há aba inferior, item de menu lateral nem atalho na Home.Open the Visit detail, scroll to Tools and tap the stock count tile. This is the entry available in all three markets. There is no bottom tab, no side-menu item and no Home shortcut.Abra el Detalle de la visita, baje hasta Herramientas y toque el tile del conteo de stock. Ese es el acceso disponible en los tres mercados. No hay pestaña inferior, ítem de menú lateral ni atajo en el Home.
Segundo caminho: a lista de pendências do encerramento de visitaSecond path: the visit-end pending listSegundo camino: la lista de pendientes del cierre de visitaAo encerrar a visita, o app lista o que ficou pendente. Se a contagem de estoque estiver pendente, o cartão dela é tocável e abre esta mesma tela; ao voltar, a lista de pendências é recalculada. Esse caminho existe apenas no Brasil e na África do Sul — o Chile tem o tile, mas não declara a categoria de pendência.When closing the visit, the app lists what is still pending. If stock count is pending, its card is tappable and opens this same screen; on return, the pending list is recomputed. This path exists only in Brazil and South Africa — Chile has the tile but doesn't declare the pending category.Al cerrar la visita, la app lista lo que quedó pendiente. Si el conteo de stock está pendiente, su tarjeta es tocable y abre esta misma pantalla; al volver, la lista de pendientes se recalcula. Ese camino existe solo en Brasil y Sudáfrica — Chile tiene el tile, pero no declara la categoría de pendiente.
A visita tem de estar iniciadaThe visit must be startedLa visita tiene que estar iniciadaTodo tile da grade passa por uma verificação: se a visita ainda não foi iniciada, aparece um modal oferecendo iniciá-la. Confirmar inicia a visita mas não abre a ferramenta — é preciso tocar no tile de novo. O cartão de pendência do encerramento não passa por essa verificação (a visita já está em curso).Every tile in the grid goes through a check: if the visit hasn't been started, a modal appears offering to start it. Confirming starts the visit but does not open the tool — you have to tap the tile again. The visit-end pending card skips that check (the visit is already underway).Todo tile de la grilla pasa por una verificación: si la visita todavía no fue iniciada, aparece un modal ofreciendo iniciarla. Confirmar inicia la visita pero no abre la herramienta — hay que tocar el tile de nuevo. La tarjeta de pendiente del cierre no pasa por esa verificación (la visita ya está en curso).
A tela abre com a lista prontaThe screen opens with the list readyLa pantalla abre con la lista listaO que a ferramenta recebe é só o identificador do varejo — nem a visita nem o código SAP são passados adiante; a própria tela rebusca a visita no cache, e só no momento do envio. Os produtos vêm do catálogo já sincronizado; puxar a lista para baixo rebusca o catálogo no servidor.All the tool receives is the retail identifier — neither the visit nor the SAP code is passed along; the screen re-fetches the visit from cache, and only at submit time. The products come from the already-synced catalog; pulling the list down re-fetches the catalog from the server.Lo que la herramienta recibe es solo el identificador del punto de venta — ni la visita ni el código SAP se pasan adelante; la propia pantalla vuelve a buscar la visita en el caché, y solo en el momento del envío. Los productos vienen del catálogo ya sincronizado; deslizar la lista hacia abajo vuelve a buscar el catálogo en el servidor.

A chave de configuração se chama stock_history, não stock_countThe config key is called stock_history, not stock_countLa clave de configuración se llama stock_history, no stock_count Quem for procurar o interruptor desta feature no End Market Configuration não vai achar nenhuma chave stock_count na grade de ferramentas: o tile é declarado como stock_history (nome herdado de quando a tela só mostrava o histórico), e é esse item que dispara a navegação para a contagem. A chave stock_count existe, mas em outro lugar — é o nome da categoria de pendência no encerramento de visita. Duas chaves, dois gates distintos, e é comum confundi-los. Vale o mesmo aviso do lado da transação: "LocationStockUploadAPI" existe só como serviceName — não há arquivo build_location_stock_upload_…; o builder real é BuildStockCountDispatcherPayloadUseCase. Anyone looking for this feature's switch in the End Market Configuration will find no stock_count key in the tools grid: the tile is declared as stock_history (a name inherited from when the screen only showed history), and that item is what triggers navigation to the count. The stock_count key does exist, but elsewhere — it is the name of the visit-end pending category. Two keys, two distinct gates, and they are easy to confuse. The same warning applies on the transaction side: "LocationStockUploadAPI" exists only as the serviceName — there is no build_location_stock_upload_… file; the real builder is BuildStockCountDispatcherPayloadUseCase. Quien busque el interruptor de esta feature en el End Market Configuration no va a encontrar ninguna clave stock_count en la grilla de herramientas: el tile se declara como stock_history (nombre heredado de cuando la pantalla solo mostraba el historial), y es ese ítem el que dispara la navegación al conteo. La clave stock_count existe, pero en otro lugar — es el nombre de la categoría de pendiente en el cierre de visita. Dos claves, dos gates distintos, y es común confundirlos. Vale el mismo aviso del lado de la transacción: "LocationStockUploadAPI" existe solo como serviceName — no hay archivo build_location_stock_upload_…; el builder real es BuildStockCountDispatcherPayloadUseCase.

Estrutura da telaScreen structureEstructura de la pantalla

Última sincronizaçãoLast syncÚltima sincronización: Faixa no topo com a data e hora em que o catálogo de produtos foi baixado — não é a data da contagem.A strip at the top with the date and time the product catalog was downloaded — not the date of the count.Franja arriba con la fecha y hora en que se bajó el catálogo de productos — no es la fecha del conteo.
CabeçalhoHeaderEncabezado: Ícone da ferramenta e o título Contagem de estoque. Não há cartão do varejo aqui — o nome do varejo fica na tela da visita.The tool icon and the Stock count title. There is no retail card here — the retail name stays on the visit screen.Ícono de la herramienta y el título Conteo de stock. No hay tarjeta del punto de venta aquí — el nombre queda en la pantalla de la visita.
Dois filtros em cascataTwo cascading filtersDos filtros en cascada: Duas listas de seleção: Categoria e Marca. A de marca só fica habilitada depois de escolher uma categoria, e mostra apenas as marcas daquela categoria. Escolher uma categoria nova limpa a marca. Qualquer mudança de filtro volta a lista para os primeiros 20 produtos.Two pickers: Category and Brand. The brand one is enabled only after a category is chosen, and shows only that category's brands. Choosing a new category clears the brand. Any filter change resets the list to the first 20 products.Dos listas de selección: Categoría y Marca. La de marca se habilita solo después de elegir una categoría, y muestra solo las marcas de esa categoría. Elegir una categoría nueva limpia la marca. Cualquier cambio de filtro devuelve la lista a los primeros 20 productos.
Cabeçalho de colunasColumn headerEncabezado de columnas: Faixa única acima da lista: Marca à esquerda (com Histórico de contagem de estoque como legenda) e os rótulos Alta e Baixa alinhados exatamente sobre os dois campos de entrada. Desaparece quando não há produtos.A single strip above the list: Brand on the left (with Stock count history as a caption) and the High and Low labels aligned exactly over the two input fields. It disappears when there are no products.Franja única arriba de la lista: Marca a la izquierda (con Historial de conteo de stock como leyenda) y los rótulos Alta y Baja alineados exactamente sobre los dos campos de entrada. Desaparece cuando no hay productos.
Cartão de produtoProduct cardTarjeta de producto: Um cartão por produto, com borda fina e cantos bem arredondados. Em cima: botão de informação, nome do produto (até 2 linhas) e os dois campos-pílula de quantidade. Embaixo: a grade de histórico.One card per product, with a thin border and strongly rounded corners. On top: info button, product name (up to 2 lines) and the two pill fields for quantity. Below: the history grid.Una tarjeta por producto, con borde fino y esquinas bien redondeadas. Arriba: botón de información, nombre del producto (hasta 2 líneas) y los dos campos-píldora de cantidad. Abajo: la grilla de historial.
Grade de histórico (4 contagens)History grid (4 counts)Grilla de historial (4 conteos): Mini-tabela dentro do cartão: as datas viram colunas (pílulas azuis no topo, as 4 contagens mais recentes primeiro) e Alta / Baixa são rótulos de linha à esquerda, escritos uma única vez. Célula sem dado mostra -. Quando há menos de 4 contagens, as colunas restantes ficam com -.A mini table inside the card: dates become columns (blue pills on top, the 4 most recent counts first) and High / Low are row labels on the left, written once. A cell with no data shows -. When there are fewer than 4 counts, the remaining columns hold -.Mini-tabla dentro de la tarjeta: las fechas se vuelven columnas (píldoras azules arriba, los 4 conteos más recientes primero) y Alta / Baja son rótulos de fila a la izquierda, escritos una sola vez. Una celda sin dato muestra -. Cuando hay menos de 4 conteos, las columnas restantes quedan con -.
Botão de informação do produtoProduct info buttonBotón de información del producto: O ícone à esquerda do nome abre um modal com o nome e a foto do produto. É o mesmo componente usado na vitrine de pedido e na verificação de preço.The icon left of the name opens a modal with the product's name and photo. It's the same component used in the order showcase and in price check.El ícono a la izquierda del nombre abre un modal con el nombre y la foto del producto. Es el mismo componente usado en la vitrina de pedido y en la verificación de precio.
Carregamento por rolagemScroll loadingCarga por desplazamiento: A lista começa com 20 produtos e cresce de 20 em 20 conforme se rola, com uma pausa curta antes de cada leva. Enquanto houver produtos por carregar, uma rodinha fica embaixo da última linha.The list starts with 20 products and grows 20 at a time as you scroll, with a short pause before each batch. While products remain to load, a spinner sits under the last row.La lista empieza con 20 productos y crece de 20 en 20 al desplazar, con una pausa corta antes de cada lote. Mientras queden productos por cargar, una rueda queda debajo de la última fila.
Contador "X de Y""X of Y" counterContador "X de Y": Abaixo da lista: quantos produtos já estão na tela do total filtrado.Below the list: how many products are on screen out of the filtered total.Debajo de la lista: cuántos productos ya están en pantalla del total filtrado.
Barra de resumoSummary barBarra de resumen: Barra fixa no rodapé que só aparece depois da primeira quantidade digitada. Fechada, mostra três números — preenchidos, soma da Alta, soma da Baixa — e o botão de enviar.A bar pinned to the bottom that only appears after the first quantity is typed. Collapsed, it shows three numbers — filled, High total, Low total — and the submit button.Barra fija al pie que solo aparece después de la primera cantidad escrita. Cerrada, muestra tres números — llenados, suma de Alta, suma de Baja — y el botón de enviar.
Painel expandido do resumoExpanded summary panelPanel expandido del resumen: Arrastar a barra para cima abre a conferência: os produtos contados agrupados por categoria, com subtotal de Alta e de Baixa por categoria, cinco números no rodapé (total de produtos, preenchidos, vazios, soma da Alta, soma da Baixa) e o botão Limpar tudo. Produto sem contagem não aparece aqui; coluna não preenchida aparece com um marcador de vazio.Dragging the bar up opens the review: counted products grouped by category, with a High and a Low subtotal per category, five numbers in the footer (total products, filled, empty, High total, Low total) and the Clear all button. A product with no count isn't listed here; an unfilled column shows an empty marker.Arrastrar la barra hacia arriba abre la revisión: los productos contados agrupados por categoría, con subtotal de Alta y de Baja por categoría, cinco números al pie (total de productos, llenados, vacíos, suma de Alta, suma de Baja) y el botón Limpiar todo. Un producto sin conteo no aparece aquí; una columna no completada muestra un marcador de vacío.
Puxar para atualizarPull to refreshDeslizar para actualizar: Rebusca o catálogo no servidor. As quantidades já digitadas e os filtros ativos são preservados; a lista volta a mostrar os primeiros 20 produtos.Re-fetches the catalog from the server. Quantities already typed and the active filters are preserved; the list goes back to showing the first 20 products.Vuelve a buscar el catálogo en el servidor. Las cantidades ya escritas y los filtros activos se preservan; la lista vuelve a mostrar los primeros 20 productos.

A tela não tem busca, ordenação nem abas. A lista sai na ordem em que o backend entrega o catálogo. Comparada com a feature irmã — a verificação de preço, que tem a mesma anatomia de lista, dois campos por linha e barra de resumo —, a contagem de estoque ganha os dois filtros e a grade de histórico, e perde o cartão único que envolvia a tabela: aqui cada produto é um cartão próprio.The screen has no search, no sorting and no tabs. The list comes out in the order the backend delivers the catalog. Compared with its sibling feature — price check, which has the same list anatomy, two fields per row and a summary bar — stock count gains the two filters and the history grid, and loses the single card that wrapped the table: here each product is its own card.La pantalla no tiene búsqueda, orden ni pestañas. La lista sale en el orden en que el backend entrega el catálogo. Comparada con la feature hermana — la verificación de precio, que tiene la misma anatomía de lista, dos campos por fila y barra de resumen —, el conteo de stock gana los dos filtros y la grilla de historial, y pierde la tarjeta única que envolvía la tabla: aquí cada producto es una tarjeta propia.

Estados da telaScreen statesEstados de la pantalla

A contagem de estoque não tem "status" de negócio — nada é aprovado, rejeitado ou fica pendente dentro da tela. O que existe são os estados da própria tela (e, fora dela, a pendência do encerramento de visita):Stock count has no business "status" — nothing gets approved, rejected or left pending inside the screen. What exists are the screen's own states (and, outside it, the visit-end pending):El conteo de stock no tiene "estado" de negocio — nada se aprueba, se rechaza ni queda pendiente dentro de la pantalla. Lo que existe son los estados de la propia pantalla (y, fuera de ella, el pendiente del cierre de visita):

CarregandoLoadingCargando: Rodinha centralizada com o logo do app, cobrindo a tela inteira, enquanto o catálogo é lido.A centered spinner with the app logo, covering the whole screen, while the catalog is read.Rueda centrada con el logo de la app, cubriendo la pantalla entera, mientras se lee el catálogo.
ErroErrorError: Tela de falha com botão de tentar de novo, que recarrega a ferramenta do zero. Acontece quando o catálogo não pode ser lido nem do cache nem do servidor.A failure screen with a retry button that reloads the tool from scratch. It happens when the catalog can be read neither from cache nor from the server.Pantalla de fallo con botón de reintentar, que recarga la herramienta desde cero. Ocurre cuando el catálogo no puede leerse ni del caché ni del servidor.
Lista vaziaEmpty listLista vacía: Quando o filtro (ou o catálogo) não devolve nenhum produto, aparece o cartão de estado vazio com ícone e a mensagem "nenhum produto com histórico de vendas para este varejo". O cabeçalho de colunas desaparece junto. Vale notar que a mensagem descreve um filtro que o código não aplica (ver Pendências).When the filter (or the catalog) returns no product, the empty-state card appears with an icon and the message "no products with sales history for this retail". The column header disappears with it. Note that the message describes a filter the code doesn't apply (see Pending items).Cuando el filtro (o el catálogo) no devuelve ningún producto, aparece la tarjeta de estado vacío con ícono y el mensaje "sin productos con historial de ventas para este punto de venta". El encabezado de columnas desaparece junto. Cabe notar que el mensaje describe un filtro que el código no aplica (ver Pendientes).
Lista sem nada preenchidoList with nothing filledLista sin nada completado: Estado inicial: todos os campos vazios e sem barra de resumo. Não há como enviar nesse estado.Initial state: all fields empty and no summary bar. There is no way to submit in this state.Estado inicial: todos los campos vacíos y sin barra de resumen. No hay manera de enviar en ese estado.
EnviandoSubmittingEnviando: O botão de enviar mostra carregamento e para de aceitar toque. Os campos continuam editáveis.The submit button shows a loading state and stops accepting taps. The fields stay editable.El botón de enviar muestra carga y deja de aceptar toques. Los campos siguen editables.
Pendência no encerramento (BR/ZA)Visit-end pending (BR/ZA)Pendiente en el cierre (BR/ZA): Fora da tela: se algum produto do catálogo tiver histórico de contagem para aquele varejo, a contagem é considerada devida na visita e aparece na lista de pendências do encerramento. Marcada como não bloqueante — nunca impede finalizar a visita. O contador é sempre 1, nunca o número de produtos.Outside the screen: if any catalog product has count history for that retail, the count is considered due in the visit and shows up in the visit-end pending list. Flagged as non-blocking — it never prevents finishing the visit. The counter is always 1, never the number of products.Fuera de la pantalla: si algún producto del catálogo tiene historial de conteo para ese punto de venta, el conteo se considera debido en la visita y aparece en la lista de pendientes del cierre. Marcado como no bloqueante — nunca impide finalizar la visita. El contador es siempre 1, nunca el número de productos.

Nada é salvo em rascunhoNothing is saved as a draftNada se guarda como borrador As quantidades digitadas vivem só na memória da tela. Sair pelo botão de voltar — sem modal de confirmação — descarta tudo, e fechar o app também. Depois de um envio bem-sucedido as quantidades são apagadas de propósito, e reabrir a ferramenta mostra a lista completa com todos os campos vazios: o app não guarda marca de "já contado" no domínio. O único vestígio de que a contagem aconteceu é o registro de despacho, e é exatamente ele que o encerramento de visita consulta. The typed quantities live only in the screen's memory. Leaving via the back button — with no confirmation modal — discards everything, and so does killing the app. After a successful submission the quantities are wiped on purpose, and reopening the tool shows the full list with every field empty: the app keeps no "already counted" marker in the domain. The only trace that the count happened is the dispatch record, and that is exactly what visit end consults. Las cantidades escritas viven solo en la memoria de la pantalla. Salir por el botón de volver — sin modal de confirmación — descarta todo, y cerrar la app también. Tras un envío exitoso las cantidades se borran a propósito, y reabrir la herramienta muestra la lista completa con todos los campos vacíos: la app no guarda marca de "ya contado" en el dominio. El único vestigio de que el conteo ocurrió es el registro de despacho, y es exactamente lo que consulta el cierre de visita.

Contar e enviarCount and submitContar y enviar

Filtrar a listaFiltering the listFiltrar la lista

Escolha uma categoria para reduzir a lista; só então a lista de marcas fica utilizável, já restrita às marcas daquela categoria. As categorias aparecem na ordem fixa do app (não em ordem alfabética); as marcas, em ordem alfabética. Cada lista tem sua própria opção de limpar. Filtrar não apaga o que já foi digitado: as quantidades de um produto que saiu da lista continuam guardadas e continuam entrando no envio.Pick a category to narrow the list; only then does the brand picker become usable, already restricted to that category's brands. Categories appear in the app's fixed order (not alphabetically); brands, alphabetically. Each picker has its own clear option. Filtering does not erase what was already typed: quantities for a product that left the list stay stored and still go into the submission.Elija una categoría para reducir la lista; solo entonces la lista de marcas queda utilizable, ya restringida a las marcas de esa categoría. Las categorías aparecen en el orden fijo de la app (no alfabético); las marcas, en orden alfabético. Cada lista tiene su propia opción de limpiar. Filtrar no borra lo ya escrito: las cantidades de un producto que salió de la lista siguen guardadas y siguen entrando en el envío.

Digitar uma quantidadeTyping a quantityEscribir una cantidad

Os dois campos de cada cartão aceitam apenas dígitos — ponto, vírgula e sinal de menos são recusados na digitação, e o teclado abre no modo numérico sem decimal. Ou seja: não é possível contar meia caixa; a contagem é sempre um número inteiro. Apagar o conteúdo volta o campo a "não contado": se as duas colunas do produto ficarem vazias, ele sai do resumo e do envio como se nunca tivesse sido tocado. O outro campo do mesmo produto nunca é afetado ao editar um deles.Both fields on each card accept digits only — dot, comma and minus sign are refused as you type, and the keyboard opens in numeric mode without a decimal. In other words: you cannot count half a case; a count is always a whole number. Clearing the content returns the field to "not counted": if both of a product's columns end up empty, it drops out of the summary and out of the submission as if never touched. Editing one field never affects the other on the same product.Los dos campos de cada tarjeta aceptan solo dígitos — punto, coma y signo menos se rechazan al escribir, y el teclado abre en modo numérico sin decimal. O sea: no se puede contar media caja; el conteo es siempre un número entero. Borrar el contenido devuelve el campo a "no contado": si las dos columnas del producto quedan vacías, sale del resumen y del envío como si nunca hubiera sido tocado. Editar un campo nunca afecta al otro del mismo producto.

Por ser inteiro e sem separadores, a leitura do número não depende da convenção do mercado — a contagem de estoque não tem o problema de vírgula-versus-ponto que a verificação de preço tem.Being integer and separator-free, reading the number doesn't depend on market convention — stock count doesn't have the comma-versus-dot problem price check has.Al ser entero y sin separadores, la lectura del número no depende de la convención del mercado — el conteo de stock no tiene el problema de coma-versus-punto que tiene la verificación de precio.

Limpar tudoClear allLimpiar todo

Dentro do painel expandido do resumo. Abre um modal de confirmação; confirmando, todas as quantidades são apagadas de uma vez — inclusive as de produtos escondidos pelo filtro — e a barra de resumo desaparece. Os campos da lista se limpam junto, inclusive o que estiver com o cursor dentro. Os filtros não são afetados.Inside the expanded summary panel. It opens a confirmation modal; on confirm, all quantities are wiped at once — including those of products hidden by the filter — and the summary bar disappears. The list fields clear along with it, including one that currently has the cursor in it. The filters are not affected.Dentro del panel expandido del resumen. Abre un modal de confirmación; al confirmar, todas las cantidades se borran de una vez — incluidas las de productos escondidos por el filtro — y la barra de resumen desaparece. Los campos de la lista se limpian junto, incluso el que tenga el cursor dentro. Los filtros no se afectan.

EnviarSubmitEnviar

ConfirmaçãoConfirmationConfirmaciónO botão da barra de resumo abre um modal avisando que a contagem será enviada. Cancelar volta à lista sem enviar nada.The summary-bar button opens a modal warning that the count will be sent. Cancelling returns to the list without sending anything.El botón de la barra de resumen abre un modal avisando que el conteo será enviado. Cancelar vuelve a la lista sin enviar nada.
EnvioSubmissionEnvíoO app monta uma linha por produto contado — varejo, produto, lote, as duas quantidades, os nomes das duas unidades de medida, a visita e o representante — e manda tudo num único envio. Produtos sem contagem não entram.The app builds one row per counted product — retail, product, batch, both quantities, both unit-of-measure names, the visit and the rep — and sends it all in a single submission. Products with no count are left out.La app arma una fila por producto contado — punto de venta, producto, lote, las dos cantidades, los nombres de las dos unidades de medida, la visita y el representante — y manda todo en un único envío. Los productos sin conteo no entran.
Resultado em telaOn-screen resultResultado en pantallaSucesso mostra o aviso verde, apaga as quantidades e volta para o detalhe da visita. Falha mostra o aviso vermelho (com o código do erro) e mantém a tela como está, com tudo preenchido, para tentar de novo — inclusive o que foi digitado enquanto o envio estava em voo.Success shows the green notice, wipes the quantities and returns to the visit detail. Failure shows the red notice (with the error code) and leaves the screen as it is, everything filled in, so you can retry — including whatever was typed while the submission was in flight.El éxito muestra el aviso verde, borra las cantidades y vuelve al detalle de la visita. El fallo muestra el aviso rojo (con el código del error) y deja la pantalla como está, con todo completado, para reintentar — incluso lo que se escribió mientras el envío estaba en vuelo.

Sem conexão o envio falha na hora — e reenviar pode duplicarOffline the submission fails right away — and resending may duplicateSin conexión el envío falla en el momento — y reenviar puede duplicar A contagem de estoque não entra na fila de reenvio automático do Dispatcher — offline ela vai ao transporte, falha e é registrada como erro. O registro fica visível na Central de dados e pode ser reenviado à mão, mas — ao contrário da verificação de preço — a contagem não é um dos tipos marcados como reenvio seguro, então repetir o envio traz aviso de possível duplicidade. Nada bloqueia o encerramento da visita por causa de uma contagem pendente; pior, um envio que falhou ainda marca a pendência como resolvida (ver Pendências). Stock count does not enter the Dispatcher's automatic retry queue — offline it goes to transport, fails and is recorded as an error. The record shows up in the Data center and can be resent by hand, but — unlike price check — the count is not one of the types flagged as safe to resend, so repeating the submission carries a possible-duplicate warning. Nothing blocks closing the visit over a pending count; worse, a submission that failed still marks the pending as resolved (see Pending items). El conteo de stock no entra en la cola de reenvío automático del Dispatcher — offline va al transporte, falla y se registra como error. El registro queda visible en la Central de datos y puede reenviarse a mano, pero — a diferencia de la verificación de precio — el conteo no es uno de los tipos marcados como reenvío seguro, así que repetir el envío trae aviso de posible duplicidad. Nada bloquea el cierre de la visita por un conteo pendiente; peor, un envío que falló igual marca el pendiente como resuelto (ver Pendientes).

Arquitetura e fluxo de dadosArchitecture & data flowArquitectura y flujo de datos

Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox, com dois caminhos que não se cruzam. A leitura é do catálogo de produtos — um agregado compartilhado por várias features (§29 do CLAUDE.md): um único RPC traz o catálogo do mercado inteiro, que é gravado no ObjectBox, e a contagem de estoque lê de lá através do seu UseCase próprio, que filtra pela flag de elegibilidade. A escrita não usa esse proto nem nenhum outro: as quantidades digitadas vão como JSON pelo Dispatcher.Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox, with two paths that never cross. Reading is the product catalog — an aggregate shared by several features (CLAUDE.md §29): a single RPC brings the whole market catalog, it is written to ObjectBox, and stock count reads from there through its own UseCase, which filters on the eligibility flag. Writing uses neither that proto nor any other: the typed quantities go as JSON through the Dispatcher.Clean Architecture + Riverpod + Freezed + gRPC + ObjectBox, con dos caminos que no se cruzan. La lectura es del catálogo de productos — un agregado compartido por varias features (§29 del CLAUDE.md): un único RPC trae el catálogo del mercado entero, que se graba en ObjectBox, y el conteo de stock lee de allí a través de su UseCase propio, que filtra por la flag de elegibilidad. La escritura no usa ese proto ni ningún otro: las cantidades escritas van como JSON por el Dispatcher.

Leitura — catálogo de produtosRead — product catalogLectura — catálogo de productos

ProductCatalogReplygRPC proto
- toDTOProductCatalogDTODTO · Freezed
  - toDomain · compute (isolate)ProductCatalogEntitydomain · lastSyncAt gerado aqui
    - toModelProductCatalogModelObjectBox · 11 boxes
      - toDomainProductCatalogEntitydomain · cache
        
        GetProductsForStockCountUseCaseStockCountNotifier + Statefiltra isAvailableForStockCount
        
        → UIStockCountPage

Escrita — contagensWrite — countsEscritura — conteos

StockCountState.entriesMap<productSfid, StockCountEntryEntity>
- submit · + resource + visit (cache)StockCountDispatcherPayloadInputentities cruas · 7 campos
  - buildDispatcherEnvelope1 envelope · sem fatiamento
    - SubmitStockCountUseCaseDispatcherOrchestrator
      - sendTransactionLocationStockUploadAPIgRPC · Dispatcher · salesforce
        
        ackDispatchTransactionhistórico local · lido pelo encerramento de visita

Os dois caminhos não se encontram — e nem tocam o estoque da vanThe two paths never meet — and neither touches van stockLos dos caminos no se encuentran — y ninguno toca el stock de la van O envio não grava nada no domínio do catálogo nem em nenhuma box da feature: as quantidades digitadas nunca são persistidas, nem antes nem depois do envio. StockCountEntryEntity existe só na camada de domínio — não tem proto, DTO nem Model, e não há pasta stock_count em lib/data. A única gravação local que um envio produz é o registro de auditoria do despacho. E, apesar do nome, o StockControlConectaRep.proto (o saldo da van) não é lido nem atualizado por esta feature: o grep de StockControl dentro de lib/presentation/stock_count/ devolve zero. A transação vive em 26 · LocationStockUpload. Submission writes nothing into the catalog domain nor into any box of the feature: the typed quantities are never persisted, before or after sending. StockCountEntryEntity exists only in the domain layer — it has no proto, no DTO and no Model, and there is no stock_count folder under lib/data. The only local write a submission produces is the dispatch audit record. And, despite the name, StockControlConectaRep.proto (the van balance) is neither read nor updated by this feature: grepping StockControl inside lib/presentation/stock_count/ returns zero. The transaction lives in 26 · LocationStockUpload. El envío no graba nada en el dominio del catálogo ni en ninguna box de la feature: las cantidades escritas nunca se persisten, ni antes ni después del envío. StockCountEntryEntity existe solo en la capa de dominio — no tiene proto, DTO ni Model, y no hay carpeta stock_count en lib/data. La única grabación local que un envío produce es el registro de auditoría del despacho. Y, a pesar del nombre, el StockControlConectaRep.proto (el saldo de la van) no se lee ni se actualiza por esta feature: el grep de StockControl dentro de lib/presentation/stock_count/ devuelve cero. La transacción vive en 26 · LocationStockUpload.

Modelo de dadosData modelModelo de datos

O catálogo de produtos 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 se mantêm em todas as camadas e o que muda é pouquíssimo: as relações viram ToOne/ToMany no Model, um campo é renomeado no Proto e o lastSyncAt não existe no wire. O fetch é write-through: todo retorno remoto é gravado no ObjectBox (a gravação limpa e regrava 11 boxes) e a tela passa a ler do cache.The product catalog 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. Names stay the same across layers and very little changes: relations become ToOne/ToMany in the Model, one field is renamed in the Proto, and lastSyncAt doesn't exist on the wire. Fetch is write-through: every remote response is written to ObjectBox (the write clears and rewrites 11 boxes) and the screen then reads from cache.El catálogo de productos 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 se mantienen en todas las capas y cambia muy poco: las relaciones pasan a ToOne/ToMany en el Model, un campo se renombra en el Proto y el lastSyncAt no existe en el wire. El fetch es write-through: toda respuesta remota se graba en ObjectBox (la grabación limpia y regraba 11 boxes) y la pantalla lee del caché.

O catálogo chega num container ProductCatalogEntity de 2 campos (lastSyncAt gerado no mapper + products[]); cada item é um Product de 24 campos, com 9 sub-estruturas aninhadas. Desses 24 campos, a contagem de estoque lê oito: productSfid, name, categoryGroup e brandFamily (filtros e agrupamento), o bloco eligibility (para filtrar), salesHistory (a grade de histórico), uom (os nomes das duas unidades no payload) e manufacturingSkus (lote e SKU no payload). Os outros 16 são carregados e ignorados — inclusive pricingByGroup, ou seja, a tela nunca resolve preço, e halfPack, ou seja, não há meia-embalagem aqui. Existe ainda uma décima segunda estrutura, StockCountEntry, que só existe no domínio: é o que o representante digita, e não tem proto, DTO nem Model. A seguir, na ordem: o proto, as estruturas de dados campo-a-campo por camada, e os mappers.The catalog arrives in a 2-field ProductCatalogEntity container (lastSyncAt generated in the mapper + products[]); each item is a 24-field Product with 9 nested sub-structures. Of those 24 fields, stock count reads eight: productSfid, name, categoryGroup and brandFamily (filters and grouping), the eligibility block (to filter), salesHistory (the history grid), uom (both unit names in the payload) and manufacturingSkus (batch and SKU in the payload). The other 16 are loaded and ignored — including pricingByGroup, i.e. the screen never resolves a price, and halfPack, i.e. there is no half-pack here. There is also a twelfth structure, StockCountEntry, which exists only in the domain: it is what the rep types, and it has no proto, no DTO and no Model. Next, in order: the proto, the field-by-field data structures per layer, and the mappers.El catálogo llega en un container ProductCatalogEntity de 2 campos (lastSyncAt generado en el mapper + products[]); cada ítem es un Product de 24 campos, con 9 sub-estructuras anidadas. De esos 24 campos, el conteo de stock lee ocho: productSfid, name, categoryGroup y brandFamily (filtros y agrupamiento), el bloque eligibility (para filtrar), salesHistory (la grilla de historial), uom (los nombres de las dos unidades en el payload) y manufacturingSkus (lote y SKU en el payload). Los otros 16 se cargan y se ignoran — incluido pricingByGroup, o sea, la pantalla nunca resuelve precio, y halfPack, o sea, no hay media-envase aquí. Existe además una duodécima estructura, StockCountEntry, que solo existe en el dominio: es lo que el representante escribe, y no tiene proto, DTO ni Model. A continuación, en orden: el proto, las estructuras de datos campo a campo por capa, y los mappers.

Proto

ProductCatalogConectaRep.proto · proto3 · package mn.bat.conectarep.streambridge. Um serviço (ProductCatalogConectaRepService), um método unário, 12 messages e nenhum enum. A contagem de estoque não tem proto de escrita — o envio é JSON pelo Dispatcher:One service (ProductCatalogConectaRepService), a single unary method, 12 messages and no enums. Stock count has no write proto — the submission is JSON through the Dispatcher:Un servicio (ProductCatalogConectaRepService), un método unario, 12 messages y ningún enum. El conteo de stock no tiene proto de escritura — el envío es JSON por el Dispatcher:

getProductCatalogunary

MétodoMethodMétodo

rpc getProductCatalog(ProductCatalogRequest) returns (ProductCatalogReply)

path /mn.bat.conectarep.streambridge.ProductCatalogConectaRepService/getProductCatalog

Request · ProductCatalogRequest

locationHierarchySfid: string · #1 · hierarquia do representante de vendas (resolvida no repository, §25)sales rep hierarchy (resolved in the repository, §25)jerarquía del representante de ventas (resuelta en el repository, §25)
dateReference: string · #2 · optional — o datasource aceita, e o único caller não passa (ver Pendências)optional — the datasource accepts it, and the only caller never passes it (see Pending items)optional — el datasource lo acepta, y el único caller no lo pasa (ver Pendientes)
lastModifiedDate: string · #3 · optional — não plumbado em camada nenhuma (ver Pendências)optional — not plumbed in any layer (see Pending items)optional — no plumbeado en ninguna capa (ver Pendientes)

Reply · ProductCatalogReply

repeated Product products — o catálogo do mercado inteiro, sem recorte por varejo. Os 24 campos de Product e as 9 sub-estruturas estão detalhados nas Estruturas de dados abaixo.the whole market catalog, with no per-retail slice. Product's 24 fields and the 9 sub-structures are detailed in Data structures below.el catálogo del mercado entero, sin recorte por punto de venta. Los 24 campos de Product y las 9 sub-estructuras están detallados en Estructuras de datos abajo.

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 destaque marca onde o tipo primeiro muda. ¹ = optional no proto. Todo Model tem ainda um @Id() int id que não aparece nas outras camadas e não está contado.One dropdown per structure, nested by hierarchy. Each table has one column per layer — Proto · DTO · Model · Entity; the highlighted text marks where the type first changes. ¹ = optional in the proto. Every Model also carries an @Id() int id that doesn't appear in the other layers and isn't counted.Un dropdown por estructura, anidados por jerarquía. Cada tabla tiene una columna por capa — Proto · DTO · Model · Entity; el texto destacado marca dónde primero cambia el tipo. ¹ = optional en el proto. Todo Model lleva además un @Id() int id que no aparece en las otras capas y no está contado.

ProductCatalog raiz 2 campos

Campo	Proto	DTO	Model	Entity
`lastSyncAt`	—	—	`DateTime`	DateTime
`products`	repeated Product	List<ProductDTO>	`ToMany<ProductModel>`	List<ProductEntity>

Product ProductCatalog.products[] 24 campos

Campo	Proto	DTO	Model	Entity
`productSfid`	string	String	String	String
`name`	string	String	String	String
`code`	string	String	String	String
`erpNumber`	string	String	String	String
`imageUrl`	string	String	String	String
`sequence`	int32	int	int	int
`category`	string	String	String	String
`categoryGroup`	string	String	String	String
`brandFamily`	string	String	String	String
`materialGroup`	string	String	String	String
`brandVariant`	string	String	String	String
`packContentSize`	string	String	String	String
`isFreeOfCharge`	bool	bool	bool	bool
`isVatRetention` ¹	bool	`bool?`	bool?	bool?
`splitGroup`	string	String	String	String
`internalId`	string	String	String	String
`invoiceUom`	string	String	String	String
`uom`	ProductUom	ProductUomDTO	`ToOne<ProductUomModel>`	ProductUomEntity
`halfPack`	ProductHalfPack	ProductHalfPackDTO	`ToOne<ProductHalfPackModel>`	ProductHalfPackEntity
`eligibility`	ProductEligibility	ProductEligibilityDTO	`ToOne<ProductEligibilityModel>`	ProductEligibilityEntity
`pricingByGroup`	repeated PricingGroup	List<PricingGroupDTO>	`ToMany<PricingGroupModel>`	List<PricingGroupEntity>
`soqByAccount`	repeated SoqByAccount	List<SoqByAccountDTO>	`ToMany<SoqByAccountModel>`	List<SoqByAccountEntity>
`salesHistory`	repeated SalesHistory	List<SalesHistoryDTO>	`ToMany<SalesHistoryModel>`	List<SalesHistoryEntity>
`manufacturingSkus`	repeated ManufacturingSku	List<ManufacturingSkuDTO>	`ToMany<ManufacturingSkuModel>`	List<ManufacturingSkuEntity>

Nenhum campo desta estrutura é tipado como enum na Entity. categoryGroup e category continuam String crua nas quatro camadas; a conversão para CategoryGroup só acontece na leitura, dentro dos getters do State, para ordenar e rotular. Consequência: um valor desconhecido do backend atravessa a stack inteira sem log e só se manifesta na tela. O proto declara splitGroup/internalId/invoiceUom depois das sub-estruturas; DTO, Model e Entity os declaram antes — mesmos 24 campos, ordem de declaração diferente.No field of this structure is typed as an enum in the Entity. categoryGroup and category stay raw String across all four layers; conversion to CategoryGroup happens only on read, inside the State getters, to sort and label. Consequence: an unknown backend value crosses the whole stack with no log and only shows up on screen. The proto declares splitGroup/internalId/invoiceUom after the sub-structures; DTO, Model and Entity declare them before — same 24 fields, different declaration order.Ningún campo de esta estructura está tipado como enum en la Entity. categoryGroup y category siguen siendo String cruda en las cuatro capas; la conversión a CategoryGroup ocurre solo en la lectura, dentro de los getters del State, para ordenar y rotular. Consecuencia: un valor desconocido del backend atraviesa la stack entera sin log y solo se manifiesta en la pantalla. El proto declara splitGroup/internalId/invoiceUom después de las sub-estructuras; DTO, Model y Entity los declaran antes — mismos 24 campos, orden de declaración diferente.

ProductEligibility Product.eligibility · o filtro da feature 6 campos

Campo	Proto	DTO	Model	Entity
`isAvailableForOrder`	bool	bool	bool	bool
`isAvailableForBuyback`	bool	bool	bool	bool
`isAvailableForVanLoad`	bool	bool	bool	bool
`isAvailableForPriceCheck`	bool	bool	bool	bool
`isAvailableForStockCount`	bool	bool	bool	bool
`isAvailableForPromotionReward` ¹	bool	`bool?`	bool?	bool?

isAvailableForStockCount é o campo #5 e o único que esta feature consulta. É o sinal mecânico da §29: um bloco de flags isAvailableFor* significa agregado compartilhado, logo um repository neutro e um UseCase por consumidora. Os 5 primeiros caem em false quando ausentes do JSON; o 6º, sendo optional no proto, é o único que preserva null.isAvailableForStockCount is field #5 and the only one this feature consults. It is §29's mechanical signal: a block of isAvailableFor* flags means a shared aggregate, hence one neutral repository and one UseCase per consumer. The first 5 fall back to false when absent from the JSON; the 6th, being optional in the proto, is the only one that preserves null.isAvailableForStockCount es el campo #5 y el único que esta feature consulta. Es la señal mecánica de la §29: un bloque de flags isAvailableFor* significa agregado compartido, por lo tanto un repository neutro y un UseCase por consumidora. Los 5 primeros caen en false cuando están ausentes del JSON; el 6º, siendo optional en el proto, es el único que preserva null.

ProductUom Product.uom · a origem de "Alta" e "Baixa" 3 campos

Campo	Proto	DTO	Model	Entity
`primaryName`	string	String	String	String
`secondaryName`	string	String	String	String
`conversionFactor`	double	double	double	double

primaryName é a unidade Alta e secondaryName a Baixa; os dois saem no payload como uom1Name e uom2Name. conversionFactor não é usado pela contagem de estoque — a tela não converte Baixa em Alta nem soma as duas: elas são enviadas como duas medidas independentes.primaryName is the High unit and secondaryName the Low one; both go into the payload as uom1Name and uom2Name. conversionFactor is not used by stock count — the screen neither converts Low into High nor adds them up: they are sent as two independent measures.primaryName es la unidad Alta y secondaryName la Baja; las dos salen en el payload como uom1Name y uom2Name. conversionFactor no se usa en el conteo de stock — la pantalla no convierte Baja en Alta ni suma las dos: se envían como dos medidas independientes.

ProductHalfPack Product.halfPack · não usado aqui 2 campos

Campo Proto DTO Model Entity

allowed bool bool bool bool

increment double double double double

Carregado e ignorado: como os dois campos de contagem só aceitam inteiros, não há fração de embalagem nesta tela. Quem usa halfPack é a criação de pedido e a recompra.Loaded and ignored: since both count fields accept integers only, there is no pack fraction on this screen. halfPack is used by order creation and buyback.Cargado e ignorado: como los dos campos de conteo solo aceptan enteros, no hay fracción de envase en esta pantalla. Quien usa halfPack es la creación de pedido y la recompra.

Campo	Proto	DTO	Model	Entity
`allowed`	bool	bool	bool	bool
`increment`	double	double	double	double

SalesHistory Product.salesHistory[] · a grade de histórico 3 campos

Campo	Proto	DTO	Model	Entity
`accountSfid`	string	String	String	String
`isStockCount`	bool	bool	bool	bool
`records`	repeated SalesHistoryRecord	List<SalesHistoryRecordDTO>	`ToMany<SalesHistoryRecordModel>`	List<SalesHistoryRecordEntity>

Esta é uma das duas estruturas do catálogo recortadas por varejo (a outra é SoqByAccount): cada produto pode ter um histórico por accountSfid. O cartão escolhe o bloco cujo accountSfid casa com o varejo da rota. O isStockCount é o que o encerramento de visita usa para decidir se a contagem é devida — e é a única leitura de negócio de salesHistory fora desta tela (o merge de visita ad hoc também o percorre, para retê-lo por conta).This is one of the two catalog structures sliced per retail (the other is SoqByAccount): each product may have one history per accountSfid. The card picks the block whose accountSfid matches the route's retail. isStockCount is what visit end uses to decide whether the count is due — and it is the only business read of salesHistory outside this screen (the ad-hoc visit merge also walks it, to retain it per account).Esta es una de las dos estructuras del catálogo recortadas por punto de venta (la otra es SoqByAccount): cada producto puede tener un historial por accountSfid. La tarjeta elige el bloque cuyo accountSfid coincide con el punto de venta de la ruta. El isStockCount es lo que el cierre de visita usa para decidir si el conteo es debido — y es la única lectura de negocio de salesHistory fuera de esta pantalla (el merge de visita ad hoc también lo recorre, para retenerlo por cuenta).

SalesHistoryRecord SalesHistory.records[] · ppq = Alta · psq = Baixa 4 campos

Campo	Proto	DTO	Model	Entity
`dateReference`	string	String	String	String
`ppq`	int32	int	int	int
`psq`	string	String	String	String
`hasCountStock`	bool	bool	bool	bool

A estrutura mais importante e a mais mal nomeada da feature. ppq e psq são nomes de wire que nunca são expandidos nem renomeados em camada alguma — não existe primaryPackage/salesQuantity em lugar nenhum do repositório. A redefinição de Jul/2026 (Stock/Venda → Alta/Baixa) foi feita só na apresentação: ppq passou a ser lido como a linha Alta e psq como a linha Baixa, sem tocar proto, DTO, Model, Entity nem o streambridge. Note a assimetria de tipo, que é do contrato e não um erro de mapeamento: ppq é numérico e psq é texto — por isso a linha Baixa mostra - quando vem vazia (uma string em branco), enquanto a Alta sempre mostra um número, inclusive 0. dateReference é a string que vira a pílula de data, ordenada decrescente antes de cortar as 4 primeiras. hasCountStock chega, é mapeado nas 4 camadas e não tem nenhum leitor no app.The feature's most important and worst-named structure. ppq and psq are wire names that are never expanded or renamed in any layer — there is no primaryPackage/salesQuantity anywhere in the repository. The Jul/2026 redefinition (Stock/Sale → High/Low) was done in the presentation only: ppq came to be read as the High row and psq as the Low row, without touching proto, DTO, Model, Entity or the streambridge. Note the type asymmetry, which comes from the contract and is not a mapping bug: ppq is numeric and psq is text — that is why the Low row shows - when it arrives empty (a blank string), while High always shows a number, including 0. dateReference is the string that becomes the date pill, sorted descending before taking the first 4. hasCountStock arrives, is mapped across all 4 layers and has no reader in the app.La estructura más importante y peor nombrada de la feature. ppq y psq son nombres de wire que nunca se expanden ni se renombran en ninguna capa — no existe primaryPackage/salesQuantity en ningún lugar del repositorio. La redefinición de Jul/2026 (Stock/Venta → Alta/Baja) se hizo solo en la presentación: ppq pasó a leerse como la fila Alta y psq como la fila Baja, sin tocar proto, DTO, Model, Entity ni el streambridge. Note la asimetría de tipo, que viene del contrato y no es un error de mapeo: ppq es numérico y psq es texto — por eso la fila Baja muestra - cuando llega vacía (una cadena en blanco), mientras Alta siempre muestra un número, incluso 0. dateReference es la cadena que se vuelve la píldora de fecha, ordenada descendente antes de cortar las 4 primeras. hasCountStock llega, se mapea en las 4 capas y no tiene ningún lector en la app.

ManufacturingSku Product.manufacturingSkus[] · lote no payload 5 campos

Campo	Proto	DTO	Model	Entity
`manufacturingSkuSfid`	string	String	String	String
`batchId`	string	String	String	String
`name`	string	String	String	String
`code`	string	String	String	String
`erpNumber`	string	String	String	String

O builder do payload usa só o primeiro item da lista, e dele só manufacturingSkuSfid e batchId. Produto sem nenhum SKU de fabricação envia os dois campos como string vazia (ver Pendências).The payload builder uses only the first item of the list, and from it only manufacturingSkuSfid and batchId. A product with no manufacturing SKU sends both fields as an empty string (see Pending items).El builder del payload usa solo el primer ítem de la lista, y de él solo manufacturingSkuSfid y batchId. Un producto sin ningún SKU de fabricación envía los dos campos como cadena vacía (ver Pendientes).

PricingGroup Product.pricingByGroup[] · não usado aqui 2 campos

Campo	Proto	DTO	Model	Entity
`pricingGroupId`	string	String	String	String
`priceEntries`	repeated PriceEntry	List<PriceEntryDTO>	`ToMany<PriceEntryModel>`	List<PriceEntryEntity>

Carregado e ignorado. A contagem de estoque é a única das consumidoras do catálogo que não resolve preço — não há grupo de preço, nem valor, nem total monetário em nenhum lugar da tela ou do payload.Loaded and ignored. Stock count is the only catalog consumer that doesn't resolve a price — there is no pricing group, no value and no monetary total anywhere on the screen or in the payload.Cargado e ignorado. El conteo de stock es la única de las consumidoras del catálogo que no resuelve precio — no hay grupo de precio, ni valor, ni total monetario en ningún lugar de la pantalla o del payload.

PriceEntry PricingGroup.priceEntries[] 10 campos

Campo	Proto	DTO	Model	Entity
`manufacturingSkuId`	`manufacturingSKUId`	String	String	String
`manufacturingSkuBatchId`	string	String	String	String
`validFrom`	string	String	String	String
`validTo`	string	String	String	String
`priceWithVat`	double	double	double	double
`priceWithoutVat`	double	double	double	double
`rrpWithVat` ¹	double	`double?`	double?	double?
`withholdingTax` ¹	double	`double?`	double?	double?
`priceEntryId`	string	String	String	String
`cashFeePercentage` ¹	double	`double?`	double?	double?

O único rename de todo o catálogo: o proto escreve manufacturingSKUId (SKU em maiúsculas) e as camadas Dart usam manufacturingSkuId. Nenhum destes 10 campos é lido pela contagem de estoque.The catalog's only rename: the proto writes manufacturingSKUId (uppercase SKU) and the Dart layers use manufacturingSkuId. None of these 10 fields is read by stock count.El único rename de todo el catálogo: el proto escribe manufacturingSKUId (SKU en mayúsculas) y las capas Dart usan manufacturingSkuId. Ninguno de estos 10 campos es leído por el conteo de stock.

SoqByAccount Product.soqByAccount[] · não usado aqui 2 campos

Campo Proto DTO Model Entity

accountSfid string String String String

value int32 int int int

Quantidade sugerida de pedido por varejo. Carregada e ignorada — a contagem não sugere quantidade nenhuma; o campo é vazio até o representante digitar.Suggested order quantity per retail. Loaded and ignored — the count suggests no quantity at all; the field is empty until the rep types.Cantidad sugerida de pedido por punto de venta. Cargada e ignorada — el conteo no sugiere ninguna cantidad; el campo está vacío hasta que el representante escribe.

StockCountEntry domain-only · nunca persistido 3 campos

Campo	Proto	DTO	Model	Entity
`productSfid`	—	—	—	`String`
`highUomCount`	—	—	—	`int?`
`lowUomCount`	—	—	—	`int?`

O que o representante digita. Só existe na camada de domínio — sem proto, sem DTO, sem Model, sem box. Um getter hasAnyCount devolve verdadeiro quando ao menos uma das duas contagens é não-nula; é ele que decide se o produto entra no resumo e no envio. Os dois campos são int? e não int de propósito: null significa "não contado" e é semanticamente diferente de zero ("contei, e não tem nenhum"). A entrada é removida do mapa — não zerada — quando as duas colunas ficam vazias. Antes de Jul/2026 esta estrutura tinha um único campo newStockCount.What the rep types. It exists only in the domain layer — no proto, no DTO, no Model, no box. A hasAnyCount getter returns true when at least one of the two counts is non-null; it is what decides whether the product enters the summary and the submission. Both fields are int? rather than int on purpose: null means "not counted" and is semantically different from zero ("I counted, and there are none"). The entry is removed from the map — not zeroed — when both columns go empty. Before Jul/2026 this structure had a single newStockCount field.Lo que el representante escribe. Solo existe en la capa de dominio — sin proto, sin DTO, sin Model, sin box. Un getter hasAnyCount devuelve verdadero cuando al menos uno de los dos conteos es no nulo; es él quien decide si el producto entra en el resumen y en el envío. Los dos campos son int? y no int a propósito: null significa "no contado" y es semánticamente distinto de cero ("conté, y no hay ninguno"). La entrada se elimina del mapa — no se pone en cero — cuando las dos columnas quedan vacías. Antes de Jul/2026 esta estructura tenía un único campo newStockCount.

Mappers

O catálogo tem 11 arquivos de mapper (um por estrutura), cada um com as 5 direções — 55 métodos de mapeamento em 44 extensions. StockCountEntry não tem mapper: nasce e morre no domínio.The catalog has 11 mapper files (one per structure), each with the 5 directions — 55 mapping methods across 44 extensions. StockCountEntry has no mapper: it is born and dies in the domain.El catálogo tiene 11 archivos de mapper (uno por estructura), cada uno con las 5 direcciones — 55 métodos de mapeo en 44 extensions. StockCountEntry no tiene mapper: nace y muere en el dominio.

DireçãoDirectionDirección	MétodoMethodMétodo	Quem chamaCallerQuién llama
JSON → DTO	`fromMap(map)` (static)(static)(static)	o datasource Mock, dentro de um isolatethe Mock datasource, inside an isolateel datasource Mock, dentro de un isolate
Proto → DTO	`toDTO()`	o datasource Remote, sobre o `ProductCatalogReply`the Remote datasource, on `ProductCatalogReply`el datasource Remote, sobre el `ProductCatalogReply`
DTO → Entity	`toDomain()`	o repository — no caminho remoto dentro de um `compute` (isolate); é aqui que o `lastSyncAt` nascethe repository — on the remote path inside a `compute` (isolate); this is where `lastSyncAt` is bornel repository — en el camino remoto dentro de un `compute` (isolate); es aquí donde nace el `lastSyncAt`
Entity → Model	`toModel()`	o datasource Local, ao gravar (preenche os `ToOne`/`ToMany`)the Local datasource, on write (fills the `ToOne`/`ToMany`)el datasource Local, al grabar (llena los `ToOne`/`ToMany`)
Model → Entity	`toDomain()`	o datasource Local, ao ler — o caminho que a tela usa em 99% dos casosthe Local datasource, on read — the path the screen uses 99% of the timeel datasource Local, al leer — el camino que la pantalla usa en el 99% de los casos

Duas notas de robustez: o mapper Proto→DTO é o único ponto onde optional vira null (via hasX()); e o Model→Entity do Product usa asserção de não-nulo nos três ToOne (uom, halfPack, eligibility) — um cache gravado sem eles lançaria exceção na leitura.Two robustness notes: the Proto→DTO mapper is the only place where optional becomes null (via hasX()); and Product's Model→Entity uses a non-null assertion on all three ToOne relations (uom, halfPack, eligibility) — a cache written without them would throw on read.Dos notas de robustez: el mapper Proto→DTO es el único punto donde optional se vuelve null (vía hasX()); y el Model→Entity del Product usa aserción de no nulo en las tres relaciones ToOne (uom, halfPack, eligibility) — un caché grabado sin ellas lanzaría excepción en la lectura.

Os únicos deltasThe only deltasLos únicos deltas

Relações → ToOne/ToMany no Model. Onze campos: products, os três ToOne do Product (uom, halfPack, eligibility), os quatro ToMany dele (pricingByGroup, soqByAccount, salesHistory, manufacturingSkus), priceEntries e records. Proto e Entity usam listas e objetos; só o ObjectBox usa relação.Relations → ToOne/ToMany in the Model. Eleven fields: products, Product's three ToOne (uom, halfPack, eligibility), its four ToMany (pricingByGroup, soqByAccount, salesHistory, manufacturingSkus), priceEntries and records. Proto and Entity use lists and objects; only ObjectBox uses relations.Relaciones → ToOne/ToMany en el Model. Once campos: products, los tres ToOne del Product (uom, halfPack, eligibility), sus cuatro ToMany (pricingByGroup, soqByAccount, salesHistory, manufacturingSkus), priceEntries y records. Proto y Entity usan listas y objetos; solo ObjectBox usa relaciones.
optional do proto → tipo nulável a partir do DTO. Cinco campos, todos marcados ¹: isVatRetention, isAvailableForPromotionReward, cashFeePercentage, rrpWithVat e withholdingTax. Nenhum deles é lido pela contagem de estoque.Proto optional → nullable type from the DTO on. Five fields, all marked ¹: isVatRetention, isAvailableForPromotionReward, cashFeePercentage, rrpWithVat and withholdingTax. None of them is read by stock count.optional del proto → tipo nulable a partir del DTO. Cinco campos, todos marcados ¹: isVatRetention, isAvailableForPromotionReward, cashFeePercentage, rrpWithVat y withholdingTax. Ninguno de ellos es leído por el conteo de stock.
Um rename, no Proto. manufacturingSKUId (proto) → manufacturingSkuId (Dart), em PriceEntry. É a única divergência de nome em todo o catálogo.One rename, in the Proto. manufacturingSKUId (proto) → manufacturingSkuId (Dart), in PriceEntry. It is the only name divergence in the whole catalog.Un rename, en el Proto. manufacturingSKUId (proto) → manufacturingSkuId (Dart), en PriceEntry. Es la única divergencia de nombre en todo el catálogo.
lastSyncAt não existe no wire. É gerado no mapper DTO→Entity e sobrevive ao filtro do UseCase porque este devolve o container, não a lista crua — é ele que alimenta a faixa de sincronização (§23).lastSyncAt doesn't exist on the wire. It is generated in the DTO→Entity mapper and survives the UseCase filter because the latter returns the container, not the bare list — it is what feeds the sync strip (§23).lastSyncAt no existe en el wire. Se genera en el mapper DTO→Entity y sobrevive al filtro del UseCase porque este devuelve el container, no la lista cruda — es lo que alimenta la franja de sincronización (§23).
Nenhum enum tipado, em nenhuma camada. Ao contrário de quase toda outra feature do app, o catálogo não converte string em enum no mapper: categoryGroup, category e os nomes de unidade de medida ficam String nas quatro camadas, e a tipagem só acontece na leitura da tela.No typed enum, in any layer. Unlike almost every other feature in the app, the catalog doesn't convert strings into enums in the mapper: categoryGroup, category and the unit-of-measure names stay String across all four layers, and typing happens only when the screen reads them.Ningún enum tipado, en ninguna capa. A diferencia de casi toda otra feature de la app, el catálogo no convierte cadenas en enums en el mapper: categoryGroup, category y los nombres de unidad de medida quedan String en las cuatro capas, y el tipado ocurre solo cuando la pantalla los lee.
E um não-delta que engana: ppq (numérico) e psq (texto) atravessam as quatro camadas sem nenhuma mudança de nome ou tipo. A reinterpretação Alta/Baixa é puramente de apresentação — por isso ela não aparece como delta em lugar nenhum desta seção.And one non-delta that misleads: ppq (numeric) and psq (text) cross all four layers with no change of name or type. The High/Low reinterpretation is purely presentational — which is why it appears as a delta nowhere in this section.Y un no-delta que engaña: ppq (numérico) y psq (texto) atraviesan las cuatro capas sin ningún cambio de nombre o tipo. La reinterpretación Alta/Baja es puramente de presentación — por eso no aparece como delta en ningún lugar de esta sección.

Repository

A contagem de estoque não tem repository próprio. Ela lê pelo ProductCatalogRepositoryInterface — o repository único e neutro do catálogo, que não conhece nenhuma feature consumidora (§29). São 5 métodos, nenhum deles nomeado por feature; a contagem usa exatamente um (getProductCatalog), através do seu UseCase. A escrita não passa por aqui: vai pelo repository do Dispatcher, que só conhece o gateway gRPC.Stock count has no repository of its own. It reads through ProductCatalogRepositoryInterface — the catalog's single, neutral repository, which knows no consuming feature (§29). There are 5 methods, none named after a feature; the count uses exactly one (getProductCatalog), through its UseCase. Writing doesn't go through here: it goes through the Dispatcher repository, which knows only the gRPC gateway.El conteo de stock no tiene repository propio. Lee por el ProductCatalogRepositoryInterface — el repository único y neutro del catálogo, que no conoce ninguna feature consumidora (§29). Son 5 métodos, ninguno nombrado por feature; el conteo usa exactamente uno (getProductCatalog), a través de su UseCase. La escritura no pasa por aquí: va por el repository del Dispatcher, que solo conoce el gateway gRPC.

getProductCatalog({source}) mock / local / remote

RetornoReturnRetorno Future<Result<ProductCatalogEntity, Failure>>

O único método que a contagem de estoque exercita, e o único com árvore de decisão. A origem é escolhida pelo parâmetro source (default local) cruzado com a sessão mock e a conectividade:The only method stock count exercises, and the only one with a decision tree. The source is chosen by the source parameter (default local) crossed with the mock session and connectivity:El único método que el conteo de stock ejercita, y el único con árbol de decisión. El origen se elige por el parámetro source (default local) cruzado con la sesión mock y la conectividad:

getProductCatalog(source)
- useMock || source == mock → JSON do mercado, decodificado em isolate→ market JSON, decoded in an isolate→ JSON del mercado, decodificado en isolate
- source == local || !isConnected → cache; cache vazio devolve NetworkFailure→ cache; an empty cache returns NetworkFailure→ caché; un caché vacío devuelve NetworkFailure
- source == remote && isConnected → remoto com fallback→ remote with fallback→ remoto con fallback
  - currentResourceProvider resolve o locationHierarchySfid aqui (§25); resource nulo → cacheresolves locationHierarchySfid here (§25); null resource → cacheresuelve el locationHierarchySfid aquí (§25); resource nulo → caché
  - toDomain em compute (isolate)
  - saveProductCatalog write-through: limpa e regrava as 11 boxeswrite-through: clears and rewrites the 11 boxeswrite-through: limpia y regraba las 11 boxes
  - falhafailurefallo → cai para o cache; cache vazio → Error(failure)→ falls back to cache; empty cache → Error(failure)→ cae al caché; caché vacío → Error(failure)

A tela abre sempre com local e só pede remote no pull-to-refresh. Consequência prática: abrir a ferramenta nunca vai à rede — se o catálogo nunca foi sincronizado, a tela abre em erro em vez de buscar. O locationHierarchySfid é resolvido dentro do repository, nunca passado pelo Notifier (§25).The screen always opens with local and only asks for remote on pull-to-refresh. Practical consequence: opening the tool never hits the network — if the catalog was never synced, the screen opens in error instead of fetching. locationHierarchySfid is resolved inside the repository, never passed by the Notifier (§25).La pantalla siempre abre con local y solo pide remote en el pull-to-refresh. Consecuencia práctica: abrir la herramienta nunca va a la red — si el catálogo nunca fue sincronizado, la pantalla abre en error en vez de buscar. El locationHierarchySfid se resuelve dentro del repository, nunca lo pasa el Notifier (§25).

getCachedProductCatalog() local

RetornoReturnRetorno Future<Result<ProductCatalogEntity?, Failure>>

Leitura pura do cache, sem fallback. Devolve null dentro de um Success quando não há nada gravado. A contagem de estoque não o chama — o filtro por elegibilidade obriga a passar pelo UseCase, que usa o método acima.A pure cache read, no fallback. Returns null inside a Success when nothing is stored. Stock count doesn't call it — the eligibility filter forces going through the UseCase, which uses the method above.Lectura pura del caché, sin fallback. Devuelve null dentro de un Success cuando no hay nada grabado. El conteo de stock no lo llama — el filtro por elegibilidad obliga a pasar por el UseCase, que usa el método de arriba.

getCachedProductCatalogLastSyncAt() local

RetornoReturnRetorno Future<DateTime?>

O único método da interface que não devolve Result: em caso de exceção ele registra o erro e devolve null, engolindo a falha de propósito — quem pergunta "quando sincronizou?" não deve quebrar por causa disso. Serve ao motor de frescor de dados, não à tela: a faixa de sincronização da contagem de estoque lê o lastSyncAt que já vem dentro do container (§23).The only interface method that doesn't return a Result: on exception it logs the error and returns null, swallowing the failure on purpose — asking "when did it sync?" shouldn't break over it. It serves the data-freshness engine, not the screen: stock count's sync strip reads the lastSyncAt that already comes inside the container (§23).El único método de la interfaz que no devuelve Result: en caso de excepción registra el error y devuelve null, tragando el fallo a propósito — quien pregunta "¿cuándo sincronizó?" no debe romperse por eso. Sirve al motor de frescura de datos, no a la pantalla: la franja de sincronización del conteo de stock lee el lastSyncAt que ya viene dentro del container (§23).

getCachedProductBySfid({productSfid}) local · §28 A

RetornoReturnRetorno Future<Result<ProductEntity?, Failure>>

Lookup de item único no padrão §28 categoria A (cache-only, nunca remoto), por varredura linear sobre o catálogo inteiro. Nenhuma feature do app o chama — nem a contagem de estoque, que já tem os produtos no State e os indexa por productSfid no próprio mapa de contagens.Single-item lookup in the §28 category A pattern (cache-only, never remote), by linear scan over the whole catalog. No app feature calls it — not stock count either, which already holds the products in State and indexes them by productSfid in the counts map itself.Lookup de ítem único en el patrón §28 categoría A (cache-only, nunca remoto), por barrido lineal sobre el catálogo entero. Ninguna feature de la app lo llama — tampoco el conteo de stock, que ya tiene los productos en el State y los indexa por productSfid en el propio mapa de conteos.

saveProductCatalog({productCatalog}) local

RetornoReturnRetorno Future<Result<void, Failure>>

Gravação explícita do catálogo no cache, usada pelo motor de sincronização. Não é o caminho do write-through do fetch remoto — esse chama o datasource local direto, dentro do próprio método de busca.Explicit catalog write to cache, used by the sync engine. It is not the remote fetch's write-through path — that one calls the local datasource directly, inside the fetch method itself.Grabación explícita del catálogo en el caché, usada por el motor de sincronización. No es el camino del write-through del fetch remoto — ese llama al datasource local directo, dentro del propio método de búsqueda.

Datasources

Três datasources do catálogo, com três tratamentos de erro diferentes. Nenhum deles é da contagem de estoque: são compartilhados por todas as consumidoras do catálogo. A feature não tem datasource próprio — nem local (não persiste nada) nem remoto (a escrita vai pelo gateway do Dispatcher).Three catalog datasources, with three different error treatments. None of them belongs to stock count: they are shared by every catalog consumer. The feature has no datasource of its own — neither local (it persists nothing) nor remote (the write goes through the Dispatcher gateway).Tres datasources del catálogo, con tres tratamientos de error diferentes. Ninguno de ellos es del conteo de stock: son compartidos por todas las consumidoras del catálogo. La feature no tiene datasource propio — ni local (no persiste nada) ni remoto (la escritura va por el gateway del Dispatcher).

Remote ProductCatalogRemoteDataSource gRPC · 1

getProductCatalog({locationHierarchySfid, dateReference?})

MétodoMethodMétodo: Future<ProductCatalogDTO> — o único método da classethe class's only methodel único método de la clase
EnvioSendsEnvío: ProductCatalogRequest — locationHierarchySfid sempre; dateReference só é atribuído se não-nulo; lastModifiedDate (#3) nunca é atribuídolocationHierarchySfid always; dateReference is only assigned when non-null; lastModifiedDate (#3) is never assignedlocationHierarchySfid siempre; dateReference solo se asigna si no es nulo; lastModifiedDate (#3) nunca se asigna
RetornoReturnsRetorno: ProductCatalogDTO — reply.toDTO(), o catálogo do mercado inteiroProductCatalogDTO — reply.toDTO(), the whole market catalogProductCatalogDTO — reply.toDTO(), el catálogo del mercado entero
Fluxo de usoUsage flowFlujo de uso: Alcançado só pelo caminho remoto do repository — na contagem de estoque, apenas pelo pull-to-refreshReached only by the repository's remote path — in stock count, only via pull-to-refreshAlcanzado solo por el camino remoto del repository — en el conteo de stock, solo por pull-to-refresh
Tratamento de erroError handlingManejo de error: Dois ramos: GrpcError vai ao GrpcExceptionHandler; qualquer outro vira ServerException com log. O repository converte em Failure.Two branches: GrpcError goes to GrpcExceptionHandler; anything else becomes a logged ServerException. The repository converts it into a Failure.Dos ramas: GrpcError va al GrpcExceptionHandler; cualquier otro se vuelve ServerException con log. El repository lo convierte en Failure.

Local ProductCatalogLocalDataSource ObjectBox · 5

Envio nenhum (banco local). Fluxo de uso: é a origem real de tudo que a contagem de estoque mostra. Tratamento de erro uniforme: todos os métodos lançam CacheException com log e mensagem própria por operação. Note que todos são síncronos — não há Future nesta classe.No send (local database). Usage flow: it is the real source of everything stock count shows. Uniform error handling: every method throws a logged CacheException with its own per-operation message. Note that all are synchronous — there is no Future in this class.Ningún envío (base local). Flujo de uso: es el origen real de todo lo que el conteo de stock muestra. Manejo de error uniforme: todos los métodos lanzan CacheException con log y mensaje propio por operación. Note que todos son síncronos — no hay Future en esta clase.

getProductCatalog()

ProductCatalogEntity? — o primeiro (e único) registro da box convertido em Entity, ou null se a box está vazia. É a leitura que abre a tela.the box's first (and only) row converted to an Entity, or null when the box is empty. This is the read that opens the screen.el primer (y único) registro de la box convertido en Entity, o null si la box está vacía. Es la lectura que abre la pantalla.

getProductCatalogLastSyncAt()

DateTime? — só o timestamp, sem materializar o catálogo. Serve ao motor de frescor.just the timestamp, without materialising the catalog. It serves the freshness engine.solo el timestamp, sin materializar el catálogo. Sirve al motor de frescura.

saveProductCatalog({entity})

void — chama clearProductCatalog() antes de gravar: é substituição total, não merge. O catálogo é sempre um registro só.calls clearProductCatalog() before writing: it is a full replacement, not a merge. The catalog is always a single row.llama clearProductCatalog() antes de grabar: es sustitución total, no merge. El catálogo es siempre un solo registro.

mergeAdhocProductCatalog({incoming, accountSfid})

void — merge aditivo dos produtos que chegam num reply de visita ad hoc, e o único método desta classe ausente da interface do repository. Importa para a contagem de estoque porque é por aqui que uma visita ad hoc pode acrescentar produtos (e histórico) ao catálogo já em cache.additive merge of products arriving in an ad hoc visit reply, and the only method of this class absent from the repository interface. It matters to stock count because this is how an ad hoc visit can add products (and history) to the already-cached catalog.merge aditivo de los productos que llegan en un reply de visita ad hoc, y el único método de esta clase ausente de la interfaz del repository. Importa al conteo de stock porque es por aquí que una visita ad hoc puede agregar productos (e historial) al catálogo ya en caché.

clearProductCatalog()

void — remove em cascata 11 boxes, dos filhos para o pai: PriceEntry, PricingGroup, SoqByAccount, SalesHistoryRecord, SalesHistory, ManufacturingSku, ProductUom, ProductHalfPack, ProductEligibility, Product e por fim o próprio catálogo. É o custo real de cada pull-to-refresh.cascade-removes 11 boxes, children first: PriceEntry, PricingGroup, SoqByAccount, SalesHistoryRecord, SalesHistory, ManufacturingSku, ProductUom, ProductHalfPack, ProductEligibility, Product and finally the catalog itself. This is the real cost of every pull-to-refresh.elimina en cascada 11 boxes, de los hijos al padre: PriceEntry, PricingGroup, SoqByAccount, SalesHistoryRecord, SalesHistory, ManufacturingSku, ProductUom, ProductHalfPack, ProductEligibility, Product y por fin el propio catálogo. Es el costo real de cada pull-to-refresh.

Mock ProductCatalogMockDataSource JSON · 1

getProductCatalog()

MétodoMethodMétodo: Future<ProductCatalogDTO> — memoizado em memória: a primeira chamada carrega, as seguintes reusam o mesmo Futurememoized in memory: the first call loads, the following ones reuse the same Futurememoizado en memoria: la primera llamada carga, las siguientes reusan el mismo Future
EnvioSendsEnvío: nenhum — lê o asset do mercado ativo, escolhendo entre o mock sintético e o dump real conforme a flag de mock realnone — reads the active market's asset, choosing between the synthetic mock and the real dump per the real-mock flagninguno — lee el asset del mercado activo, eligiendo entre el mock sintético y el dump real según la flag de mock real
RetornoReturnsRetorno: o DTO decodificado num compute (isolate), porque o maior arquivo real tem 745 KBthe DTO decoded in a compute (isolate), because the largest real file is 745 KBel DTO decodificado en un compute (isolate), porque el mayor archivo real tiene 745 KB
Fluxo de usoUsage flowFlujo de uso: sessão mock, ou source == mock explícitomock session, or an explicit source == mocksesión mock, o source == mock explícito
Tratamento de erroError handlingManejo de error: reseta a memoização e lança CacheException com log — para uma falha transitória de asset não ficar grudada na sessãoresets the memoization and throws a logged CacheException — so a transient asset failure doesn't stick to the sessionresetea la memoización y lanza CacheException con log — para que un fallo transitorio de asset no quede pegado a la sesión

Enums e labelsEnums & labelsEnums y labels

A contagem de estoque não define nenhum enum próprio — nem de status, nem de tipo, nem de aba. Ela consome quatro enums de outras áreas. Os rótulos Alta e Baixa, apesar de parecerem candidatos naturais a enum, são chaves de tradução: as unidades de medida reais vêm como texto livre do backend, no ProductUom.Stock count defines no enum of its own — no status, no type, no tab. It consumes four enums from other areas. The High and Low labels, though they look like natural enum candidates, are translation keys: the real units of measure arrive as free text from the backend, inside ProductUom.El conteo de stock no define ningún enum propio — ni de estado, ni de tipo, ni de pestaña. Consume cuatro enums de otras áreas. Los rótulos Alta y Baja, aunque parezcan candidatos naturales a enum, son claves de traducción: las unidades de medida reales llegan como texto libre del backend, dentro del ProductUom.

CategoryGroup 9 · o filtro e a ordemthe filter and the orderel filtro y el orden

case	value	shortLabel
`fmc`	`"fmc"`	`"FMC"`
`nc`	`"nc"`	`"NC"`
`ryo`	`"ryo"`	`"RYO"`
`modi`	`"modi"`	`"VUSE"`
`oral`	`"oral"`	`"Oral"`
`otp`	`"otp"`	`"OTP"`
`partnership`	`"partnership"`	`"Partnership"`
`other`	`"other"`	`"Other"`
`unknown`	`""`	`""`

Usado em dois lugares da feature, ambos por fromValue (compara em minúsculas, cai em unknown): a ordem da lista de categorias do filtro, e a ordem dos grupos no painel de resumo. Nos dois casos o critério é a posição de declaração do enum, não ordem alfabética — por isso FMC vem sempre primeiro. O shortLabel é o texto exibido; note que modi aparece como "VUSE", e que unknown tem rótulo vazio. Como o campo atravessa as camadas como String crua (§07), um grupo desconhecido do backend só é detectado aqui, sem log, e vai para o fim da ordenação.Used in two places in the feature, both via fromValue (compares lowercased, falls back to unknown): the order of the filter's category list, and the order of the groups in the summary panel. In both cases the criterion is the enum's declaration position, not alphabetical order — which is why FMC always comes first. shortLabel is the displayed text; note that modi shows as "VUSE", and that unknown has an empty label. Since the field crosses the layers as a raw String (§07), a group unknown to the backend is only detected here, with no log, and sorts last.Usado en dos lugares de la feature, ambos por fromValue (compara en minúsculas, cae en unknown): el orden de la lista de categorías del filtro, y el orden de los grupos en el panel de resumen. En los dos casos el criterio es la posición de declaración del enum, no orden alfabético — por eso FMC viene siempre primero. El shortLabel es el texto exhibido; note que modi aparece como "VUSE", y que unknown tiene rótulo vacío. Como el campo atraviesa las capas como String cruda (§07), un grupo desconocido del backend solo se detecta aquí, sin log, y va al final del ordenamiento.

DataSourceType 3

case	uso na featureuse in the featureuso en la feature
`mock`	nunca pedido explicitamente pela feature — a sessão mock é decidida no repositorynever asked for explicitly by the feature — the mock session is decided in the repositorynunca pedido explícitamente por la feature — la sesión mock se decide en el repository
`local`	o default do UseCase e do `_load`: como a tela abrethe UseCase's and `_load`'s default: how the screen opensel default del UseCase y del `_load`: cómo abre la pantalla
`remote`	passado apenas pelo `refresh()`, ou seja, só pelo pull-to-refreshpassed only by `refresh()`, i.e. only by pull-to-refreshpasado solo por el `refresh()`, o sea, solo por pull-to-refresh

Enum sem propriedade value — é um seletor interno de camada, não um código de wire.An enum with no value property — it is an internal layer selector, not a wire code.Enum sin propiedad value — es un selector interno de capa, no un código de wire.

ConectaInputType 6 · a variante do campo-pílulathe pill field variantla variante del campo-píldora

case	notanotenota
`outlined`	campo padrão de formuláriostandard form fieldcampo estándar de formulario
`outlinedCompact`	variante baixa — a usada pela verificação de preçolow variant — the one price check usesvariante baja — la que usa la verificación de precio
`outlinedPill`	cantos totalmente arredondadosfully rounded cornersesquinas totalmente redondeadas
`outlinedPillCompact`	a variante desta feature — pílula achatada, criada em Jul/2026 para os dois campos Alta/Baixathis feature's variant — flattened pill, created in Jul/2026 for the two High/Low fieldsla variante de esta feature — píldora achatada, creada en Jul/2026 para los dos campos Alta/Baja
`borderless`	sem bordano bordersin borde
`search`	barra de busca — não usada aqui, a tela não tem buscasearch bar — not used here, the screen has no searchbarra de búsqueda — no usada aquí, la pantalla no tiene búsqueda

DispatcherType 42 · 1 relevante1 relevant1 relevante

propriedadepropertypropiedad	valorvaluevalor
case	`stockCount`
`serviceName`	`"LocationStockUploadAPI"`
`enabledMarkets`	`[BR, CL, ZA]`
`destination`	não declarado → default `salesforce`not declared → defaults to `salesforce`no declarado → default `salesforce`
`lightweight`	não — o conjunto tem só 3 tipos (`notificationRead`, `answerTask`, `priceCheck`)no — the set has only 3 types (`notificationRead`, `answerTask`, `priceCheck`)no — el conjunto tiene solo 3 tipos (`notificationRead`, `answerTask`, `priceCheck`)
`resendMayDuplicate`	`true` — derivado de não ser lightweight`true` — derived from not being lightweight`true` — derivado de no ser lightweight
`resolveServiceName(hasPromotion: false)`	`"LocationStockUploadAPI"` (sem prefixo `Promo_`)(no `Promo_` prefix)(sin prefijo `Promo_`)

O enum tem 42 valores, dos quais 36 têm builder de payload. A diferença mais consequente entre a contagem de estoque e a feature irmã está nesta tabela: a verificação de preço é um dos 3 tipos lightweight, e a contagem não — logo o reenvio manual de uma contagem carrega risco de duplicidade que o da verificação não tem. Note também que existem quatro outros valores com "stock" no nome (stockReconciliation, stockRequest, stockAllocationExecution, stockUnload), todos sem builder e todos do domínio da van — nenhum tem relação com esta feature.The enum has 42 values, 36 of which have a payload builder. The most consequential difference between stock count and its sibling feature is in this table: price check is one of the 3 lightweight types, and the count is not — so manually resending a count carries a duplicate risk that resending a check doesn't. Note too that there are four other values with "stock" in the name (stockReconciliation, stockRequest, stockAllocationExecution, stockUnload), all without a builder and all from the van domain — none relates to this feature.El enum tiene 42 valores, de los cuales 36 tienen builder de payload. La diferencia más consecuente entre el conteo de stock y la feature hermana está en esta tabla: la verificación de precio es uno de los 3 tipos lightweight, y el conteo no — así que el reenvío manual de un conteo lleva riesgo de duplicidad que el de la verificación no tiene. Note también que existen cuatro otros valores con "stock" en el nombre (stockReconciliation, stockRequest, stockAllocationExecution, stockUnload), todos sin builder y todos del dominio de la van — ninguno se relaciona con esta feature.

Chaves de traduçãoTranslation keysClaves de traducción

São 27 chaves com o prefixo stock_count_*, todas presentes nos 6 mercados — zero assimetria (§10). Quatro delas não têm consumidor no app: stock_count_stock e stock_count_sale ("Estoque"/"Venda"), órfãs desde a troca das colunas para Alta/Baixa; stock_count_clear_filter, órfã desde a remoção do botão de limpar filtro; e stock_count_summary_stat_units ("Total Unidades"), substituída pelos dois totais separados. Fora do prefixo, a feature ainda depende de visit_detail_stock_history (o rótulo do tile) e visit_end_pending_stock_count (o rótulo do cartão de pendência), e o painel de resumo reutiliza três chaves de price_check_* — coluna "Marca", marcador de vazio e rótulo de subtotal.There are 27 keys prefixed stock_count_*, all present in all 6 markets — zero asymmetry (§10). Four of them have no consumer in the app: stock_count_stock and stock_count_sale ("Stock"/"Sale"), orphaned since the columns became High/Low; stock_count_clear_filter, orphaned since the clear-filter button was removed; and stock_count_summary_stat_units ("Total Units"), replaced by the two separate totals. Outside the prefix, the feature also depends on visit_detail_stock_history (the tile label) and visit_end_pending_stock_count (the pending card label), and the summary panel reuses three price_check_* keys — the "Brand" column, the empty marker and the subtotal label.Son 27 claves con el prefijo stock_count_*, todas presentes en los 6 mercados — cero asimetría (§10). Cuatro de ellas no tienen consumidor en la app: stock_count_stock y stock_count_sale ("Stock"/"Venta"), huérfanas desde el cambio de las columnas a Alta/Baja; stock_count_clear_filter, huérfana desde la remoción del botón de limpiar filtro; y stock_count_summary_stat_units ("Total Unidades"), sustituida por los dos totales separados. Fuera del prefijo, la feature depende además de visit_detail_stock_history (el rótulo del tile) y visit_end_pending_stock_count (el rótulo de la tarjeta de pendiente), y el panel de resumen reutiliza tres claves de price_check_* — la columna "Marca", el marcador de vacío y el rótulo de subtotal.

ChaveKeyClave	BR	ZA	CL · AR · PY · PE
`stock_count_title`	Contagem de Estoque	Stock Count	Conteo de Stock
`stock_count_high_uom`	Alta	High	Alta
`stock_count_low_uom`	Baixa	Low	Baja
`stock_count_history_title`	Histórico de contagem de estoque	Stock count history	Historial de conteo de stock
`stock_count_category`	Categoria	Category	Categoría
`stock_count_brand`	Marca	Brand	Marca
`stock_count_empty_state`	Nenhum produto com histórico de vendas para este varejo	No products with sales history for this retail	Sin productos con historial de ventas para este punto de venta
`stock_count_filled_label`	Preenchidos	Filled	Llenados
`stock_count_summary_modal_title`	Contagens a enviar	Stock counts to send	Conteos a enviar
`stock_count_summary_subtitle`	{filled} de {total} produtos contados	{filled} of {total} products counted	{filled} de {total} productos contados
`stock_count_summary_stat_total`	Total Produtos	Total Products	Total Productos
`stock_count_summary_stat_empty`	Vazios	Empty	Vacíos
`stock_count_summary_clear_all`	Limpar tudo	Clear all entries	Limpiar todo
`stock_count_submit_confirm_title`	Enviar contagem de estoque?	Submit stock count?	¿Enviar conteo de stock?
`stock_count_submit_confirm_yes`	Sim, enviar	Yes, submit	Sí, enviar
`stock_count_submit_success_message`	Contagem de estoque salva com sucesso.	Stock count saved successfully.	Conteo de stock guardado correctamente.
`stock_count_submit_error_message`	Falha ao salvar a contagem de estoque. Tente novamente.	Failed to save stock count. Please try again.	No se pudo guardar el conteo de stock. Inténtalo de nuevo.
`visit_detail_stock_history` (tile)(tile)(tile)	Falta	Stock Count	Conteo de Stock
`visit_end_pending_stock_count`	Contagem de estoque	Stock count	Conteo de inventario
`dispatcher_type_stockCount`	Contagem de estoque	Stock count	Conteo de stock

Recorte das chaves visíveis; as 10 restantes do prefixo são as 4 chaves órfãs e as 6 mensagens e botões dos dois modais de confirmação. Três nomes diferentes para a mesma coisa convivem hoje: o tile do Brasil diz "Falta", o cartão de pendência diz "Contagem de estoque" e o título da tela diz "Contagem de Estoque" — e em espanhol o cartão de pendência diz "Conteo de inventario" enquanto todo o resto diz "Conteo de stock" (ver Pendências).A slice of the visible keys; the remaining 10 in the prefix are the 4 orphan keys and the 6 messages and buttons of the two confirmation modals. Three different names for the same thing coexist today: Brazil's tile says "Falta" (shortage), the pending card says "Contagem de estoque" and the screen title says "Contagem de Estoque" — and in Spanish the pending card says "Conteo de inventario" while everything else says "Conteo de stock" (see Pending items).Recorte de las claves visibles; las 10 restantes del prefijo son las 4 claves huérfanas y los 6 mensajes y botones de los dos modales de confirmación. Tres nombres diferentes para la misma cosa conviven hoy: el tile de Brasil dice "Falta", la tarjeta de pendiente dice "Contagem de estoque" y el título de la pantalla dice "Contagem de Estoque" — y en español la tarjeta de pendiente dice "Conteo de inventario" mientras todo el resto dice "Conteo de stock" (ver Pendientes).

UseCases

A feature usa quatro UseCases: um para ler o catálogo filtrado, um para resolver a visita, um para montar o payload e um para despachar. Todos com provider keepAlive. O de leitura é a materialização da §29 do CLAUDE.md: o catálogo tem um repository neutro e um UseCase por feature consumidora — hoje são 7 UseCases sobre o mesmo repository (pedido, recompra, carga de van, verificação de preço, contagem de estoque, prêmio de promoção e o de passagem sem filtro), cada um filtrando pela sua flag de elegibilidade.The feature uses four UseCases: one to read the filtered catalog, one to resolve the visit, one to build the payload and one to dispatch. All with a keepAlive provider. The read one is CLAUDE.md §29 made concrete: the catalog has one neutral repository and one UseCase per consuming feature — today 7 UseCases sit on the same repository (order, buyback, van load, price check, stock count, promotion reward and the unfiltered pass-through), each filtering on its own eligibility flag.La feature usa cuatro UseCases: uno para leer el catálogo filtrado, uno para resolver la visita, uno para armar el payload y uno para despachar. Todos con provider keepAlive. El de lectura es la materialización de la §29 del CLAUDE.md: el catálogo tiene un repository neutro y un UseCase por feature consumidora — hoy son 7 UseCases sobre el mismo repository (pedido, recompra, carga de van, verificación de precio, conteo de stock, premio de promoción y el de paso sin filtro), cada uno filtrando por su flag de elegibilidad.

GetProductsForStockCountUseCase 1 · a listathe listla lista

MétodoMethodMétodo	RetornaReturnsDevuelve	UsoUseUso
`execute({source = local})`	`Result<ProductCatalogEntity, Failure>`	Chama `repository.getProductCatalog(source:)` e devolve o container inteiro com `copyWith(products: …where(eligibility.isAvailableForStockCount))`. Devolver o container e não a lista crua é deliberado: assim o `lastSyncAt` sobrevive ao filtro e alimenta a faixa de sincronização da tela (§23). Dois chamadores: o `StockCountNotifier` e o cálculo de pendências do encerramento de visita.Calls `repository.getProductCatalog(source:)` and returns the whole container with `copyWith(products: …where(eligibility.isAvailableForStockCount))`. Returning the container instead of the bare list is deliberate: that way `lastSyncAt` survives the filter and feeds the screen's sync strip (§23). Two callers: the `StockCountNotifier` and the visit-end pendings computation.Llama `repository.getProductCatalog(source:)` y devuelve el container entero con `copyWith(products: …where(eligibility.isAvailableForStockCount))`. Devolver el container y no la lista cruda es deliberado: así el `lastSyncAt` sobrevive al filtro y alimenta la franja de sincronización de la pantalla (§23). Dos llamadores: el `StockCountNotifier` y el cálculo de pendientes del cierre de visita.

O filtro é só a flag de elegibilidade. Não há recorte por varejo — e é essa a origem da divergência com o texto do estado vazio e com o critério do encerramento de visita (ver Pendências). Também não há recorte por preço nem por estoque, ao contrário da vitrine de pedido. Os dois filtros visíveis (categoria e marca) são aplicados depois, nos getters do State — o UseCase não os conhece.The filter is only the eligibility flag. There is no per-retail slice — and that is the origin of the divergence with the empty-state copy and with the visit-end criterion (see Pending items). There is no slice by price or stock either, unlike the order showcase. The two visible filters (category and brand) are applied later, in the State getters — the UseCase doesn't know about them.El filtro es solo la flag de elegibilidad. No hay recorte por punto de venta — y ese es el origen de la divergencia con el texto del estado vacío y con el criterio del cierre de visita (ver Pendientes). Tampoco hay recorte por precio ni por stock, a diferencia de la vitrina de pedido. Los dos filtros visibles (categoría y marca) se aplican después, en los getters del State — el UseCase no los conoce.

GetVisitsUseCase 1 · a visita, do cachethe visit, from cachela visita, del caché

MétodoMethodMétodo	RetornaReturnsDevuelve	UsoUseUso
`getCachedByAccountSfid({accountSfid})`	`Result<VisitEntity?, Failure>`	Único método deste UseCase que a feature usa, e só no momento do envio. Como a tela recebe apenas o identificador do varejo (§17), é daqui que saem o `sfid` da visita, o código SAP e o nome do varejo para o payload. Cache-only, no padrão §28 categoria A. O resultado é reduzido a `valueOrNull`: uma falha de leitura é indistinguível de "não há visita", e o envio segue com os três campos vazios.The only method of this UseCase the feature uses, and only at submit time. Since the screen receives just the retail identifier (§17), this is where the visit `sfid`, the SAP code and the retail name for the payload come from. Cache-only, in the §28 category A pattern. The result is reduced to `valueOrNull`: a read failure is indistinguishable from "there is no visit", and the submission proceeds with those three fields empty.Único método de este UseCase que la feature usa, y solo en el momento del envío. Como la pantalla recibe apenas el identificador del punto de venta (§17), es de aquí que salen el `sfid` de la visita, el código SAP y el nombre del punto de venta para el payload. Cache-only, en el patrón §28 categoría A. El resultado se reduce a `valueOrNull`: un fallo de lectura es indistinguible de "no hay visita", y el envío sigue con los tres campos vacíos.

BuildStockCountDispatcherPayloadUseCase 1 · payload

MétodoMethodMétodo	RetornaReturnsDevuelve	UsoUseUso
`build({input})`	`DispatcherEnvelope`	Contrato do `DispatcherPayloadBuilder` e único método da classe — não existe `buildAll` e não há fatiamento: sai um envelope só, com todos os itens num array, independentemente de quantos produtos foram contados. É síncrono e `const`, sem nenhum método privado. Toda construção wire mora aqui (§36): a formatação da data, a derivação do `resourceSfid` primário/secundário, a resolução do código ISO da moeda e a decisão de omitir produto sem contagem.The `DispatcherPayloadBuilder` contract and the class's only method — there is no `buildAll` and no chunking: one single envelope comes out, with every item in one array, no matter how many products were counted. It is synchronous and `const`, with no private methods at all. All wire construction lives here (§36): date formatting, deriving the primary/secondary `resourceSfid`, resolving the currency ISO code and the decision to omit a product with no count.Contrato del `DispatcherPayloadBuilder` y único método de la clase — no existe `buildAll` y no hay corte: sale un solo envelope, con todos los ítems en un array, independientemente de cuántos productos se contaron. Es síncrono y `const`, sin ningún método privado. Toda construcción wire vive aquí (§36): el formateo de la fecha, la derivación del `resourceSfid` primario/secundario, la resolución del código ISO de la moneda y la decisión de omitir un producto sin conteo.

O inputThe inputEl input — StockCountDispatcherPayloadInput, Freezed, 7 campos, todos obrigatórios e sem default (um deles nulável):Freezed, 7 fields, all required and with no default (one of them nullable):Freezed, 7 campos, todos obligatorios y sin default (uno de ellos nulable):

accountSfid: String · identificador do varejo, vindo da rotaretail identifier, from the routeidentificador del punto de venta, desde la ruta
entries: List<StockCountEntryEntity> · entity crua, 3 campos cadaraw entity, 3 fields eachentity cruda, 3 campos cada una
products: List<ProductEntity> · entity crua, os 24 campos do catálogoraw entity, the catalog's 24 fieldsentity cruda, los 24 campos del catálogo
resource: ResourceEntity · o representante cru — o builder é que decide entre primaryResourceSfid e secondaryResourceSfid, exatamente como a §36 exigethe raw rep — the builder is what decides between primaryResourceSfid and secondaryResourceSfid, exactly as §36 requiresel representante crudo — el builder es quien decide entre primaryResourceSfid y secondaryResourceSfid, exactamente como la §36 exige
visit: VisitEntity? · obrigatório porém nulável — sem visita em cache, três campos do payload saem vaziosrequired yet nullable — with no cached visit, three payload fields go out emptyobligatorio pero nulable — sin visita en caché, tres campos del payload salen vacíos
market: EndMarket · o mercado ativo, lido pelo Notifier e nunca guardado no State (§34)the active market, read by the Notifier and never stored in State (§34)el mercado activo, leído por el Notifier y nunca guardado en el State (§34)
submittedAt: DateTime · o relógio injetado pelo Notifier, não uma data já formatada — exatamente o que a §36 exigethe clock injected by the Notifier, not a pre-formatted date — exactly what §36 requiresel reloj inyectado por el Notifier, no una fecha ya formateada — exactamente lo que la §36 exige

O que o payload carregaWhat the payload carriesQué lleva el payload — uma chave raiz, "StockTrackingDeatils" (o erro de grafia é do contrato), com um array de 24 chaves por item:one root key, "StockTrackingDeatils" (the misspelling is the contract's), holding an array of 24 keys per item:una clave raíz, "StockTrackingDeatils" (el error de grafía es del contrato), con un array de 24 claves por ítem:

Chave JSONJSON keyClave JSON	OrigemOriginOrigen
`orderPoNumber`	fixo `""`fixed `""`fijo `""`
`stockId`	fixo `""`fixed `""`fijo `""`
`isAvailable`	calculado — `alta > 0 \|\| baixa > 0`. O único campo que lê a Baixa junto com a Alta.computed — `high > 0 \|\| low > 0`. The only field that reads Low alongside High.calculado — `alta > 0 \|\| baja > 0`. El único campo que lee la Baja junto con la Alta.
`availableQuantity`	`entry.highUomCount ?? 0`
`baseUOM`	`product.uom.primaryName`
`baseUOMQuatity`	`entry.highUomCount ?? 0` (grafia do contrato)(contract spelling)(grafía del contrato)
`batchId`	`product.manufacturingSkus.first.batchId` ou `""`or `""`o `""`
`damageQuantity`	fixo `""` — String, não númerofixed `""` — a String, not a numberfijo `""` — String, no número
`defaultUOM`	`product.uom.primaryName` (igual a `baseUOM`)(same as `baseUOM`)(igual a `baseUOM`)
`defaultUOMQuatity`	`entry.highUomCount ?? 0`
`location`	`resource.locationSfid`
`productId`	`product.productSfid`
`SKUId`	`product.manufacturingSkus.first.manufacturingSkuSfid` ou `""`or `""`o `""`
`uom1Quantity`	a Alta — `entry.highUomCount?.toString() ?? ""` (String, e vazio em vez de zero)the High — `entry.highUomCount?.toString() ?? ""` (String, and empty rather than zero)la Alta — `entry.highUomCount?.toString() ?? ""` (String, y vacío en vez de cero)
`uom2Quantity`	a Baixa — `entry.lowUomCount?.toString() ?? ""` (String, e vazio em vez de zero)the Low — `entry.lowUomCount?.toString() ?? ""` (String, and empty rather than zero)la Baja — `entry.lowUomCount?.toString() ?? ""` (String, y vacío en vez de cero)
`uom1Name`	`product.uom.primaryName`
`uom2Name`	`product.uom.secondaryName`
`currencyIsoCode`	calculado do mercado — BR `"BRL"` · CL `"CLP"` · ZA `"ZAR"`computed from the market — BR `"BRL"` · CL `"CLP"` · ZA `"ZAR"`calculado del mercado — BR `"BRL"` · CL `"CLP"` · ZA `"ZAR"`
`type`	fixo `"Stock Check"`fixed `"Stock Check"`fijo `"Stock Check"`
`visit`	`input.visit?.sfid ?? ""`
`marketIso`	`input.market.name` — `"BR"` / `"CL"` / `"ZA"`
`sellableQuantity`	`entry.highUomCount ?? 0`
`sapCustomerId`	`input.visit?.accountData.customerCode ?? ""`
`resourceId`	calculado — `primaryResourceSfid` ou `secondaryResourceSfid`, conforme `resource.isPrimaryResource`computed — `primaryResourceSfid` or `secondaryResourceSfid`, per `resource.isPrimaryResource`calculado — `primaryResourceSfid` o `secondaryResourceSfid`, según `resource.isPrimaryResource`

O builder itera os produtos (não as entradas), então a ordem dos itens segue a ordem do catálogo; um produto sem entrada, ou com as duas colunas vazias, é pulado. Note a assimetria entre as duas unidades: availableQuantity, baseUOMQuatity, defaultUOMQuatity e sellableQuantity — quatro chaves —, mais uma quinta em uom1Quantity, carregam a Alta e só a Alta; a Baixa chega ao backend por uma única chave, uom2Quantity. Note também que as quatro chaves numéricas usam ?? 0 enquanto as duas uomNQuantity usam ?? "": contar só a Baixa produz availableQuantity: 0 e uom1Quantity: "" no mesmo item. O envelope leva ainda o serviceName "LocationStockUploadAPI", o varejo (sfid + código SAP + nome), a data em dateReference e o accountSfid como referência da transação. A tabela completa campo-a-campo com tipos e regras e o exemplo de JSON estão em 26 · LocationStockUpload.The builder iterates the products (not the entries), so item order follows the catalog order; a product with no entry, or with both columns empty, is skipped. Note the asymmetry between the two units: availableQuantity, baseUOMQuatity, defaultUOMQuatity and sellableQuantity — four keys —, plus a fifth in uom1Quantity, carry the High and only the High; the Low reaches the backend through one single key, uom2Quantity. Note too that the four numeric keys use ?? 0 while the two uomNQuantity use ?? "": counting only the Low produces availableQuantity: 0 and uom1Quantity: "" on the same item. The envelope also carries the serviceName "LocationStockUploadAPI", the retail (sfid + SAP code + name), the date in dateReference and the accountSfid as the transaction reference. The full field-by-field table with types and rules, plus the JSON example, is in 26 · LocationStockUpload.El builder itera los productos (no las entradas), así que el orden de los ítems sigue el orden del catálogo; un producto sin entrada, o con las dos columnas vacías, se omite. Note la asimetría entre las dos unidades: availableQuantity, baseUOMQuatity, defaultUOMQuatity y sellableQuantity — cuatro claves —, más una quinta en uom1Quantity, llevan la Alta y solo la Alta; la Baja llega al backend por una única clave, uom2Quantity. Note también que las cuatro claves numéricas usan ?? 0 mientras las dos uomNQuantity usan ?? "": contar solo la Baja produce availableQuantity: 0 y uom1Quantity: "" en el mismo ítem. El envelope lleva además el serviceName "LocationStockUploadAPI", el punto de venta (sfid + código SAP + nombre), la fecha en dateReference y el accountSfid como referencia de la transacción. La tabla completa campo a campo con tipos y reglas y el ejemplo de JSON están en 26 · LocationStockUpload.

SubmitStockCountUseCase 1 · enviosubmitenvío

MétodoMethodMétodo	RetornaReturnsDevuelve	UsoUseUso
`submit({envelope})`	`Future<Result<DispatcherAck, Failure>>`	Delegação pura ao `DispatcherOrchestrator.dispatch` — corpo de uma linha, sem validação, sem log e sem gravação. Não monta payload e não conhece o tipo, que vem dentro do envelope. Como só existe um envelope, não há `Future.wait` nem alinhamento por índice (ao contrário de pesquisas e merchandising).Pure delegation to `DispatcherOrchestrator.dispatch` — a one-line body, with no validation, no logging and no write. It builds no payload and doesn't know the type, which comes inside the envelope. Since there is only one envelope, there is no `Future.wait` and no index alignment (unlike surveys and merchandising).Delegación pura al `DispatcherOrchestrator.dispatch` — cuerpo de una línea, sin validación, sin log y sin grabación. No arma payload y no conoce el tipo, que viene dentro del envelope. Como solo existe un envelope, no hay `Future.wait` ni alineación por índice (a diferencia de encuestas y merchandising).

O orquestrador é quem grava o registro no histórico local de despachos, com o tipo, o serviceName, a referência, o mercado e o estado do envio. O caminho é remote-first por construção (§36): a escrita não tem datasource local nenhum — o repository do Dispatcher só conhece o gateway gRPC, e a única persistência é o registro de auditoria gravado depois que a chamada remota resolve. Em caso de sucesso, o payload é apagado do registro, então um envio bem-sucedido não pode ser reenviado; em erro o payload é preservado e o reenvio manual fica disponível — com aviso de duplicidade, porque a contagem não é lightweight. Offline o envelope nem entra na fila: a fila atende um único tipo, o de visita, então a contagem vai ao transporte, falha e é gravada como erro.The orchestrator is what writes the record into the local dispatch history, with the type, the serviceName, the reference, the market and the send state. The path is remote-first by construction (§36): the write has no local datasource at all — the Dispatcher repository knows only the gRPC gateway, and the only persistence is the audit record written after the remote call resolves. On success the payload is erased from the record, so a successful submission cannot be resent; on error the payload is preserved and manual resend is available — with a duplicate warning, because the count is not lightweight. Offline the envelope doesn't even enter the queue: the queue serves a single type, the visit one, so the count goes to transport, fails and is recorded as an error.El orquestador es quien graba el registro en el historial local de despachos, con el tipo, el serviceName, la referencia, el mercado y el estado del envío. El camino es remote-first por construcción (§36): la escritura no tiene datasource local alguno — el repository del Dispatcher solo conoce el gateway gRPC, y la única persistencia es el registro de auditoría grabado después de que la llamada remota resuelve. En caso de éxito el payload se borra del registro, así que un envío exitoso no puede reenviarse; en error el payload se preserva y el reenvío manual queda disponible — con aviso de duplicidad, porque el conteo no es lightweight. Offline el envelope ni entra en la cola: la cola atiende un único tipo, el de visita, así que el conteo va al transporte, falla y se graba como error.

Notifier & State

O StockCountNotifier (@riverpod, with AsyncGuard<StockCountState>) é o cérebro da tela e é uma family chaveada por accountSfid — um único parâmetro, ao contrário da verificação de preço, que precisa de dois. O build() é magro: observa os 4 UseCases e devolve _load() dentro do guardedBuild. O State (StockCountState, Freezed) é a fonte única de verdade: guarda o catálogo, o mapa de contagens digitadas (chaveado por productSfid), os dois filtros, a paginação e as flags de envio. Todos os totais, contagens, listas de opções e o agrupamento por categoria são calculados em getters do State — a Page e os widgets não decidem nada (§27). Segue a §37 — build() magro, _load() como dono único da montagem, refresh() sem sufixo de feature, sem invalidateSelf e sem AsyncValue.loading no refresh.The StockCountNotifier (@riverpod, with AsyncGuard<StockCountState>) is the screen's brain and is a family keyed by accountSfid — a single parameter, unlike price check, which needs two. build() is thin: it watches the 4 UseCases and returns _load() inside guardedBuild. The State (StockCountState, Freezed) is the single source of truth: it holds the catalog, the map of typed counts (keyed by productSfid), the two filters, pagination and the submit flags. Every total, count, option list and the per-category grouping are computed in State getters — the Page and the widgets decide nothing (§27). It follows §37 — thin build(), _load() as sole owner of assembly, refresh() with no feature suffix, no invalidateSelf and no AsyncValue.loading on refresh.El StockCountNotifier (@riverpod, with AsyncGuard<StockCountState>) es el cerebro de la pantalla y es una family indexada por accountSfid — un único parámetro, a diferencia de la verificación de precio, que necesita dos. El build() es delgado: observa los 4 UseCases y devuelve _load() dentro del guardedBuild. El State (StockCountState, Freezed) es la fuente única de verdad: guarda el catálogo, el mapa de conteos escritos (indexado por productSfid), los dos filtros, la paginación y las flags de envío. Todos los totales, conteos, listas de opciones y el agrupamiento por categoría se calculan en getters del State — la Page y los widgets no deciden nada (§27). Sigue la §37 — build() delgado, _load() como dueño único del armado, refresh() sin sufijo de feature, sin invalidateSelf y sin AsyncValue.loading en el refresh.

MétodosMethodsMétodos

build({accountSfid}) @override

RetornoReturnRetorno FutureOr<StockCountState>

Atribui os 4 UseCases via ref.watch (catálogo filtrado, visitas, builder de payload, envio) e devolve guardedBuild(body: () => _load(accountSfid:)). Nada é montado inline. O provider é autoDispose: sair da tela descarta o State — é isso que faz as contagens não sobreviverem à navegação.Assigns the 4 UseCases via ref.watch (filtered catalog, visits, payload builder, submit) and returns guardedBuild(body: () => _load(accountSfid:)). Nothing is assembled inline. The provider is autoDispose: leaving the screen discards the State — that is what makes the counts not survive navigation.Asigna los 4 UseCases vía ref.watch (catálogo filtrado, visitas, builder de payload, envío) y devuelve guardedBuild(body: () => _load(accountSfid:)). Nada se arma inline. El provider es autoDispose: salir de la pantalla descarta el State — eso es lo que hace que los conteos no sobrevivan a la navegación.

_load({accountSfid, source = local}) private

RetornoReturnRetorno Future<StockCountState>

Dono único da montagem. Chama execute(source:), faz getOrThrow() (a falha sobe como Failure e o AsyncGuard a converte em estado de erro) e devolve um State novo com products, lastSyncAt e visibleCount: 20. Não preserva nada — quem preserva é o refresh().Sole owner of assembly. Calls execute(source:), does getOrThrow() (the failure bubbles as a Failure and AsyncGuard turns it into an error state) and returns a fresh State with products, lastSyncAt and visibleCount: 20. It preserves nothing — preserving is refresh()'s job.Dueño único del armado. Llama execute(source:), hace getOrThrow() (el fallo sube como Failure y el AsyncGuard lo convierte en estado de error) y devuelve un State nuevo con products, lastSyncAt y visibleCount: 20. No preserva nada — quien preserva es el refresh().

refresh() pull-to-refresh

RetornoReturnRetorno Future<void>

Null-guard no state.value, depois runGuarded em torno de _load(source: remote) seguido de fresh.copyWith(...) que devolve três campos client do State anterior: entries, selectedCategoryGroup e selectedBrandFamily. Não devolve visibleCount — de propósito: a lista volta ao topo com 20 itens. Também não devolve isSubmitting nem submitSucceeded, então um refresh disparado durante um envio em voo zera as duas flags.Null-guards state.value, then runGuarded around _load(source: remote) followed by fresh.copyWith(...) restoring three client fields from the previous State: entries, selectedCategoryGroup and selectedBrandFamily. It doesn't restore visibleCount — deliberately: the list returns to the top with 20 items. It also doesn't restore isSubmitting or submitSucceeded, so a refresh fired during an in-flight submission clears both flags.Null-guard en el state.value, luego runGuarded alrededor de _load(source: remote) seguido de fresh.copyWith(...) que devuelve tres campos client del State anterior: entries, selectedCategoryGroup y selectedBrandFamily. No devuelve visibleCount — a propósito: la lista vuelve al tope con 20 ítems. Tampoco devuelve isSubmitting ni submitSucceeded, así que un refresh disparado durante un envío en vuelo pone en cero las dos flags.

loadMore()

RetornoReturnRetorno Future<void>

Guarda por hasMoreToLoad, espera 600 ms, e então relê o State e revalida a guarda antes de subir o visibleCount em 20 (limitado ao total filtrado). A releitura pós-await é a disciplina correta e evita crescer a janela sobre um State que mudou durante a espera — por exemplo por causa de um filtro aplicado nesse intervalo.Guards on hasMoreToLoad, waits 600 ms, and then re-reads the State and re-validates the guard before raising visibleCount by 20 (clamped to the filtered total). The post-await re-read is the correct discipline and avoids growing the window over a State that changed during the wait — for instance because a filter was applied in that interval.Guarda por hasMoreToLoad, espera 600 ms, y entonces relee el State y revalida la guarda antes de subir el visibleCount en 20 (limitado al total filtrado). La relectura post-await es la disciplina correcta y evita crecer la ventana sobre un State que cambió durante la espera — por ejemplo por un filtro aplicado en ese intervalo.

selectCategory({categoryGroup})