# Multiempresa, Permissões e Segurança

## Hierarquia organizacional

```mermaid
flowchart TD
    G["Grupo / Tenant"] --> C1["Empresa A"]
    G --> C2["Empresa B"]
    C1 --> E1["Matriz"]
    C1 --> E2["Filial"]
    E1 --> D1["Depósito"]
    E2 --> D2["Depósito"]
```

### Grupo

Limite máximo de isolamento. Dados de grupos diferentes nunca podem ser consultados conjuntamente, nem por relatório consolidado.

### Empresa

Pessoa jurídica com CNPJ, regime, fiscal, financeiro e propriedade patrimonial próprios.

### Estabelecimento

Matriz ou filial vinculada a uma empresa. Pode possuir endereço, inscrição, séries, depósitos, caixa e operação próprios.

### Depósito

Local de guarda ou estado logístico. Pode representar estoque físico, qualidade, terceiros, trânsito ou área produtiva, mas o tipo deve ser explícito.

## Usuários e memberships

Usuário é identidade global. O acesso ocorre por memberships:

- usuário no grupo;
- empresas permitidas;
- estabelecimentos permitidos;
- depósitos permitidos quando necessário;
- roles;
- permissões adicionais ou revogadas;
- período de validade;
- status.

Um usuário não deve ganhar acesso a uma nova empresa apenas porque foi criada no grupo.

## RBAC com escopo

Permissões seguem `modulo.recurso.acao`, por exemplo:

- `inventory.stock.view`
- `inventory.adjustment.approve`
- `sales.order.cancel`
- `finance.payable.settle`
- `fiscal.invoice.authorize`
- `marketplace.connection.manage`
- `manufacturing.order.release`

A decisão exige simultaneamente:

1. módulo habilitado;
2. membership ativo;
3. permissão;
4. escopo compatível;
5. regra contextual, como limite de desconto ou segregação de função.

## Perfis iniciais

- administrador N4STi;
- administrador do grupo;
- administrador da empresa;
- comercial;
- comprador;
- estoquista;
- expedidor;
- financeiro contas a pagar;
- financeiro contas a receber;
- fiscal;
- PCP;
- operador de produção;
- supervisor de produção;
- consulta/auditoria.

Roles são modelos editáveis. Permissões sensíveis exigem confirmação explícita.

## Habilitação de módulos

Tabela de assinatura/configuração por empresa:

- módulo;
- status;
- início/fim;
- configuração JSON validada por schema apenas para opções não relacionais;
- dependências;
- motivo da alteração;
- autor.

Desabilitar um módulo:

- bloqueia novas operações no backend;
- preserva consulta histórica quando autorizada;
- não apaga dados;
- suspende jobs daquele módulo com estratégia definida;
- não invalida documentos originados anteriormente.

Dependências exemplares:

- Marketplace depende de Catálogo, Estoque e Vendas.
- Produção depende de Catálogo, Estoque e Almoxarifado.
- NF-e depende de Fiscal, Pessoas, Produtos e Vendas.
- Expedição depende de Vendas e Estoque.

## Consolidação

Relatórios consolidados devem consultar somente empresas selecionadas e permitidas. Dados monetários mantêm empresa e moeda de origem. Eliminações intercompany serão módulo futuro e nunca implícitas.

Não consolidar:

- numeração fiscal;
- certificado;
- conta bancária;
- saldo de estoque como se tivesse o mesmo proprietário;
- contas a pagar/receber sem identificar a empresa;
- permissões.

## Autenticação

- senha com Argon2id;
- sessão regenerada no login e em elevação de privilégio;
- cookies `Secure`, `HttpOnly`, `SameSite=Lax`;
- expiração por inatividade e absoluta;
- MFA TOTP preparado e obrigatório para administradores/fiscal em fase definida;
- recuperação com token único, curto e armazenado como hash;
- rate limiting de login e recuperação;
- encerramento de outras sessões.

## Segurança web

- CSRF em toda mutação por navegador;
- escaping contextual de saída;
- CSP progressiva;
- prepared statements;
- validação server-side;
- uploads fora do document root;
- proteção contra path traversal e SSRF;
- allowlist de hosts nas integrações;
- timeouts curtos e limites de tamanho;
- headers HSTS, X-Content-Type-Options e frame policy;
- CORS fechado por padrão.

## Auditoria

Registrar:

- grupo, empresa e estabelecimento;
- usuário e sessão;
- ação e recurso;
- ID do registro;
- antes/depois sanitizado;
- IP e user-agent;
- correlation ID;
- motivo quando exigido;
- data UTC.

Nunca registrar senha, token, certificado, chave privada ou dados integrais de cartão. Auditoria não pode ser alterada por usuários comuns.

## LGPD

- inventário das categorias de dados;
- finalidade e base de tratamento documentadas;
- retenção parametrizada;
- exportação e anonimização controladas;
- exclusão somente quando obrigações fiscais/comerciais permitirem;
- mascaramento em telas e logs;
- registro de acesso a dados sensíveis;
- operadores externos documentados.

## Testes obrigatórios de isolamento

Para cada endpoint e query de negócio:

1. usuário autorizado na Empresa A acessa A;
2. o mesmo usuário tenta ID da Empresa B e recebe 404/403 sem vazamento;
3. usuário sem módulo recebe bloqueio de backend;
4. relatório consolidado inclui somente empresas permitidas;
5. job com group/company incorretos é recusado;
6. webhook não consegue escolher arbitrariamente outro tenant.