Design Docs com IA

# Contexto para Agentes de IA

## Sobre este projeto
Sistema de pagamentos da empresa X, responsável por processar ~2M transações/dia.
Arquitetura: microserviços em Go (core) e TypeScript (edge/BFF).

## Convenções obrigatórias
- **Nomenclatura**: camelCase em TypeScript, snake_case em Go.
- **Erros**: use o pacote interno `pkg/errors` — NUNCA `errors.New` nativo.
- **Testes**: cobertura mínima 80% em arquivos de domínio. Use table-driven tests em Go.
- **Commits**: Conventional Commits (feat:, fix:, chore:, docs:).

## Arquivos sensíveis (NÃO modificar sem aprovação)
- `internal/crypto/*` — código de criptografia homologado (PCI-DSS)
- `migrations/*` — migrações só podem ser adicionadas, nunca editadas
- `.github/workflows/deploy-prod.yml` — revisão obrigatória do SRE

## Decisões arquiteturais chave
- Mensageria: RabbitMQ (não Kafka) — ver ADR-023 para contexto.
- Database: PostgreSQL 15 com particionamento por merchant_id.
- Cache: Redis Cluster com TTL padrão de 5 minutos.

## Como rodar testes localmente
```bash
make test        # unit tests
make test-int    # integration tests (requer docker-compose up)
make lint        # golangci-lint + eslint
```

## Onde procurar contexto adicional
- `docs/adr/` — Architecture Decision Records
- `docs/runbooks/` — Procedimentos operacionais
- `docs/rfcs/` — Request for Comments em aberto
- `CHANGELOG.md` — Histórico de mudanças

# PRD: Checkout Express (1-click)

**Autor:** Ana Souza (PM)
**Status:** Draft → Review → Approved
**Última atualização:** 2025-02-14

## 1. Problema
Taxa de abandono no checkout atual é de 43% (vs. benchmark do mercado de 28%).
Principais causas (research com 500 usuários em Jan/25):
- 58%: "processo longo demais"
- 31%: "precisei digitar cartão de novo"
- 11%: outros

## 2. Usuário-alvo
Usuários recorrentes (2+ compras nos últimos 90 dias) que já têm ao menos um
meio de pagamento salvo. Volume estimado: 240k usuários ativos.

## 3. Solução proposta (sem implementação!)
Permitir que o usuário conclua a compra em um único clique a partir da página
do produto, pulando o fluxo padrão de checkout.

## 4. Requisitos funcionais
- FR-01: Botão "Comprar em 1-click" visível na página do produto
- FR-02: Modal de confirmação com endereço + pagamento pré-selecionados
- FR-03: Usuário pode alterar endereço/pagamento antes de confirmar
- FR-04: Email de confirmação enviado em até 60s

## 5. Requisitos não-funcionais
- NFR-01: Tempo de resposta do botão < 300ms (p95)
- NFR-02: Disponibilidade de 99.95%
- NFR-03: Conformidade com PCI-DSS (sem armazenar CVV)

## 6. Métricas de sucesso
- **Primária:** redução de 20% no abandono de checkout em 90 dias
- **Secundária:** aumento de 15% no LTV dos usuários ativos
- **Guardrail:** taxa de chargeback não pode aumentar mais de 0.3%

## 7. Fora de escopo
- Suporte a parcelamento customizado (próximo quarter)
- Integração com carteiras digitais (Apple Pay, Google Pay) — RFC separado
- Experiência em tablet (foco inicial: desktop + mobile)

## 8. Riscos
- **R1:** Usuários podem acidentalmente comprar. Mitigação: modal de confirmação.
- **R2:** Fraude pode aumentar. Mitigação: antifraude obrigatório em 1-click.

## 9. Prazo
- Discovery/PRD: concluído
- Design técnico (TRD): até 2025-02-28
- Desenvolvimento: 4 sprints (mar-abr/25)
- Launch: 2025-05-05 (com feature flag para 10% do tráfego)

# ADR-0023: Adoção de RabbitMQ como broker primário

- **Status:** Accepted
- **Data:** 2024-11-07
- **Decisores:** João (Tech Lead), Marina (SRE), Pedro (Arquiteto)
- **Contexto técnico:** Sistema de pagamentos, 2M tx/dia, picos de 10x

## Contexto
Precisamos de um broker de mensageria para desacoplar o serviço de ingestão
do serviço de processamento. Critérios de avaliação:
- Latência < 50ms (p99)
- Suporte a DLQ (Dead Letter Queue) nativo
- Operação por time interno sem SaaS obrigatório
- Maturidade e ecossistema em Go

## Opções consideradas
1. **Apache Kafka** — alto throughput, mas overhead operacional alto
2. **AWS SQS** — managed, mas vendor lock-in e latência maior
3. **RabbitMQ** — protocolo AMQP, DLQ nativo, operação conhecida pelo time
4. **NATS** — leve, mas ecossistema Go menos maduro em 2024

## Decisão
Adotar **RabbitMQ 3.13** como broker primário para mensageria entre serviços.

