# Plano de Âmbito — Arquivo Geral de Documentos (além do financeiro)

Estado: plano aprovado ao nível de âmbito; desenho detalhado e implementação por
iniciar. Este documento não altera código nem esquema; serve para fixar o âmbito
antes de desenhar o trabalho técnico, que continuará a ser detalhado na fase F7 do
`docs/project-todo.md`.

## Motivação

A Sibyla arquiva hoje apenas documentos financeiros (faturas, faturas-recibo, notas
de crédito/débito, recibos, extratos bancários — `FinancialDocumentType`), com um
pipeline construído à volta da integração determinística em Excel/Cegid.

O pedido de negócio é mais amplo: arquivar **todos** os documentos relevantes da
empresa, não só os financeiros, cada um organizado, pesquisável e ligado à sua área
(empresa interna, departamento, e/ou contraparte), incluindo:

- Contratos de arrendamento (imóveis, escritórios, armazéns).
- Apólices e contratos de seguro.
- Contratos com clientes, incluindo avenças (prestação de serviços recorrente).
- Contratos com fornecedores.
- Contratos de trabalho.
- Licenças (de software, de atividade, alvarás, certificações).
- Financiamentos (empréstimos, linhas de crédito).
- Leasing / ALD (viaturas e equipamento).
- Outras categorias a definir à medida que surgirem necessidades reais (o desenho
  deve permitir adicionar categorias sem reescrever o modelo).

## Decisões de âmbito já tomadas

1. **Reaproveitar o pipeline Hermes.** Estes documentos devem passar pelo mesmo
   padrão de extração/catalogação automática que hoje serve os documentos
   financeiros (upload → extração assistida por IA → gates determinísticos onde
   fizerem sentido → revisão humana quando a confiança for insuficiente), em vez de
   um simples upload com tags manuais. Isto implica um novo contrato de extração
   (equivalente ao `sibyla.extraction.v3.1`, mas para metadados contratuais: partes,
   datas, valores, prazos de aviso prévio, renovação automática, etc.) e,
   provavelmente, um novo perfil/instrução Hermes dedicado (ou uma extensão
   claramente delimitada do `documental-agent`), porque os campos a extrair e as
   regras de evidência são diferentes dos documentos financeiros.
2. **Incluir alertas de vencimento/renovação no âmbito.** Datas de início, fim,
   renovação e pré-aviso são metadados de primeira classe, não apenas texto livre.
   O âmbito inclui um mecanismo de alerta antes do vencimento (ex.: contrato de
   arrendamento a renovar, seguro a expirar, licença a caducar, leasing a terminar).
3. **Faseamento.** Esta expansão entra como uma nova fase **F7**, depois do roadmap
   financeiro atual (F0–F6), sem alterar o faseamento nem as prioridades já
   definidas para o MVP financeiro. F7 pode começar a ser desenhada em detalhe antes
   de F0–F6 estarem 100% concluídas, mas não deve consumir capacidade de engenharia
   à frente dos gates de segurança e produção já identificados para o financeiro.

## Por que isto não é apenas "adicionar valores a `FinancialDocumentType`"

`FinancialDocumentType` é deliberadamente um enum fechado
(`src/Sibyla.Domain/Documents/DocumentTypeSettingsContracts.cs`, comentário na
interface `IDocumentTypeSettingsService`): está amarrado à lógica determinística de
elegibilidade de integração financeira (`FinancialIntegrationEligibility`) e à
taxonomia de extração do Hermes financeiro. Não é seguro nem correto misturar
"Contrato de Arrendamento" ou "Apólice de Seguro" nesse mesmo enum.

