docs(skill): sincroniza a skill nfeio-php-sdk com v3.2.0 + v3.3.0#28
Merged
Conversation
A skill versionada no repo estava na baseline v3.1.0 — duas releases atrás. (As atualizações de v3.2.0 haviam sido aplicadas na cópia local ~/.claude, removida quando a skill passou a ser versionada aqui.) v3.2.0 (add-safe-retry-idempotency): - Retry method-aware (tabela de decisão; POST não retenta em 5xx/ambíguo; Idempotency-Key restaura retry pleno mas a API ainda não honra o header). - FailurePhase + failurePhase/curlErrno na ApiConnectionException. - Override de retry por chamada (RequestOptions->retry). - findByExternalId (rota /external, contrato de coleção, miss=200 lista vazia, lag de indexação) + isDuplicateExternalId + ciclo de emissão idempotente. - Pitfalls #17/#18; decision tree; descrições dos reference files. v3.3.0 (expand-service-invoice-dto): - ServiceInvoice: campos tipados number/checkCode/description/cityServiceCode/ baseTaxAmount/issRate/issTaxAmount/amountNet + borrower (Borrower DTO, federalTaxNumber int|string|null). - raw agora populado (SDK-wide, por item em list); provider via raw['provider']. - totalAmount documentado como phantom @deprecated (sempre null) — pitfall #19. - Nota sobre o teste de alinhamento YAML<->DTO (ancorado por path). Fatos verificados contra o src/ (ordem dos args de RequestOptions, cases do FailurePhase, allowlist de errnos 5/6/7/35, assinatura static de isDuplicateExternalId, campos do Borrower).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
O que
A skill de agente versionada no repo (
skills/nfeio-php-sdk/) estava na baseline v3.1.0 — duas releases atrás do SDK publicado. Este PR a sincroniza com v3.2.0 (retry seguro + idempotência) e v3.3.0 (expansão do DTOServiceInvoice). Sem a sincronização, a skill induz geração de código desatualizado (ex.: assumir que POST retenta em 5xx, ignorarfindByExternalId, ler->totalAmount).Mudanças (3 arquivos)
SKILL.mddescription: novos gatilhos (emissão idempotente, method-aware retry, campos tipados).RequestOptions->retry).ApiConnectionExceptioncomfailurePhase/curlErrno.externalId; override de retry por chamada;totalAmountphantom deprecated + campos v3.3.0 +rawpopulado.externalIde leitura denumber/checkCode.references/error-handling-and-patterns.mdFailurePhase(errnos 5/6/7/35, PSR-18), nota de mudança de comportamento vs v3.1, override por requisição com exemplo.references/service-invoices-and-polling.mdfindByExternalId+isDuplicateExternalId(static) na lista de métodos.Borrower(federalTaxNumberint|string|null),rawpopulado (por item; SDK-wide),providerviaraw,totalAmountphantom, teste de alinhamento./external, lag de indexação.Verificação
Fatos conferidos contra
src/neste commit: ordem dos args deRequestOptions(apiKey, baseUrl, timeout, retry), cases doFailurePhase, allowlist de errnos (5/6/7/35), assinaturastaticdeisDuplicateExternalId, campos doBorrower. Varredura por afirmações de retry desatualizadas: zero restantes.Fecha a tarefa 4.4 da change
expand-service-invoice-dto.