docs(okf): formaliza SCHEMA.md — Nível N1, relacionamentos narrativos válidos
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).
This commit is contained in:
+182
@@ -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: `<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)
|
||||
|
||||
```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)**
|
||||
Reference in New Issue
Block a user