Relatório: Sistema de Documentação KMS (Docusaurus)

Data: 2026-01-09
Responsável: Engenheiro de Software Sênior
Status: ✅ Implementado e Operacional

1. Resumo Executivo

Foi implementado o sistema de documentação KMS (Knowledge Management System) utilizando Docusaurus 3.9, integrado à Central de Gerenciamento do Clio SIGAD. O sistema está acessível via https://docs.arboreolab.com.br e também pelo card "KMS - Base de Conhecimento" no frontend.

2. Componentes Implementados

2.1 Frontend - Card KMS

Arquivo: iface-frontend-vuejs/src/views/gerenciamentos/GerenciadorDocs.vue

Nova seção "Documentação" adicionada
Card KMS com badge "Docusaurus"
Método openKMS() que abre a URL configurável via VITE_KMS_URL
Estilo CSS personalizado (gradiente roxo/azul)

2.2 Docusaurus

Localização: /home/arboreolab/Clio/docs/

Item	Configuração
Versão	Docusaurus 3.9.2
Template	Classic + TypeScript
Porta	3001
Idioma	pt-BR

Estrutura de Diretórios:

/home/arboreolab/Clio/docs/
├── docs/
│   ├── intro.md                    # Página inicial
│   ├── infraestrutura/
│   │   ├── _category_.json
│   │   ├── visao-geral.md
│   │   ├── mariadb.md
│   │   └── motor-rag.md
│   ├── guia-usuario/
│   │   ├── _category_.json
│   │   ├── primeiros-passos.md
│   │   └── busca.md
│   ├── api/
│   │   ├── _category_.json
│   │   └── visao-geral.md
│   └── kms/
│       └── _category_.json         # Sincronizado do KMS
├── blog/                           # Changelog
├── src/                            # Componentes React
├── static/                         # Assets estáticos
├── docusaurus.config.ts            # Configuração principal
├── sidebars.ts                     # Sidebar
├── ecosystem.config.js             # PM2
├── sync-kms.sh                     # Script de sincronização
└── build/                          # Produção

2.3 PM2

┌────┬─────────────┬─────────┬─────────┬──────────┬────────┬───────────┐
│ id │ name        │ mode    │ pid     │ uptime   │ status │ port      │
├────┼─────────────┼─────────┼─────────┼──────────┼────────┼───────────┤
│ 10 │ clio-docs   │ fork    │ 2623570 │ online   │ online │ 3001      │
└────┴─────────────┴─────────┴─────────┴──────────┴────────┴───────────┘

2.4 Nginx

Arquivo: /etc/nginx/sites-available/docs.arboreolab.com.br

Proxy reverso localhost:3001
SSL via Let's Encrypt (certbot)
Redirect HTTP → HTTPS

2.5 DNS

Tipo	Nome	Valor	TTL
A	docs	212.85.22.243	300

3. Documentação Criada

Página	Categoria	Descrição
`intro.md`	Root	Introdução ao Clio SIGAD
`visao-geral.md`	Infraestrutura	Arquitetura do sistema
`mariadb.md`	Infraestrutura	Configuração do banco
`motor-rag.md`	Infraestrutura	FregeRAG - busca semântica
`primeiros-passos.md`	Guia Usuário	Onboarding
`busca.md`	Guia Usuário	Como pesquisar documentos
`visao-geral.md`	API	Endpoints REST

4. Script de Sincronização KMS

Arquivo: /home/arboreolab/Clio/docs/sync-kms.sh

Funcionalidades:

Sincroniza .md de .github/knowledge-management-system/ para docs/docs/kms/
Suporta modo --build (rebuild Docusaurus)
Suporta modo --watch (polling 30s)
Cria categoria automaticamente

Uso:

# Sincronizar apenas
./sync-kms.sh

# Sincronizar e rebuild
./sync-kms.sh --build

# Modo watch
./sync-kms.sh --watch

5. URLs de Acesso

Ambiente	URL
Produção	https://docs.arboreolab.com.br
Local	http://127.0.0.1:3001
Via Frontend	Card KMS em /gerenciadores

6. Comandos de Manutenção

# Status PM2
pm2 status clio-docs

# Logs
pm2 logs clio-docs --lines 50 --nostream

# Rebuild completo
cd /home/arboreolab/Clio/docs && npm run build && pm2 restart clio-docs

# Sincronizar conteúdo KMS
/home/arboreolab/Clio/docs/sync-kms.sh --build

7. Configuração do Frontend

A URL do KMS é configurável via variável de ambiente:

# .env.local ou .env.production
VITE_KMS_URL=https://docs.arboreolab.com.br

Se não definida, usa fallback http://localhost:3001.

8. Próximos Passos Sugeridos

Conteúdo: Adicionar mais documentação técnica e tutoriais
Busca: Habilitar plugin Algolia para busca avançada
Versionamento: Configurar versionamento de docs por release
i18n: Adicionar tradução EN se necessário
CI/CD: Automatizar build no deploy do Clio

9. Arquivos Modificados/Criados

Modificados

iface-frontend-vuejs/src/views/gerenciamentos/GerenciadorDocs.vue

Criados

/home/arboreolab/Clio/docs/ (projeto completo Docusaurus)
/etc/nginx/sites-available/docs.arboreolab.com.br
Certificado SSL Let's Encrypt

10. Dependências

Pacote	Versão
@docusaurus/core	3.9.2
@docusaurus/preset-classic	3.9.2
prism-react-renderer	^2.3.0
react	^19.0.0
react-dom	^19.0.0
typescript	~5.7.2

Relatório gerado em: 2026-01-09 18:10 UTC

1. Resumo Executivo​

2. Componentes Implementados​

2.1 Frontend - Card KMS​

2.2 Docusaurus​

2.3 PM2​

2.4 Nginx​

2.5 DNS​

3. Documentação Criada​

4. Script de Sincronização KMS​

5. URLs de Acesso​

6. Comandos de Manutenção​

7. Configuração do Frontend​

8. Próximos Passos Sugeridos​

9. Arquivos Modificados/Criados​

Modificados​

Criados​

10. Dependências​