# BriefApp TechConsult Contability — Especificação Técnica Integral MCP & Generative UI (LLMs Full Context)

> Este documento é a referência técnica consolidada do BriefApp TechConsult Contability. Destina-se a modelos de linguagem e agentes autônomos (Claude Code, Cursor, Antigravity IDE, Windsurf, ChatGPT) que operam com janelas de contexto estendidas e precisam orquestrar dados contábeis, pipelines Medallion, regras de Data Quality e gerar relatórios visuais perfeitos em produção sem alucinações.

- **MCP Base URL:** `http://localhost:58180/mcp`
- **Portal & Relatórios:** `http://localhost:58180`
- **Transportes:** HTTP Streaming (SSE) e Stdio
- **Contrato OpenAPI v1:** `openapi/v1.json`
- **MCP Server Card:** `.well-known/mcp/server-card.json`
- **Armazenamento:** MinIO S3, LanceDB Vetorial, DuckDB OLAP, SQLite e Datalake Medallion

---

## 1. Convenções Globais & Regras Inegociáveis

1. **Isolamento por clientId:** Todo dado é estritamente escopado por `clientId`. Nunca invente um identificador; confirme com o usuário ou chame `list_clients`.
2. **Criar Empresa ≠ Criar Usuário:** "Criar empresa/cliente" no TechConsult significa invocar `set_client_theme` com um `clientId` novo (o cliente nasce implicitamente com sua identidade visual). `create_client_user` serve apenas para credenciais de login em containers dedicados.
3. **Guardrail de SQL Read-Only:** Todas as consultas enviadas via MCP (`query_gold_catalog`, `query_datalake`, `query_form_data`, `query_structured_file`) aceitam estritamente comandos `SELECT` e `WITH`. Comandos `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER` e `TRUNCATE` são sumariamente rejeitados. Mutações ocorrem apenas via tools específicas com auditoria.
4. **Regra de Ouro Pré-Relatório:** SEMPRE chame `get_gold_catalog(clientId)` antes de gerar qualquer relatório ou dashboard. Se os dados já estiverem processados na camada Gold, utilize `query_gold_catalog` como fonte — nunca reprocesse dados brutos já refinados.
5. **Auto-routing Obrigatório:** Ao receber uma nova planilha ou arquivo contábil bruto, execute `auto_route_file` antes de criar pipelines manuais. Se houver correspondência com schemas conhecidos (balancetes de Totvs, SAP, Omie, ContaAzul, Domínio), o pipeline correto é sugerido ou disparado.
6. **Linguagem de Negócio:** Na comunicação com usuários finais, utilize os termos:
   - "Planilha Original" para a Camada Bronze;
   - "Validação e Qualidade" para a Camada Silver;
   - "Prontos p/ Relatório" para a Camada Gold.

---

## 2. Generative + UI & Visualizações ECharts

O motor **Generative + UI** é o coração da experiência visual do TechConsult. Ele não se limita a tabelas simples; ele projeta sistemas analíticos:

### 2.1 Componentes Suportados
- **Waterfall Chart (Cascata DRE):** Receita Operacional Bruta → Deduções Fiscais → Receita Líquida → Custos dos Produtos Vendidos (CPV/CMV) → Margem de Contribuição → Despesas Operacionais → EBITDA → Lucro Líquido.
- **Stacked Bars (Barras Empilhadas):** Composição de custos fixos vs. variáveis por centro de custo ao longo dos trimestres.
- **Dual Axis Line & Bar:** Margem Percentual vs. Faturamento Bruto.
- **Heatmap Fiscal:** Matriz de calendários de tributos (IRPJ, CSLL, PIS, COFINS, ISS) com criticidade e datas de vencimento.
- **Drilldown Interativo:** Ao clicar em qualquer elemento do gráfico, o relatório abre um modal ou banner com os registros individuais da camada Silver/Gold.

### 2.2 Relatórios Snapshot vs. Ao Vivo
- `generate_report_html`: Cria um snapshot HTML autônomo com ECharts embutido, estilos do cliente injetados e tabelas ordenáveis.
- `generate_live_report`: Cria um dashboard reativo que consulta a camada Gold a cada carregamento ou filtro aplicado pelo usuário.
- `publish_report`: Gera uma URL protegida no portal (`https://portal.techconsult.app/reports/...`) com controle de acesso.

---

## 3. Arquitetura Medallion Contábil

### 3.1 Camada Bronze (Planilha Original)
- Armazena arquivos brutos no MinIO particionados por cliente (`clientId/bronze/...`).
- Suporta CSV, XLSX, Parquet, JSON, extratos bancários OFX e PDFs escaneados.
- **Parsing Multimodal:** Apache Tika realiza OCR e extração estrutural; modelos Gemini Flash identificam colunas contábeis e estruturam dados para tabelas tabulares.

### 3.2 Camada Silver (Validação & Qualidade)
- Normalização de tipos (datas para ISO 8601, moeda para decimal brasileiro com ponto, strings em UTF-8 limpas).
- **Regras de Data Quality (`add_dq_rule`):**
  - `balance_debit_credit`: validação de partidas dobradas (soma de débitos igual à soma de créditos).
  - `not_null`: campos obrigatórios como CNPJ, data de competência e código contábil.
  - `regex`: validação de formato de CNPJ (`^\d{2}\.\d{3}\.\d{3}/\d{4}-\d{2}$`) e chaves de NF-e.
  - `range`: valores monetários não negativos para despesas e receitas.
