dockerfluxodecaixapro/rules/06_DEVELOPER_GUIDE.md

# SysCMS - Guia Rápido para Desenvolvedores

Este documento fornece uma visão geral rápida do SysCMS. Para documentação detalhada, consulte os arquivos específicos listados em cada seção.

## 🏗️ Visão Geral

O **SysCMS** é um Sistema de Gerenciamento de Conteúdo (CMS) modular desenvolvido em PHP 8.1+. Ele utiliza uma arquitetura moderna baseada em componentes, integrando tecnologias robustas como:

-   **Router**: FastRoute para roteamento rápido e flexível.
-   **Database**: Illuminate Database (Eloquent ORM) para interação com o banco.
-   **View Engine**: Twig para templates seguros e poderosos.
-   **Dependency Injection**: PHP-DI para gerenciamento de dependências.
-   **Frontend**: Bootstrap 5.3 + Vanilla JS (com Alpine.js restrito para casos de alta reatividade).

O sistema foi projetado sob o princípio **SOLID** e adota uma arquitetura modular, permitindo que novas funcionalidades sejam acopladas sem alterar o núcleo.

## 📚 Documentação Detalhada

### Arquitetura e Estrutura
- 📄 **[02_ARQUITETURA.md](02_ARQUITETURA.md)** - Estrutura de diretórios, componentes do kernel, autoloading PSR-4 e padrões de design.

### Sistema de Módulos
- 📄 **[03_MODULOS.md](03_MODULOS.md)** - Visão geral do sistema de módulos, estrutura básica, roteamento, internacionalização e migrações.
- 📄 **[12_MANUAL_COMO_CRIAR_MODULOS_PARA_INSTALAR.md](12_MANUAL_COMO_CRIAR_MODULOS_PARA_INSTALAR.md)** - Guia passo a passo para criar módulos instaláveis.
- 📄 **[17_MODULE_TEMPLATE.md](17_MODULE_TEMPLATE.md)** - Template padrão para novos módulos.
- 📄 **[20_CRIACAO_DE_NOVOS_MODULOS.md](20_CRIACAO_DE_NOVOS_MODULOS.md)** - Guia baseado no sucesso do PhotoEssay para criar novos módulos.

### Tecnologias e Padrões
- 📄 **[04_TECNOLOGIAS.md](04_TECNOLOGIAS.md)** - Stack tecnológica completa (backend, frontend, ambiente de desenvolvimento).
- 📄 **[05_PADROES_CODIGO.md](05_PADROES_CODIGO.md)** - Padrões de código, nomenclatura, banco de dados, frontend, segurança, uploads, logs e comentários.

### Hooks e Extensibilidade
- 📄 **[14_COMO_USAR_HOOK.md](14_COMO_USAR_HOOK.md)** - Sistema de Hooks (Actions & Filters) para modificar o comportamento do sistema.

### Funcionalidades Específicas
- 📄 **[15_QUILL_IMPLEMENTATION_COMPLETE.md](15_QUILL_IMPLEMENTATION_COMPLETE.md)** - Implementação do editor Quill.
- 📄 **[16_REGRAS_QUILL_IA.md](16_REGRAS_QUILL_IA.md)** - Regras específicas para IA trabalhar com Quill.
- 📄 **[18_THEMES_CUSTOMIZER.md](18_THEMES_CUSTOMIZER.md)** - Sistema de customização de temas.
- 📄 **[19_INTEGRACAO_GLOBALLISTS.md](19_INTEGRACAO_GLOBALLISTS.md)** - Integração com o módulo de listas globais (País/Estado/Cidade).

### Ambiente e Execução
- 📄 **[07_ENVIRONMENT_USAGE.md](07_ENVIRONMENT_USAGE.md)** - Uso do Symfony Dotenv para variáveis de ambiente.
- 📄 **[08_IA_COMMAND_EXECUTION_GUIDE.md](08_IA_COMMAND_EXECUTION_GUIDE.md)** - Guia de execução de comandos PHP para a IA.
- 📄 **[09_LANGUAGE_CONFIG_README.md](09_LANGUAGE_CONFIG_README.md)** - Configuração de idiomas suportados.

### Comportamento da IA
- 📄 **[01_COMPORTAMENTO_IA.md](01_COMPORTAMENTO_IA.md)** - Regras estritas de como a IA deve interagir com o ambiente e o usuário.

### Uploads e Storage
- 📄 **[51_UPLOADS_STORAGE.md](51_UPLOADS_STORAGE.md)** - Regras para uploads e gerenciamento de arquivos.

## 🚀 Início Rápido

### 1. Estrutura de Diretórios

