Dependências entre Documentos¶
Grafo de Dependências¶
service.yaml
├── referencia → openapi.yaml
├── referencia → SLA document
└── referencia → SRC-BR-xxx, DATA-BR-xxx
openapi.yaml
├── depende → DATA-BR-xxx (schemas)
└── define → EP-BR-xxx (endpoints)
DATA-BR-xxx
├── depende → SRC-BR-xxx (origem)
├── contem → FIELD-BR-xxx
└── processado_por → PIPE-BR-xxx
SLA document
├── define → SLO values
├── referencia → SVC-BR-xxx
└── depende → SLI measurements
INC-YYYY-XXXX
└── pode_gerar → CHG-YYYY-XXXX
└── pode_gerar → REL-YYYY-XXXX
Diagrama de Dependências¶
graph TD
SRC["SRC-BR-xxx<br/>(fonte de dados)"]
PIPE["PIPE-BR-xxx<br/>(pipeline)"]
DATA["DATA-BR-xxx<br/>(dataset)"]
FIELD["FIELD-BR-xxx<br/>(campos)"]
OAS["openapi.yaml"]
SVC["service.yaml<br/>(Service Master Record)"]
SLA["SLA document"]
SLO["SLO / SLI"]
INC["INC-YYYY-XXXX<br/>(incidente)"]
CHG["CHG-YYYY-XXXX<br/>(mudança)"]
REL["REL-YYYY-XXXX<br/>(release)"]
SRC --> PIPE
PIPE --> DATA
DATA --> FIELD
DATA --> OAS
OAS --> SVC
SLA --> SVC
SLA --> SLO
INC -->|pode gerar| CHG
CHG -->|pode gerar| REL
Ordem de Criação Recomendada¶
| # | Artefato | Motivo |
|---|---|---|
| 1 | Estrutura da Organization (GitHub) | Tudo parte daqui |
| 2 | Templates (api-template) |
Base para os repositórios seguintes |
| 3 | ADR-0001 |
Documentar a decisão de arquitetura antes de implementar |
| 4 | LICENSE |
Escolher antes de publicar qualquer código |
| 5 | SRC-BR-xxx (sources) |
Dados primeiro — identificar origem antes de modelar |
| 6 | DATA-BR-xxx (datasets) |
Definir dados antes de codificar endpoints |
| 7 | openapi.yaml |
Spec first — o contrato precede a implementação |
| 8 | service.yaml |
Service Master Record referencia a spec e os dados |
| 9 | README.md |
Para o usuário externo — depois de ter algo a dizer |
| 10 | SECURITY.md |
Antes de publicar qualquer coisa |
| 11 | POL-SEC-001 |
Política mínima de segurança |
| 12 | POL-ACC-001 |
Controle de acesso desde o início |
Princípio: Dados e Contratos Antes do Código
Definir fontes de dados e especificação OpenAPI antes de escrever código.
Código pode ser refatorado sem impacto externo.
A spec e os contratos de dados são o acordo público — mudá-los tem custo para os consumidores.
Relações entre Políticas¶
graph LR
POL_SEC["POL-SEC-001<br/>Segurança"]
POL_ACC["POL-ACC-001<br/>Acesso"]
POL_DEV["POL-DEV-001<br/>Dev Seguro"]
POL_CHG["POL-CHG-001<br/>Mudanças"]
POL_INC["POL-INC-001<br/>Incidentes"]
POL_BAK["POL-BAK-001<br/>Backup"]
POL_SEC --> POL_ACC
POL_SEC --> POL_DEV
POL_CHG --> POL_INC
POL_BAK --> POL_INC
POL-SEC-001 é a política-raiz. Todas as outras políticas de segurança derivam dela ou a referenciam.
Como Registrar Dependências nos Arquivos YAML¶
Para que a navegação Customer → Source funcione, todo arquivo deve referenciar seus vizinhos:
# service.yaml
service:
id: SVC-BR-001
api: API-BR-001
sla: SLA-BR-001
data:
datasets: [DATA-BR-001]
sources: [SRC-BR-001]
# dataset.yaml
dataset:
id: DATA-BR-001
source: SRC-BR-001
exposed_by: API-BR-001
transformed_by: PIPE-BR-001
# source record
source:
id: SRC-BR-001
name: IBGE — Malha Municipal
used_by: [DATA-BR-001]
Próximo passo¶
Com as dependências mapeadas, consulte o Quickstart — Dia 1 para as instruções operacionais de execução.