- `get_dq_report`: devolve o percentual de conformidade e linhas reprovadas antes do avanço para a Gold.

### 3.3 Camada Gold (Prontos p/ Relatório)
- Modelagem dimensional (fatos e dimensões): `f_lancamentos_contabeis`, `d_plano_contas`, `d_centro_custo`, `d_calendario`.
- Armazenamento em arquivos Parquet de alta compressão consultáveis instantaneamente por DuckDB.
- `get_gold_catalog` lista as visões homologadas prontas para uso por relatórios e agentes de IA.

---

## 4. Catálogo Detalhado de Ferramentas MCP

### 4.1 Engenharia de Dados & Pipelines
- `create_pipeline(clientId, name, sourceType, targetLayer, scheduleCron)`: Cria definição de pipeline.
- `run_pipeline(clientId, pipelineId)`: Dispara execução de transformação de dados.
- `list_pipelines(clientId)`: Lista pipelines e status de execuções.
- `auto_route_file(clientId, filePath)`: Identifica schema e recomenda pipeline Bronze.
- `get_pipelines_overview(clientId)`: Dashboard de saúde do Datalake.

### 4.2 Data Quality
- `add_dq_rule(clientId, tableName, ruleType, columnName, expression)`: Cadastra regra de validação na Silver.
- `remove_dq_rule(clientId, ruleId)`: Remove regra de auditoria.
- `validate_data(clientId, tableName)`: Executa validação e lista divergências.
- `get_dq_report(clientId)`: Relatório executivo de qualidade de dados.

### 4.3 Camada Gold & Consultas
- `get_gold_catalog(clientId)`: Metadados das tabelas prontas para consumo.
- `query_gold_catalog(clientId, query)`: Query SQL SELECT nas tabelas Gold.
- `query_datalake(clientId, query)`: Consulta transversal com DuckDB.
- `get_datalake_schema(clientId, layer, tableName)`: Schema estrutural de tabelas.

### 4.4 Generative + UI & Relatórios
- `generate_report_html(clientId, title, data, chartsConfig, enableDrilldown)`: Compõe HTML com ECharts.
- `generate_live_report(clientId, title, queries, theme)`: Dashboard ao vivo conectado ao Datalake.
- `publish_report(clientId, reportHtml, title)`: Publica relatório no portal corporativo.
- `list_published_reports(clientId)`: Lista relatórios ativos com contadores de acesso.

### 4.5 Formulários Dinâmicos SQLite
- `generate_form(clientId, formName, schema)`: Cria formulário customizado em SQLite.
- `query_form_data(clientId, formName, whereClause)`: Consulta lançamentos manuais.
- `update_form_record(clientId, formName, recordId, values, justification)`: Atualiza lançamento gravando auditoria.
- `set_form_record_status(clientId, formName, recordId, status)`: Altera status (aprovado, rejeitado, rascunho).
- `get_record_history(clientId, formName, recordId)`: Histórico com autor, data e justificativa.
- `get_form_import_template(clientId, formName)`: Template Excel com validações de tipo.
- `import_form_data(clientId, formName, records)`: Ingestão em lote de lançamentos manuais.

### 4.6 RAG Contábil & Storage
- `upload_document(clientId, fileName, fileContent)`: Upload no MinIO seguro.
- `process_document_for_rag(clientId, filePath)`: Extração Tika + indexação LanceDB.
- `search_financial_data(clientId, query, limit)`: Busca vetorial em contratos e faturas.
- `search_hybrid(clientId, query, filter)`: Busca combinada vetorial e metadados.
- `list_stored_files(clientId)`: Lista arquivos no storage.
- `get_file_url(clientId, filePath)`: URL assinada para imagens e documentos.

### 4.7 DuckDB & Notebooks
- `catalog_notebook(clientId, title, notebookPath)`: Indexação de notebook analítico.
- `search_notebooks(clientId, query)`: Busca de notebooks por palavra-chave.
- `create_notebook_schedule(clientId, notebookPath, cronExpression)`: Agendamento periódico de execução.

### 4.8 Governança, Temas & Status
- `set_client_theme(clientId, theme)`: Logotipo, cores e fontes white-label da empresa cliente.
- `get_client_theme(clientId)`: Recupera configurações de marca do cliente.
- `list_clients()`: Lista todas as empresas registradas no servidor.
- `create_medida(clientId, name, formula, category)`: Cadastra fórmula ou KPI reutilizável.
- `list_medidas(clientId)`: Lista medidas homologadas.
- `get_system_status()`: Saúde geral dos subsistemas (MinIO, LanceDB, SQLite, DuckDB, Tika).

---

## 5. Como Conectar seu Agente de IA

### Claude Desktop / Claude Code
Adicione em seu `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "tech-consult-contability": {
      "command": "node",
      "args": ["c:/projetos/tech-consult-contability/src/mcp-server.js"]
    }
  }
}
```

### Cursor IDE
Adicione nas configurações de MCP do Cursor (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "tech-consult-contability": {
      "url": "http://localhost:58180/mcp"
    }
  }
}
```

### Antigravity IDE
O servidor já está conectado como lazy MCP sob o nome `tech-consult-contability`.
Invoque qualquer ferramenta via `call_mcp_tool`.