📐 Convenção de Organização — SAP BTP + Joule Lab

Regra de ouro: esta pasta é a fonte de verdade do projeto.

Tudo que for criado para este projeto (documentos, prints, scripts, código) entra aqui.

---

🗂️ Estrutura padrão

SAP_BTP_Joule_Lab/
├── README.md                    # índice geral + linha do tempo (SEMPRE atualizado)
├── docs/
│   ├── caderno_de_estudos.md    # aulas: conceito → comando → lição aprendida
│   ├── joule_comandos.md        # como usar a Joule (somente comandos!)
│   ├── ai_lab_app.md            # doc do app de exemplo
│   ├── automacao_cdp.md         # doc da automação de navegador
│   ├── organizacao.md           # ESTE arquivo (a convenção)
│   └── sessoes/                 # diário: uma sessão por data
│       └── AAAA-MM-DD_tema.md
├── chats/                       # transcrições dos chats (para agentes)
│   └── AAAA-MM-DD_HH-MM_titulo.md
├── prints/
│   ├── destaques/               # prints-chave com nomes descritivos (NN-descricao.png)
│   ├── 01_btp_cockpit_e_booster/
│   ├── 02_build_code_lobby/
│   ├── 03_dev_space_bas/
│   ├── 04_ide_e_storyboard/
│   ├── 05_joule/
│   └── 06_troubleshooting/
├── automacao/
│   ├── cdp.mjs                  # automação de navegador (CDP)
│   ├── exportar_chat.py         # exporta chats do OpenCode → chats/
│   └── gerar_site.py            # gera ./site (publicado no Coolify)
├── site/                        # site estático gerado (nginx no Coolify)
├── exemplos/                    # código (ex.: exemplos/ai-lab = app CAP + IA)
└── logs/                        # evidências técnicas (deploys, logins, erros)

---

✍️ Como contribuir (regras)

---

🐙 Regra do GITHUB (versionamento oficial)

Repositório: https://github.com/hugomarquesit/sap-btp-joule-lab (privado)

# autenticação já configurada via gh CLI (keyring)
gh auth status                     # confere
ciclo normal de publicação (ao final de cada sessão)
cd ~/Rede/vizionai/02_Business_EdTech_AI/SAP_BTP_Joule_Lab
python3 automacao/gerar_site.py    # se docs/prints mudaram
git add -A && git commit -m "docs: <resumo da sessão>" && git push

• O repositório é privado (contém caminhos internos/infra da VisionAI).

🧼 Checklist ANTES de cada push (sanitização obrigatória)

💡 O exportar_chat.py aplica a sanitização automaticamente na geração do Markdown.

• Estrutura espelhada na pasta local (prints/, docs/, chats/, automacao/, exemplos/, logs/, site/).

---

💬 Regra do CHAT (histórico para agentes)

Toda conversa de chat deste projeto deve ser exportada para chats/.

# exporta a sessão mais recente do OpenCode
python3 automacao/exportar_chat.py
ou uma sessão específica
python3 automacao/exportar_chat.py ses_xxxxxxxx
listar sessões
python3 automacao/exportar_chat.py --list

• O script lê o banco do OpenCode (~/.local/share/opencode/opencode.db), gera um

Markdown legível (usuário + assistente + ferramentas em bloco recolhível)

e salva em chats/AAAA-MM-DD_HH-MM_titulo.md.

• Por quê: qualquer agente (ou pessoa) que abrir o projeto entende o que foi

conversado, decidido e executado — sem depender do histórico local do OpenCode.

---

🚀 Regra do COOLIFY (deploy oficial)

Premissa (pasta 00_Startup_Infrastructure): tudo roda no Coolify v4

(192.168.15.4:8000). Nada de serviço "solto" em localhost.

Exemplo aplicado (site de docs):

API=http://192.168.15.4:8000/api/v1   # token: ver config do MCP do Coolify
1) projeto
curl -s -X POST "$API/projects" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"SAP BTP Joule Lab","description":"Lab SAP BTP + Build Code + Joule"}'
2) aplicação (imagem nginx)
curl -s -X POST "$API/applications/dockerimage" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"project_uuid":"<proj>","server_uuid":"<srv>","environment_name":"production",
       "docker_registry_image_name":"nginx","docker_registry_image_tag":"alpine",
       "name":"sap-joule-lab-docs","ports_exposes":"80"}'
3) domínio + volume + deploy
curl -s -X PATCH "$API/applications/<app>" ... -d '{"domains":"https://sap-lab.visionai.com.br"}'
curl -s -X POST "$API/applications/<app>/storages" ... -d '{"type":"file","is_directory":true,
       "fs_path":"/home/hugo/vizionai/.../site","mount_path":"/usr/share/nginx/html"}'
curl -s -X POST "$API/deploy?uuid=<app>" -H "Authorization: Bearer $TOKEN"

Publicar o site depois de atualizar docs/prints:

python3 automacao/gerar_site.py   # regenera ./site (docs em HTML + galeria)
depois, no Coolify: redeploy da aplicação (ou via API /deploy)

---

📖 Regras de conteúdo

• Toda lição no formato conceito → comando → aprendizado (didático, reutilizável).
• Registrar os erros e as soluções — é o conteúdo mais valioso de um troubleshooting.
• Nunca versionar segredos (senhas, tokens, service keys): usar placeholders.
• Preferir comandos reproduzíveis (CLI/API) em vez de "cliques mágicos".
• Ao usar automação de UI, documentar o motivo e os limites (docs/automacao_cdp.md).

---

🔗 Relacionamento com o resto da VisionAI

• Service line: 02_Business_EdTech_AI (junto de Tcts e outros projetos).
• Este projeto é trial/lab: não usar credenciais corporativas; documentar limites do trial.
• Ao virar produto (ex.: app CAP + IA corporativo), avaliar promoção para nova service line

e atualizar o INDICE.md do ecossistema.