# Instruções de implementação — Claude Code

## Papel

Implemente o N4STi Gestão em incrementos pequenos, revisáveis e testáveis. Não altere decisões arquiteturais silenciosamente. Quando uma regra estiver ambígua, registre a dúvida e interrompa apenas a parte afetada.

## Stack definida

- Ubuntu Server 24.04 LTS.
- PHP 8.3 ou versão posterior explicitamente aprovada.
- PHP 8.3 sem framework, com núcleo próprio e monólito modular.
- MySQL 8.0, `utf8mb4`, InnoDB e modo SQL estrito.
- Redis para filas, cache, locks distribuídos e rate limiting.
- Apache 2.4 com `mod_rewrite`, HTTPS e PHP-FPM preferencialmente.
- HTML5, CSS, JavaScript, jQuery e Bootstrap 5 com assets locais.
- Composer somente para autoload PSR-4, NFePHP e bibliotecas pontuais aprovadas.
- PHPUnit para backend e Playwright para fluxos críticos.
- NFePHP quando o módulo fiscal entrar no escopo.

Não introduza framework PHP ou JavaScript, ORM, banco NoSQL ou microserviço sem ADR aprovado. Não usar Laravel, Symfony, CodeIgniter, CakePHP, Vue, React ou Angular.

## Organização do código

Use módulos de domínio dentro de uma aplicação PHP única:

```text
app/
  Core/
  Modules/
    Identity/
    Organizations/
    People/
    Catalog/
    Inventory/
    Sales/
    Purchasing/
    Finance/
    Manufacturing/
    Outsourcing/
    Logistics/
    Fiscal/
    Marketplaces/
    Reporting/
    Platform/
config/
database/
  migrations/
  seeds/
public/
  index.php
  assets/
routes/
storage/
tests/
```

Cada módulo deve possuir, conforme necessário: `Domain`, `Application`, `Infrastructure`, `Http`, `Policies`, `Events`, `Listeners`, `Jobs`, `Views` e `Tests`.

O núcleo próprio deve fornecer apenas serviços transversais: front controller, roteador, Request/Response, middleware, sessão, CSRF, autenticação, autorização, conexão mysqli/PDO aprovada, transações, validação, views, configuração, logs, filas e migrations. Não transforme o núcleo em um framework genérico.

Não acessar tabela de outro módulo por lógica espalhada. Use serviços de aplicação, interfaces de consulta ou eventos de domínio. Transações que exigem consistência imediata podem atravessar módulos dentro do mesmo processo, desde que documentadas.

## Regras inegociáveis

1. Toda tabela de negócio deve carregar `group_id`; as juridicamente específicas também devem carregar `company_id` e, quando aplicável, `establishment_id`.
2. Toda consulta deve ser protegida por escopo e Policy. Não confiar em IDs enviados pelo navegador.
3. Valores monetários usam `DECIMAL`, nunca `float`.
4. Quantidades usam `DECIMAL(20,6)` ou precisão definida por unidade; nunca `float`.
5. Datas persistidas em UTC; documentos fiscais preservam também timezone e representação legal necessária.
6. Estoque não é alterado com `UPDATE quantity = ...` fora do serviço de movimentação.
7. Lançamentos confirmados não são apagados. Corrigir por estorno/reversão.
8. Webhooks e comandos externos devem ser idempotentes.
9. Toda integração possui payload sanitizado, correlation ID, tentativas e dead-letter.
10. Segredos nunca entram no repositório ou nos logs.
11. Certificados A1 devem ser criptografados em repouso e acessados somente pelo worker fiscal.
12. Migrations próprias devem ser versionadas, transacionais quando suportado e retrocompatíveis durante deploy; alterações destrutivas exigem plano em etapas.
13. SQL deve usar prepared statements. Nunca concatenar entrada do usuário.
14. Controllers devem apenas receber/validar a requisição, autorizar e chamar o serviço de aplicação.

## Processo obrigatório por história

1. Confirmar módulo, regra e critérios de aceite.
2. Criar/ajustar migration própria e constraints.
3. Implementar domínio e serviços antes da tela.
4. Criar Policies e validação de autorização.
5. Criar testes unitários e de integração.
6. Implementar UI com estados vazio, carregando, sucesso e erro.
7. Criar teste de fluxo quando crítico.
8. Executar lint, análise estática, testes e build.
9. Atualizar documentação afetada.
10. Entregar resumo com riscos, migrations e rollback.

## Definition of Done

- critérios de aceite atendidos;
- isolamento multiempresa testado;
- permissões testadas;
- auditoria registrada;
- sem consulta N+1 relevante;
- transações e locks revisados;
- mensagens de erro compreensíveis;
- keyboard navigation nos fluxos operacionais;
- cobertura de casos de repetição/idempotência;
- migration e rollback validados em base descartável;
- nenhum dado sensível em log, fixture ou screenshot.

## Proibições

- Não criar coluna polimórfica genérica quando chaves estrangeiras explícitas forem possíveis.
- Não armazenar JSON para substituir modelagem relacional central.
- Não duplicar saldo como fonte de verdade sem mecanismo de reconciliação.
- Não permitir edição direta de documento fiscal autorizado.
- Não acoplar Mercado Livre diretamente aos controllers de Venda ou Produto.
- Não criar arquivos PHP misturando SQL, regra de negócio, HTML e JavaScript.
- Não usar variáveis globais para contexto de empresa ou usuário.
- Não construir um Active Record improvisado; consultas ficam em repositories explícitos.
- Não executar chamadas externas dentro de transação longa de banco.
- Não habilitar módulo somente escondendo menu; backend também deve bloquear.
- Não implementar regra fiscal por suposição.

## Entregas iniciais

Antes de telas de negócio, produzir:

- estrutura do repositório e núcleo PHP mínimo;
- ambiente de desenvolvimento;
- autenticação;
- contexto de grupo/empresa/estabelecimento;
- RBAC;
- feature flags de módulos;
- auditoria;
- health checks;
- pipeline de testes;
- seed mínimo demonstrativo.