# 1. Visão Geral Da Arquitetura

## Stack recomendada

- Frontend: React com Vite, React Router, TanStack Query, React Hook Form e Zod.
- Backend: Node.js com arquitetura modular; para manutenção de longo prazo, a recomendação é `Fastify + módulos por domínio + Prisma` no app layer.
- Banco: MySQL 8 como banco transacional principal.
- Storage: S3 compatível, abstraído por `files` + `document_records` + `generated_documents`.
- Fila: Redis + BullMQ para OCR, extração, consolidação de fatos, geração de questionário e montagem de pacote.
- OCR/extração: pipeline assíncrono com OCR, parser documental e normalização para `document_extractions`.
- IA: camada orquestradora por tenant, sempre resolvendo a credencial ativa do `law_firm`.

## Arquitetura lógica

1. O frontend React opera como backoffice jurídico e portal seguro do cliente.
2. O backend expõe APIs por domínio: identidade, clientes, casos, repositório, workflows, forms, fatos, questionário, IA e auditoria.
3. O MySQL armazena o estado transacional, os catálogos, a rastreabilidade e a auditoria jurídica.
4. O storage externo guarda binários; o banco guarda metadados, classificação, checksums e vínculo com caso/cliente.
5. A fila executa tarefas pesadas e reprocessamentos sem bloquear o fluxo operacional.

## Uso de API key por tenant

- Cada escritório possui suas próprias credenciais em `law_firm_ai_credentials`.
- A configuração operacional fica em `law_firm_ai_settings`.
- Nenhuma chamada usa chave global.
- A chave fica apenas criptografada em `encrypted_api_key`.
- Cada `ai_run` referencia a credencial usada por `api_key_reference_id`.
- A rotação é suportada por `rotated_from_credential_id`, `is_active`, `is_default` e `key_last4`.

## Fluxo do questionário inteligente

1. O sistema dispara `questionnaire_runs` após analisar workflow, forms, documentos, mensagens, fatos e extrações.
2. A análise registra fontes consultadas em `questionnaire_run_sources`.
3. Cada formulário avaliado gera cobertura por campo em `questionnaire_run_forms` e `questionnaire_run_field_results`.
4. O motor cria `information_requests` e abre uma `questionnaire_session` com token seguro.
5. A IA gera apenas perguntas necessárias em `questionnaire_questions`.
6. Cada resposta entra em `questionnaire_answers`, pode criar/atualizar `case_facts` e dispara reavaliação.
7. A sessão encerra automaticamente quando não houver mais pendências obrigatórias.

# 2. Lista Das Tabelas

## Estrutura do escritório e acesso

- `law_firms`: tenant principal do sistema.
- `offices`: filiais/unidades do escritório.
- `roles`: perfis base do tenant.
- `permissions`: permissões por módulo.
- `role_permissions`: associação entre perfis e permissões.
- `users`: funcionários do escritório.
- `user_offices`: vínculo de usuários com filiais.
- `user_roles`: papéis atribuídos ao usuário, com escopo.

## Catálogos

- `case_statuses`: catálogo de status de casos.
- `repository_item_types`: catálogo de tipos do repositório unificado.
- `channels`: catálogo de canais de entrada/saída.
- `document_types`: catálogo de documentos jurídicos.
- `ai_run_types`: catálogo de operações de IA.
- `questionnaire_statuses`: catálogo de status de sessões do questionário.

## Clientes e processos

- `clients`: cadastro principal do cliente.
- `client_addresses`: endereços do cliente.
- `client_identifiers`: identificadores oficiais do cliente.
- `cases`: processos/casos por cliente.
- `case_timeline_events`: eventos, marcos e deadlines do caso.
- `related_parties`: spouse, child, employer, petitioner, preparer, interpreter e dependents.

## IA por escritório e auditoria de execução

- `law_firm_ai_credentials`: credenciais criptografadas por escritório.
- `law_firm_ai_settings`: configuração operacional da IA por escritório.
- `ai_runs`: trilha de execução, tokens, custo, modelo e credencial usada.

## Repositório unificado e evidências

- `repository_items`: cabeçalho unificado de qualquer evidência/interação; operacionalmente tende a apontar para cliente, mas aceita artefatos de tenant como templates e assets internos.
- `conversations`: agrupamento de threads por canal.
- `files`: metadados de arquivos em storage externo.
- `messages`: mensagens de email, WhatsApp e similares.
- `call_logs`: chamadas telefônicas e transcrições.
- `form_submissions`: submissões estruturadas.
- `document_records`: registro jurídico/classificação documental.
- `document_extractions`: extrações estruturadas a partir de documentos.

## Workflow e formulários

