Envio de clave (clue)Clue uploadEnvío de clave (clue)

Envio de clave é a transação de saída que persiste uma clave no backend. É disparada pelo ClaveNotifier quando o representante de vendas conclui o formulário de clave. A feature clave é a fonte; ambos os contextos (geográfico e falsificado) usam o mesmo builder e o mesmo serviceName. Clue upload is the outbound transaction that persists a clue in the backend. It's fired by the ClaveNotifier when the sales rep completes the clue form. The clave feature is the source; both contexts (geographic and counterfeit) use the same builder and the same serviceName. Envío de clave es la transacción de salida que persiste una clave en el backend. La dispara el ClaveNotifier cuando el representante de ventas completa el formulario de clave. La feature clave es la fuente; ambos contextos (geográfico y falsificado) usan el mismo builder y el mismo serviceName.

DispatcherConectaRep.proto · proto3 · package mn.bat.conectarep.dispatcher. O serviço expõe um único RPC genérico — não existe mensagem por transação. TODA transação de escrita do app usa este mesmo sendTransaction; o que muda é o serviceName (discriminador) e o JSON dentro de message.The service exposes a single generic RPC — there's no per-transaction message. EVERY write transaction in the app uses this same sendTransaction; what changes is the serviceName (discriminator) and the JSON inside message.El servicio expone un único RPC genérico — no existe mensaje por transacción. TODA transacción de escritura de la app usa este mismo sendTransaction; lo que cambia es el serviceName (discriminador) y el JSON dentro de message.

Para clave, resendMayDuplicate == true: um reenvio (ex.: recuperação de fila offline) pode duplicar a clave no backend; a idempotência via tid é o que mitiga isso.For clue, resendMayDuplicate == true: a resend (e.g. offline-queue recovery) may duplicate the clue on the backend; idempotency via tid is what mitigates it.Para clave, resendMayDuplicate == true: un reenvío (p. ej. recuperación de cola offline) puede duplicar la clave en el backend; la idempotencia vía tid es lo que lo mitiga.

Diferente do envio de pedido, a clave tem um único DispatcherType (clue → ClueUploadAPI) e sem variantes de serviceName. O que muda são os dois contextos de origem, decididos no ClaveNotifier por ClaveEntry. Ambos compartilham a mesma estrutura de payload; divergem só em source, em quais campos são preenchidos e no que dispara depois.Unlike order placement, the clue has a single DispatcherType (clue → ClueUploadAPI) and no serviceName variants. What changes are the two origin contexts, decided in ClaveNotifier by ClaveEntry. Both share the same payload structure; they diverge only in source, in which fields are filled and in what fires afterwards.A diferencia del envío de pedido, la clave tiene un único DispatcherType (clue → ClueUploadAPI) y sin variantes de serviceName. Lo que cambia son los dos contextos de origen, decididos en ClaveNotifier por ClaveEntry. Ambos comparten la misma estructura de payload; divergen solo en source, en qué campos se completan y en lo que dispara después.

A transação é orquestrada pelo ClaveNotifier (remote-first, §36). O notifier apenas reúne entities cruas e valores injetados; o builder é o dono único da derivação de resourceSfid e da formatação de data. A cascata:The transaction is orchestrated by the ClaveNotifier (remote-first, §36). The notifier only gathers raw entities and injected values; the builder is the sole owner of the resourceSfid derivation and date formatting. The cascade:La transacción se orquesta desde el ClaveNotifier (remote-first, §36). El notifier solo reúne entities crudas y valores inyectados; el builder es el dueño único de la derivación de resourceSfid y del formateo de fecha. La cascada:

• ClaveNotifiersubmit()
  • reúne entities cruas + injetadosgathers raw entities + injectedreúne entities crudas + inyectadosClueUploadDispatcherPayloadInput
    • build()BuildClueUploadDispatcherPayloadUseCasemonta o wireassembles the wirearma el wire
      • devolvereturnsdevuelveDispatcherEnvelope
        • SubmitClueUploadUseCaseDispatcherRepository
          • serializa + authserialize + authserializa + authDispatcherGateway
            • sendTransactionBackendgRPC

