# N4STi Gestão — Especificação Mestra

Versão: 0.1.0  
Status: baseline para desenvolvimento  
Responsável pelo produto: N4STi  
Implementação: Claude Code  

## Objetivo

Construir um ERP web multiempresa, modular e auditável que una gestão comercial, estoque, compras, financeiro, fiscal, produção, industrialização por terceiros, logística, expedição e marketplaces.

O sistema deve atender desde uma empresa comercial simples até um grupo com vários CNPJs, regimes tributários diferentes, fábricas, depósitos, filiais e operações consolidadas.

## Princípios obrigatórios

1. Multiempresa real desde a primeira migração.
2. Isolamento de dados por grupo, empresa e estabelecimento.
3. Consolidação gerencial sem misturar obrigações jurídicas.
4. Estoque baseado em movimentos imutáveis, não apenas em saldo editável.
5. Integrações assíncronas, idempotentes e auditáveis.
6. Módulos habilitáveis por empresa sem quebrar dependências.
7. Rastreabilidade integral entre documento, movimento, usuário e integração.
8. Interface consistente, responsiva e utilizável com leitor de código de barras.
9. Modular monolith primeiro; serviços separados apenas quando métricas justificarem.
10. Nenhuma regra fiscal presumida pelo programador: regras parametrizadas e validadas por especialista fiscal.
11. PHP sem framework, com arquitetura própria documentada e dependências externas mínimas.

## Ordem de leitura para o Claude Code

1. `CLAUDE.md`
2. `01_PRODUCT_SPEC.md`
3. `02_ARCHITECTURE.md`
4. `03_TENANCY_SECURITY.md`
5. `04_DOMAIN_DATA.md`
6. `05_MODULE_SPECS.md`
7. `06_CRITICAL_WORKFLOWS.md`
8. `07_INTEGRATIONS.md`
9. `08_UX_DESIGN_SYSTEM.md`
10. `09_TESTING_QUALITY.md`
11. `10_INFRA_OPERATIONS.md`
12. `11_ROADMAP_BACKLOG.md`
13. `12_ACCEPTANCE_GATES.md`

## Escopo da primeira entrega comercial

- núcleo multiempresa, usuários, perfis e auditoria;
- cadastro de pessoas, empresas, estabelecimentos e depósitos;
- produtos, variações, fotos, fiscal básico e estrutura para marketplaces;
- estoque, reservas, transferências, inventário e rastreabilidade;
- clientes, fornecedores e transportadoras;
- orçamentos, pedidos e vendas;
- contas a pagar/receber, caixa e conciliação manual;
- integração inicial com Mercado Livre;
- preparação estrutural para NF-e e produção.

## Fora da primeira entrega

- contabilidade completa e SPED contábil;
- folha de pagamento;
- MRP avançado e APS;
- Shopee, Amazon e demais canais;
- BI com data warehouse;
- aplicativo móvel nativo;
- automação de regras tributárias sem validação fiscal.

Esses itens não devem ser impedidos pelo desenho, mas também não devem atrasar a fundação.

## Vocabulário

- **Grupo:** tenant principal e limite de segurança.
- **Empresa:** pessoa jurídica/CNPJ com fiscal e financeiro próprios.
- **Estabelecimento:** matriz ou filial operacional da empresa.
- **Depósito:** localização lógica/física de estoque.
- **Catálogo:** definição compartilhável do produto.
- **Oferta:** produto disponibilizado por empresa/canal/tabela.
- **Saldo:** projeção calculada a partir de movimentos.
- **Reserva:** quantidade comprometida ainda não expedida.
- **Documento de origem:** venda, compra, OP, transferência ou ajuste que motivou um movimento.
- **Industrialização externa:** envio de insumos a terceiro e retorno de produto transformado.

## Regra de alteração deste pacote

Mudanças estruturais devem gerar um ADR em `DECISIONS.md`. Mudanças de escopo devem atualizar o spec, os critérios de aceite e o backlog no mesmo commit.