diff --git a/DOCUMENTACAO/README b/DOCUMENTACAO/README index 655cb65..4ab42c0 100644 --- a/DOCUMENTACAO/README +++ b/DOCUMENTACAO/README @@ -30,16 +30,17 @@ No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regr | :--- | :--- | :--- | :--- | :--- | | **1. Código-Fonte** | `.ts`, `.vue`, `.js` | JSDoc + comentários inline | Desenvolvedores / IA | Comentários claros e coerentes quanto à aplicação prática e contexto de negócio. | | **2. Ajuda na Tela (UI)** | `*-front/.../{componente}.ajuda.md` | Markdown co-localizado | Usuários da UI | Para `modalX.vue`, o arquivo **DEVE** ser `modalX.ajuda.md`. Explica objetivo, botões, campos e instruções de uso. | -| **3. Wiki do Usuário** | `/../wiki//` | Markdown (VitePress) | Usuários / Clientes | Aplicação VitePress voltada ao acesso dos usuários. Manuais operacionais, tutoriais de uso, conceitos de negócio e fluxos da aplicação. | -| **4. Wiki de Desenvolvimento** | `/../wiki/dev//` | Markdown (VitePress) | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), filas BullMQ, CRONs e ADRs. | +| **3. Wiki do Usuário** | `//` | Markdown (VitePress) | Usuários / Clientes | Aplicação VitePress voltada ao acesso dos usuários. Manuais operacionais, tutoriais de uso, conceitos de negócio e fluxos da aplicação. Arquivos e mídias pesadas no MinIO Paiol. | +| **4. Wiki de Desenvolvimento** | `/dev//` | Markdown (VitePress) | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), filas BullMQ, CRONs e ADRs. | | **5. Integração de IA** | Rota Backend `/llm.md` | Markdown dinâmico | Agentes de IA / LLMs | Catálogo vivo de schemas Zod, enums canônicos e contratos de API para consumo por LLMs. | -| **6. Memória das Ações da IA e Identidade** | `/memorias-ia/` | YAML / Markdown | Agentes de IA / Auditoria | Arquivo mandatório `modulo.yml` (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`), índice central `historico-acoes.md` (`Data \| Memória / Ação \| Arquivo Memoria \| Citações no Código-Fonte`) e arquivos dedicados de sessão `sessao-AAAA-MM-DD-slug.md`. | +| **6. Memória das Ações da IA e Identidade** | `/memorias-ia/` | YAML / Markdown | Agentes de IA / Auditoria | Arquivo mandatório `modulo.yml` (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`, `modulo-acesso`, `modulo-wiki`), índice central `historico-acoes.md` (`Data \| Memória / Ação \| Arquivo Memoria \| Citações no Código-Fonte`) e arquivos dedicados de sessão `sessao-AAAA-MM-DD-slug.md`. | -> ℹ️ **Arquitetura VitePress (`/../wiki`) e Identidade do Projeto**: -> - `/../wiki/` é uma aplicação **VitePress**. -> - `/../wiki//` representa a documentação de **acesso dos usuários e operadores** (onde `` provém de `memorias-ia/modulo.yml`). -> - `/../wiki/dev//` representa a documentação de **acesso interno pela equipe de desenvolvimento e arquitetura**. -> - O arquivo `/memorias-ia/modulo.yml` é **obrigatório em todos os projetos** e define `modulo-id`, `modulo-caminho`, `modulo-descricao` e `modulo-tipo`. +> ℹ️ **Arquitetura VitePress (``, padrão: `/../wiki`) e Identidade do Projeto**: +> - `` é uma aplicação **VitePress** cujo caminho é definido em `memorias-ia/modulo.yml` (fallback padrão: `../wiki/`). +> - `//` representa a documentação de **acesso dos usuários e operadores** (onde `` provém de `memorias-ia/modulo.yml`). +> - `/dev//` representa a documentação de **acesso interno pela equipe de desenvolvimento e arquitetura**. +> - O arquivo `/memorias-ia/modulo.yml` é **obrigatório em todos os projetos**. +> - **Mídias e Arquivos no MinIO Paiol:** Imagens, manuais em PDF, gravações em vídeo e anexos pesados **NUNCA** devem ser commitados no Git da Wiki; devem ser enviados ao MinIO Paiol via `./.agent/scripts/upload-paiol-wiki.sh` e referenciados via URLs `https://paiol.idz.one/wiki/...`. --- diff --git a/DOCUMENTACAO/templates/modulo-dominio.md.template b/DOCUMENTACAO/templates/modulo-dominio.md.template index 7e45433..b131726 100644 --- a/DOCUMENTACAO/templates/modulo-dominio.md.template +++ b/DOCUMENTACAO/templates/modulo-dominio.md.template @@ -56,3 +56,14 @@ VARIÁVEIS A PREENCHER: ## Vocabulário de Interface (Linguagem Ubíqua) - ``: `` + +--- + +## Manuais, Diagramas e Anexos (MinIO Paiol) + +- [Manual Operacional (PDF)](https://paiol.idz.one/wiki//manual-.pdf) + diff --git a/TOOLS b/TOOLS index 2cb09be..80ae427 100644 --- a/TOOLS +++ b/TOOLS @@ -109,6 +109,11 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot - **Por que ajuda as IAs e Operadores:** Permite que comandos de longa duração (como `/plano.executar todos` e loops `/goal`) avisem o operador imediatamente no momento da conclusão, emitindo popup no desktop (KDE `kdialog`, FreeDesktop `notify-send` / `gdbus`, macOS Notification Center via `osascript`), som de alerta discreto (PipeWire, PulseAudio ou macOS `afplay`) e campainha no terminal (`\a`). Totalmente assíncrono, não-bloqueante e seguro para ambientes headless. - **Uso:** `sh .agent/notificar.sh "" "" [sucesso|aviso|erro]` +### upload-paiol-wiki.sh (`.agent/scripts/upload-paiol-wiki.sh`) +- **Descrição:** Utilitário de linha de comando para upload de arquivos e mídias da Wiki para o bucket público `wiki` no MinIO Paiol (`https://paiol.idz.one/wiki/...`). +- **Por que ajuda as IAs e Operadores:** Previne o inchaço (*bloat*) do Git da Wiki desacoplando binários pesados (PDFs, imagens em alta resolução, vídeos, capturas de tela e anexos), gerando links e snippets Markdown prontos para inclusão imediata na documentação. +- **Uso:** `sh .agent/scripts/upload-paiol-wiki.sh [modulo-override]` + --- ## 8. Instalação Rápida (Copia e Cola) diff --git a/TOOLS.md b/TOOLS.md index fd21b8e..80ae427 100644 --- a/TOOLS.md +++ b/TOOLS.md @@ -102,7 +102,21 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot --- -## 7. Instalação Rápida (Copia e Cola) +## 7. Utilitários Nativos do Framework .agent + +### notificar.sh (`.agent/notificar.sh`) +- **Descrição:** Utilitário unificado de notificação para o Sistema Operacional, compatível nativamente com **Linux** e **macOS**. +- **Por que ajuda as IAs e Operadores:** Permite que comandos de longa duração (como `/plano.executar todos` e loops `/goal`) avisem o operador imediatamente no momento da conclusão, emitindo popup no desktop (KDE `kdialog`, FreeDesktop `notify-send` / `gdbus`, macOS Notification Center via `osascript`), som de alerta discreto (PipeWire, PulseAudio ou macOS `afplay`) e campainha no terminal (`\a`). Totalmente assíncrono, não-bloqueante e seguro para ambientes headless. +- **Uso:** `sh .agent/notificar.sh "" "" [sucesso|aviso|erro]` + +### upload-paiol-wiki.sh (`.agent/scripts/upload-paiol-wiki.sh`) +- **Descrição:** Utilitário de linha de comando para upload de arquivos e mídias da Wiki para o bucket público `wiki` no MinIO Paiol (`https://paiol.idz.one/wiki/...`). +- **Por que ajuda as IAs e Operadores:** Previne o inchaço (*bloat*) do Git da Wiki desacoplando binários pesados (PDFs, imagens em alta resolução, vídeos, capturas de tela e anexos), gerando links e snippets Markdown prontos para inclusão imediata na documentação. +- **Uso:** `sh .agent/scripts/upload-paiol-wiki.sh [modulo-override]` + +--- + +## 8. Instalação Rápida (Copia e Cola) Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm`, `bun` e `snap` já configurados). diff --git a/global/rules/ddd-documentacao-primeiro.md b/global/rules/ddd-documentacao-primeiro.md index f6fefa6..cb1816f 100644 --- a/global/rules/ddd-documentacao-primeiro.md +++ b/global/rules/ddd-documentacao-primeiro.md @@ -44,6 +44,31 @@ Todo desenvolvimento e manutenção no ecossistema deve obrigatoriamente respeit --- +## Armazenamento de Arquivos e Mídias da Wiki no MinIO Paiol + +Para evitar o inchaço (*bloat*) irreversível do repositório Git da Wiki (``), **arquivos binários e mídias pesadas** (manuais em PDF, imagens em alta resolução, fluxogramas, diagramas, gravações em vídeo e anexos) **NUNCA** devem ser commitados no Git da Wiki. + +### Protocolo de Envio e Nomenclatura: +- **Destino:** Bucket público `wiki` no MinIO Paiol: + ``` + https://paiol.idz.one/wiki/{modulo}/{funcionalidade/pagina}-{aleatorio}.{ext} + ``` + Onde `{modulo}` é extraído de `modulo-id` em `memorias-ia/modulo.yml` e `{aleatorio}` é um sufixo alfanumérico curto (8 caracteres) para renovação de cache e prevenção de colisão. +- **Envio via Utilitário CLI (Recomendado):** + ```bash + ./.agent/scripts/upload-paiol-wiki.sh + ``` +- **Envio Direto via cURL:** + ```bash + curl -X PUT --upload-file ./manual.pdf https://paiol.idz.one/wiki/{modulo}/{funcionalidade/pagina}-{aleatorio}.pdf + ``` +- **Referência nos Markdowns da Wiki:** + Nos arquivos `.md` da Wiki, utilize exclusivamente as URLs públicas geradas: + - Para imagens: `![Descrição](https://paiol.idz.one/wiki/{modulo}/{slug}-{aleatorio}.png)` + - Para manuais/documentos: `[Baixar Manual (PDF)](https://paiol.idz.one/wiki/{modulo}/{slug}-{aleatorio}.pdf)` + +--- + ## Protocolo DDD Para toda nova demanda, módulo ou funcionalidade, execute os passos abaixo: diff --git a/global/rules/proibido-commit-ia.md b/global/rules/proibido-commit-ia.md index 3007af7..7198f93 100644 --- a/global/rules/proibido-commit-ia.md +++ b/global/rules/proibido-commit-ia.md @@ -71,6 +71,15 @@ Na Wiki (caminho resolvido dinamicamente via `modulo-wiki` em `memorias-ia/modul - Havendo conflitos de merge, a IA resolve as marcações diretamente na `master`, preservando a coerência da documentação dos 6 pilares. - Adiciona os arquivos resolvidos (`git -C add -A`), finaliza o rebase (`git -C rebase --continue` ou commit) e envia com `git push origin master`. +3. **Proibição de Binários Pesados no Git da Wiki (Usar MinIO Paiol)**: + - É expressamente proibido versionar no Git da Wiki arquivos binários ou mídias pesadas (manuais em `.pdf`, vídeos `.mp4`/`.webm`, imagens pesadas, pacotes `.zip`). + - Todo arquivo estático da Wiki DEVE ser enviado ao MinIO Paiol: + ```bash + ./.agent/scripts/upload-paiol-wiki.sh + ``` + ou via `curl -X PUT --upload-file ... https://paiol.idz.one/wiki/{modulo}/{slug}-{aleatorio}.{ext}`. + - Apenas o arquivo Markdown contendo a URL pública gerada deve ser commitado no repositório. + --- ## Exemplos diff --git a/global/skills/documentacao/SKILL.md b/global/skills/documentacao/SKILL.md index 7b3f640..096f28a 100644 --- a/global/skills/documentacao/SKILL.md +++ b/global/skills/documentacao/SKILL.md @@ -65,6 +65,9 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza # Criar um ADR na Wiki Dev + commit/push na wiki /documentacao adr "" + +# Upload de arquivo/mídia (PDF, imagem, vídeo) para o MinIO Paiol com link pronto para a Wiki +/documentacao upload ``` *Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`/../wiki`) deve finalizar executando `git add`, `git commit`, `git pull --rebase` (resolvendo conflitos na master se houver) e `git push` diretamente na branch `master` dentro de `../wiki`. @@ -78,3 +81,4 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza 3. **JSDoc de Aplicação:** Explicar a utilidade prática no sistema, não apenas repetir tipos. 4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `/../wiki/`. 5. **Fronteira Git e Gestão em Master na Wiki:** Toda atualização em `/../wiki` DEVE ser commitada, sincronizada com resolução de conflitos e enviada via `git push` diretamente na branch `master` de `../wiki`. Na aplicação principal (``), a IA pode comitar apenas em branches de trabalho, sendo proibido comitar na `master` (ver `rules/proibido-commit-ia.md`). +6. **Mídias e Binários no MinIO Paiol:** Arquivos pesados (PDFs, vídeos, imagens e anexos) NUNCA devem ser commitados no Git da Wiki; envie sempre para o MinIO Paiol via `./.agent/scripts/upload-paiol-wiki.sh` e versione apenas a URL pública nos arquivos Markdown. diff --git a/global/skills/documentar-dominio-modulo/SKILL.md b/global/skills/documentar-dominio-modulo/SKILL.md index db46f2a..c32d876 100644 --- a/global/skills/documentar-dominio-modulo/SKILL.md +++ b/global/skills/documentar-dominio-modulo/SKILL.md @@ -53,9 +53,16 @@ Breve descrição do propósito do módulo para o gestor e operador. 3. Emissão de relatórios e acompanhamento de conformidade. ``` +### Inclusão de Imagens, Diagramas e Manuais em PDF +Para enriquecer a Wiki com capturas de tela ou manuais, envie os arquivos para o MinIO Paiol antes de incluí-los no Markdown: +```bash +./.agent/scripts/upload-paiol-wiki.sh +``` +Utilize exclusivamente a URL pública gerada (`https://paiol.idz.one/wiki/...`) no Markdown. **Nunca comite arquivos binários no Git da Wiki.** + --- -## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`/../wiki/dev//`) +## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`/dev//`) Estruturar a especificação técnica, modelos de banco e arquitetura: @@ -86,11 +93,12 @@ Estruturar a especificação técnica, modelos de banco e arquitetura: ## Checklist Final -- [ ] Documentação de usuário criada/atualizada em `/../wiki//`? -- [ ] Documentação técnica criada/atualizada em `/../wiki/dev//`? +- [ ] Documentação de usuário criada/atualizada em `//`? +- [ ] Documentação técnica criada/atualizada em `/dev//`? - [ ] Glossário com os termos centrais do domínio documentado? - [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`? - [ ] Rota `/llm.md` no backend reflete o módulo? +- [ ] Imagens, manuais e anexos hospedados no MinIO Paiol (sem binários no Git da Wiki)? --- diff --git a/rules/ddd-documentacao-primeiro.md b/rules/ddd-documentacao-primeiro.md index f6fefa6..cb1816f 100644 --- a/rules/ddd-documentacao-primeiro.md +++ b/rules/ddd-documentacao-primeiro.md @@ -44,6 +44,31 @@ Todo desenvolvimento e manutenção no ecossistema deve obrigatoriamente respeit --- +## Armazenamento de Arquivos e Mídias da Wiki no MinIO Paiol + +Para evitar o inchaço (*bloat*) irreversível do repositório Git da Wiki (``), **arquivos binários e mídias pesadas** (manuais em PDF, imagens em alta resolução, fluxogramas, diagramas, gravações em vídeo e anexos) **NUNCA** devem ser commitados no Git da Wiki. + +### Protocolo de Envio e Nomenclatura: +- **Destino:** Bucket público `wiki` no MinIO Paiol: + ``` + https://paiol.idz.one/wiki/{modulo}/{funcionalidade/pagina}-{aleatorio}.{ext} + ``` + Onde `{modulo}` é extraído de `modulo-id` em `memorias-ia/modulo.yml` e `{aleatorio}` é um sufixo alfanumérico curto (8 caracteres) para renovação de cache e prevenção de colisão. +- **Envio via Utilitário CLI (Recomendado):** + ```bash + ./.agent/scripts/upload-paiol-wiki.sh + ``` +- **Envio Direto via cURL:** + ```bash + curl -X PUT --upload-file ./manual.pdf https://paiol.idz.one/wiki/{modulo}/{funcionalidade/pagina}-{aleatorio}.pdf + ``` +- **Referência nos Markdowns da Wiki:** + Nos arquivos `.md` da Wiki, utilize exclusivamente as URLs públicas geradas: + - Para imagens: `![Descrição](https://paiol.idz.one/wiki/{modulo}/{slug}-{aleatorio}.png)` + - Para manuais/documentos: `[Baixar Manual (PDF)](https://paiol.idz.one/wiki/{modulo}/{slug}-{aleatorio}.pdf)` + +--- + ## Protocolo DDD Para toda nova demanda, módulo ou funcionalidade, execute os passos abaixo: diff --git a/rules/proibido-commit-ia.md b/rules/proibido-commit-ia.md index 3007af7..7198f93 100644 --- a/rules/proibido-commit-ia.md +++ b/rules/proibido-commit-ia.md @@ -71,6 +71,15 @@ Na Wiki (caminho resolvido dinamicamente via `modulo-wiki` em `memorias-ia/modul - Havendo conflitos de merge, a IA resolve as marcações diretamente na `master`, preservando a coerência da documentação dos 6 pilares. - Adiciona os arquivos resolvidos (`git -C add -A`), finaliza o rebase (`git -C rebase --continue` ou commit) e envia com `git push origin master`. +3. **Proibição de Binários Pesados no Git da Wiki (Usar MinIO Paiol)**: + - É expressamente proibido versionar no Git da Wiki arquivos binários ou mídias pesadas (manuais em `.pdf`, vídeos `.mp4`/`.webm`, imagens pesadas, pacotes `.zip`). + - Todo arquivo estático da Wiki DEVE ser enviado ao MinIO Paiol: + ```bash + ./.agent/scripts/upload-paiol-wiki.sh + ``` + ou via `curl -X PUT --upload-file ... https://paiol.idz.one/wiki/{modulo}/{slug}-{aleatorio}.{ext}`. + - Apenas o arquivo Markdown contendo a URL pública gerada deve ser commitado no repositório. + --- ## Exemplos diff --git a/scripts/upload-paiol-wiki.sh b/scripts/upload-paiol-wiki.sh new file mode 100755 index 0000000..9815690 --- /dev/null +++ b/scripts/upload-paiol-wiki.sh @@ -0,0 +1,137 @@ +#!/usr/bin/env bash +# ============================================================================== +# Script Utilitário: Upload de Arquivos e Mídias da Wiki para o MinIO Paiol +# Envia arquivos (PDFs, imagens, vídeos, anexos) para o MinIO Paiol e gera +# links formatados para inclusão em documentos Markdown da Wiki. +# +# Padrão: +# curl -X PUT --upload-file ./manual.pdf https://paiol.idz.one/wiki/{modulo}/{slug}-{aleatorio}.pdf +# ============================================================================== + +set -e + +VERDE="\033[0;32m" +AMARELO="\033[1;33m" +VERMELHO="\033[0;31m" +AZUL="\033[0;34m" +NEGRITO="\033[1m" +RESET="\033[0m" + +exibir_ajuda() { + echo -e "${AZUL}${NEGRITO}Uso:${RESET} $0 [modulo-override]" + echo "" + echo -e "${NEGRITO}Exemplos:${RESET}" + echo " $0 ./manual.pdf licenciamento/dispensa-licenca" + echo " $0 ./fluxograma.png denuncias/fluxo-fiscalizacao" + echo " $0 ./relatorio.pdf auditoria/relatorio-anual quipo" + echo "" + echo -e "${NEGRITO}Parâmetros:${RESET}" + echo " Caminho do arquivo local a ser enviado" + echo " Identificador semântico da funcionalidade ou página da Wiki" + echo " [modulo-override] (Opcional) Sobrescreve o modulo-id de memorias-ia/modulo.yml" + exit 1 +} + +if [ "$1" = "-h" ] || [ "$1" = "--help" ] || [ -z "$1" ] || [ -z "$2" ]; then + exibir_ajuda +fi + +ARQUIVO="$1" +SLUG_ORIGINAL="$2" +MODULO_OVERRIDE="$3" + +if [ ! -f "$ARQUIVO" ]; then + echo -e "${VERMELHO}Erro:${RESET} Arquivo '$ARQUIVO' não encontrado ou não é um arquivo regular." >&2 + exit 1 +fi + +# Identificar a raiz do projeto pai para ler memorias-ia/modulo.yml +if [ -f "memorias-ia/modulo.yml" ]; then + ROOT_DIR="." +elif [ -f "../memorias-ia/modulo.yml" ]; then + ROOT_DIR=".." +elif [ -f "../../memorias-ia/modulo.yml" ]; then + ROOT_DIR="../.." +else + ROOT_DIR="." +fi + +# Resolver modulo-id +if [ -n "$MODULO_OVERRIDE" ]; then + MODULO_ID="$MODULO_OVERRIDE" +elif [ -f "$ROOT_DIR/memorias-ia/modulo.yml" ]; then + MODULO_ID=$(grep -E "^modulo-id:" "$ROOT_DIR/memorias-ia/modulo.yml" | awk '{print $2}' || true) +fi + +if [ -z "$MODULO_ID" ]; then + echo -e "${AMARELO}Aviso:${RESET} 'modulo-id' não encontrado em memorias-ia/modulo.yml. Usando 'geral'." >&2 + MODULO_ID="geral" +fi + +# Obter extensão e nome base +NOME_COMPLETO=$(basename "$ARQUIVO") +EXT="${NOME_COMPLETO##*.}" +EXT=$(echo "$EXT" | tr '[:upper:]' '[:lower:]') + +# Sanitizar slug (remover barras no início/fim e espaços) +SLUG=$(echo "$SLUG_ORIGINAL" | sed 's|^/||;s|/$||;s| \+|-|g') + +# Gerar sufixo aleatório alfanumérico de 8 caracteres +if command -v openssl >/dev/null 2>&1; then + ALEATORIO=$(openssl rand -hex 4) +elif command -v md5sum >/dev/null 2>&1; then + ALEATORIO=$(head -c 16 /dev/urandom | md5sum | head -c 8) +else + ALEATORIO=$(head -c 8 /dev/urandom | tr -dc 'a-z0-9' | head -c 8) +fi + +URL_DESTINO="https://paiol.idz.one/wiki/${MODULO_ID}/${SLUG}-${ALEATORIO}.${EXT}" + +echo -e "${AZUL}${NEGRITO}Enviando arquivo para o MinIO Paiol...${RESET}" +echo -e " Arquivo: ${NEGRITO}$ARQUIVO${RESET}" +echo -e " Módulo: ${NEGRITO}$MODULO_ID${RESET}" +echo -e " Slug: ${NEGRITO}$SLUG${RESET}" +echo -e " Destino: ${NEGRITO}$URL_DESTINO${RESET}" + +TEMP_RESPOSTA=$(mktemp) + +HTTP_STATUS=$(curl -s -o "$TEMP_RESPOSTA" -w "%{http_code}" -X PUT --upload-file "$ARQUIVO" "$URL_DESTINO") + +if [ "$HTTP_STATUS" -ge 200 ] && [ "$HTTP_STATUS" -lt 300 ]; then + rm -f "$TEMP_RESPOSTA" + echo -e "\n${VERDE}${NEGRITO}✓ Upload realizado com sucesso no MinIO Paiol!${RESET}" + echo -e " ${NEGRITO}URL:${RESET} $URL_DESTINO\n" + + echo -e "${NEGRITO}--- Snippets prontos para a Wiki Markdown ---${RESET}" + + NOME_FORMATADO=$(echo "$SLUG" | awk -F'/' '{print $NF}' | tr '-' ' ' | awk '{for(i=1;i<=NF;i++)sub(/./,toupper(substr($i,1,1)),$i)}1') + + case "$EXT" in + png|jpg|jpeg|svg|gif|webp) + echo -e "${AZUL}Imagem:${RESET}" + echo "![$NOME_FORMATADO]($URL_DESTINO)" + ;; + pdf) + echo -e "${AZUL}Documento / Manual PDF:${RESET}" + echo "[Baixar $NOME_FORMATADO (PDF)]($URL_DESTINO)" + ;; + mp4|webm) + echo -e "${AZUL}Vídeo:${RESET}" + echo "" + ;; + *) + echo -e "${AZUL}Arquivo / Download:${RESET}" + echo "[Baixar $NOME_FORMATADO]($URL_DESTINO)" + ;; + esac + echo "" + exit 0 +else + CONTEUDO_ERRO=$(cat "$TEMP_RESPOSTA" 2>/dev/null || true) + rm -f "$TEMP_RESPOSTA" + echo -e "\n${VERMELHO}${NEGRITO}✗ Falha no upload para o Paiol (HTTP $HTTP_STATUS)${RESET}" >&2 + if [ -n "$CONTEUDO_ERRO" ]; then + echo -e "Resposta do servidor: $CONTEUDO_ERRO" >&2 + fi + exit 1 +fi diff --git a/skills/documentacao/SKILL.md b/skills/documentacao/SKILL.md index 7b3f640..096f28a 100644 --- a/skills/documentacao/SKILL.md +++ b/skills/documentacao/SKILL.md @@ -65,6 +65,9 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza # Criar um ADR na Wiki Dev + commit/push na wiki /documentacao adr "" + +# Upload de arquivo/mídia (PDF, imagem, vídeo) para o MinIO Paiol com link pronto para a Wiki +/documentacao upload ``` *Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`/../wiki`) deve finalizar executando `git add`, `git commit`, `git pull --rebase` (resolvendo conflitos na master se houver) e `git push` diretamente na branch `master` dentro de `../wiki`. @@ -78,3 +81,4 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza 3. **JSDoc de Aplicação:** Explicar a utilidade prática no sistema, não apenas repetir tipos. 4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `/../wiki/`. 5. **Fronteira Git e Gestão em Master na Wiki:** Toda atualização em `/../wiki` DEVE ser commitada, sincronizada com resolução de conflitos e enviada via `git push` diretamente na branch `master` de `../wiki`. Na aplicação principal (``), a IA pode comitar apenas em branches de trabalho, sendo proibido comitar na `master` (ver `rules/proibido-commit-ia.md`). +6. **Mídias e Binários no MinIO Paiol:** Arquivos pesados (PDFs, vídeos, imagens e anexos) NUNCA devem ser commitados no Git da Wiki; envie sempre para o MinIO Paiol via `./.agent/scripts/upload-paiol-wiki.sh` e versione apenas a URL pública nos arquivos Markdown. diff --git a/skills/documentar-dominio-modulo/SKILL.md b/skills/documentar-dominio-modulo/SKILL.md index 9f013f8..d715dc4 100644 --- a/skills/documentar-dominio-modulo/SKILL.md +++ b/skills/documentar-dominio-modulo/SKILL.md @@ -55,6 +55,13 @@ Breve descrição do propósito do módulo para o gestor e operador. 3. Emissão de relatórios e acompanhamento de conformidade. ``` +### Inclusão de Imagens, Diagramas e Manuais em PDF +Para enriquecer a Wiki com capturas de tela ou manuais, envie os arquivos para o MinIO Paiol antes de incluí-los no Markdown: +```bash +./.agent/scripts/upload-paiol-wiki.sh +``` +Utilize exclusivamente a URL pública gerada (`https://paiol.idz.one/wiki/...`) no Markdown. **Nunca comite arquivos binários no Git da Wiki.** + --- ## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`/dev//`) @@ -94,6 +101,7 @@ Estruturar a especificação técnica, modelos de banco e arquitetura: - [ ] Glossário com os termos centrais do domínio documentado? - [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`? - [ ] Rota `/llm.md` no backend reflete o módulo? +- [ ] Imagens, manuais e anexos hospedados no MinIO Paiol (sem binários no Git da Wiki)? ---