> 🇧🇷 Tradução em Português. [English version](../../guides/config-migration-guide.md)

# Guia de Migração de Configuração

Migre do `core-config.yaml` monolítico para a hierarquia de configuração em camadas.

**ADR:** [ADR-PRO-002 — Hierarquia de Configuração](../architecture/adr/adr-pro-002-configuration-hierarchy.md)
**Story:** PRO-4 — Implementação do Core-Config Split

---

## Visão Geral

O LMAS v3.12+ introduz uma hierarquia de configuração em 4 níveis que substitui o arquivo único `core-config.yaml`:

| Nível | Arquivo | Status no Git | Propósito |
|-------|---------|---------------|-----------|
| **L1** Framework | `framework-config.yaml` | Commitado (somente leitura) | Padrões do framework, localização de recursos |
| **L2** Projeto | `project-config.yaml` | Commitado | Metadados do projeto, integrações, squads |
| **Pro** Extensão | `pro/pro-config.yaml` | Submódulo | Funcionalidades premium (lmas-pro) |
| **L3** App | `apps/<name>/lmas-app.config.yaml` | Commitado | Sobrescritas por app |
| **L4** Local | `local-config.yaml` | Gitignored | IDE, MCP, secrets, específico da máquina |

Ordem de resolução: L1 → L2 → Pro → L3 → L4 (último vence para escalares, deep merge para objetos).

---

## Migração Rápida

### Automática (Recomendada)

```bash
# Pré-visualizar o que vai acontecer
lmas config migrate --dry-run

# Executar migração
lmas config migrate

# Verificar
lmas config validate
lmas config show --debug
```

### Manual

1. Copie o template para configuração local:
   ```bash
   lmas config init-local
   ```

2. As configurações de framework e projeto já estão no lugar. Edite `project-config.yaml` para valores específicos do projeto.

3. Edite `local-config.yaml` para configurações específicas da máquina (IDE, MCP, secrets).

---

## Estratégia de Merge

| Tipo | Comportamento | Exemplo |
|------|---------------|---------|
| **Escalares** | Último vence | L2 `timeout: 30` sobrescreve L1 `timeout: 10` |
| **Objetos** | Deep merge | L2 adiciona chaves aos objetos de L1 |
| **Arrays** | Substituição | Array de L2 substitui array de L1 inteiramente |
| **+append** | Concatenação | `+append: [new]` concatena ao array pai |
| **null** | Deletar chave | `key: null` remove a chave do resultado mergeado |

---

## Qual Arquivo Editar?

| Configuração | Nível | Arquivo |
|--------------|-------|---------|
| Nome e descrição do projeto | L2 | `project-config.yaml` |
| Integração com GitHub | L2 | `project-config.yaml` |
| Configuração do CodeRabbit (não-secret) | L2 | `project-config.yaml` |
| Secrets/comandos do CodeRabbit | L4 | `local-config.yaml` |
| Seleção de IDE | L4 | `local-config.yaml` |
| Configuração de MCP | L4 | `local-config.yaml` |
| Definições de squad | L2 | `project-config.yaml` |
| Sobrescritas de performance | L4 | `local-config.yaml` |
| Localização de recursos do framework | L1 | `framework-config.yaml` (não editar) |
| Padrões de performance do framework | L1 | `framework-config.yaml` (não editar) |

---

## Variáveis de Ambiente

Apenas `local-config.yaml` (L4) deve conter referências `${ENV_VAR}`:

```yaml
# local-config.yaml
mcp:
  docker_mcp:
    gateway:
      url: "${MCP_GATEWAY_URL:-http://localhost:8080/mcp}"
```

Se padrões `${...}` forem encontrados em L1 ou L2, `lmas config validate` emitirá um aviso — esses arquivos são commitados no git e não devem conter valores específicos de ambiente.

---

## Compatibilidade Retroativa

O `core-config.yaml` monolítico continua funcionando. Se ele existir e nenhum `framework-config.yaml` for encontrado, o sistema carrega automaticamente em **modo legado**.

### Cronograma de Depreciação

| Versão | Comportamento |
|--------|---------------|
| **v3.12.0** | Configuração em camadas disponível, monolítico ainda suportado |
| **v3.13.0** | Avisos de depreciação quando modo legado detectado |
| **v4.0.0** | Suporte ao monolítico removido |

Para suprimir avisos de depreciação: `LMAS_SUPPRESS_DEPRECATION=1`

---

## Solução de Problemas

### Configuração não carrega após migração

```bash
# Verificar qual modo está ativo
lmas config show --debug
# Procure por "[Legacy]" vs "[L1]", "[L2]", "[L4]" nas anotações
```

### Valores não aparecem na configuração resolvida

```bash
# Comparar níveis para encontrar onde um valor está definido
lmas config diff --levels L1,L2

# Verificar um nível específico
lmas config show --level L2
```

### Erros de sintaxe YAML

```bash
# Validar todos os níveis
lmas config validate

# Validar nível específico
lmas config validate --level L4
```

### Configuração local não funciona

1. Verifique que `local-config.yaml` existe (não apenas o template):
   ```bash
   lmas config init-local
   ```
2. Verifique que não foi commitado acidentalmente — deve estar no `.gitignore`.

### Variáveis de ambiente não resolvidas

- Apenas L4 (local-config.yaml) suporta interpolação `${ENV_VAR}`.
- Verifique se a variável está definida: `echo $ENV_VAR` / `echo %ENV_VAR%`
- Use a sintaxe `${ENV_VAR:-default}` para variáveis opcionais.

---

## Referência de CLI

| Comando | Descrição |
|---------|-----------|
| `lmas config show` | Mostrar configuração totalmente resolvida |
| `lmas config show --level L2` | Mostrar nível individual (bruto, sem merge) |
| `lmas config show --debug` | Mostrar com anotações de origem por valor |
| `lmas config diff --levels L1,L2` | Comparar dois níveis |
| `lmas config migrate` | Migrar do monolítico para camadas |
| `lmas config migrate --dry-run` | Pré-visualizar migração sem alterações |
| `lmas config validate` | Validar sintaxe YAML e padrões |
| `lmas config init-local` | Criar local-config.yaml a partir do template |

---

## Perguntas Frequentes

**P: Preciso deletar o `core-config.yaml` após a migração?**
R: Não. Mantenha como backup. O sistema detecta o modo em camadas pela presença do `framework-config.yaml`. O comando de migração preserva o arquivo como `core-config.yaml.backup`.

**P: Membros da equipe podem usar IDEs diferentes?**
R: Sim. A seleção de IDE fica em L4 (local-config.yaml), que é gitignored. Cada desenvolvedor configura o seu.

**P: E se eu precisar de uma configuração que não se encaixa em nenhum nível?**
R: Use L2 (project-config.yaml) para configurações compartilhadas, L4 (local-config.yaml) para configurações pessoais/secretas.

**P: Como funciona a configuração do lmas-pro?**
R: A configuração Pro (`pro/pro-config.yaml`) faz merge entre L2 e L3. Quando o submódulo `pro/` está ausente, a resolução pula silenciosamente.

---

*Story PRO-4 | ADR-PRO-002 | CLI First*