FEATURE ROLLOUT · DOCUMENTAÇÃO

Opere o centro de verdade por HTTP

Documentos pertencem a um único portfólio, começam na versão 1 e preservam todas as versões. O conteúdo atual e o diff alimentam análises sequenciais de coerência.

Escolha o ambiente correto

Use a Management API v2 com um token fr_pat_* emitido por fr login. Leitura exige management:read; upload, nova versão e análises exigem management:write combinado com papel owner/admin. Chaves fr_ci_* continuam restritas ao CI.

leituraMembro do workspace

upload/versãoowner ou admin

análise/decisãoowner ou admin

arquivoAté 25 MB por versão

formatosPDF, DOCX, Markdown, texto, imagem, planilha e outros binários

Liste ou crie documentação

O POST cria o documento lógico e a versão 1 na mesma transação. title aceita até 160 caracteres e description até 1.000; ambos são opcionais.

shell

export APPLICATION_ID='2cbb9638-67d5-4c23-90ce-c84fa1f45418'

# listar documentos, versões, diffs, análises e sugestões
curl --fail-with-body   "$FEATURE_ROLLOUT_URL/api/applications/$APPLICATION_ID/documents"

# criar documento e versão 1 (multipart, máximo 25 MB)
curl --fail-with-body --request POST   "$FEATURE_ROLLOUT_URL/api/applications/$APPLICATION_ID/documents"   --form 'file=@docs/recorrencia.md;type=text/markdown'   --form 'title=Contrato de recorrência'   --form 'description=Regras funcionais e estados da autorização'

Entenda a resposta agregada

A resposta real também inclui providers, até dez análises recentes e suas sugestões. Cada versão inclui datas completas e, quando aplicável, o unified diff.

json

{
  "portfolio": {
    "id": "2cbb9638-67d5-4c23-90ce-c84fa1f45418",
    "name": "Pix Automático"
  },
  "canManage": true,
  "documents": [{
    "id": "6cf2492c-5331-4d42-88c8-cfe4058622ef",
    "title": "Contrato de recorrência",
    "description": "Regras funcionais e estados da autorização.",
    "currentVersion": 2,
    "versions": [{
      "id": "c96e89f8-43ef-4258-850d-0d4543fbba28",
      "version": 2,
      "fileName": "recorrencia-v2.md",
      "mimeType": "text/markdown",
      "extension": "md",
      "sizeBytes": 18420,
      "checksum": "7aa5…d921",
      "extractionStatus": "completed",
      "versionNote": "Inclui revogação",
      "diff": {
        "addedLines": 14,
        "removedLines": 3,
        "previousVersion": 1,
        "currentVersion": 2
      },
      "contentHref": "/api/document-versions/c96e89f8-43ef-4258-850d-0d4543fbba28/content"
    }]
  }],
  "analyses": []
}

Crie uma nova versão

O número é incrementado sob lock transacional. Arquivo com o mesmo SHA-256 da versão atual retorna HTTP 409. O diff é calculado sobre o texto extraído; formatos sem extração textual continuam versionados, mas podem não produzir diff.

shell

export DOCUMENT_ID='6cf2492c-5331-4d42-88c8-cfe4058622ef'

curl --fail-with-body --request POST   "$FEATURE_ROLLOUT_URL/api/documents/$DOCUMENT_ID/versions"   --form 'file=@docs/recorrencia-v2.md;type=text/markdown'   --form 'versionNote=Inclui revogação e retentativa'

# o contentHref retornado entrega bytes, preservando o Content-Type
curl --fail --remote-name   "$FEATURE_ROLLOUT_URL/api/document-versions/$VERSION_ID/content"

Analise coerência em fila sequencial

Escolha de um a quatro IDs suportados. Cada modelo conclui seu relatório antes do seguinte começar; ao final, o painel consolida score, resumo e sugestões. A resposta HTTP só termina quando a fila termina, portanto use timeout superior a 300 segundos no Docker.

x-ai/grok-4.5Grok 4.5

qwen/qwen3.8-maxQwen 3.8 Max

openai/gpt-5.6-terraGPT-5.6 Terra

anthropic/claude-opus-5Claude Opus 5

shell

export APPLICATION_ID='2cbb9638-67d5-4c23-90ce-c84fa1f45418'

curl --fail-with-body --request POST   "$FEATURE_ROLLOUT_URL/api/applications/$APPLICATION_ID/coherence-analyses"   --header 'Content-Type: application/json'   --data '{
    "models": [
      "x-ai/grok-4.5",
      "qwen/qwen3.8-max",
      "openai/gpt-5.6-terra"
    ]
  }'

# aceitar ou rejeitar uma sugestão pendente
curl --fail-with-body --request PATCH   "$FEATURE_ROLLOUT_URL/api/coherence-suggestions/$SUGGESTION_ID"   --header 'Content-Type: application/json'   --data '{"decision":"accept"}'

Aplique sugestões conscientemente

Uma sugestão possui kind create/update/deprecate, targetType task/scenario/test, justificativa, referências documentais, votos dos modelos e confiança. accept grava a mudança e registra auditoria; reject preserva o painel e encerra a sugestão.

create taskCria tarefa DOC-* na feature indicada

create scenarioCria cenário DOC-CT-* e pode vinculá-lo à tarefa

create testCria caso de teste documental

updateAtualiza campos permitidos do alvo existente

deprecateMarca tarefa/cenário/teste como descontinuado

resposta{ suggestionId, status, appliedEntityId }

Idempotência de decisão

Repetir a decisão de uma sugestão já encerrada devolve o estado existente e não reaplica a mudança.