DashDescomplicar/okf/SCHEMA.md

type, layer, title, description, tags, timestamp, status

type	layer	title	description	tags	timestamp	status
Schema	okf	OKF Schema — DashDescomplicar	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).	dashdescomplicar okf schema governanca convencoes	2026-07-07	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: <Origem>-<verbo>-<Destino>.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)

---
type: Entity
layer: wiki
tags: [stack, dashdescomplicar, tag2, tag3]
title: "Nome-Da-Entidade"
---

Relacionamento (Tier 3 narrativo)

---
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)