# Convenções de Nomenclatura — Mud Sentinel

**Documento:** `engenharia/02-convencoes-de-nomenclatura.md`  
**Versão:** 1.0.0  
**Status:** Vigente

---

## 1. Idioma

| Superfície | Idioma | Justificativa |
|------------|--------|---------------|
| Código (tipos, funções, módulos) | Inglês | Padrão de indústria, libs, hiring |
| Documentação de produto / UI primária | Português (Brasil) | Público-alvo inicial |
| Commits / PRs | Inglês ou PT-BR consistente por time; preferir inglês técnico curto | Padronizar no onboarding |
| Eventos / atributos de telemetria | Inglês `snake_case` | Ferramentas de observabilidade |

---

## 2. Código

### Python

| Elemento | Convenção | Exemplo |
|----------|-----------|---------|
| Pacotes/módulos | `snake_case` | `case_export` |
| Classes | `PascalCase` | `CaseExporter` |
| Funções/métodos | `snake_case` | `finalize_case` |
| Constantes | `UPPER_SNAKE` | `MAX_GRAPH_DEPTH` |
| Privados | prefixo `_` | `_validate_state` |

### TypeScript

| Elemento | Convenção | Exemplo |
|----------|-----------|---------|
| Arquivos componentes | `PascalCase.tsx` | `EntityGraph.tsx` |
| Hooks / utils | `camelCase.ts` | `useCaseFilters.ts` |
| Tipos/Interfaces | `PascalCase` | `CaseSummary` |
| Constantes | `UPPER_SNAKE` ou `camelCase` export const | preferir `UPPER_SNAKE` para verdadeiras constantes |

---

## 3. Bounded contexts e packages

- Nome curto, estável: `catalog`, `graph`, `cases`, `ai`.
- Evitar nomes vagos: `manager`, `common`, `util` como dumping ground.
- Shared kernel: `shared_kernel` (não `core` ambíguo).

---

## 4. APIs HTTP

| Elemento | Convenção | Exemplo |
|----------|-----------|---------|
| Recursos | substantivos plurais, kebab se multiword | `/api/v1/cases`, `/api/v1/ingest-runs` |
| Path params | `snake` ou `camel` — **escolher um** e padronizar | preferir `case_id` em query; `{caseId}` aceitável em path se consistente TS |
| Query params | `snake_case` | `?tenant_id=` interno nunca; tenant vem do token |
| Headers custom | `X-Mud-` prefix raro; preferir padrões (`Idempotency-Key`, `Authorization`) | |
| Campos JSON | `snake_case` na API pública | alinhado a Python; documentar no OpenAPI |

**Decisão API JSON:** `snake_case` (ADR-005). Frontend mapeia para `camelCase` se necessário na UI.

---

## 5. Banco de dados

| Elemento | Convenção | Exemplo |
|----------|-----------|---------|
| Tabelas | `snake_case` plural | `cases`, `case_events` |
| Colunas | `snake_case` | `created_at` |
| PK | `id` (UUID) | |
| FK | `<ref>_id` | `tenant_id` |
| Índices | `ix_<table>_<cols>` | `ix_cases_tenant_id_status` |
| Unique | `uq_<table>_<cols>` | |
| Check | `ck_<table>_<name>` | |

Tabelas prefixadas por contexto quando houver risco de colisão: `risk_rules`, `graph_edges`.

---

## 6. Eventos

Formato:

```text
<context>.<entity>.<past_tense_verb>.v<version>
```

Exemplos:

- `cases.case.finalized.v1`
- `ingestion.ingest_run.published.v1`
- `ai.completion.generated.v1`

Consumers/queues: `q.<context>.<purpose>` (ex.: `q.search.index_entity`).

---

## 7. Logs e métricas

| Elemento | Convenção |
|----------|-----------|
| Campos de log | `snake_case` |
| Métricas Prometheus | `mud_<subsystem>_<metric>_<unit>` | `mud_ingest_lag_seconds` |
| Labels | baixa cardinalidade (`tenant_plan`, não `tenant_id` em Prometheus hot path se explosivo) |

---

## 8. Features flags

`ff_<area>_<nome>` — ex.: `ff_graph_path_finding`.

Entitlements: `ent_<capability>` — ex.: `ent_api_access`.

---

## 9. Branches e artifacts

- Branches: `feat/cases-export-manifest`, `fix/tenancy-isolation-query`.
- Tags de release: `vMAJOR.MINOR.PATCH`.
- Imagens Docker: `mudsentinel/<app>:<gitsha>` e `:vX.Y.Z` em release.

---

## 10. Proibições

- Nomes em português no código (`finalizarCaso`).
- Abreviações obscuras (`mgr`, `ctxproc2`).
- `tmp`, `new`, `old`, `final2` em main.
- IDs sequenciais expostos em API pública multi-tenant (preferir UUID/ULID).