Execução de recompraBuyback executionEjecución de recompra

Execução de recompra é a transação de saída que persiste o desfecho da coleta de uma recompra no backend. É disparada pelo BuybackCollectionNotifier quando o representante de vendas aceita, rejeita ou reagenda. A fonte é a BuybackEntity em coleta; o resultado é a recompra atualizada, refletida na feature de Recompra. Buyback execution is the outbound transaction that persists a buyback's collection outcome in the backend. It's fired by the BuybackCollectionNotifier when the sales rep accepts, rejects or reschedules. The source is the BuybackEntity being collected; the result is the updated buyback, reflected in the Buyback feature. Ejecución de recompra es la transacción de salida que persiste el desenlace de la recolección de una recompra en el backend. Se dispara desde el BuybackCollectionNotifier cuando el representante de ventas acepta, rechaza o reprograma. La fuente es la BuybackEntity en recolección; el resultado es la recompra actualizada, reflejada en la feature de Recompra.

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

Um único DispatcherType (buybackExecution) e um único serviceName (SalesReturnUplift) cobrem as três ações. A ação chega no input como BuybackAction; o builder a converte em status via action.writeStatus. Não há campo de tipo no envelope além do DispatcherType: aceitar, rejeitar e reagendar produzem o mesmo payload, divergindo apenas no status e — só no reagendamento — nos campos rescheduledTerritory e rescheduledUpliftDate.A single DispatcherType (buybackExecution) and a single serviceName (SalesReturnUplift) cover all three actions. The action arrives on the input as BuybackAction; the builder maps it to status via action.writeStatus. There's no type field on the envelope beyond the DispatcherType: accept, reject and reschedule produce the same payload, diverging only in status and — reschedule only — in the rescheduledTerritory and rescheduledUpliftDate fields.Un único DispatcherType (buybackExecution) y un único serviceName (SalesReturnUplift) cubren las tres acciones. La acción llega en el input como BuybackAction; el builder la convierte en status vía action.writeStatus. No hay campo de tipo en el envelope más allá del DispatcherType: aceptar, rechazar y reprogramar producen el mismo payload, divergiendo solo en status y — solo en reprogramación — en los campos rescheduledTerritory y rescheduledUpliftDate.

A transação é orquestrada pelo BuybackCollectionNotifier (remote-first, §36). O notifier apenas reúne a entity crua e os valores injetados; o builder é o dono único da formatação de data e da derivação wire (status, território de reagendamento). Após o sucesso remoto, o notifier grava a recompra atualizada no cache local. A cascata:The transaction is orchestrated by the BuybackCollectionNotifier (remote-first, §36). The notifier only gathers the raw entity and injected values; the builder is the sole owner of date formatting and wire derivation (status, reschedule territory). After the remote success, the notifier writes the updated buyback to the local cache. The cascade:La transacción se orquesta desde el BuybackCollectionNotifier (remote-first, §36). El notifier solo reúne la entity cruda y los valores inyectados; el builder es el dueño único del formateo de fecha y la derivación wire (status, territorio de reprogramación). Tras el éxito remoto, el notifier graba la recompra actualizada en el cache local. La cascada:

• BuybackCollectionNotifiernotifier
  • reúne entity crua + injetadosgathers raw entity + injectedreúne entity cruda + inyectadosBuybackExecutionDispatcherPayloadInput
    • build()BuildBuybackExecutionDispatcherPayloadUseCasemonta o wireassembles the wirearma el wire
      • devolvereturnsdevuelveDispatcherEnvelope
        • SubmitBuybackExecutionUseCaseDispatcherRepository
          • serializa + authserialize + authserializa + authDispatcherGateway
            • sendTransactionBackendgRPC

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

BuybackExecutionDispatcherPayloadInput (Freezed). Carrega o dado como existe no domínio; nada de formato wire. O relógio chega como submittedAt (via DateTimeUtils.now()); o resource vem do currentResourceProvider.BuybackExecutionDispatcherPayloadInput (Freezed). Carries data as it exists in the domain; no wire shaping. The clock arrives as submittedAt (via DateTimeUtils.now()); resource comes from currentResourceProvider.BuybackExecutionDispatcherPayloadInput (Freezed). Lleva el dato como existe en el dominio; nada de formato wire. El reloj llega como submittedAt (vía DateTimeUtils.now()); resource viene del currentResourceProvider.

O JSON serializado no campo message do request. A tabela tem 4 colunas — Campo JSON · Tipo · Origem do Dado · Regra — e lista toda chave que o build() emite (11 no total: 1 wrapper + 10 campos do cabeçalho). Campo, Tipo e Origem são código cru; só a Regra é prosa. Um exemplo completo (ação reschedule/BR) está em transaction_example.json, ao lado deste doc.The JSON serialized into the request's message field. The table has 4 columns — JSON field · Type · Data source · Rule — and lists every key that build() emits (11 in total: 1 wrapper + 10 header fields). Field, Type and Source are raw code; only Rule is prose. A full example (reschedule/BR action) sits in transaction_example.json, next to this doc.El JSON serializado en el campo message del request. La tabla tiene 4 columnas — Campo JSON · Tipo · Origen del Dato · Regla — y lista toda clave que build() emite (11 en total: 1 wrapper + 10 campos del encabezado). Campo, Tipo y Origen son código crudo; solo la Regla es prosa. Un ejemplo completo (acción reschedule/BR) está en transaction_example.json, junto a este doc.