## Consequências

### Positivas
- Time tem 5+ anos de experiência operando RabbitMQ
- DLQ e retry exponencial nativos reduzem código boilerplate
- Protocolo AMQP permite clientes em qualquer linguagem

### Negativas (aceitas)
- Throughput menor que Kafka (~40k msgs/s vs 200k+) — não é gargalo no volume atual
- Replicação entre DCs mais complexa — mitigado com federation
- Escala vertical primária — planejar sharding se >100k msgs/s

## Revisão
Reavaliar decisão se:
- Volume ultrapassar 80k msgs/s sustentado
- Surgir requisito de event sourcing/replay por >7 dias
- Time perder expertise operacional em RabbitMQ

"""
Gerador automatizado de ADR (Architecture Decision Record) a partir de notas livres.
Uso: python gerar_adr.py --input notas_reuniao.txt --output docs/adr/
"""

import argparse
import os
from datetime import date
from pathlib import Path
from openai import OpenAI

# Cliente OpenAI (define OPENAI_API_KEY no ambiente)
client = OpenAI()

# Template/prompt estruturado — força o formato ADR
ADR_SYSTEM_PROMPT = """
Você é um arquiteto de software sênior especializado em documentação técnica.
Sua tarefa é transformar notas livres de uma reunião em um ADR formal.

Regras obrigatórias:
1. Use EXATAMENTE o formato Markdown abaixo (não adicione seções extras).
2. Se alguma informação estiver ausente, escreva "[A preencher: ...]" — NUNCA invente.
3. Seja conciso: cada seção em no máximo 4-5 linhas.
4. Use voz ativa e tempo presente.
5. O status inicial é sempre "Proposed".

Formato:
# ADR-{id}: {título curto e descritivo}

- **Status:** Proposed
- **Data:** {data_atual}
- **Decisores:** {nomes extraídos}

## Contexto
{Situação que motivou a decisão — 3 a 5 linhas}

## Opções consideradas
1. **{Opção 1}** — {prós e contras em 1 linha}
2. **{Opção 2}** — {prós e contras em 1 linha}
N. ...

## Decisão
{Qual opção foi escolhida e justificativa principal — 2 a 4 linhas}

## Consequências

### Positivas
- {Benefício 1}
- {Benefício 2}

### Negativas (aceitas)
- {Custo 1}
- {Custo 2}
"""

def gerar_adr(notas: str, proximo_id: int) -> str:
    """Gera um ADR formatado a partir de notas brutas."""
    resposta = client.chat.completions.create(
        model="gpt-4o",
        temperature=0.2,  # Baixa para maior consistência no formato
        messages=[
            {"role": "system", "content": ADR_SYSTEM_PROMPT},
            {"role": "user", "content": (
                f"ID do ADR: {proximo_id:04d}\n"
                f"Data atual: {date.today().isoformat()}\n\n"
                f"Notas brutas:\n{notas}"
            )}
        ]
    )
    return resposta.choices[0].message.content

def proximo_id(pasta: Path) -> int:
    """Descobre o próximo número de ADR disponível."""
    pasta.mkdir(parents=True, exist_ok=True)
    existentes = [f.stem.split('-')[0] for f in pasta.glob("*.md")]
    ids = [int(e) for e in existentes if e.isdigit()]
    return max(ids, default=0) + 1

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", required=True, help="Arquivo com as notas")
    parser.add_argument("--output", default="docs/adr/", help="Pasta de destino")
    args = parser.parse_args()

    pasta = Path(args.output)
    notas = Path(args.input).read_text(encoding="utf-8")
    novo_id = proximo_id(pasta)

    print(f"🧠 Gerando ADR-{novo_id:04d} a partir de {args.input}...")
    conteudo = gerar_adr(notas, novo_id)

    # Extrai o título da primeira linha do markdown para o nome do arquivo
    titulo = conteudo.split("\n")[0].replace("#", "").strip()
    slug = "-".join(titulo.lower().split()[2:7])  # pula "ADR-XXXX:"
    slug = "".join(c if c.isalnum() or c == "-" else "" for c in slug)

    arquivo = pasta / f"{novo_id:04d}-{slug}.md"
    arquivo.write_text(conteudo, encoding="utf-8")
    print(f"✅ ADR salvo em {arquivo}")

if __name__ == "__main__":
    main()

"""
Assistente conversacional para documentação técnica.
Indexa docs/**/*.md e responde perguntas citando as fontes.
"""

from pathlib import Path
from openai import OpenAI
from langchain_community.document_loaders import DirectoryLoader, TextLoader
from langchain.text_splitter import MarkdownTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma

client = OpenAI()

# ── 1. Carregamento dos documentos ─────────────────────────────
def carregar_docs(pasta: str = "docs/") -> list:
    """Carrega todos os .md da pasta de documentação."""
    loader = DirectoryLoader(
        pasta,
        glob="**/*.md",
        loader_cls=TextLoader,
        loader_kwargs={"encoding": "utf-8"}
    )
    docs = loader.load()
    print(f"📚 Carregados {len(docs)} documentos.")
    return docs

