# GED — Documentos privados

## 1. Objetivo

O módulo GED armazena documentos jurídicos e administrativos vinculados aos clientes do escritório. O arquivo permanece privado e somente usuários autenticados, com permissão explícita e pertencentes ao mesmo escritório, podem acessar seus metadados ou gerar uma URL temporária de download.

## 2. Entidade principal

A tabela `documents` registra:

- UUID público usado nas rotas;
- escritório e cliente proprietários;
- usuário que enviou, atualizou ou excluiu;
- categoria, título, descrição, data e tags;
- nome original do arquivo;
- disco e caminho privados;
- MIME type, extensão e tamanho;
- checksum SHA-256;
- status `active` ou `archived`;
- timestamps e soft delete.

O ID numérico interno não é exposto nas URLs do GED.

## 3. Armazenamento

O disco é definido por `DOCUMENTS_DISK`. Produção deve usar:

```dotenv
DOCUMENTS_DISK=s3
```

Os arquivos são gravados no padrão:

```text
offices/{office_id}/clients/{client_id}/documents/{uuid}.{extension}
```

O nome físico é aleatório. O nome enviado pelo usuário existe apenas como metadado em `original_name`.

O bucket S3 deve permanecer privado. Não configure ACL pública, URL pública permanente ou listagem pública do bucket.

## 4. Formatos e tamanho

Formatos aceitos por padrão:

- PDF;
- DOC e DOCX;
- XLS e XLSX;
- JPG, JPEG e PNG;
- TXT.

O tamanho máximo padrão é 20 MB e pode ser alterado por:

```dotenv
DOCUMENTS_MAX_SIZE_KB=20480
```

Alterações na lista de formatos devem ser feitas em `config/documents.php` e acompanhadas de testes.

## 5. Categorias

Categorias oficiais:

```text
contract
power_of_attorney
petition
evidence
court_decision
identification
financial
correspondence
other
```

Novas categorias devem preservar compatibilidade com o frontend e a documentação OpenAPI.

## 6. Endpoints

```http
GET    /api/v1/documents
POST   /api/v1/documents
GET    /api/v1/documents/{document}
PUT    /api/v1/documents/{document}
GET    /api/v1/documents/{document}/download-url
DELETE /api/v1/documents/{document}
```

O parâmetro `{document}` recebe o UUID público.

## 7. Upload

O upload usa `multipart/form-data`.

Campos obrigatórios:

- `client_id`;
- `category`;
- `title`;
- `file`.

Campos opcionais:

- `description`;
- `document_date`;
- `tags`.

Exemplo conceitual:

```text
client_id: 10
category: contract
title: Contrato de honorários
file: contrato.pdf
tags[]: contrato
tags[]: assinado
```

O cliente informado precisa pertencer ao escritório do usuário autenticado. Caso contrário, a API responde `404`.

## 8. Busca e filtros

A listagem aceita:

- `search`: título, nome original, descrição ou checksum completo;
- `client_id`;
- `category`;
- `status`;
- `date_from`;
- `date_to`;
- `per_page`, limitado a 100.

## 9. Download privado

O endpoint de download não transmite o arquivo pela aplicação. Ele gera uma URL assinada e temporária do storage privado.

```http
GET /api/v1/documents/{uuid}/download-url?expires_in=15
```

`expires_in` é informado em minutos e aceita valores entre 1 e 60. O padrão é configurado por:

```dotenv
DOCUMENTS_TEMPORARY_URL_MINUTES=10
```

A URL nunca deve ser persistida no banco ou enviada para logs.

## 10. Exclusão e retenção

`DELETE` aplica soft delete ao registro e grava `deleted_by_user_id`.

O arquivo privado não é removido imediatamente. Essa decisão preserva documentos jurídicos contra exclusão acidental e permite que uma política futura de retenção, restauração e expurgo seja implementada de forma controlada.

Documentos excluídos deixam de ser encontrados pelo route model binding e pelas listagens comuns.

## 11. Permissões

```text
documents.view
documents.create
documents.update
documents.download
documents.delete
```

Toda rota exige JWT e a permissão correspondente.

## 12. Segurança multi-tenant

- `office_id` vem do usuário autenticado;
- o frontend não escolhe o escritório;
- o cliente e o documento devem pertencer ao mesmo escritório do usuário;
- registros de outro escritório retornam `404`;
- disco e caminho interno não são retornados no JSON;
- URLs de download expiram;
- checksum SHA-256 permite verificar integridade e apoiar futuras rotinas de duplicidade ou auditoria.

## 13. Testes obrigatórios

O módulo cobre:

- upload privado;
- formatos não permitidos;
- vínculo com cliente de outro escritório;
- busca, filtros e isolamento;
- atualização de metadados;
- URL temporária;
- permissão de download;
- soft delete com preservação do objeto privado.