docs: Adiciona o Guia Técnico e Quick Start e atualiza referências em documentos existentes

CAFernandes · CAFernandes · commit 3287f1fdcf67 · 2025-07-01T17:43:02.000-03:00
diff --git a/README.md b/README.md
@@ -246,6 +246,21 @@ make ci
 - 🎯 [Examples](examples/) - Exemplos práticos
 - 🧪 [Testing Guide](docs/testing.md) - Como testar
 
+---
+
+## 📚 Guia Técnico e Quick Start
+
+Consulte o arquivo [`docs/guia-tecnico-quickstart.md`](docs/guia-tecnico-quickstart.md) para um guia completo das funcionalidades, exemplos de uso, dicas de integração e melhores práticas com o Express-PHP + Cycle ORM Extension.
+
+Principais tópicos:
+- Funcionalidades detalhadas da extensão
+- Quick start para integração com Express-PHP
+- Exemplos de CRUD, queries avançadas, validação, transações e mais
+- Dicas de performance e troubleshooting
+- Links para suporte e comunidade
+
+---
+
 ## 🛡️ Requisitos
 
 - **PHP**: 8.1 ou superior
@@ -300,7 +315,7 @@ Este projeto está licenciado sob a **MIT License** - veja o arquivo [LICENSE](L
 
 - 🐛 **Issues**: [GitHub Issues](https://github.com/CAFernandes/express-php-cycle-orm-extension/issues)
 - 💬 **Discussões**: [GitHub Discussions](https://github.com/CAFernandes/express-php-cycle-orm-extension/discussions)
-- 📧 **Email**: caio@express-php.dev
+<!-- - 📧 **Email**: caio@express-php.dev -->
 
 ---
 
@@ -312,4 +327,4 @@ Este projeto está licenciado sob a **MIT License** - veja o arquivo [LICENSE](L
 
 ⭐ **Se você gostou, deixe uma estrela!** ⭐
 
-</div>
+</div>
diff --git a/docs/advanced.md b/docs/advanced.md
@@ -1,5 +1,7 @@
 # Advanced Usage - Express-PHP Cycle ORM Extension
 
+> Consulte também o [Guia Técnico e Quick Start](./guia-tecnico-quickstart.md) para exemplos de uso avançado, dicas de performance e integração.
+
 ## 🏗️ Custom Repositories
 
 ### Creating Custom Repositories
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,6 +1,7 @@
-
 # Configuration Guide - Express-PHP Cycle ORM Extension
 
+> Consulte também o [Guia Técnico e Quick Start](./guia-tecnico-quickstart.md) para exemplos práticos de configuração e melhores práticas.
+
 ## 🔧 Environment Variables
 
 ### Database Configuration
@@ -447,4 +448,4 @@ class CycleConfigProvider
         }
     }
 }
-```
+```
diff --git a/docs/cycle-request.md b/docs/cycle-request.md
@@ -1,5 +1,7 @@
 # Integração Cycle ORM Extension para Express-PHP
 
+> Consulte também o [Guia Técnico e Quick Start](./guia-tecnico-quickstart.md) para visão geral, exemplos e integração rápida.
+
 ## Visão Geral
 A extensão injeta recursos do Cycle ORM no seu projeto Express-PHP de forma **opcional, segura e sem acoplamento** ao core do framework, utilizando um wrapper inteligente: `CycleRequest`.
 
diff --git a/docs/guia-tecnico-quickstart.md b/docs/guia-tecnico-quickstart.md
@@ -0,0 +1,134 @@
+# Guia Técnico e Quick Start — Express-PHP Cycle ORM Extension
+
+## Sumário
+- [Visão Geral](#visão-geral)
+- [Funcionalidades Principais](#funcionalidades-principais)
+- [Quick Start](#quick-start)
+- [Recursos Avançados](#recursos-avançados)
+- [Dúvidas e Suporte](#dúvidas-e-suporte)
+
+---
+
+## Visão Geral
+A extensão Express-PHP Cycle ORM integra o Cycle ORM ao microframework Express-PHP, fornecendo injeção automática de serviços, gerenciamento inteligente de transações, validação de entidades, helpers para queries e arquitetura baseada em middlewares, tudo com zero configuração manual.
+
+## Funcionalidades Principais
+
+### Injeção Automática de Serviços
+- `$req->orm`: Instância do Cycle ORM
+- `$req->em`: EntityManager para persistência
+- `$req->db`: Database Manager
+- `$req->repository(EntityClass)`: Repositório da entidade
+- `$req->entity(EntityClass, $data)`: Cria entidade populada
+- `$req->find(EntityClass, $id)`: Busca por PK
+- `$req->paginate($query, $page, $perPage)`: Paginação de resultados
+- `$req->validateEntity($entity)`: Validação automática
+
+### Gerenciamento Inteligente de Transações
+- Transações abertas automaticamente em cada request
+- Commit automático em sucesso, rollback em exceções
+- Middleware `TransactionMiddleware` customizável
+
+### Validação de Entidades
+- Validação básica via reflection (tipos, campos obrigatórios)
+- Pode ser estendida com regras customizadas
+
+### Helpers para Queries
+- Filtros dinâmicos, busca textual, ordenação e paginação via helpers
+- Eager loading de relacionamentos com `.load('relacao')`
+
+### Arquitetura Middleware-Driven
+- Middlewares: `CycleMiddleware`, `TransactionMiddleware`, `EntityValidationMiddleware`, `HealthCheckMiddleware`
+- Compatível com qualquer stack de middlewares do Express-PHP
+
+### CLI Integrada
+- Comandos: `make:entity`, `cycle:schema --sync`, `cycle:status`, `migrate`, `seed` etc.
+
+### Zero Configuração
+- Auto-discovery: basta instalar, sem necessidade de registrar providers manualmente
+- Configuração mínima via `.env` e `config/cycle.php`
+
+### Compatibilidade
+- 100% compatível com handlers e middlewares Express-PHP
+- Proxy transparente: `CycleRequest` expõe todos métodos do `Request` original
+
+### Exemplos Avançados
+- CRUD completo, queries com joins, subqueries, operações em lote, analytics, health check, etc.
+- Veja exemplos em `examples/basic-usage.php` e `examples/advanced-queries.php`
+
+---
+
+## Quick Start
+
+### 1. Instalação
+```bash
+composer require express-php/cycle-orm-extension
+```
+
+### 2. Configuração do Ambiente
+Crie ou edite o arquivo `.env`:
+```env
+DB_CONNECTION=mysql
+DB_HOST=localhost
+DB_PORT=3306
+DB_DATABASE=express_api
+DB_USERNAME=root
+DB_PASSWORD=
+
+CYCLE_SCHEMA_CACHE=true
+CYCLE_AUTO_SYNC=false
+CYCLE_SCHEMA_STRICT=false
+```
+
+### 3. Gerar Primeira Entidade
+```bash
+php express make:entity User
+```
+
+### 4. Sincronizar o Schema
+```bash
+php express cycle:schema --sync
+```
+
+### 5. Implementação Básica de API
+Exemplo de `public/index.php`:
+```php
+<?php
+require_once 'vendor/autoload.php';
+
+use Express\Core\Application;
+use App\Models\User;
+
+$app = new Application();
+
+// Listar usuários
+$app->get('/api/users', function($req, $res) {
+    $users = $req->repository(User::class)->findAll();
+    $res->json(['users' => $users]);
+});
+
+// Criar usuário
+$app->post('/api/users', function($req, $res) {
+    $user = $req->entity(User::class, $req->body);
+    $req->em->persist($user);
+    $res->status(201)->json(['user' => $user]);
+});
+
+$app->run();
+```
+
+---
+
+## Recursos Avançados
+- Paginação: `$req->paginate($query, $page, $perPage)`
+- Filtros: `CycleHelpers::applyFilters($query, $filters, $campos)`
+- Busca textual: `CycleHelpers::applySearch($query, $search, $campos)`
+- Eager loading: `$query->load('relacao')`
+- Validação: `$req->validateEntity($entity)`
+
+---
+
+## Dúvidas e Suporte
+- Documentação: [docs.express-php.dev/cycle-orm](https://docs.express-php.dev/cycle-orm)
+<!-- - Discord: [express-php.dev/discord](https://express-php.dev/discord) -->
+- Issues: [github.com/express-php/cycle-orm-extension/issues](https://github.com/express-php/cycle-orm-extension/issues)
diff --git a/docs/index.md b/docs/index.md
@@ -1,5 +1,7 @@
 # Documentação Express-PHP Cycle ORM Extension
 
+> Consulte o [Guia Técnico e Quick Start](./guia-tecnico-quickstart.md) para um resumo completo e exemplos práticos.
+
 ## Índice de Documentos
 
 - [Instalação](installation.md)
diff --git a/docs/installation.md b/docs/installation.md
@@ -1,5 +1,7 @@
 # Installation
 
+> **Dica:** Para um passo a passo completo, consulte também o [Guia Técnico e Quick Start](./guia-tecnico-quickstart.md).
+
 ## Requirements
 
 - PHP 8.1 or higher
@@ -10,37 +12,30 @@
 ## Composer Installation
 
 ```bash
-composer require cafernandes/express-php-cycle-orm-extension
-```
-
-## Manual Installation
-
-1. Download the package
-2. Add to your `composer.json`:
-
-```json
-{
-    "require": {
-        "cafernandes/express-php-cycle-orm-extension": "^1.0"
-    }
-}
+composer require express-php/cycle-orm-extension
 ```
 
-3. Run `composer install`
-
 ## Environment Setup
 
-Copy the example environment file:
+Crie ou edite o arquivo `.env`:
 
-```bash
-cp vendor/cafernandes/express-php-cycle-orm-extension/.env.example .env
-```
+```env
+DB_CONNECTION=mysql
+DB_HOST=localhost
+DB_PORT=3306
+DB_DATABASE=express_api
+DB_USERNAME=root
+DB_PASSWORD=
 
-Configure your database settings in `.env`.
+CYCLE_SCHEMA_CACHE=true
+CYCLE_AUTO_SYNC=false
+CYCLE_SCHEMA_STRICT=false
+CYCLE_LOG_QUERIES=false
+```
 
 ## Verification
 
-To verify the installation worked:
+Para verificar se a instalação funcionou:
 
 ```php
 <?php
@@ -50,7 +45,6 @@ use Express\Core\Application;
 
 $app = new Application();
 
-// Check if Cycle ORM is available
 if ($app->has('cycle.orm')) {
     echo "✅ Cycle ORM Extension installed successfully!";
 } else {
@@ -60,6 +54,6 @@ if ($app->has('cycle.orm')) {
 
 ## Next Steps
 
-- [Configuration](configuration.md)
-- [Basic Usage](usage.md)
-- [Advanced Features](advanced.md)
+- [Configuração](configuration.md)
+- [Uso Básico](usage.md)
+- [Avançado](advanced.md)
diff --git a/docs/usage.md b/docs/usage.md
@@ -1,40 +1,40 @@
 # Usage Guide - Express-PHP Cycle ORM Extension
 
+> **Dica:** Consulte também o [Guia Técnico e Quick Start](./guia-tecnico-quickstart.md) para um resumo completo das funcionalidades, exemplos e melhores práticas.
+
 ## 🚀 Quick Start
 
-### 1. Installation
+### 1. Instalação
 
 ```bash
-composer require cafernandes/express-php-cycle-orm-extension
+composer require express-php/cycle-orm-extension
 ```
 
-### 2. Environment Configuration
+### 2. Configuração do Ambiente
 
-Create or update your `.env` file:
+Crie ou edite o arquivo `.env`:
 
 ```env
-# Database Configuration
 DB_CONNECTION=mysql
 DB_HOST=localhost
 DB_PORT=3306
 DB_DATABASE=express_api
 DB_USERNAME=root
 DB_PASSWORD=
 
-# Cycle ORM Settings
 CYCLE_SCHEMA_CACHE=true
 CYCLE_AUTO_SYNC=false
 CYCLE_SCHEMA_STRICT=false
 CYCLE_LOG_QUERIES=false
 ```
 
-### 3. Create Your First Entity
+### 3. Gerar Primeira Entidade
 
 ```bash
 php express make:entity User
 ```
 
-This creates `app/Models/User.php`:
+Isso cria `app/Models/User.php`:
 
 ```php
 <?php
@@ -65,13 +65,13 @@ class User
 }
 ```
 
-### 4. Sync Database Schema
+### 4. Sincronizar o Schema
 
 ```bash
 php express cycle:schema --sync
 ```
 
-### 5. Basic API Implementation
+### 5. Implementação Básica de API
 
 ```php
 <?php
@@ -82,28 +82,19 @@ use App\Models\User;
 
 $app = new Application();
 
-// List users
+// Listar usuários
 $app->get('/api/users', function($req, $res) {
     $users = $req->repository(User::class)->findAll();
     $res->json(['users' => $users]);
 });
 
-// Create user
+// Criar usuário
 $app->post('/api/users', function($req, $res) {
     $user = $req->entity(User::class, $req->body);
     $req->em->persist($user);
     $res->status(201)->json(['user' => $user]);
 });
 
-// Get user by ID
-$app->get('/api/users/:id', function($req, $res) {
-    $user = $req->find(User::class, $req->params['id']);
-    if (!$user) {
-        return $res->status(404)->json(['error' => 'User not found']);
-    }
-    $res->json(['user' => $user]);
-});
-
 $app->run();
 ```
 

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`		`-`
`2`	`1`	`# Configuration Guide - Express-PHP Cycle ORM Extension`
`3`	`2`
	`3`	`+> Consulte também o [Guia Técnico e Quick Start](./guia-tecnico-quickstart.md) para exemplos práticos de configuração e melhores práticas.`
	`4`	`+`
`4`	`5`	`## 🔧 Environment Variables`
`5`	`6`
`6`	`7`	`### Database Configuration`
`@@ -447,4 +448,4 @@ class CycleConfigProvider`
`447`	`448`	`}`
`448`	`449`	`}`
`449`	`450`	`}`
`450`		-```
	`451`	+```