O input (entities cruas)The input (raw entities)El input (entities crudas)

ClueUploadDispatcherPayloadInput (Freezed). Carrega o dado como existe no domínio; nada de formato wire. O relógio chega como submittedAt (via DateTimeUtils.now()); a ResourceEntity chega crua e o builder deriva o resourceSfid.ClueUploadDispatcherPayloadInput (Freezed). Carries data as it exists in the domain; no wire shaping. The clock arrives as submittedAt (via DateTimeUtils.now()); the ResourceEntity arrives raw and the builder derives the resourceSfid.ClueUploadDispatcherPayloadInput (Freezed). Lleva el dato como existe en el dominio; nada de formato wire. El reloj llega como submittedAt (vía DateTimeUtils.now()); la ResourceEntity llega cruda y el builder deriva el resourceSfid.

O JSON serializado no campo message do request. As tabelas abaixo têm 4 colunas — Campo JSON · Tipo · Origem do Dado · Regra — e listam toda chave que o build() emite (12 no total: 1 raiz + 11 no objeto). Campo, Tipo e Origem são código cru; só a Regra é prosa. Um exemplo completo (contexto geográfico/CL) está em transaction_example.json, ao lado deste doc.The JSON serialized into the request's message field. The tables below have 4 columns — JSON field · Type · Data source · Rule — and list every key that build() emits (12 total: 1 root + 11 in the object). Field, Type and Source are raw code; only Rule is prose. A full example (geographic/CL context) sits in transaction_example.json, next to this doc.El JSON serializado en el campo message del request. Las tablas abajo tienen 4 columnas — Campo JSON · Tipo · Origen del Dato · Regla — y listan toda clave que build() emite (12 en total: 1 raíz + 11 en el objeto). Campo, Tipo y Origen son código crudo; solo la Regla es prosa. Un ejemplo completo (contexto geográfico/CL) está en transaction_example.json, junto a este doc.

Raiz do payloadPayload rootRaíz del payload

• ClueUploadDetails[] objeto únicosingle objectobjeto único 11 camposfieldscampos

  Campo JSON	TipoTypeTipo	Origem do DadoData sourceOrigen del Dato	RegraRuleRegla
  typePdv	string	input.typePdv	geográfica → nome do tipo de PDV; falsificado → account.customerCodegeographic → PDV type name; counterfeit → account.customerCodegeográfica → nombre del tipo de PDV; falsificado → account.customerCode
  visibleProduct	bool?	input.visibleProduct	produto visível; null se não respondido (sem coerção)product visible; null if unanswered (no coercion)producto visible; null si no respondido (sin coerción)
  productF	bool?	input.productF	produto falsificado; só no contexto falsificado, senão nullcounterfeit product; counterfeit context only, else nullproducto falsificado; solo en el contexto falsificado, si no null
  additionalInformation	string	input.additionalInformation	texto livre; default ""free text; defaults to ""texto libre; default ""
  address	string	input.address	geográfica → endereço do mapa; falsificado → ""geographic → map address; counterfeit → ""geográfica → dirección del mapa; falsificado → ""
  latitude	double	input.latitude	geográfica → lat do mapa; falsificado → 0.0geographic → map lat; counterfeit → 0.0geográfica → lat del mapa; falsificado → 0.0
  longitude	double	input.longitude	geográfica → long do mapa; falsificado → 0.0geographic → map long; counterfeit → 0.0geográfica → long del mapa; falsificado → 0.0
  resourceSfid	string	Derivado	resource.isPrimaryResource ? primaryResourceSfid : secondaryResourceSfidresource.isPrimaryResource ? primaryResourceSfid : secondaryResourceSfidresource.isPrimaryResource ? primaryResourceSfid : secondaryResourceSfid
  submissionDate	string	input.submittedAt	formato yyyy-MM-dd HH:mm:ss (isoDateTime)yyyy-MM-dd HH:mm:ss format (isoDateTime)formato yyyy-MM-dd HH:mm:ss (isoDateTime)
  source	string	input.source.value	POS BAT (falsificado) / POS OUT BAT (geográfica)POS BAT (counterfeit) / POS OUT BAT (geographic)POS BAT (falsificado) / POS OUT BAT (geográfica)
  hasDnpResponde	bool	input.hasDnpResponde	o notifier injeta true nos dois fluxos (default da entity é false). Chave com typo mantida verbatim (ver Pendências)the notifier injects true in both flows (entity default is false). Misspelled key kept verbatim (see Pending)el notifier inyecta true en ambos flujos (el default de la entity es false). Clave con typo mantenida verbatim (ver Pendientes)

