FEATURE ROLLOUT · DOCUMENTAÇÃO

Objetos, vínculos e identificadores

O modelo separa estrutura organizacional, definição do produto, prova de execução e centro documental. IDs técnicos são usados nas URLs; IDs de negócio preservam rastreabilidade no catálogo e no CI.

Hierarquia canônica

Nas URLs e no banco, um portfólio é chamado de application. Na interface, o termo apresentado é portfólio. Eles são o mesmo objeto.

text

Workspace
└── Projeto
    └── Portfólio (application)
        ├── Repositório
        ├── Documentações → versões → diffs
        └── Feature
            ├── Tarefas ↔ cenários
            ├── Execuções → testes → evidências
            ├── Riscos
            ├── Checklist e sign-offs
            └── Fases de rollout

UUID técnico e ID de negócio

workspaceIdUUID · escopo de permissão e chaves

projectIdUUID · usado nas APIs de configuração do projeto

applicationIdUUID · usado nas APIs de documentação do portfólio

documentId/versionIdUUID · documento lógico e versão imutável

feature.idTexto estável, por exemplo LBP-PIX-001

task.idTexto estável e único no catálogo, por exemplo TSK-PIX-002

scenario.idTexto estável e único, por exemplo CT-PIX-002

evidence.id/risk.idNúmero gerado pelo banco

Não invente UUIDs

Copie IDs das respostas do dashboard/API ou do estado já provisionado. Slugs selecionam o destino no catálogo v2; UUIDs selecionam recursos internos.

Projeto

Agrupa portfólios dentro de um workspace e define o limite administrativo para renomear, transferir e excluir. A exclusão remove em cascata portfólios, features, testes e documentos relacionados.

idUUID imutável

workspaceIdWorkspace proprietário

slugGerado do nome e único no workspace

name2–100 caracteres

descriptionAté 500 caracteres

createdAt/updatedAtTimestamps ISO 8601

Portfólio

É a aplicação ou domínio funcional que concentra features, repositórios e o centro documental. O catálogo v2 procura o portfólio por project slug + application slug + repository fullName.

idUUID usado em /api/applications/:applicationId/*

projectIdProjeto pai

slugIdentificador usado por CI, por exemplo pix-automatico

nameNome apresentado no painel

descriptionEscopo do portfólio

repositoryNome completo, por exemplo conta-facil/lb-pay

Feature

Unidade liberável e principal contexto de prontidão. O score não é livre: no catálogo v2 ele deve ser igual à soma arredondada de readinessWeight × progress das tarefas.

idID de negócio global, 3–100 caracteres

useCaseJornada ou capacidade atendida

name/descriptionTítulo e contrato funcional

statusEstado apresentado no painel

score0–100, calculável pelas tarefas

deployWindowJanela textual ou ISO 8601

dimensionsLeituras auxiliares de prontidão; não substituem tarefas

Tarefa e cenário

A tarefa descreve trabalho e carrega peso/progresso. O cenário descreve comportamento verificável. A relação é N:N por scenarioRefs: toda tarefa precisa de ao menos um cenário e todo cenário precisa ser referenciado.

task.descriptionPor que e o que será entregue

implementationDetailsComo a mudança será implementada

acceptanceCriteriaLista objetiva; ao menos um item

readinessWeightPeso 1–100; a soma da feature deve ser 100

progress0–100; deve concordar com status

remainingWorkObrigatório quando progress < 100

scenario.titleComportamento esperado

scenario.resultPASS, FAIL, PEND ou estado aceito pelo painel

scenario.metaÚltima execução, ambiente ou justificativa

Evidência

Prova material ligada a uma feature e, quando possível, a um cenário. Evidência de catalog representa uma expectativa declarada; evidência de ci é produzida por uma execução imutável e nunca é apagada pela reconciliação do catálogo.

kindIMAGEM, JSON, TEXTO ou classificação equivalente

titleNome humano do artefato

descriptionO que o artefato comprova

doubleCheckedtrue somente após verificação por um segundo modelo

scenarioRefID de cenário relacionado

payloadTypeimage ou text

contentTypeMIME real, como application/json

content/contentUrlConteúdo inline ou referência HTTP(S)

encodingutf8 ou base64

Documento e versão

O documento é a identidade lógica dentro de um único portfólio. Cada upload cria uma versão imutável; a versão atual alimenta a análise de coerência. O diff compara texto extraído da versão anterior com a nova.

document.idUUID lógico e estável

title/descriptionContexto opcional do arquivo

currentVersionInteiro iniciado em 1

version.idUUID imutável da versão

fileName/mimeType/sizeBytesMetadados do binário

checksumSHA-256 usado para bloquear versão duplicada

extractionStatusEstado da extração de texto

diffLinhas adicionadas/removidas e unified diff

contentHrefDownload/visualização autorizada

Risco, gate e rollout

Riscos altos ou críticos bloqueiam o gate. Checklist bloqueante aberto, cenário diferente de PASS, ausência de execução aprovada em homologação e sign-off pendente para produção também entram como bloqueadores.

risk.severityCRÍTICO, ALTO, MÉDIO ou BAIXO

risk.mitigationAção concreta de redução/aceitação

checklist.blockingTransforma item incompleto em bloqueador

signoff.statusPENDENTE, APROVADO, RESSALVA ou REJEITADO

rollout.environmentci, homologation ou production

rollout.gateStatusblocked, pending, passed ou failed

rollbackPlanPassos explícitos para reversão