📚 Guia de Uso - Gateway CSuite - Portal de Documentação

Versão: 1.0
Data: 2025-01-03
URL Base: https://csuite.internut.com.br/docs
Gateway: https://csuite.internut.com.br/

📋 Índice

1. Visão Geral
2. Acessando a Documentação
3. Navegação pela Documentação
4. Explorador de Documentos
5. Estrutura de Categorias
6. Acessando Documentos Específicos
7. Formato de URLs
8. Tipos de Documentos Suportados
9. Dicas e Boas Práticas
10. Troubleshooting

🎯 Visão Geral

O portal de documentação do CSuite (/docs) é um sistema centralizado para acessar toda a documentação técnica, guias de uso, manuais e referências do ecossistema CSuite.

Funcionalidades Principais

• ✅ Página Principal de Documentação - Visão geral organizada por categorias
• ✅ Explorador de Documentos - Busca e navegação por todos os documentos
• ✅ Navegação por Categorias - Documentos organizados por tipo
• ✅ Visualização de Documentos - Suporte para Markdown, JSON, Mermaid
• ✅ URLs Amigáveis - Links diretos para documentos específicos

🌐 Acessando a Documentação

URL Principal

https://csuite.internut.com.br/docs

Endpoints Disponíveis

🧭 Navegação pela Documentação

1. Página Principal (/docs)

A página principal exibe:
- README Principal - Visão geral da documentação
- Categorias Organizadas - Lista de todas as categorias disponíveis
- Documentos por Categoria - Acesso rápido aos documentos mais importantes

2. Navegação por Categoria

Cada categoria tem sua própria página com:
- README da categoria (se existir)
- Lista completa de documentos
- Informações sobre o tipo de conteúdo

Exemplo:

https://csuite.internut.com.br/docs/guides
https://csuite.internut.com.br/docs/strategic
https://csuite.internut.com.br/docs/api

🔍 Explorador de Documentos

Acessando o Explorador

https://csuite.internut.com.br/docs/explorer

Funcionalidades

• Busca por Nome - Filtra documentos em tempo real
• Filtro por Tipo - Filtra por extensão (md, json, mmd, etc.)
• Visualização por Categoria - Agrupa documentos por categoria
• Informações de Arquivo - Tamanho, data de modificação, tipo

Como Usar

1. Acesse /docs/explorer
2. Use a barra de busca para filtrar documentos
3. Clique em um documento para visualizar
4. Use os filtros para refinar a busca

📁 Estrutura de Categorias

A documentação está organizada em 12 categorias principais:

Acessando uma Categoria

https://csuite.internut.com.br/docs/{categoria}

Exemplos:
- https://csuite.internut.com.br/docs/guides - Todos os guias
- https://csuite.internut.com.br/docs/strategic - Documentação estratégica
- https://csuite.internut.com.br/docs/api - Documentação de APIs

📄 Acessando Documentos Específicos

Formato de URL

https://csuite.internut.com.br/docs/{categoria}/{filename}

Exemplos Práticos

Guia de API

https://csuite.internut.com.br/docs/guides/GUIA_USO_APIS_CONTEXT.md

Documento Estratégico

https://csuite.internut.com.br/docs/strategic/CSUITE_MENTAL_MODEL.md

Manual do Usuário

https://csuite.internut.com.br/docs/manuals/Manual_do_Usuário_CSuite_para_CFO.md

Acesso Direto via /docs/guide/

Para documentos em guides/ ou na raiz, você pode usar:

https://csuite.internut.com.br/docs/guide/{filename}

Exemplo:

https://csuite.internut.com.br/docs/guide/GUIA_USO_APIS_CONTEXT.md

🔗 Formato de URLs

Caracteres Especiais

O sistema suporta URLs com caracteres especiais (acentos, espaços, etc.) usando URL encoding:

Exemplo:

Manual_do_Usuário_CSuite_para_CFO.md

É acessível via:

https://csuite.internut.com.br/docs/manuals/Manual_do_Usu%C3%A1rio_CSuite_para_CFO.md

O sistema decodifica automaticamente os caracteres especiais.

Regras de URL

• ✅ Use - ou _ para separar palavras em nomes de arquivo
• ✅ Evite espaços (use _ ou -)
• ✅ Caracteres especiais são suportados via URL encoding
• ✅ Extensões são preservadas (.md, .json, .mmd)

📝 Tipos de Documentos Suportados

1. Markdown (.md)

Formato mais comum:
- Renderizado como HTML
- Suporte a sintaxe Markdown completa
- Code blocks com syntax highlighting
- Tabelas, listas, links