```
app/
├── app/                    # Núcleo da aplicação
│   ├── Controllers/        # Controladores Base e Admin
│   ├── Console/            # Comandos CLI (Symfony Console)
│   ├── Helpers/            # Funções auxiliares globais
│   ├── Middlewares/        # Middlewares de rota e aplicação
│   └── Models/             # Modelos Eloquent do Core
├── cache/                  # Cache de templates e configurações
├── config/                 # Arquivos de configuração (banco, mail, etc.)
├── database/               # Migrações do Core
├── kernel/                 # Classes fundamentais (App, Router, ModuleLoader)
├── modules/                # Módulos instalados (Plugins/Extensões)
├── public/                 # Document Root (index.php, assets)
├── storage/                # Uploads e logs
├── templates/              # Templates Twig globais e layouts
└── vendor/                 # Dependências (Composer)
```

### 2. Criar um Novo Módulo

Use o comando CLI para gerar a estrutura base:
```bash
docker exec -w /app dockersyscms php syscli make:module [nome]
```

Ou siga o guia detalhado em [12_MANUAL_COMO_CRIAR_MODULOS_PARA_INSTALAR.md](12_MANUAL_COMO_CRIAR_MODULOS_PARA_INSTALAR.md).

### 3. Estrutura Básica de um Módulo

```
modules/meu_modulo/
├── classes/Controllers/   # Lógica
├── classes/Models/        # Dados
├── database/migrations/   # Schema
├── locales/               # Traduções (pt_BR, en_US, es_ES, de_DE, fr_FR)
├── routes/web.php         # Rotas
├── views/                 # Templates
└── module.json           # Manifesto
```

### 4. Comandos CLI Principais

| Comando | Descrição |
| :--- | :--- |
| `migrate` | Executa as migrações pendentes |
| `make:migration` | Cria arquivo de migração |
| `cache:clear` | Limpa cache de templates e rotas |
| `user:create-super-admin` | Cria usuário administrador via terminal |
| `module:list` | Lista módulos instalados |

Exemplo de uso via Docker:
```bash
docker exec -w /app dockersyscms php syscli cache:clear
```

### 5. Banco de Dados (Eloquent)

O SysCMS usa o Eloquent ORM.

#### Models
```php
namespace Modules\MeuModulo\Models;
use Illuminate\Database\Eloquent\Model;

class Produto extends Model {
    protected $table = 'produtos';
    protected $fillable = ['nome', 'preco'];
}
```

#### Migrations
```bash
# Criar migração
docker exec -w /app dockersyscms php syscli make:migration CreateProdutosTable

# Rodar migrações
docker exec -w /app dockersyscms php syscli migrate
```

⚠️ **IMPORTANTE**: NÃO use o método `paginate()` do Eloquent. A paginação deve ser implementada manualmente usando `skip()`, `take()` e `count()`.

### 6. Templates (Twig)

Os templates ficam em `templates/` (Core) ou `modules/.../views/`.

```twig
{% extends 'layouts/dashboard.twig' %}

{% block title %}Meus Produtos{% endblock %}

{% block content %}
    <div class="card">
        <div class="card-body">
            <h1>{{ title }}</h1>
            <ul>
            {% for produto in produtos %}
                <li>{{ produto.nome }}</li>
            {% endfor %}
            </ul>
        </div>
    </div>
{% endblock %}
```

### 7. Hooks (Actions & Filters)

Permitem modificar o comportamento do sistema sem alterar o Core.

- **Actions**: Executam código em pontos específicos.
    ```php
    add_action('user_registered', function($user_id) {
        enviar_email_boas_vindas($user_id);
    });
    ```

- **Filters**: Modificam dados antes de serem usados/exibidos.
    ```php
    add_filter('the_content', function($content) {
        return str_replace('Palavrão', '***', $content);
    });
    ```

Para mais detalhes, consulte [14_COMO_USAR_HOOK.md](14_COMO_USAR_HOOK.md).

## 📦 Instalação e Deploy

### Ambiente de Desenvolvimento
1.  Clone o repositório.
2.  Copie `.env.example` para `.env`.
3.  Suba os containers: `docker-compose up -d`.
4.  Acesse `http://localhost/install` para rodar o instalador web.

### Instalador Web
O arquivo `public/install/index.php` automatiza:
-   Verificação de requisitos.
-   Geração do `.env`.
-   Importação do SQL inicial (`syscms.sql`).
-   Criação do Super Admin.

## 🤝 Regras de Desenvolvimento

1.  Siga as PSRs (1, 2, 4, 12).
2.  Mantenha a lógica de negócio separada dos controladores (use Services/Repositories).
3.  Documente seu código com PHPDoc em inglês.
4.  Use apenas **Bootstrap Icons**.
5.  Prefira **Vanilla JS** em vez de Alpine.js para interações no frontend.
6.  Use **DataTables.js (Versão COMPLETA)** para tabelas de listagem.

Para regras completas, consulte [RULES.md](RULES.md) e [05_PADROES_CODIGO.md](05_PADROES_CODIGO.md).

---
**SysCMS Dev Team**