--- type: Schema layer: okf title: "OKF Schema — DashDescomplicar" description: >- Schema canónico do Organizational Knowledge Framework (OKF) para o projecto DashDescomplicar. Formaliza o padrão já em uso — entidades curadas + relacionamentos narrativos em Markdown — e declara o Nível de Maturidade actual (N1). tags: [dashdescomplicar, okf, schema, governanca, convencoes] timestamp: 2026-07-07 status: active --- # OKF Schema — DashDescomplicar **Schema canónico do projecto. Formaliza, sem alterar, o padrão já em produção em `okf/entidades/` e `okf/relacionamentos/`.** Alinhado com o OKF global Descomplicar® (`Hub/04-Stack/02.04-Sistemas/90.Conhecimento/OKF/SCHEMA.md`) e com `QR-OKF-Project-Level.md` (Hub, v2.0) — padrão genérico de OKF de projecto. Este ficheiro documenta explicitamente uma decisão já tomada em `SPEC-OKF-Projeto-Sistema-Excelencia.md` (§3.6, §5.4): DashDescomplicar mantém-se em **N1**, com `okf/relacionamentos/*.md` como Tier 3 narrativo válido (não `relations.jsonl`). --- ## 1. Modelo em Uso DashDescomplicar usa **2 das 3 camadas** do modelo OKF de projecto — não implementa Tier 2 (inventário automático do código) nem Tier 3 máquina-legível (`relations.jsonl`): | Tier | Nome | Estado neste projecto | Origem | |------|------|------------------------|--------| | **1** | Entidades curadas | ✅ Implementado — `okf/entidades/*.md` (25 fichas) | Escrita humana | | **2** | Inventários derivados do código | ❌ Não implementado — sem `okf/inventory/`, sem `scripts/okf-gen-inventory.mjs` | N/A | | **3** | Grafo derivado (`relations.jsonl`) | ❌ Não implementado — substituído pelo Tier 3 narrativo (§5) | N/A | **Tier 3 narrativo (em uso):** `okf/relacionamentos/*.md` — um ficheiro Markdown por aresta, com frontmatter + descrição prosa (e, quando aplicável, fluxo de dados/tabelas). Ver §5 para a decisão formal de não migrar para `relations.jsonl`. --- ## 2. Estrutura de Pastas (real) ``` okf/ ├── SCHEMA.md ← este ficheiro ├── index.md ← catálogo navegável das 25 entidades + 21 relacionamentos ├── FASE-C-VALIDACAO.md ← registo histórico da validação Fase C ├── entidades/ ← Tier 1 — 25 fichas curadas │ ├── Dashboard-Engine.md │ ├── Express-API.md │ ├── Painel-Monitor.md │ ├── Integracao-Hetzner.md │ └── ... └── relacionamentos/ ← Tier 3 narrativo — 21 fichas de aresta ├── DashboardEngine-exibe-Paineis.md ├── MySQL-Pool-alimenta-Servicos.md └── ... ``` Sem `inventory/`, sem `relations.jsonl`, sem `graph-metrics.json`, sem `scripts/okf-*.mjs` — nenhum destes é exigido a N1 (ver §6). --- ## 3. Nomenclatura ### Fichas de entidade (`okf/entidades/`) - **PascalCase-com-hífens**, descritivo, **sem prefixo `okf-*`** — diferente do padrão WhatSMS/Pleno (`okf-svc-*`, `okf-dom-*`). Esta convenção já está consolidada nas 25 fichas existentes; não se migra retroactivamente. - Exemplos reais: `Dashboard-Engine.md`, `Painel-Monitor.md`, `Integracao-Hetzner.md`, `MySQL-Pool.md`. ### Fichas de relacionamento (`okf/relacionamentos/`) - Nome descreve a aresta: `--.md` (ex.: `Integracao-Hetzner-alimenta-Monitor.md`). - Quando há múltiplos destinos ou uma relação agregada, o nome reflecte o padrão dominante (ex.: `Paineis-consomem-DeskCRM.md`). ### Wikilinks - Referência cruzada: `[[Dashboard-Engine]]` (nome do ficheiro sem extensão), resolvido contra `okf/entidades/*.md`. --- ## 4. Frontmatter (real, validado por inspecção — não por script) ### Entidade (Tier 1) ```yaml --- type: Entity layer: wiki tags: [stack, dashdescomplicar, tag2, tag3] title: "Nome-Da-Entidade" --- ``` ### Relacionamento (Tier 3 narrativo) ```yaml --- type: Relationship layer: wiki tags: [stack, dashdescomplicar, relacionamento, tag3, tag4] title: "Origem-verbo-Destino" --- ``` **Nota de convenção:** `type`/`layer` usam a casing e os valores do padrão de wiki do Hub (`type: Entity`, `layer: wiki`), não o par `type: entity`/`layer: okf` do schema WhatSMS/Pleno. Não é um erro a corrigir por este ficheiro — é a convenção já estabelecida e consistente nas 46 fichas existentes (25 entidades + 21 relacionamentos); mantém-se como está. Frontmatter **não inclui** `category`, `status`, `desk_project` ou `timestamp` por ficha — mais leve que o schema WhatSMS/Pleno, adequado à escala N1. Estado/categoria são comunicados em prosa dentro do corpo (ex.: secção `## Estado` em `Painel-Monitor.md`). --- ## 5. Relacionamentos Narrativos vs `relations.jsonl` — Decisão **Decisão (já tomada, `SPEC-OKF-Projeto-Sistema-Excelencia.md` §3.6/§5.4, não reaberta aqui):** DashDescomplicar **não migra** `okf/relacionamentos/*.md` para `relations.jsonl`. **Justificação:** - `relations.jsonl` só é **obrigatório a partir de N3** (`QR-OKF-Project-Level.md` §Níveis de Maturidade) — DashDescomplicar está em N1 (§6). - O custo de construir e manter `scripts/okf-gen-graph.mjs` (parser + geração de arestas `derived`/`reciprocal`) não se justifica para 21 arestas geridas manualmente sem atrito. - `okf/relacionamentos/*.md` (um ficheiro por aresta, com frontmatter + descrição narrativa, por vezes com fluxo de dados/tabelas de detalhe — ex. `MySQL-Pool-alimenta-Servicos.md`) é reconhecido formalmente pelo `QR-OKF-Project-Level.md` (§Relacionamentos narrativos vs `relations.jsonl`) como **fonte Tier 3 adicional válida**, própria para relações que beneficiam de explicação processual em vez de uma aresta plana. - Se o projecto crescer para N3 (≥50 ficheiros de código E ≥3 serviços/domínios — ver §6), `relations.jsonl` pode ser gerado a partir destas mesmas fichas (`okf-gen-graph.mjs` pode parsear `relacionamentos/*.md` como origem `origin: narrative`, per QR) sem duplicar trabalho manual — mas essa geração **não é criada por este ficheiro**. --- ## 6. Nível de Maturidade: N1 | Nível | Critério de entrada | Requisitos | Estado DashDescomplicar | |-------|---------------------|-------------|--------------------------| | **N1** | Qualquer projecto com `okf/` | `entidades/` + `index.md` | ✅ Cumprido — 25 entidades + `index.md` | | N2 | ≥50 ficheiros de código | + `inventory/` automático | ❌ Não implementado | | N3 | ≥50 ficheiros E ≥3 serviços/domínios | + `relations.jsonl` + `SCHEMA.md` formal | ❌ Não implementado | | N4 | Produção activa | + overlays risk/churn + `okf-feat-*` + `specs-by-entity.json` + drift-check | ❌ Não implementado | **Justificação (N1, escala do projecto):** - 25 entidades Tier 1 bem documentadas, 21 relacionamentos narrativos — cobertura curada completa para a superfície do projecto. - Volume de código (`src/` + `api/`, TypeScript): **75 ficheiros `.ts`/`.tsx`** — acima do limiar literal de 50 ficheiros que define a entrada em N2 no `QR-OKF-Project-Level.md`. Isto por si só sugeriria N2. - **Mas** o requisito real de N2 não é a contagem de ficheiros — é a existência de `okf/inventory/` **automático**, gerado por script (`scripts/okf-gen-inventory.mjs`). Nenhum dos dois existe neste repositório (confirmado: sem pasta `scripts/`, sem `okf/inventory/`, sem ficheiros `okf-gen-*`). Sem essa infra-estrutura de geração, o projecto não cumpre o requisito formal de N2, independentemente do volume de código. - Esta avaliação está alinhada com `SPEC-OKF-Projeto-Sistema-Excelencia.md` §3.6 (mapeamento explícito: "CodeRED/DashDescomplicar = N1, mantêm-se aí por agora — escala pequena não justifica N2+ ainda") e §5.4 (Fase 4: "CodeRED/DashDescomplicar: criar SCHEMA.md mínimo documentando o padrão `relacionamentos/*.md` já em uso como válido"). - **Nota de avaliação (reportada, não decidida aqui):** o volume de código (75 ficheiros) é tecnicamente suficiente para justificar a criação de `scripts/okf-gen-inventory.mjs` e subir a N2 num ciclo futuro — mas essa subida implica trabalho de automação novo (fora do âmbito desta Fase 4, que é apenas formalização documental) e não foi implementada aqui. --- ## 7. Estrutura de Conteúdo das Fichas de Entidade (real) As fichas em `okf/entidades/` **não seguem o formato rígido 5W2H+PDCA** (usado em WhatSMS v2/Pleno) — usam secções livres, adaptadas ao tipo de componente, tipicamente um subconjunto de: - `## Responsabilidades` — o que o componente faz - `## Stack` — tecnologias usadas - `## Localizações` — paths no repo, rotas, deploy - `## Tipos` — interfaces/tipos TypeScript relevantes (quando aplicável) - `## APIs Consumidas` / `## Dependências` — o que consome / de que depende - `## Fornece a` — quem consome este componente - `## Estado` — activo/suspenso/proposto, marcos relevantes Este formato é adequado à escala N1 (fichas de 60-100 linhas, foco técnico denso) e mantém-se sem alteração. --- ## 8. Regras de Qualidade 1. Frontmatter mínimo presente em toda a ficha (`type`, `layer`, `tags`, `title`). 2. Toda a entidade referenciada em `okf/index.md` com wikilink bidireccional (entidade ↔ relacionamentos que a tocam). 3. Toda a relação com ficha própria em `okf/relacionamentos/`, mínimo `Origem`/`Destino`/`Tipo`/`Descrição`. 4. PT-PT estrito, sem brasileirismos. 5. Primeira tag de qualquer ficha: `stack`; segunda: `dashdescomplicar`. 6. Sem Tier 2/3 automáticos a este nível — nada a regenerar; toda a manutenção é manual. --- ## 9. Manutenção | O quê | Quem | Quando | |-------|------|--------| | Entidades Tier 1 (novos componentes) | Developer | Quando um novo painel/integração é criado | | Relacionamentos narrativos | Developer | Quando uma nova aresta de dados/dependência surge | | `okf/index.md` | Developer | Após qualquer alteração a entidades/relacionamentos | | `SCHEMA.md` | Developer | Quando o padrão evolui ou o Nível de Maturidade muda | --- ## Referências - OKF Global (`Hub/04-Stack/02.04-Sistemas/90.Conhecimento/OKF/SCHEMA.md`) — schema canónico, taxonomia, 5W2H+PDCA - `QR-OKF-Project-Level.md` (Hub) — padrão genérico de OKF de projecto, v2.0 - `SPEC-OKF-Projeto-Sistema-Excelencia.md` (`Hub/04-Stack/docs/SPECS/`) — §3.6 (Níveis de Maturidade), §5.4 (Fase 4 — decisão de manter CodeRED/DashDescomplicar em N1) - WhatSMS v2 (`okf/SCHEMA.md`) — referência viva do padrão N4 completo (3 tiers automáticos) - CodeRED (`okf/SCHEMA.md`) — mesmo padrão de relacionamentos narrativos, formalizado em paralelo a este ficheiro **OKF Schema DashDescomplicar | v1.0 | 2026-07-07** **Alinhado com `Hub/04-Stack/02.04-Sistemas/90.Conhecimento/OKF/SCHEMA.md` (OKF global) e `QR-OKF-Project-Level.md` (padrão de projecto)**