CorsooEngenharia de Organização

Apêndice B — Schema de Referência

Referência normativa para implementações. Chaves e valores de schema em inglês; conteúdo na língua do projeto.

Projeto

{
  "id": "#1848",
  "name": "Sistema de Gestão Escolar",
  "logline": "Uma plataforma que centraliza toda a gestão acadêmica e administrativa da instituição.",
  "version": "1.0",
  "status": "production",
  "visibility": "private",
  "health": {
    "value": "on_track",
    "trend": "accelerating"
  },
  "registered_at": "2026-03-06T14:00:00Z",
  "greenlight": {
    "audience": {
      "age_rating": "livre",
      "languages": ["pt-BR"]
    },
    "market": {
      "type": "B2B",
      "segment": "educação",
      "geography": ["Brasil"]
    },
    "tone": "formal",
    "distribution": ["web", "mobile"],
    "budget": {
      "estimated": 100000,
      "currency": "BRL",
      "approved_at": "2026-03-01T00:00:00Z"
    },
    "amendment_tolerance_pct": 10,
    "approved_by": "Daniel",
    "approved_at": "2026-03-01T00:00:00Z"
  },
  "roles": {
    "screenplay_writer": {
      "name": "Ana Silva",
      "certified": true,
      "certification_id": "CORSOO-SW-0042"
    },
    "executive_producer": { "name": "Carlos Mendes" },
    "director": { "name": "Beatriz Costa" },
    "team": [
      { "name": "dev_01", "role": "backend" },
      { "name": "dev_02", "role": "frontend" }
    ]
  }
}

Status válidos por nível

Projeto:

draft | greenlit | pre_production | production | post_production | final_cut | released | archived

Fluxo:

pending | in_production | in_post | done | blocked | cut

Passo:

pending | in_progress | done | blocked | cancelled

Saúde (health.value): on_track | at_risk | late | done

Tendência (health.trend): accelerating | stable | decelerating

Recurso (security_status): declared | verified | rejected

Visibilidade: private | public

Fluxo

{
  "id": "#1848.01",
  "name": "Login",
  "narrative": "O @[actor:Usuário] acessa a @[screen:Tela de Login] e insere suas credenciais. O @[system:API de Autenticação] valida o @[data:Email] e a @[data:Senha]. A @[rule:Senha mínimo 8 caracteres] é aplicada. Em caso de sucesso, o sistema gera um @[resource:JWT Token] e redireciona para o @[screen:Dashboard]. Em caso de falha, exibe mensagem de erro e oferece link para o @[flow:Recuperação de Senha].",
  "status": "in_production",
  "health": { "value": "on_track", "trend": "stable" },
  "risk": {
    "level": "low",
    "description": "",
    "mitigation": "",
    "dependency": null
  },
  "dependencies": [],
  "estimated_days": 2,
  "deadline": "2026-03-20T00:00:00Z",
  "rework_count": 0,
  "post_production": {
    "criteria": [
      "Fluxo funciona sozinho",
      "Fluxo funciona com suas dependências",
      "Fluxo não quebra o que já foi entregue"
    ],
    "passed": false,
    "validated_by": null,
    "validated_at": null
  }
}

Passo

{
  "id": "#1848.01.4",
  "description": "Integração com API de autenticação e geração de JWT",
  "status": "pending",
  "risk": {
    "level": "medium",
    "description": "Depende de credenciais da API ainda não fornecidas",
    "mitigation": "Mockar resposta até receber credenciais",
    "dependency": null
  },
  "assigned_to": "dev_01",
  "participants": [],
  "estimated_hours": 4,
  "due_at": "2026-03-12T00:00:00Z",
  "actual_hours": null,
  "started_at": null,
  "done_at": null,
  "blocked_since": null,
  "blocked_reason": null,
  "blocking_address": null,
  "resources": [
    {
      "name": "jsonwebtoken",
      "type": "library",
      "version": "9.0.0",
      "url": "https://npmjs.com/package/jsonwebtoken",
      "license": "MIT",
      "security_status": "verified",
      "added_by": "dev_01",
      "added_at": "2026-03-06T10:00:00Z"
    }
  ]
}

Inventário (gerado pelo parser)

{
  "inventory": {
    "actors": ["Usuário", "Administrador"],
    "screens": ["Tela de Login", "Dashboard", "Perfil do Usuário"],
    "systems": ["API de Autenticação", "Serviço de Email"],
    "resources": ["JWT Token", "bcrypt"],
    "rules": ["Senha mínimo 8 caracteres", "Email único no sistema"],
    "data": ["Email", "Senha", "Nome completo"],
    "flows": ["Recuperação de Senha", "Cadastro"]
  }
}

Lançamento do fluxo de caixa

