fix: Corrige compatibilidade com Express PHP e padrões de código

- Atualiza implementação do CycleMiddleware para usar setAttribute corretamente
- Corrige tipos e anotações para PHPStan nível 9
- Aplica padrões PSR-12 em todo o código
- Remove padrões ignorados desnecessários do PHPStan
- Melhora formatação e organização do código
- Adiciona documentação complementar

Todos os testes estão passando:
- PHPUnit: 68 testes OK
- PHPStan: Nível 9 sem erros
- PSR-12: 100% compatível

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: CAFernandes

README.md

@@ -32,12 +32,22 @@ composer require cafernandes/express-php-cycle-orm-extension
 // bootstrap/app.php
 use CAFernandes\ExpressPHP\CycleORM\CycleServiceProvider;
 
+// Configure as variáveis de ambiente antes do registro
+$_ENV['DB_CONNECTION'] = 'sqlite';
+$_ENV['DB_DATABASE'] = __DIR__ . '/database/database.sqlite';
+
+// Registre o provider
 $app->register(new CycleServiceProvider($app));
 ```
 
 ### 2. Configurar Variáveis de Ambiente
 
 ```env
+# SQLite (desenvolvimento)
+DB_CONNECTION=sqlite
+DB_DATABASE=/path/to/database.sqlite
+
+# MySQL (produção)
 DB_CONNECTION=mysql
 DB_HOST=localhost
 DB_PORT=3306
@@ -46,35 +56,86 @@ DB_USERNAME=your_username
 DB_PASSWORD=your_password
 ```
 
-### 3. Usar no Controller
+### 3. Uso Básico - Acesso Direto ao Database
+
+```php
+// Acesso direto para queries simples
+$app->get('/api/users', function ($req, $res) use ($app) {
+    $database = $app->make('cycle.database');
+    $users = $database->database()->query('SELECT * FROM users')->fetchAll();
+    
+    return $res->json(['data' => $users]);
+});
+
+// Inserção com query builder
+$app->post('/api/users', function ($req, $res) use ($app) {
+    $database = $app->make('cycle.database');
+    $data = $req->getParsedBody();
+    
+    $database->database()->insert('users')->values([
+        'name' => $data['name'],
+        'email' => $data['email'],
+        'created_at' => date('Y-m-d H:i:s')
+    ])->run();
+    
+    return $res->json(['message' => 'User created']);
+});
+```
+
+### 4. Uso Avançado - Arquitetura Limpa com Repositórios
 
 ```php
 use CAFernandes\ExpressPHP\CycleORM\Http\CycleRequest;
 