Ação → statusAction → statusAcción → status

A ação escolhida pelo rep vira o status wire pelo mapa do enum BuybackAction: accept→F, reject→R, reschedule→RS. Este é o único campo que distingue as três ações no payload.The rep's chosen action becomes the wire status via the BuybackAction enum map: accept→F, reject→R, reschedule→RS. This is the only field distinguishing the three actions in the payload.La acción elegida por el rep se convierte en el status wire por el mapa del enum BuybackAction: accept→F, reject→R, reschedule→RS. Este es el único campo que distingue las tres acciones en el payload.

Reagendamento condicionalConditional rescheduleReprogramación condicional

isReschedule = action == BuybackAction.reschedule comanda os dois campos de reagendamento. rescheduledUpliftDate só é formatada quando isReschedule e a data de entrada não é nula; caso contrário vai "". rescheduledTerritory só recebe locationHierarchyId quando isReschedule. Nas ações accept/reject ambos são "".isReschedule = action == BuybackAction.reschedule drives both reschedule fields. rescheduledUpliftDate is formatted only when isReschedule and the input date is non-null; otherwise it's "". rescheduledTerritory gets locationHierarchyId only when isReschedule. On accept/reject both are "".isReschedule = action == BuybackAction.reschedule comanda ambos campos de reprogramación. rescheduledUpliftDate se formatea solo cuando isReschedule y la fecha de entrada no es nula; de lo contrario es "". rescheduledTerritory recibe locationHierarchyId solo cuando isReschedule. En accept/reject ambos son "".

Território derivado no builderTerritory derived in the builderTerritorio derivado en el builder

O rescheduledTerritory sai de resource.locationHierarchyId — derivado no build() a partir da entity crua, nunca pré-resolvido no notifier (CLAUDE.md §36).rescheduledTerritory comes from resource.locationHierarchyId — derived in build() from the raw entity, never pre-resolved in the notifier (CLAUDE.md §36).rescheduledTerritory sale de resource.locationHierarchyId — derivado en build() desde la entity cruda, nunca pre-resuelto en el notifier (CLAUDE.md §36).

Data via DateTimeUtilsDate via DateTimeUtilsFecha vía DateTimeUtils

Ambas as datas wire (dateReference do envelope e rescheduledUpliftDate) passam por DateTimeUtils.formatDate(format: DateFormatType.isoDate) (yyyy-MM-dd) — nunca montadas à mão (CLAUDE.md §14).Both wire dates (envelope dateReference and rescheduledUpliftDate) go through DateTimeUtils.formatDate(format: DateFormatType.isoDate) (yyyy-MM-dd) — never hand-assembled (CLAUDE.md §14).Ambas fechas wire (dateReference del envelope y rescheduledUpliftDate) pasan por DateTimeUtils.formatDate(format: DateFormatType.isoDate) (yyyy-MM-dd) — nunca montadas a mano (CLAUDE.md §14).

Remote-firstRemote-firstRemote-first

O SubmitBuybackExecutionUseCase persiste no remote primeiro; só após o sucesso o notifier atualiza o cache local (novo BuybackStatus e — no reagendamento — a nova upliftDate), e limpa as flags canAccept/canReject/canReschedule (CLAUDE.md §36).The SubmitBuybackExecutionUseCase persists remote first; only after success does the notifier update the local cache (new BuybackStatus and — on reschedule — the new upliftDate), and clear the canAccept/canReject/canReschedule flags (CLAUDE.md §36).El SubmitBuybackExecutionUseCase persiste en remote primero; solo tras el éxito el notifier actualiza el cache local (nuevo BuybackStatus y — en reprogramación — la nueva upliftDate), y limpia las flags canAccept/canReject/canReschedule (CLAUDE.md §36).

Sem promoçãoNo promotionSin promoción

Recompra nunca aplica promoção, então o serviceName nunca recebe o prefixo Promo_ — é sempre SalesReturnUplift cru.Buyback never applies a promotion, so the serviceName never takes the Promo_ prefix — it's always raw SalesReturnUplift.La recompra nunca aplica promoción, así que el serviceName nunca recibe el prefijo Promo_ — es siempre SalesReturnUplift crudo.

O que o builder ainda não preenche ou envia inerte, documentado fiel ao estado atual do código (nunca descrito como se já existisse):What the builder does not yet fill, or ships inert, documented faithfully to the current code state (never described as already existing):Lo que el builder aún no completa, o envía inerte, documentado fiel al estado actual del código (nunca descrito como si ya existiera):