From 0e8a1f04ce805b070d28550e394db7cb9a79b083 Mon Sep 17 00:00:00 2001 From: Emanuel Almeida Date: Tue, 7 Jul 2026 21:20:02 +0100 Subject: [PATCH] =?UTF-8?q?docs(okf):=20formaliza=20SCHEMA.md=20=E2=80=94?= =?UTF-8?q?=20N=C3=ADvel=20N1,=20relacionamentos=20narrativos=20v=C3=A1lid?= =?UTF-8?q?os?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documenta explicitamente o padrão já em uso em okf/entidades/ e okf/relacionamentos/*.md (Tier 1 curado + Tier 3 narrativo). Declara Nível de Maturidade N1 com justificação — sem inventory/ automático nem relations.jsonl, apesar do volume de código (75 ficheiros .ts/.tsx) exceder o limiar literal de N2, por falta de infraestrutura de geração. Decisão de não migrar relacionamentos/*.md para relations.jsonl (SPEC-OKF-Projeto-Sistema-Excelencia.md §3.6/§5.4) — custo de automação não compensa a escala actual (21 arestas). Fase 4 do PLAN-OKF-Projeto-Sistema-Excelencia.md (Hub). --- okf/SCHEMA.md | 182 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 okf/SCHEMA.md diff --git a/okf/SCHEMA.md b/okf/SCHEMA.md new file mode 100644 index 0000000..9a605c0 --- /dev/null +++ b/okf/SCHEMA.md @@ -0,0 +1,182 @@ +--- +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)**