# ── 2. Chunking semântico ──────────────────────────────────────
def dividir_em_chunks(docs: list) -> list:
    """Quebra os documentos em pedaços que cabem no contexto do modelo."""
    splitter = MarkdownTextSplitter(
        chunk_size=1000,       # ~250 tokens por chunk
        chunk_overlap=150       # overlap preserva contexto entre chunks
    )
    return splitter.split_documents(docs)

# ── 3. Indexação vetorial ──────────────────────────────────────
def construir_indice(chunks: list, pasta_db: str = "./chroma_docs") -> Chroma:
    """Cria o vector store com embeddings dos chunks."""
    embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
    db = Chroma.from_documents(
        chunks,
        embedding=embeddings,
        persist_directory=pasta_db
    )
    print(f"💾 Índice persistido em {pasta_db}")
    return db

# ── 4. Busca + Resposta com citações ───────────────────────────
def responder(pergunta: str, db: Chroma, k: int = 4) -> str:
    """Busca os k chunks mais relevantes e pede ao LLM uma resposta com citações."""
    # Recupera chunks semanticamente similares à pergunta
    resultados = db.similarity_search(pergunta, k=k)

    # Monta o contexto com citações
    contexto = "\n\n".join(
        f"[fonte: {r.metadata.get('source', 'desconhecido')}]\n{r.page_content}"
        for r in resultados
    )

    prompt = f"""Você é um assistente técnico da empresa. Responda à pergunta
usando APENAS o contexto fornecido. Cite as fontes como [fonte: arquivo.md]
ao longo da resposta. Se o contexto não responder a pergunta, diga isso
explicitamente — NUNCA invente informações.

CONTEXTO:
{contexto}

PERGUNTA: {pergunta}

RESPOSTA:"""

    resposta = client.chat.completions.create(
        model="gpt-4o-mini",    # mais barato, suficiente para RAG
        temperature=0.1,
        messages=[{"role": "user", "content": prompt}]
    )
    return resposta.choices[0].message.content

# ── Main ───────────────────────────────────────────────────────
if __name__ == "__main__":
    docs = carregar_docs("docs/")
    chunks = dividir_em_chunks(docs)
    db = construir_indice(chunks)

    # Loop interativo
    print("\n🤖 Assistente de docs pronto. Digite 'sair' para encerrar.\n")
    while True:
        pergunta = input("❓ Pergunta: ").strip()
        if pergunta.lower() in {"sair", "exit", "quit"}:
            break
        print("\n" + responder(pergunta, db) + "\n")

# Detecta drift entre código e documentação a cada Pull Request
name: Docs Drift Check

on:
  pull_request:
    paths:
      - 'src/**'
      - 'docs/**'

jobs:
  drift-check:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write  # para comentar no PR
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # precisamos do histórico para ver o diff

      - name: Gerar diff do PR
        id: diff
        run: |
          git diff origin/${{ github.base_ref }}...HEAD -- src/ > code.diff
          git diff origin/${{ github.base_ref }}...HEAD -- docs/ > docs.diff

      - name: Perguntar à IA se há drift
        id: ai-check
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          python - << 'EOF'
          import os, json
          from openai import OpenAI
          client = OpenAI()

          code_diff = open("code.diff").read()
          docs_diff = open("docs.diff").read()

          if not code_diff.strip():
              print("Sem mudanças em src/, nada a verificar.")
              exit(0)

          prompt = f"""Analise o diff de código abaixo e verifique se a documentação
          foi atualizada adequadamente. Responda em JSON:
          {{
            "drift_detected": true|false,
            "severity": "low|medium|high",
            "affected_docs": ["caminho/arquivo.md", ...],
            "suggested_changes": "texto explicando o que atualizar"
          }}

          CÓDIGO ALTERADO:
          {code_diff[:8000]}

          DOCS ALTERADOS:
          {docs_diff[:4000] or "(nenhum)"}
          """

          resp = client.chat.completions.create(
              model="gpt-4o-mini",
              response_format={"type": "json_object"},
              messages=[{"role": "user", "content": prompt}]
          )
          result = json.loads(resp.choices[0].message.content)

          with open("drift_result.json", "w") as f:
              json.dump(result, f)

          if result["drift_detected"]:
              print(f"::warning::Drift detectado: {result['severity']}")
          EOF

      - name: Comentar no PR se houver drift
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            if (!fs.existsSync('drift_result.json')) return;
            const r = JSON.parse(fs.readFileSync('drift_result.json', 'utf8'));
            if (!r.drift_detected) return;

            const body = `### 📚 Docs Drift Detectado (${r.severity})

            **Documentos afetados:** ${r.affected_docs.join(', ')}

            **Sugestão:**
            ${r.suggested_changes}

            _Este comentário foi gerado automaticamente pelo workflow \`docs-drift\`._`;

            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body
            });