O desenho terá de introduzir, a par do `FinancialDocumentType` existente, uma
segunda família de tipo de documento — por exemplo um `DocumentFamily`
(`Financial` | `CorporateArchive`) ao nível do `Document`, com uma taxonomia própria
para o arquivo geral (ex.: `CorporateDocumentType`: `Lease`, `InsurancePolicy`,
`ClientContract`, `ClientRetainer` (avença), `SupplierContract`,
`EmploymentContract`, `License`, `Financing`, `LeaseFinancing` (ALD), `Other`). Os
dois pipelines partilham a infraestrutura comum já existente (registo, storage
imutável do original, hash, revisões, auditoria, jobs) mas divergem depois da
extração: o financeiro segue para os gates de IVA/Excel/Cegid; o arquivo geral segue
para gates de metadados contratuais (partes resolvidas, datas coerentes, sem
integração Excel/Cegid).

## Ligação "à sua área"

O modelo já tem os blocos certos para isto e devem ser reaproveitados, não
reinventados:

- `BusinessEntity` com `EntityRoleAssignment` (`InternalCompany`, `Supplier`,
  `Customer`) já cobre senhorio/inquilino, seguradora, cliente e fornecedor como
  contrapartes. Pode precisar de um papel novo (`Counterparty` genérico, ou papéis
  específicos como `Insurer`, `Landlord`, `Lender`, `LeasingCompany`) consoante o
  nível de granularidade que se quiser nos relatórios e alertas.
- `DepartmentId` já liga um documento a um departamento da empresa interna.
- Contratos de trabalho não têm hoje uma contraparte-pessoa modelada (o domínio
  atual só conhece `BusinessEntity` e `Identity.User`/membership). É preciso decidir
  se a contraparte de um contrato de trabalho é uma referência a um `User` existente,
  uma nova entidade "Colaborador" leve, ou apenas texto livre com pesquisa (mais
  simples, menos estruturado). Fica como decisão em aberto para o desenho F7.
- Avenças (contratos de cliente com faturação recorrente) são o caso que mais
  claramente atravessa as duas famílias: o contrato em si pertence ao arquivo geral,
  mas as faturas que ele gera continuam a ser documentos financeiros normais. O
  desenho deve permitir ligar um `CorporateDocument` de avença aos `Document`
  financeiros recorrentes que ele origina (mesmo `CounterpartyEntityId`, e
  idealmente uma referência explícita ao contrato de origem), para que se veja
  facilmente "que faturas pertencem a esta avença".

## Pesquisa

"Pesquisável" implica pesquisa por texto sobre metadados estruturados (partes,
datas, tipo, departamento) e, idealmente, sobre o conteúdo do próprio documento. A
Sibyla já tem uma componente de extração de texto de PDF
(`src/Sibyla.PdfTextExtractor`) reaproveitável como base para indexação de texto
completo; falta decidir o motor de pesquisa (índice PostgreSQL `tsvector`/`pg_trgm`,
suficiente à escala esperada, versus um motor de pesquisa dedicado) — decisão a
tomar no desenho F7, não agora.

## Alertas de vencimento/renovação

Metadados mínimos por documento do arquivo geral: `EffectiveDate`, `ExpiryDate`,
`RenewalDate`, `NoticePeriodDays`, `AutoRenews` (bool). Um job periódico (no mesmo
padrão dos jobs de manutenção já previstos em F3) verifica documentos a X dias do
vencimento/pré-aviso e gera alertas para o(s) responsável(is) do departamento/
empresa interna associado. Canal de alerta (email, Mattermost, painel na Web) fica
por decidir no desenho F7 — pode reaproveitar os canais Hermes Gateway já
existentes para outras notificações.

## Fora de âmbito nesta fase de planeamento

- Qualquer alteração de esquema, migração, entidade ou código.
- Escolha final da taxonomia completa de `CorporateDocumentType` (a lista acima é de
  arranque; deve ser validada com o negócio antes do desenho técnico).
- Escolha do motor de pesquisa e do canal de alertas.
- Modelação da contraparte de contratos de trabalho (pessoa vs texto livre).

## Próximo passo

Detalhar F7 em `docs/project-todo.md` ao nível de backlog (já feito neste commit de
planeamento) e, quando F7 for priorizada, produzir um plano técnico ao nível dos
planos já existentes (`docs/document-cataloging-remediation-plan.md` é o padrão de
detalhe a seguir), cobrindo esquema, contrato de extração, instruções Hermes,
serviços, API e UI.