Pular para o conteúdo principal

Known limitations

Achados reais, confirmados no código (ou confirmados ao vivo) — vários dos quais nenhum teste unitário isolado tinha pegado antes deste Business Case existir. A versão técnica completa, com citações de arquivo:linha, vive em examples/marketplace-mercatto/GAPS.md; esta página é o índice para o leitor, na ordem em que os capítulos as referenciam.

F.1 — O Settlement não trava no estado do Workflow​

executeSettlement() pode ser chamado com ou sem um evento de entrega jamais ter sido registrado — a Ishtaran valida invariantes financeiros, nunca fatos do mundo físico. Isso é um design deliberado, não um bug: confirmar a entrega antes de liquidar é trabalho do integrador. Veja Confirming delivery.

F.2 — Sem clawback depois de um Settlement completo​

Uma vez que um Settlement distribuiu totalmente o Distributable Amount, não existe mecanismo na plataforma para reverter o que já foi creditado. Qualquer correção depois desse ponto é um novo movimento separado — nunca uma edição do Settlement histórico.

F.3 — Sem rota pública para ler a Pricing Policy de antemão​

Um integrador só descobre o percentual real da Fee a partir do resultado de um Settlement em si — nunca antes de chamá-lo. Veja Settlement and Split.

F.4 — Sem mecanismo oficial no Sandbox para pular cooldowns de Withdrawal​

Nem o cooldown de 24h de ativação do destino nem o cooldown de 168h de mudança de destino podem ser adiantados. Este Business Case nunca os contorna — veja Withdrawal.

F.9 — Algumas chamadas precisam de uma sessão de Member, não uma API Key​

accounts.authorizeApplication, toda mutação de workflows.*, e events.ingest rejeitam uma Application API Key hoje. Veja Architecture.

F.10 — Sem API financeira self-service para AccountHolders​

O próprio login de um vendedor só consegue gerenciar a própria identidade — não conferir o saldo nem pedir um saque. Toda chamada financeira em nome dele usa as credenciais do próprio marketplace. Veja Seller balance.

F.15 — Settlements parciais rápidos podem esbarrar num conflito transiente de concorrência​

Comportamento padrão e esperado de concorrência otimista (409 CONCURRENT_MODIFICATION) quando chamadas de Settlement chegam próximas demais no tempo, no mesmo pedido — a resposta correta é uma nova tentativa limitada, igual a qualquer API com concorrência otimista. Veja Partial Settlement.

F.16 — O caminho real de execução do Settlement é SelfCustody, não "calcula Fee e grava no Ledger"​

Versões anteriores deste tutorial (e do próprio diagrama de arquitetura) descreviam executeSettlement como gravando Ledger Entries diretamente. Isso era correto para o modelo ManagedCustody da plataforma, mas SelfCustody — o único modo que este Sandbox de fato roda hoje (DEC-037, docs/architecture/CUSTODY-EXECUTION-MODES.md) — é diferente: executeSettlement monta um SigningRequest real e retorna com o Settlement em Executing; nada está finalizado, e nenhum Ledger Entry existe ainda, até que toda execution leg seja assinada, transmitida e confirmada. Veja Settlement and Split para a mecânica completa, e self-custody-settlement.ts para o código de assinar/confirmar/esperar que todo capítulo a partir dali reutiliza.

F.17 — O Settlement agora exige um NetworkCostPayerAccount registrado​

Transmitir as execution legs de um Settlement custa recursos de rede reais, cobrados separadamente da Platform Fee — a Mercatto precisa dizer à Ishtaran, uma vez por AssetNetwork, qual das suas próprias Accounts paga por isso. Sem isso, executeSettlement falha antes mesmo de montar qualquer SigningRequest. Veja Settlement and Split e register-network-cost-payer-account.ts.

F.18 — Questão de produto em aberto: como um NetworkCostPayerAccount novo recebe seu primeiro saldo?​

Registrar um NetworkCostPayerAccount (F.17) não basta sozinho — a plataforma também confere o saldo Available real dessa Account antes de deixá-la pagar qualquer coisa, e não existe hoje nenhuma rota para financiar uma Account independentemente de uma Transaction. Para o primeiro Settlement real de um marketplace novo, isso é um problema real de ovo-e-galinha que a plataforma ainda não resolve: nada foi liquidado ainda para financiar a account, mas financiá-la exige uma liquidação. A verificação local deste tutorial contornou isso com uma ferramenta só de desenvolvimento, nunca algo utilizável em Sandbox ou Production — isso fica registrado como uma decisão em aberto para o dono da plataforma, não resolvida aqui. Veja GAPS.md §F.18 para o detalhe completo.

O resto​

O GAPS.md também documenta achados de execução da plataforma fora do escopo deste tutorial, da mesma rodada de auditoria:

  • Nada ainda liga a aprovação de Settlement/Withdrawals diretamente à criação automática de SigningRequest — o próprio código deste tutorial (release-order.ts, withdraw.ts) é quem faz esse papel hoje, chamando executeSettlement/request e depois conduzindo o protocolo de assinatura explicitamente. Trabalho real dos dois lados, tanto no Sandbox quanto em Production — não é uma lacuna exclusiva de Production.
  • Execução real em blockchain — uma transação assinada de fato chegando numa rede real — é exclusiva de Production e ainda não está disponível; o broadcast/confirmação do Sandbox é simulado do início ao fim, deliberadamente, não é um atalho que este tutorial esconde.

Dois achados anteriores desta lista — o modelo de Network Fee não distinguindo o ativo transferido do recurso que paga pela execução na rede, e a inexistência de uma checagem pré-broadcast de viabilidade — foram resolvidos pelo Network Execution Engine da plataforma (veja Settlement and Split e Withdrawal); o GAPS.md §F.13/F.14 mantém os achados originais registrados junto com o que de fato mudou.

Nenhuma dessas é corrigida inventando um workaround — cada uma ou é corrigida na raiz (veja a própria trilha de auditoria de Ledger/Settlement da plataforma) ou é documentada com precisão suficiente para que uma sessão futura continue exatamente de onde esta parou.