Extra Documentação Técnica com Markdown • Trilha Progressiva em 4 Níveis

🎯 Nível 1: Fundamentos

Problema 8.1 — Diagrama de Contexto de Sistema (C4 Nível 1) em Mermaid

Contexto: Construir um diagrama de contexto C4 modelando a interação de um Cliente Bancário com o Sistema de Internet Banking e dois sistemas externos (Mainframe Legado e Gateway de E-mails).

Requisitos de Execução:

  1. Declarar C4Context.
  2. Adicionar o ator Person(cliente, "Cliente do Banco", "Correntista da instituição").
  3. Adicionar o sistema de fronteira System(banking, "Internet Banking", "Permite transferências e consultas").
  4. Conectar os elementos usando Rel(...).

Resultado Esperado

```mermaid
C4Context
    title Diagrama de Contexto do Sistema Bancário
    Person(cliente, "Cliente do Banco", "Correntista da instituição")
    System(banking, "Internet Banking", "Permite transferências e consultas")
    System_Ext(email, "Gateway de E-mail", "Serviço externo de envio de notificações")

    Rel(cliente, banking, "Utiliza", "HTTPS")
    Rel(banking, email, "Dispara avisos através de", "SMTP")
```

📤 Instruções de Entrega (Microsoft Teams)

  1. Salve o arquivo como: Atividade_08_1_SeuNome.md
  2. Envie na tarefa: Atividade Cap 08 - Modelo C4 e Arquitetura como Código
🔑 Gabarito de Código & Solução Comentada 
```mermaid
C4Context
    title Diagrama de Contexto do Sistema Bancário
    Person(cliente, "Cliente do Banco", "Correntista da instituição")
    System(banking, "Internet Banking", "Permite transferências e consultas")
    System_Ext(email, "Gateway de E-mail", "Serviço externo de envio de notificações")

    Rel(cliente, banking, "Utiliza", "HTTPS")
    Rel(banking, email, "Dispara avisos através de", "SMTP")
```

Comentário: O Nível 1 (Contexto) do Modelo C4 oculta detalhes de tecnologia internos para comunicar o escopo global a stakeholders técnicos e de negócio.

🎯 Nível 2: Prática

Problema 8.2 — Diagrama de Containers C4 (Nível 2) de uma Aplicação Web

Crie um diagrama de containers C4Container detalhando a aplicação: Single Page Application (React), API Gateway (Go), Microsserviço de Contas (Java/Spring) e Banco de Dados (PostgreSQL).

🔑 Gabarito de Código & Solução Comentada 
```mermaid
C4Container
    title Diagrama de Containers da Plataforma de Pagamentos
    Person(user, "Usuário Final")
    Container(spa, "Single-Page App", "React, TypeScript", "Interface no navegador")
    Container(api, "API Gateway", "Go, Gin", "Roteamento e Autenticação JWT")
    Container(db, "Banco de Dados", "PostgreSQL", "Armazenamento relacional ACID")

    Rel(user, spa, "Acessa", "HTTPS")
    Rel(spa, api, "Faz chamadas de API", "JSON/HTTPS")
    Rel(api, db, "Lê e grava dados", "TCP/SSL")
```

🎯 Nível 3: Integração

Problema 8.3 — Arquitetura Declarativa com a DSL D2

Escreva um arquivo de especificação arquitetural utilizando a sintaxe da moderna DSL D2 (declarative diagramming) modelando uma esteira de mensageria com Apache Kafka.

🔑 Gabarito de Código & Solução Comentada 
# arquitetura_mensageria.d2
produtor: Produtor de Eventos {
  shape: rectangle
  style.fill: "#e1f5fe"
}

kafka: Cluster Apache Kafka {
  topico_pedidos: Tópico 'pedidos-criados'
  topico_pagamentos: Tópico 'pagamentos-aprovados'
}

consumidor: Microsserviço de Faturamento {
  shape: rectangle
  style.fill: "#e8f5e9"
}

produtor -> kafka.topico_pedidos: Publica evento de checkout
kafka.topico_pedidos -> consumidor: Consome para emitir nota

🎯 Nível 4: Desafio

Problema 8.4 — Pipeline de CI para Validação de Diagramas com Mermaid CLI (mmdc)

Construa uma configuração de GitHub Actions que examine arquivos .md alterados em um Pull Request e execute o compilador mermaid-cli (@mermaid-js/mermaid-cli) em modo headless para barrar PRs com diagramas sintaticamente inválidos.

🔑 Gabarito de Código & Solução Comentada 
# .github/workflows/valida_diagramas.yml
name: Validação de Diagramas Mermaid
on: [pull_request]

jobs:
  check-mermaid:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Instalar Mermaid CLI
        run: npm install -g @mermaid-js/mermaid-cli
      - name: Validar Sintaxe dos Arquivos Markdown
        run: |
          for f in $(find . -name "*.md"); do
            echo "Checando integridade de diagramas em: $f"
            # O mmdc falhará o exit code caso o parsing falhe
            mmdc -i "$f" -o /tmp/check.png --puppeteerConfigFile .puppeteer.json || exit 1
          done