Exemplo:

https://csuite.internut.com.br/docs/guides/GUIA_USO_APIS_CONTEXT.md

2. JSON (.json)

Retornado como JSON puro:
- Útil para schemas, configurações
- Content-Type: application/json

Exemplo:

https://csuite.internut.com.br/docs/api/schema.json

3. Mermaid (.mmd)

Diagramas Mermaid:
- Renderizado como code block
- Pode ser visualizado com extensões do navegador

Exemplo:

https://csuite.internut.com.br/docs/architecture/diagram.mmd

💡 Dicas e Boas Práticas

1. Usando o Explorador

• Use a busca para encontrar documentos rapidamente
• Filtre por tipo para encontrar schemas JSON ou diagramas
• Navegue por categoria para explorar tópicos relacionados

2. Links Diretos

• Salve links diretos para documentos importantes
• Compartilhe links específicos em vez de apenas /docs
• Use bookmarks para acesso rápido

3. Navegação

• Comece pela página principal (/docs) para visão geral
• Use o explorador (/docs/explorer) para busca
• Navegue por categoria para documentos relacionados

4. Documentos Relacionados

Muitos documentos têm seções de "Documentação Relacionada" com links para:
- Outros guias relevantes
- Documentação de APIs relacionadas
- Documentos estratégicos ou arquiteturais

🔧 Troubleshooting

Problema: Documento não encontrado (404)

Possíveis causas:
1. Nome do arquivo incorreto
2. Categoria incorreta
3. Arquivo não existe no repositório

Solução:
- Verifique o nome exato do arquivo
- Use o explorador (/docs/explorer) para encontrar o documento
- Verifique se o arquivo existe na categoria correta

Problema: Caracteres especiais na URL

Solução:
- O sistema decodifica automaticamente caracteres especiais
- Se houver problemas, use o explorador para obter o link correto
- Verifique se o encoding está correto na URL

Problema: Documento não renderiza corretamente

Possíveis causas:
1. Sintaxe Markdown inválida
2. Arquivo corrompido
3. Encoding incorreto

Solução:
- Verifique a sintaxe Markdown
- Verifique o encoding do arquivo (deve ser UTF-8)
- Tente acessar o arquivo diretamente no repositório

Problema: Categoria não encontrada

Solução:
- Verifique se a categoria existe (consulte lista acima)
- Use /docs/explorer para ver todas as categorias disponíveis
- Verifique se o nome da categoria está correto (case-sensitive)

📚 Documentação Relacionada

Guias de APIs

• Guia de Uso do Ecossistema
• Guia de Integração
• FAQ

Documentação Técnica

• Arquitetura - Documentação arquitetural
• APIs - Documentação de APIs
• Operations - Procedimentos operacionais

Outros Recursos

• Gateway Principal: https://csuite.internut.com.br/
• Status dos Serviços: https://csuite.internut.com.br/api/status
• Métricas: https://csuite.internut.com.br/api/metrics

🎓 Exemplos Práticos

Exemplo 1: Encontrar um Guia de API

1. Acesse /docs/explorer
2. Digite "GUIA_USO_APIS" na busca
3. Filtre por tipo "md"
4. Clique no guia desejado

Exemplo 2: Navegar por Categoria

1. Acesse /docs/guides
2. Veja a lista de todos os guias
3. Clique em um guia específico
4. Use os links relacionados para explorar mais

Exemplo 3: Acessar Documento Diretamente

Se você conhece o caminho exato:

https://csuite.internut.com.br/docs/guides/GUIA_USO_APIS_CONTEXT.md

Exemplo 4: Buscar Documentos Estratégicos

1. Acesse /docs/strategic
2. Veja todos os documentos estratégicos
3. Leia o README da categoria (se existir)
4. Explore os documentos relacionados

✅ Checklist de Uso

• [ ] Acessei a página principal (/docs)
• [ ] Explorei o explorador de documentos (/docs/explorer)
• [ ] Naveguei por pelo menos uma categoria
• [ ] Acessei um documento específico
• [ ] Entendi a estrutura de categorias
• [ ] Sei como buscar documentos
• [ ] Conheço os tipos de documentos suportados

📞 Suporte

Para problemas ou dúvidas sobre a documentação:

1. Verifique este guia - Muitas respostas estão aqui
2. Use o explorador - Para encontrar documentos
3. Consulte o FAQ - docs/guides/FAQ.md
4. Troubleshooting - docs/guides/TROUBLESHOOTING.md

Última atualização: 2025-01-03
Versão do Gateway: 1.0.0