Por que um Guia de Contratos para IA?
O Domain-System foi projetado para trabalhar em harmonia com assistentes de Inteligência Artificial (Gemini, Claude, ChatGPT, Copilot, Cursor). Para que o código gerado por IA mantenha 100% de aderência à arquitetura SOLID e Clean Architecture do sistema, todas as extensões seguem contratos explÃcitos.
1. Regras de Ouro Inegociáveis
- Zero Superglobais em Controllers: Jamais utilize
$_GET,$_POST,$_SESSION,$_FILESou$_SERVERdentro de Controllers. Utilize sempre o objetoRequest($request->input(),$request->json()) eSessionManagerInterfaceinjetados no construtor (verificado porNoSuperglobalsInControllersTest). - Inversão de Dependência (DIP): Serviços e Controllers dependem exclusivamente de interfaces em
Contracts/, nunca de repositórios PDO concretos ou clientes HTTP externos diretos. - Isolamento de Anéis (Ring 0 vs. Ring 3): Plugins em
src/Plugins/(Ring 3) comunicam-se com o Kernel (Ring 0) através deOsExtensionInterface(osRegistereosBoot) e eventos, sem alterar classes do núcleo. - SQL Agnóstico (MySQL & SQLite): Repositórios PDO devem usar SQL ANSI compatÃvel tanto com MySQL/MariaDB (produção Hostinger) quanto com SQLite em memória (suÃte PHPUnit).
2. Gerador Automático via CLI
Para iniciar qualquer plugin dentro do padrão oficial, utilize o comando:
php os-cli.php make:plugin nome_do_plugin
Esse comando cria automaticamente o manifesto plugin.json (versão 2.7.0 / os_version: 2.7), a classe Plugin.php com OsExtensionInterface e o módulo de documentação auto-descoberto manual/module.php (ManualModuleInterface).
3. Estrutura Padrão de um Plugin
src/Plugins/meu_plugin/
├── plugin.json
├── Plugin.php
├── Contracts/
│ └── MeuRepositorioInterface.php
├── Repositories/
│ └── PdoMeuRepositorio.php
├── Services/
│ └── MeuServico.php
├── Controllers/
│ └── MeuController.php
├── manual/
│ └── module.php
└── views/
├── admin/
└── front/
4. Verificação Automatizada
Antes de publicar qualquer alteração gerada com auxÃlio de IA, execute a bateria de testes de arquitetura e unidade:
php phpunit.phar tests/Architecture
php phpunit.phar