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 - Estrutura de diretórios, componentes do kernel, autoloading PSR-4 e padrões de design.

Sistema de Módulos

• 📄 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 - Guia passo a passo para criar módulos instaláveis.
• 📄 17_MODULE_TEMPLATE.md - Template padrão para novos módulos.
• 📄 20_CRIACAO_DE_NOVOS_MODULOS.md - Guia baseado no sucesso do PhotoEssay para criar novos módulos.

Tecnologias e Padrões

• 📄 04_TECNOLOGIAS.md - Stack tecnológica completa (backend, frontend, ambiente de desenvolvimento).
• 📄 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 - Sistema de Hooks (Actions & Filters) para modificar o comportamento do sistema.

Funcionalidades Específicas

• 📄 15_QUILL_IMPLEMENTATION_COMPLETE.md - Implementação do editor Quill.
• 📄 16_REGRAS_QUILL_IA.md - Regras específicas para IA trabalhar com Quill.
• 📄 18_THEMES_CUSTOMIZER.md - Sistema de customização de temas.
• 📄 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 - Uso do Symfony Dotenv para variáveis de ambiente.
• 📄 08_IA_COMMAND_EXECUTION_GUIDE.md - Guia de execução de comandos PHP para a IA.
• 📄 09_LANGUAGE_CONFIG_README.md - Configuração de idiomas suportados.

Comportamento da IA

• 📄 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 - 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:

docker exec -w /app dockersyscms php syscli make:module [nome]

Ou siga o guia detalhado em 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:

docker exec -w /app dockersyscms php syscli cache:clear

5. Banco de Dados (Eloquent)

O SysCMS usa o Eloquent ORM.

Models

namespace Modules\MeuModulo\Models;
use Illuminate\Database\Eloquent\Model;

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

Migrations

# 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/.

{% 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.

  add_action('user_registered', function($user_id) {
      enviar_email_boas_vindas($user_id);
  });
  

• Filters: Modificam dados antes de serem usados/exibidos.

  add_filter('the_content', function($content) {
      return str_replace('Palavrão', '***', $content);
  });
  

Para mais detalhes, consulte 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 e 05_PADROES_CODIGO.md.

---

SysCMS Dev Team