- `form_templates`: templates/versionamento de formulários.
- `data_fields`: catálogo universal de campos de dados.
- `form_fields`: campos dos formulários PDF/base.
- `workflow_templates`: templates de fluxo por tipo de caso.
- `workflow_steps`: etapas ordenadas do fluxo.
- `workflow_required_documents`: documentos requeridos pelo workflow.
- `workflow_required_forms`: formulários requeridos pelo workflow.
- `workflow_instances`: instância real do workflow no caso.
- `workflow_step_instances`: execução real das etapas.
- `case_required_documents`: exigências documentais materializadas no caso.
- `case_forms`: formulários materializados no caso.

## Fatos estruturados e pendências

- `missing_information_rules`: regras para detectar lacunas.
- `information_requests`: solicitação consolidada de dados pendentes.
- `information_request_items`: itens individuais faltantes.
- `client_portal_sessions`: sessão segura de portal/link.
- `client_chat_messages`: chat do portal do cliente.
- `case_facts`: fatos estruturados, versionados e rastreáveis.
- `fact_sources`: fontes/evidências de cada fato.

## Questionário inteligente por link

- `questionnaire_runs`: execução de análise de lacunas.
- `questionnaire_run_sources`: fontes consultadas pela análise.
- `questionnaire_run_forms`: formulários avaliados na análise.
- `questionnaire_run_field_results`: cobertura por campo avaliado.
- `questionnaire_sessions`: sessão segura do questionário.
- `questionnaire_questions`: perguntas geradas dinamicamente.
- `questionnaire_question_targets`: campos-alvo de cada pergunta.
- `generated_documents`: artefatos gerados pelo sistema/IA.
- `questionnaire_answers`: respostas do cliente.
- `questionnaire_events`: eventos e reavaliações da sessão.

## Geração e montagem final

- `form_mappings`: mapeamento entre campo universal e campo PDF.
- `form_fill_runs`: execuções de preenchimento de formulário.
- `packet_templates`: template de pacote final.
- `packet_template_items`: itens ordenados do pacote.
- `case_packets`: pacote gerado para um caso.
- `case_packet_items`: itens concretos do pacote.

## Auditoria e revisão humana

- `audit_logs`: log de alterações críticas.
- `reviews`: revisão humana de artefatos, fatos ou saídas de IA.

# 3. SQL MySQL 8 Completo

- Schema completo: [`database/mysql/001_schema.sql`](/Users/mini1/Downloads/neurav2/database/mysql/001_schema.sql)
- Seeds iniciais: [`database/mysql/002_seed_master_data.sql`](/Users/mini1/Downloads/neurav2/database/mysql/002_seed_master_data.sql)

## Decisões de modelagem relevantes

- IDs principais em `CHAR(36)` para uso com UUIDv7 gerado pela aplicação.
- Lookup tables com PK natural por `code` para facilitar seed, governança e integração.
- `law_firm_id` presente nos domínios transacionais para isolamento multi-tenant.
- JSON usado apenas para regras condicionais, snapshots, payloads flexíveis e extrações.
- Soft delete aplicado onde a preservação histórica importa operacionalmente.

# 4. Explicação Dos Relacionamentos

## Tenant e segurança

- `law_firms` é a raiz de isolamento.
- `offices`, `users`, `clients`, `cases`, `law_firm_ai_credentials`, `ai_runs`, `repository_items`, `workflow_instances`, `case_facts`, `questionnaire_sessions` e `audit_logs` herdam o tenant.
- `law_firm_ai_settings.active_credential_id` aponta para a credencial operacional atual.
- `ai_runs.api_key_reference_id` aponta exatamente qual credencial foi usada.

## Cliente, caso e repositório

- Um `client` pode ter múltiplos `cases`.
- Um `case` pode ter múltiplos `related_parties`.
- Todo item relevante de evidência entra em `repository_items`.
- Tabelas especializadas como `messages`, `call_logs`, `files`, `form_submissions`, `generated_documents` e `questionnaire_answers` podem se ligar ao mesmo repositório.

## Workflow e formulários

- `workflow_templates` definem a estrutura reutilizável.
- `workflow_steps`, `workflow_required_documents` e `workflow_required_forms` descrevem ordem e requisitos.
- Ao ativar um fluxo em um caso, o sistema cria `workflow_instances`, `workflow_step_instances`, `case_required_documents` e `case_forms`.
- `form_templates` e `form_fields` guardam a estrutura dos formulários.
- `form_mappings` liga `data_fields` a `form_fields`.

## Fatos e rastreabilidade

- `case_facts` representa cada valor consolidado ou proposto.
- Um fato pode pertencer ao cliente, ao caso ou a uma `related_party`.
- `fact_sources` guarda as evidências que sustentam aquele fato, inclusive `repository_items` e `ai_runs`.
- Isso permite preencher formulário com rastreabilidade jurídica completa.

## Questionário inteligente