{
  "address": "#1848.01.4",
  "type": "expense",
  "amount": 190.0,
  "currency": "BRL",
  "date": "2026-03-05",
  "category": "infrastructure",
  "description": "Licença da biblioteca de autenticação",
  "registered_by": "Carlos Mendes",
  "evidence": "NF-e 12345",
  "reversal_of": null
}

Tipos (type): contribution | expense | provision | refund Categorias v1 (category): personnel | infrastructure | vendor | acquisition | operational | financial | investment | revenue Regras: lançamentos são imutáveis; correção via novo lançamento com reversal_of apontando o original.

Emenda de Roteiro

{
  "project": "#1848",
  "number": 2,
  "date": "2026-04-10T00:00:00Z",
  "changes": [
    { "kind": "flow_added", "address": "#1848.07", "name": "Exportação de Relatórios" },
    { "kind": "flow_cut", "address": "#1848.05", "reason": "Descontinuado pelo cliente" }
  ],
  "reason": "Solicitação do cliente na revisão de abril",
  "impact": {
    "days": 6,
    "budget": 9200,
    "currency": "BRL"
  },
  "approved_by": "Carlos Mendes",
  "within_tolerance": true
}

TCA

{
  "project": "#1848",
  "declarant": {
    "name": "Fundo XYZ Capital",
    "email": "partner@xyz.vc"
  },
  "statement": "Declaro que tive conhecimento do projeto #1848 em 06/03/2026.",
  "invited_at": "2026-03-05T18:00:00Z",
  "signed_at": "2026-03-06T09:12:00Z",
  "signature": "sha256:..."
}

Slate (portfólio executivo)

{
  "generated_at": "2026-03-06T14:32:00Z",
  "summary": {
    "total_projects": 12,
    "on_track": 7,
    "at_risk": 3,
    "late": 2,
    "done": 0,
    "overall_progress_pct": 68
  },
  "daily": {
    "date": "2026-03-06",
    "steps_done_today": 47,
    "flows_delivered_today": 3,
    "blockers_active": 2,
    "blockers_resolved_today": 1
  },
  "projects": [
    {
      "id": "#1848",
      "name": "Sistema de Gestão Escolar",
      "logline": "Uma plataforma que centraliza toda a gestão acadêmica e administrativa da instituição.",
      "health": { "value": "on_track", "trend": "accelerating" },
      "progress_pct": 39,
      "flows_total": 6,
      "flows_done": 1,
      "budget_estimated": 100000,
      "budget_spent": 32000,
      "deadline": "2026-05-01T00:00:00Z",
      "days_variance": -18,
      "blockers_active": 0,
      "last_updated": "2026-03-06T14:00:00Z"
    }
  ]
}

days_variance: negativo = adiantado, positivo = atrasado. budget_spent: saídas + provisões (provisão conta como comprometido).

Fórmulas derivadas (v1)

progress_pct     = Σ(estimated_hours dos passos done) / Σ(estimated_hours de todos os passos) × 100
                   (fallback sem estimativas: contagem de passos)

prazo do fluxo   = caminho crítico das datas de entrega dos passos
                   (estimativas viram datas; dependências encadeiam datas)

budget           = Σ(horas × taxa do perfil) + Σ(recursos com custo) + contingência
contingência     = 5% (low) | 10% (medium) | 20% (high), por fluxo

health.value     = on_track  : projeção ≤ prazo e sem bloqueio crítico
                   at_risk   : projeção ≤ prazo+10% ou bloqueio ≥ 3 dias no caminho crítico
                   late      : projeção > prazo+10% ou deadline ultrapassado

health.trend     = vazão(últimos 7 dias úteis) vs vazão(7 anteriores), em horas concluídas/dia:
                   accelerating > +10% | stable ±10% | decelerating < −10%

Parser de marcação — spec

Regex de extração de atores:

@\[([a-zA-Z_]+):([^\]]+)\]

Grupo 1 = tipo (actor, screen, system...) · Grupo 2 = nome.

Marcas de controle (não geram inventário): @[SE], @[SENÃO], @[AO], @[EM_DESENVOLVIMENTO] — token único em caixa alta, sem :.

@\[([A-ZÀ-Ü_]+)\]

O parser deve:

  1. Extrair todos os elementos marcados de todos os fluxos
  2. Separar marcas de controle de atores (caixa alta sem : = controle)
  3. Deduplicar por tipo + nome exato
  4. Gerar o inventário consolidado do projeto
  5. Reprocessar a cada edição do roteiro — o inventário nunca é editado à mão

Corsoo, Engenharia de Organização · corsoo.org

← Apêndice A — Glossário · Sumário · Próximo: Apêndice C — Exemplo Completo →