--- id: topbuilder-ged-guia-geral title: GED, documentação, Storin e assinatura — guia geral topics: [ged, cms, documentos, arquivos, storin, s3, assinatura, configuracao] status: authoritative category: ESTRUTURA GERAL project: TOPBUILDER CMS Java domain: DADOS, ARQUIVOS E INTEGRAÇÕES subdomain: GED e assinatura eletrônica document_type: guide lifecycle: current authority: authoritative implementation_state: implemented verified_at: 2026-09-01 --- # GED, documentação, Storin e assinatura — guia geral Este guia explica como acessar e configurar o GED do CMS Java, a área de documentação, o repositório Storin/S3 e os fluxos de assinatura de PDF. ## Caminhos de acesso | Área | Caminho | | --- | --- | | Entrada do GED TOPTI | `/ged/topti` | | Gerenciador de arquivos | `/ged/topti/files` | | Documentação dentro do GED | `/ged/topti/docs` | | Portal técnico público | `/docs/` | | Central de assinaturas | `/ged/sign` | | Iniciar nova assinatura | `/ged/sign/new` | | Login do GED | `/ged/login?return=/ged/topti/files` | No ambiente de produção, os caminhos são relativos a `https://topti.app.br`. O portal `/docs/` publica a documentação técnica empacotada pelo Commons. A área `/ged/topti/docs` lista os repositórios configurados com `contentType: "DOCUMENTATION"`. A página inicial do ambiente funciona como portal das opções ativas: - **Arquivos** aparece quando existe ao menos um repositório `FILES`; - **Documentação** aparece quando existe ao menos um repositório `DOCUMENTATION`; - **Assinar documento avulso** e **Documentos para assinar** aparecem quando `ged-sign` está habilitado para o domínio. Opções sem repositório ou desabilitadas pela parametrização não são exibidas. ## Como o GED seleciona a configuração ```text domínio da requisição | v connections.json | seleciona ged-environment v /repositorios.json | v LOCAL / SOURCE / STRUCTURE / SITE_ASSETS / FTP / HTTP / S3 | v gerenciador de arquivos ou documentação ``` O `connections.json` associa o domínio a um ambiente. O `repositorios.json` desse ambiente define quais repositórios aparecem e quais operações cada um oferece. Uma falha de inicialização ou consulta desabilita somente o repositório afetado: ele permanece visível em vermelho, sem seleção, enquanto os demais continuam funcionando. ## Funcionalidades do gerenciador Conforme as capabilities do repositório, a interface oferece: - árvore de pastas, pesquisa e paginação; - pré-visualização de imagem, PDF, Markdown, HTML, texto e código; - download e abertura; - upload de arquivo ou pasta e criação de diretório; - edição de arquivos textuais com controle de revisão; - cópia, movimentação e exclusão por lixeira recuperável; - seleção múltipla, download ZIP e união de PDFs; - assinatura de PDF; - atualização do conteúdo do repositório. A capability efetiva é a interseção entre `writable`, o modo da localização, as `capabilities` declaradas e as funções implementadas pelo provider. O backend repete a validação: esconder um botão na tela não constitui autorização. ## Configuração externa do servidor O contexto Tomcat deve apontar para arquivos externos ao WAR. O arquivo operacional é `/opt/tomcat/conf/Catalina/localhost/ROOT.xml`: ```xml ``` Layout recomendado: ```text /var/ftp/topbuildercmsfiles/ |-- connections.json `-- topti/ |-- repositorios.json |-- arquivos.json |-- storin.json |-- ged-certificate.pfx |-- ged-certificate.password `-- public/ ``` Também são aceitas as variáveis `TOPBUILDER_SITE_CONNECTIONS_FILE`, `TOPBUILDER_SITE_CONTENT_BASE` e `TOPBUILDER_GED_CONFIGURATION_ROOT`. JSONs, tokens, certificados, senhas e conteúdo de clientes não devem ser empacotados no WAR nem expostos por rotas públicas. ## Configuração do domínio e do acesso Os campos GED ficam na entrada correspondente do `connections.json`: ```json { "domains": ["topti.app.br"], "ged-environment": "topti", "ged-token": "SEGREDO-EXTERNO", "ged-sign": "true", "ged-certificate": "topti", "ged_use_login": "true", "ged_login_group": "ID-DO-GRUPO", "ged_view_files_when_no_login": "true" } ``` - `ged-environment`: seleciona o subdiretório de configuração; - `ged-token`: acesso administrativo temporário, exclusivo do ambiente; - `ged-sign`: habilita assinatura de PDF; - `ged-certificate`: `none`, `topti` ou `file`; - `ged-certificate-file`: nome de um PFX/P12 próprio, no modo `file`; - `ged_use_login`: habilita autenticação do GED; - `ged_login_group`: grupo autorizado, obrigatório quando há login; - `ged_view_files_when_no_login`: permite consulta sem login. Tokens podem ser trocados por sessão, mas nunca devem ser documentados, gravados no catálogo de arquivos ou enviados ao navegador após a autenticação. Operações de alteração continuam sujeitas à política do ambiente e à proteção CSRF. ## Configuração dos repositórios O `/repositorios.json` é o arquivo inicial do GED. Os principais campos são: - `contentType`: `FILES` ou `DOCUMENTATION`; - `activeLocation`: localização principal; - `readOrder`: ordem de leitura e fallback; - `writeLocation`: único destino de gravação; - `writable`: habilitação geral de escrita; - `locations..type`: provider da localização; - `locations..mode`: `READ_ONLY` ou `READ_WRITE`; - `capabilities`: `upload`, `createDirectory`, `copy`, `move`, `delete` e `nativeOpen`. Tipos suportados pelo CMS incluem arquivos locais/UNC, assets públicos do site, FTP, HTTP, fonte de documentação, arquivos cadastrados na estrutura e S3. O botão **Repositórios JSON** permite consultar a configuração pelo próprio gerenciador. Na fase atual, a gravação também está liberada sem login por decisão operacional, mas mantém CSRF, limite de tamanho, validação do JSON, proteção contra alteração concorrente e substituição atômica. Essa exceção deve ser revista antes de uma abertura ampla do CMS. ## Papel do arquivos.json O `arquivos.json` permanece como catálogo de repositórios que precisam de mapeamento, indexação local ou metadados relacionados ao sistema. Ele pode guardar resumo, trava de exclusão e metadados de assinatura. Objetos do Storin não são copiados para esse catálogo. O bucket é a fonte de verdade e sua listagem é obtida ao vivo; isso evita um JSON facilmente desatualizado em relação ao armazenamento real. ## Documentação dentro do GED Um repositório de documentação usa `contentType: "DOCUMENTATION"`. Para Markdown disponível em uma pasta do servidor, pode utilizar o provider SOURCE: ```json { "id": "documentacao-source", "label": "Documentação dos fontes", "contentType": "DOCUMENTATION", "activeLocation": "source", "readOrder": ["source"], "writable": false, "locations": { "source": { "type": "SOURCE", "basePath": "/caminho/legivel/pelo/tomcat/docs/topbuilder", "mode": "READ_ONLY", "maxScanDepth": 128, "include": ["*.md", "**/*.md"], "exclude": ["_portal/**"] } } } ``` O `basePath` precisa existir no sistema operacional do servidor e ser legível pelo usuário do Tomcat. Um caminho de desenvolvimento Windows não funciona no servidor Linux. Documentos gerados e o portal independente `/docs/` continuam somente leitura. Quando a documentação canônica está empacotada no JAR do Commons, use o prefixo `classpath:` em vez de um caminho do computador: ```json { "type": "SOURCE", "basePath": "classpath:/topbuilder", "mode": "READ_ONLY", "maxScanDepth": 128, "include": ["*.md", "**/*.md"] } ``` Nesse modo, o provider lista e abre `META-INF/resources/docs/topbuilder` diretamente no JAR do Commons. O conteúdo é sempre somente leitura, não possui caminho local para abertura nativa e funciona igualmente no desktop e no CMS. ## Storin Object Storage O repositório Storin é do tipo `S3` e aponta para um arquivo externo sensível: ```json { "id": "storin", "label": "Storin Object Storage", "contentType": "FILES", "activeLocation": "storin", "readOrder": ["storin"], "writeLocation": "storin", "writable": true, "locations": { "storin": { "type": "S3", "configFile": "storin.json", "basePrefix": "", "trashPrefix": ".ged-trash/", "mode": "READ_WRITE", "connectTimeoutMillis": 15000, "apiCallTimeoutMillis": 120000, "cacheTtlSeconds": 30, "maxCachedPages": 512 } }, "capabilities": { "upload": true, "createDirectory": true, "copy": false, "move": false, "delete": true, "nativeOpen": false } } ``` `configFile` é relativo ao diretório que contém o `repositorios.json`; não é relativo ao WAR nem ao diretório corrente do Tomcat. O arquivo externo possui: ```json { "endpoint": "https://ENDPOINT-S3", "region": "REGIAO", "bucket": "BUCKET", "credentials": { "access_key_id": "CHAVE-EXTERNA", "secret_access_key": "SEGREDO-EXTERNO" } } ``` O CMS usa a API compatível com S3 diretamente: - `ListObjectsV2` lista objetos e converte prefixos em pastas; - `GetObject` realiza download; - `PutObject` envia arquivos; - um marcador de zero byte representa pasta vazia; - a exclusão copia primeiro para `.ged-trash/` e só então remove a origem; - o botão Atualizar invalida o cache e consulta novamente o bucket; - nenhum desses eventos reescreve `arquivos.json`. Cópia e movimentação permanecem inicialmente desabilitadas no S3 porque não são operações atômicas. O navegador nunca recebe endpoint privado ou credenciais. O provider usa AWS SDK for Java 2.29.0. No servidor, o conjunto completo e da mesma versão deve estar em `/opt/tomcat/lib`; no desktop, deve estar no classpath da plataforma. Um erro como `NoClassDefFoundError` de classe AWS indica conjunto incompleto de JARs, não falha do bucket nem do `arquivos.json`. ## Assinatura de PDF no gerenciador Quando `ged-sign` está habilitado, a ação **Assinar PDF** permite visualizar o arquivo e posicionar a marca na última página. O servidor registra as evidências, aplica o certificado configurado e grava uma nova cópia: ```text nome-assinado-DD-MM-AAAA-HH-mm-ss.pdf ``` O original não é sobrescrito. Os modos são: - `none`: evidência e marca visual sem PFX; - `topti`: usa `topti/ged-certificate.pfx` e `topti/ged-certificate.password`; - `file`: usa o PFX/P12 indicado por `ged-certificate-file` e o arquivo de senha companheiro. A trilha inclui ambiente, repositório, caminho, página, posição, data/hora, identidade disponível, IP, navegador e hashes. Cookies, CSRF, Authorization, senha e token puro não são gravados. ## Central de assinaturas A central `/ged/sign` trabalha com grupos, documentos e signatários. O fluxo permite: 1. enviar um novo PDF e identificar o documento; 2. apresentar o conteúdo ao signatário e colher consentimento; 3. acessar por sessão autenticada ou link individual associado ao destinatário; 4. gerar uma nova versão cumulativa a cada assinatura; 5. preservar original, versões intermediárias, hashes e relação entre versões; 6. baixar o resultado e, quando configurado, enviá-lo por e-mail; 7. aplicar o selo eletrônico da TOPTI no fechamento técnico do processo. As rotas de grupo e destinatário são geradas pelo sistema: ```text /ged/sign/group/{grupo} /ged/sign/usergrup/{hash-individual} ``` O selo da TOPTI comprova integridade, origem e processamento pela plataforma. Ele não substitui o certificado pessoal do usuário nem torna a TOPTI parte ou garantidora do conteúdo assinado. ## Diagnóstico rápido ### Repositório vermelho e desabilitado Confira a mensagem apresentada e o log do Tomcat. Causas comuns: - `basePath` inexistente ou sem permissão; - `configFile` ausente ou inválido; - credencial ou endpoint S3 inválido; - provider indisponível; - JAR do provider ausente no `/opt/tomcat/lib`; - timeout de conexão. A falha deve afetar somente esse repositório. ### Arquivo enviado externamente ao Storin não aparece Use **Atualizar conteúdo** ou aguarde o TTL do cache. Não adicione o objeto ao `arquivos.json`. ### Operação não aparece na tela Verifique, em conjunto, `writable`, `mode`, `writeLocation`, as `capabilities`, a capacidade real do provider e a autorização da sessão. ### Documentação não aparece Confirme `contentType: "DOCUMENTATION"`, `include`/`exclude`, `maxScanDepth`, a existência do `basePath` no servidor e a permissão de leitura do Tomcat.