- `questionnaire_runs` é a análise de lacunas.
- `questionnaire_run_sources` registra o que foi consultado.
- `questionnaire_run_forms` e `questionnaire_run_field_results` mostram cobertura por formulário/campo.
- `information_requests` e `information_request_items` representam a pendência de negócio.
- `questionnaire_sessions` abre a experiência do cliente.
- `questionnaire_questions` e `questionnaire_question_targets` modelam perguntas dinâmicas e seus objetivos.
- `questionnaire_answers` pode gerar `case_facts`.
- `questionnaire_events` registra reavaliações, encerramento e decisões automáticas.

# 5. Inserts Iniciais

- Arquivo: [`database/mysql/002_seed_master_data.sql`](/Users/mini1/Downloads/neurav2/database/mysql/002_seed_master_data.sql)
- Inclui:
  - `roles`
  - `permissions`
  - `role_permissions`
  - `case_statuses`
  - `repository_item_types`
  - `document_types`
  - `channels`
  - `ai_run_types`
  - `questionnaire_statuses`

# 6. Sugestão De Estrutura De Projeto

## Monorepo

```text
apps/
  api/
    src/
      modules/
        auth/
        law-firms/
        users/
        clients/
        cases/
        repository/
        documents/
        workflows/
        forms/
        facts/
        ai/
        questionnaires/
        packets/
        audit/
      infra/
        db/
        queue/
        storage/
        encryption/
        events/
      shared/
        domain/
        dto/
        errors/
        utils/
  web/
    src/
      app/
      pages/
      components/
      features/
        law-firms/
        clients/
        cases/
        repository/
        questionnaires/
        forms/
        packets/
      lib/
      hooks/
      styles/
database/
  mysql/
docs/
packages/
  config/
```

## Backend

- `modules/ai`: resolução de credencial por tenant, orçamento, auditoria e política de execução.
- `modules/repository`: unificação de emails, documentos, chamadas, notas e mensagens.
- `modules/facts`: consolidação, conflitos, confirmação humana e rastreabilidade.
- `modules/questionnaires`: gap analysis, sessão segura, perguntas, respostas e reavaliação.
- `infra/encryption`: envelope encryption com AES-256-GCM + KMS/Vault em produção.
- `infra/queue`: OCR, classificação, extraction, re-evaluation e packet assembly.

## Frontend React

- `features/questionnaires`: painel de gaps, sessão do cliente, fila de perguntas e revisões.
- `features/repository`: timeline unificada do cliente/caso.
- `features/forms`: cobertura de formulário, confiança por campo e rastreabilidade.
- `features/packets`: montagem final e checklist de evidências.

# 7. Escopo Do MVP

## Tabelas essenciais para lançar

- `law_firms`
- `offices`
- `roles`
- `permissions`
- `role_permissions`
- `users`
- `user_roles`
- `clients`
- `client_addresses`
- `client_identifiers`
- `cases`
- `related_parties`
- `law_firm_ai_credentials`
- `law_firm_ai_settings`
- `ai_run_types`
- `ai_runs`
- `repository_item_types`
- `channels`
- `repository_items`
- `files`
- `document_types`
- `document_records`
- `document_extractions`
- `form_templates`
- `data_fields`
- `form_fields`
- `workflow_templates`
- `workflow_steps`
- `workflow_required_documents`
- `workflow_required_forms`
- `workflow_instances`
- `case_required_documents`
- `case_forms`
- `case_facts`
- `fact_sources`
- `missing_information_rules`
- `information_requests`
- `information_request_items`
- `client_portal_sessions`
- `questionnaire_statuses`
- `questionnaire_runs`
- `questionnaire_run_sources`
- `questionnaire_run_forms`
- `questionnaire_run_field_results`
- `questionnaire_sessions`
- `questionnaire_questions`
- `questionnaire_question_targets`
- `questionnaire_answers`
- `questionnaire_events`
- `form_mappings`
- `form_fill_runs`
- `generated_documents`
- `audit_logs`

## O que o MVP já cobre

- multi-tenant por escritório;
- ingestão documental e de interações;
- extração de fatos com rastreabilidade;
- análise de lacunas;
- questionário inteligente por link;
- preenchimento inicial de formulários;
- trilha auditável mínima para ambiente jurídico.

# Melhorias Futuras

- particionamento por `law_firm_id` ou por tempo em tabelas de alto volume;
- busca textual híbrida com OpenSearch/Meilisearch para repositório e evidências;
- versionamento explícito de prompts/templates de IA;
- tabela dedicada de conflito de fatos para revisão humana assistida;
- serviço separado para `ai_runs` e orçamento quando o volume crescer;
- serviço separado de `repository`/ingestão quando integrações omnichannel aumentarem.

# Índices Extras Prováveis

- `repository_items (law_firm_id, client_id, item_type_code, occurred_at)`
- `case_facts (law_firm_id, data_field_id, status_code, confidence_score)`
- `questionnaire_questions (questionnaire_session_id, status_code, priority, sequence_no)`
- `document_records (law_firm_id, document_type_code, expiration_date)`
- `ai_runs (law_firm_id, ai_run_type_code, created_at)`