• Derivação de resourceSfidresourceSfid derivationDerivación de resourceSfid resourceSfid · transactionReference

  • O resourceSfid é derivado no builder: isPrimaryResource escolhe entre primaryResourceSfid e secondaryResourceSfid. O mesmo valor vira também o transactionReference do envelope (correlação).The resourceSfid is derived in the builder: isPrimaryResource picks between primaryResourceSfid and secondaryResourceSfid. The same value also becomes the envelope's transactionReference (correlation).El resourceSfid se deriva en el builder: isPrimaryResource elige entre primaryResourceSfid y secondaryResourceSfid. El mismo valor también se convierte en el transactionReference del envelope (correlación).
• DatasDatesFechas submissionDate · dateReference

  • Ambas derivam do mesmo submittedAt: submissionDate no payload usa yyyy-MM-dd HH:mm:ss (isoDateTime); o dateReference do envelope usa yyyy-MM-dd (isoDate, o default de formatDate).Both derive from the same submittedAt: submissionDate in the payload uses yyyy-MM-dd HH:mm:ss (isoDateTime); the envelope's dateReference uses yyyy-MM-dd (isoDate, the formatDate default).Ambas derivan del mismo submittedAt: submissionDate en el payload usa yyyy-MM-dd HH:mm:ss (isoDateTime); el dateReference del envelope usa yyyy-MM-dd (isoDate, el default de formatDate).
• Sobrecarga de typePdvtypePdv overloadSobrecarga de typePdv typePdv · source

  • O mesmo campo typePdv carrega semânticas diferentes por contexto: na clave geográfica é o nome do tipo de PDV selecionado; na de produto falsificado é o customerCode da conta da visita. O source é o único sinal explícito de qual contexto gerou a clave.The same typePdv field carries different semantics per context: in the geographic clue it's the selected PDV type name; in the counterfeit one it's the visit account's customerCode. The source is the only explicit signal of which context produced the clue.El mismo campo typePdv lleva semánticas distintas por contexto: en la clave geográfica es el nombre del tipo de PDV seleccionado; en la de producto falsificado es el customerCode de la cuenta de la visita. El source es la única señal explícita de qué contexto generó la clave.
• Remote-first + guard de sessãoRemote-first + session guardRemote-first + guard de sesión submit() · canSave

  • O submit() exige state.canSave e um ResourceEntity resolvido de currentResourceProvider antes de montar o input; sem sessão, retorna falha e não dispara. O SubmitClueUploadUseCase persiste remote-first (§36).submit() requires state.canSave and a ResourceEntity resolved from currentResourceProvider before building the input; with no session it returns a failure and doesn't fire. SubmitClueUploadUseCase persists remote-first (§36).submit() exige state.canSave y un ResourceEntity resuelto de currentResourceProvider antes de armar el input; sin sesión, retorna falla y no dispara. SubmitClueUploadUseCase persiste remote-first (§36).

Observações fiéis ao estado atual do código (nunca descritas como se já estivessem resolvidas):Notes faithful to the current code state (never described as already resolved):Observaciones fieles al estado actual del código (nunca descritas como ya resueltas):