docs: add Portuguese docs and English CLAUDE.md

Add README.md, docs/ (fluxo, configuracao, arquitetura) in PT-BR and a CLAUDE.md technical reference in English describing the installer flow, generated files, containers and architecture. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-19 11:53:56 -03:00
parent 009c4bc8d1
commit 25137eb5da
5 changed files with 675 additions and 0 deletions
@@ -0,0 +1,96 @@
+# Referência de Configuração
+
+Este documento descreve todos os campos coletados pelo instalador e os arquivos que
+ele gera.
+
+## Arquivo `config.toml`
+
+Gerado por `GenerateConfigTOML` em
+[`internal/tui/config.go`](../internal/tui/config.go) e montado no container do app em
+`/app/config.toml`. Se um `config.toml` já existir no diretório ao iniciar o
+instalador, seus valores são usados como **padrão** nos formulários.
+
+### `[server]`
+
+| Campo             | Origem (formulário)           | Observações                                                  |
+| ----------------- | ----------------------------- | ------------------------------------------------------------ |
+| `port`            | **fixo `8080`** no arquivo    | A porta do formulário é usada apenas no **mapeamento do host** (`<porta>:8080`). Dentro do container o app sempre escuta na `8080`. |
+| `timeout_seconds` | Servidor → Timeout            | Em segundos. Padrão `30`.                                    |
+| `environment`     | Servidor → Ambiente           | `development` ou `production`.                                |
+
+> **Atenção:** o campo "Porta" do formulário define a porta exposta no host, não a
+> porta interna. O `config.toml` sempre grava `port = 8080`.
+
+### `[database]`
+
+| Campo       | Origem               | Observações                          |
+| ----------- | -------------------- | ------------------------------------ |
+| `type`      | Banco → Tipo do Banco| `postgres` ou `oracle`.              |
+| `url`       | Banco → URL de acesso| String de conexão completa.          |
+| `max_conns` | Banco → Conexões máx.| Validado como número.                |
+| `min_conns` | Banco → Conexões mín.| Validado como número.                |
+
+### `[certificate]`
+
+| Campo        | Valor                                | Observações                                  |
+| ------------ | ------------------------------------ | -------------------------------------------- |
+| `mapped_dir` | Certificado → Diretório              | Diretório local montado em `/app/certs`.     |
+| `cert_path`  | `/app/certs/client.crt` (fixo)       | Caminho **dentro** do container.             |
+| `key_path`   | `/app/certs/client.key` (fixo)       | Caminho **dentro** do container.             |
+| `ca_path`    | `/app/certs/ca.crt` (fixo)           | Caminho **dentro** do container.             |
+
+O diretório indicado deve conter os arquivos `client.crt`, `client.key` e `ca.crt`
+(comunicação mTLS com o servidor central).
+
+### `[application]`
+
+| Campo                | Origem                          | Observações                          |
+| -------------------- | ------------------------------- | ------------------------------------ |
+| `erp`                | `TOTVS` (fixo)                  | ERP integrado.                       |
+| `central_server_url` | Aplicação → URL Servidor Central| Ex.: `https://app-dono-api.vitruvio.com.br:8443`. |
+| `enrollment_token`   | Aplicação → Token de Inscrição  | Gerado no painel web.                |
+
+### `[log]`
+
+| Campo    | Valor             |
+| -------- | ----------------- |
+| `level`  | `debug` (fixo)    |
+| `format` | `json` (fixo)     |
+
+## Arquivo `envs` (vproxy / WireGuard)
+
+Gerado por `GenerateWireguardConfig` apenas quando **não há IP público**. Passado ao
+container do vproxy via `--env-file`.
+
+| Variável     | Origem                  | Observações                                                  |
+| ------------ | ----------------------- | ------------------------------------------------------------ |
+| `PRIVKEY`    | vproxy → Chave Privada  | Chave privada WireGuard.                                     |
+| `VIP`        | vproxy → IP Virtual     | Padrão `127.0.0.1`.                                          |
+| `PSK`        | vproxy → Pre-Shared Key | Chave pré-compartilhada.                                     |
+| `PROXY_EDPS` | vproxy → Proxy EDPS     | Mapeamento de portas, ex.: `22:127.0.0.1:22`.               |
+| `MTU`        | vproxy → MTU            | Opcional. Padrão `1380`. Validado como número.              |
+| `PROTO`      | vproxy → Protocolo      | `UDP` (padrão) ou `TCP`.                                     |
+
+### Sobre o protocolo
+
+- **UDP** (padrão): melhor desempenho e estabilidade. Manter sempre que possível.
+- **TCP**: usar apenas quando firewalls restritivos bloqueiam o tráfego UDP e não for
+  possível negociar a liberação com o cliente.
+
+## Campo "Modo Compatibilidade"
+
+Presente no formulário de Servidor (`seccomp_unconfined`). Quando definido como
+**`Sim`**, os containers sobem com `--security-opt seccomp=unconfined`. Útil em
+máquinas antigas onde o perfil seccomp padrão do Docker causa falhas. Aplica-se tanto
+ao container do app quanto ao do vproxy.
+
+## Tipos de campo dos formulários
+
+Definidos em [`internal/tui/form.go`](../internal/tui/form.go):
+
+| Tipo               | Comportamento                                  |
+| ------------------ | ---------------------------------------------- |
+| `FieldTypeText`    | Texto livre.                                   |
+| `FieldTypePassword`| Texto mascarado.                               |
+| `FieldTypeNumber`  | Texto (validação numérica na gravação).        |
+| `FieldTypeSelect`  | Opções alternadas com `←`/`→`.                 |