-class UserController
+// Repository Interface
+interface UserRepositoryInterface
+{
+    public function findById(int $id): ?User;
+    public function findAll(): array;
+    public function save(User $user): void;
+}
+
+// Repository Implementation
+class UserRepository implements UserRepositoryInterface
 {
-    public function index(CycleRequest $request): JsonResponse
+    public function __construct(
+        private DatabaseInterface $database
+    ) {}
+    
+    public function findById(int $id): ?User
     {
-        // Buscar usuários com paginação automática
-        $users = $request->paginate(
-            $request->repository(User::class)->select(),
-            page: 1,
-            perPage: 10
-        );
+        $result = $this->database->query(
+            'SELECT * FROM users WHERE id = ?',
+            [$id]
+        )->fetch();
 
-        return response()->json($users);
+        return $result ? $this->mapToEntity($result) : null;
+    }
+    
+    private function mapToEntity(array $data): User
+    {
+        return new User(
+            id: $data['id'],
+            name: $data['name'],
+            email: $data['email']
+        );
     }
+}
+
+// Controller com Injeção de Dependência
+class UserController
+{
+    public function __construct(
+        private UserRepositoryInterface $repository
+    ) {}
 
-    public function store(CycleRequest $request): JsonResponse
+    public function show(int $id): JsonResponse
     {
-        // Criar entidade a partir dos dados da request
-        $user = $request->entity(User::class, [
-            'name' => $request->input('name'),
-            'email' => $request->input('email')
-        ]);
+        $user = $this->repository->findById($id);
 
-        $request->em->persist($user);
-        $request->em->run();
+        if (!$user) {
+            return response()->json(['error' => 'User not found'], 404);
+        }
 
         return response()->json($user);
     }
@@ -103,6 +164,49 @@ vendor/bin/phpunit --group integration
 
 ## 🔧 Funcionalidades Avançadas
 
+### Sincronização de Schema
+```bash
+# Sincronizar schema do banco de dados
+php bin/console cycle:schema:sync
+
+# Verificar status das migrações
+php bin/console cycle:status
+```
+
+### Configuração Completa do Cycle ORM
+```php
+// config/cycle.php
+return [
+    'default' => env('DB_CONNECTION', 'sqlite'),
+    
+    'connections' => [
+        'sqlite' => [
+            'driver' => 'sqlite',
+            'database' => env('DB_DATABASE', ':memory:'),
+        ],
+        'mysql' => [
+            'driver' => 'mysql',
+            'host' => env('DB_HOST', 'localhost'),
+            'port' => env('DB_PORT', 3306),
+            'database' => env('DB_DATABASE', 'express_php'),
+            'username' => env('DB_USERNAME', 'root'),
+            'password' => env('DB_PASSWORD', ''),
+        ],
+    ],
+    
+    'entities' => [
+        'directories' => [
+            __DIR__ . '/../src/Domain/Entities',
+        ],
+    ],
+    
+    'cache' => [
+        'enabled' => env('CYCLE_CACHE_ENABLED', true),
+        'directory' => env('CYCLE_CACHE_DIR', __DIR__ . '/../storage/cache/cycle'),
+    ],
+];
+```
+
 ### Repository Factory com Cache
 ```php
 $factory = $app->get('cycle.repository');
@@ -112,18 +216,84 @@ $userRepo = $factory->getRepository(User::class); // Cached automatically
 ### Middleware de Transação
 ```php
 $app->use(new TransactionMiddleware($app));
+
+// Transações automáticas em rotas
+$app->post('/api/users', function ($req, $res) {
+    // Transação iniciada automaticamente
+    // Commit automático em sucesso
+    // Rollback automático em erro
+});
 ```
 
 ### Sistema de Monitoramento
 ```php
 use CAFernandes\ExpressPHP\CycleORM\Monitoring\MetricsCollector;
 
-// Métricas automáticas de queries, cache, etc.
+// Ativar profiling de queries
+$_ENV['CYCLE_PROFILE_QUERIES'] = true;
+$_ENV['CYCLE_LOG_QUERIES'] = true;
+
+// Coletar métricas
 $metrics = MetricsCollector::getMetrics();
+// Exibe: queries executadas, tempo de execução, cache hits/misses
 ```
 
+### Container de Injeção de Dependência
+```php
+// Registrar repositórios no container
+$container->bind(UserRepositoryInterface::class, function ($container) {
+    return new UserRepository(
+        $container->get('cycle.database')
+    );
+});
+
+// Usar em controllers
+$userController = $container->get(UserController::class);
+```
+
+## 📚 Exemplos de Implementação
+
+### API CRUD Completa
+```php
+// Estrutura de pastas recomendada
+├── src/
+│   ├── Domain/
+│   │   ├── Entities/
+│   │   │   └── User.php
+│   │   └── Repositories/
+│   │       └── UserRepositoryInterface.php
+│   ├── Infrastructure/
+│   │   └── Repositories/
+│   │       └── UserRepository.php
+│   └── Application/
+│       ├── Controllers/
+│       │   └── UserController.php
+│       └── UseCases/
+│           └── CreateUserUseCase.php
+```
+
+### Padrões de Implementação
+
+A extensão suporta diferentes níveis de complexidade:
+
+1. **Nível Básico**: Acesso direto ao banco via Cycle Database
+   - Ideal para MVPs e prototipagem rápida
+   - Queries SQL diretas com segurança
+   - Mínima configuração necessária
+
+2. **Nível Intermediário**: Padrão Repository
+   - Organização do código em camadas
+   - Facilita testes e manutenção
+   - Reutilização de lógica de negócio
+
+3. **Nível Avançado**: Clean Architecture
+   - Separação completa de responsabilidades
+   - Use Cases e Value Objects
+   - Máxima testabilidade e flexibilidade
+
 ## 📚 Documentação Completa
 
+- [Guia Completo - Do Básico ao Avançado](docs/guia-completo.md)
 - [Documentação Principal](docs/index.md)
 - [Guia de Contribuição](CONTRIBUTING.md)
 - [Arquitetura Técnica](docs/techinical/)