feat(wiki): padronizar upload de arquivos e midias para MinIO Paiol
This commit is contained in:
parent
19df29ea45
commit
49943f82bf
13 changed files with 272 additions and 12 deletions
|
|
@ -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** | `<base_projeto>/../wiki/<modulo-id>/` | 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** | `<base_projeto>/../wiki/dev/<modulo-id>/` | 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** | `<modulo-wiki>/<modulo-id>/` | 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** | `<modulo-wiki>/dev/<modulo-id>/` | 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** | `<base_projeto>/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** | `<base_projeto>/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 (`<base_projeto>/../wiki`) e Identidade do Projeto**:
|
||||
> - `<base_projeto>/../wiki/` é uma aplicação **VitePress**.
|
||||
> - `<base_projeto>/../wiki/<modulo-id>/` representa a documentação de **acesso dos usuários e operadores** (onde `<modulo-id>` provém de `memorias-ia/modulo.yml`).
|
||||
> - `<base_projeto>/../wiki/dev/<modulo-id>/` representa a documentação de **acesso interno pela equipe de desenvolvimento e arquitetura**.
|
||||
> - O arquivo `<base_projeto>/memorias-ia/modulo.yml` é **obrigatório em todos os projetos** e define `modulo-id`, `modulo-caminho`, `modulo-descricao` e `modulo-tipo`.
|
||||
> ℹ️ **Arquitetura VitePress (`<modulo-wiki>`, padrão: `<base_projeto>/../wiki`) e Identidade do Projeto**:
|
||||
> - `<modulo-wiki>` é uma aplicação **VitePress** cujo caminho é definido em `memorias-ia/modulo.yml` (fallback padrão: `../wiki/`).
|
||||
> - `<modulo-wiki>/<modulo-id>/` representa a documentação de **acesso dos usuários e operadores** (onde `<modulo-id>` provém de `memorias-ia/modulo.yml`).
|
||||
> - `<modulo-wiki>/dev/<modulo-id>/` representa a documentação de **acesso interno pela equipe de desenvolvimento e arquitetura**.
|
||||
> - O arquivo `<base_projeto>/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/...`.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -56,3 +56,14 @@ VARIÁVEIS A PREENCHER:
|
|||
## Vocabulário de Interface (Linguagem Ubíqua)
|
||||
<Termos específicos que DEVEM ser usados nos botões, títulos e mensagens da UI para consistência com o usuário>
|
||||
- `<Ação>`: `<Termo recomendado na UI>`
|
||||
|
||||
---
|
||||
|
||||
## Manuais, Diagramas e Anexos (MinIO Paiol)
|
||||
<!--
|
||||
ATENÇÃO: Mídias pesadas, vídeos, imagens e manuais em PDF NUNCA devem ser commitados no Git da Wiki.
|
||||
Envie via: ./.agent/scripts/upload-paiol-wiki.sh <arquivo> <slug>
|
||||
Insira abaixo apenas as URLs públicas geradas:
|
||||
-->
|
||||
- [Manual Operacional (PDF)](https://paiol.idz.one/wiki/<modulo-id>/manual-<aleatorio>.pdf)
|
||||
|
||||
|
|
|
|||
5
TOOLS
5
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 "<Título>" "<Mensagem>" [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 <caminho-do-arquivo> <slug-funcionalidade-ou-pagina> [modulo-override]`
|
||||
|
||||
---
|
||||
|
||||
## 8. Instalação Rápida (Copia e Cola)
|
||||
|
|
|
|||
16
TOOLS.md
16
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 "<Título>" "<Mensagem>" [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 <caminho-do-arquivo> <slug-funcionalidade-ou-pagina> [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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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 (`<modulo-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 <caminho-do-arquivo> <slug-funcionalidade>
|
||||
```
|
||||
- **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: ``
|
||||
- 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:
|
||||
|
|
|
|||
|
|
@ -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 <modulo-wiki> add -A`), finaliza o rebase (`git -C <modulo-wiki> 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 <arquivo> <funcionalidade/pagina>
|
||||
```
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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 "<Título da Decisão>"
|
||||
|
||||
# Upload de arquivo/mídia (PDF, imagem, vídeo) para o MinIO Paiol com link pronto para a Wiki
|
||||
/documentacao upload <caminho/arquivo.ext> <slug-funcionalidade>
|
||||
```
|
||||
|
||||
*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`<base_projeto>/../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 `<base_projeto>/../wiki/`.
|
||||
5. **Fronteira Git e Gestão em Master na Wiki:** Toda atualização em `<base_projeto>/../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 (`<base_projeto>`), 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.
|
||||
|
|
|
|||
|
|
@ -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 <caminho-do-arquivo> <slug-funcionalidade>
|
||||
```
|
||||
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 (`<base_projeto>/../wiki/dev/<modulo>/`)
|
||||
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo>/`)
|
||||
|
||||
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 `<base_projeto>/../wiki/<modulo>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `<base_projeto>/../wiki/dev/<modulo>/`?
|
||||
- [ ] Documentação de usuário criada/atualizada em `<modulo-wiki>/<modulo>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `<modulo-wiki>/dev/<modulo>/`?
|
||||
- [ ] 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)?
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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 (`<modulo-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 <caminho-do-arquivo> <slug-funcionalidade>
|
||||
```
|
||||
- **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: ``
|
||||
- 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:
|
||||
|
|
|
|||
|
|
@ -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 <modulo-wiki> add -A`), finaliza o rebase (`git -C <modulo-wiki> 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 <arquivo> <funcionalidade/pagina>
|
||||
```
|
||||
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
|
||||
|
|
|
|||
137
scripts/upload-paiol-wiki.sh
Executable file
137
scripts/upload-paiol-wiki.sh
Executable file
|
|
@ -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 <caminho-do-arquivo> <slug-funcionalidade-ou-pagina> [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> Caminho do arquivo local a ser enviado"
|
||||
echo " <slug-funcionalidade> 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 ""
|
||||
;;
|
||||
pdf)
|
||||
echo -e "${AZUL}Documento / Manual PDF:${RESET}"
|
||||
echo "[Baixar $NOME_FORMATADO (PDF)]($URL_DESTINO)"
|
||||
;;
|
||||
mp4|webm)
|
||||
echo -e "${AZUL}Vídeo:${RESET}"
|
||||
echo "<video controls src=\"$URL_DESTINO\" width=\"100%\"></video>"
|
||||
;;
|
||||
*)
|
||||
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
|
||||
|
|
@ -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 "<Título da Decisão>"
|
||||
|
||||
# Upload de arquivo/mídia (PDF, imagem, vídeo) para o MinIO Paiol com link pronto para a Wiki
|
||||
/documentacao upload <caminho/arquivo.ext> <slug-funcionalidade>
|
||||
```
|
||||
|
||||
*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`<base_projeto>/../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 `<base_projeto>/../wiki/`.
|
||||
5. **Fronteira Git e Gestão em Master na Wiki:** Toda atualização em `<base_projeto>/../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 (`<base_projeto>`), 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.
|
||||
|
|
|
|||
|
|
@ -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 <caminho-do-arquivo> <slug-funcionalidade>
|
||||
```
|
||||
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 (`<modulo-wiki>/dev/<modulo>/`)
|
||||
|
|
@ -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)?
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue