Estrutura do Projeto

O Projeto Base USP segue a estrutura de diretórios padrão do Laravel 11, que organiza o código de forma lógica e facilita a manutenção. Compreender essa estrutura é fundamental para navegar e estender o projeto.

Visão Geral dos Diretórios Principais

A organização básica dos diretórios é a seguinte:

nome-do-seu-projeto/
├── app/                  # Núcleo da aplicação (Models, Controllers, Providers, etc.)
│   ├── Console/
│   ├── Exceptions/
│   ├── Helpers/          # Diretório para funções auxiliares (ex: helpers.php)
│   ├── Http/
│   │   ├── Controllers/  # Controllers (inclui Auth/, Admin/)
│   │   ├── Middleware/   # Middlewares customizados (ex: EnsureEmailIsVerifiedGlobally.php)
│   │   └── Requests/     # Form Requests (inclui Auth/, Admin/)
│   ├── Models/           # Eloquent Models (ex: User.php)
│   ├── Notifications/    # Classes de Notificação (ex: VerifyUserEmail.php)
│   └── Providers/        # Service Providers (AppServiceProvider, AuthServiceProvider, etc.)
├── bootstrap/            # Arquivos de inicialização e cache gerado
│   └── cache/
├── config/               # Arquivos de configuração da aplicação (app.php, auth.php, database.php, etc.)
├── database/             # Arquivos relacionados ao banco de dados
│   ├── factories/        # Factories para gerar dados de teste (UserFactory.php)
│   ├── migrations/       # Arquivos de Migrations para estrutura do DB
│   └── seeders/          # Seeders para popular o DB (DatabaseSeeder.php, RolesAndPermissionsSeeder.php)
├── public/               # Ponto de entrada HTTP (index.php) e assets públicos (compilados)
│   ├── build/            # Assets compilados pelo Vite
│   └── storage/          # Link simbólico para storage/app/public
├── resources/            # Arquivos fonte não compilados
│   ├── css/              # Arquivos CSS fonte (app.css)
│   ├── js/               # Arquivos JavaScript fonte (app.js, bootstrap.js)
│   └── views/            # Arquivos Blade (layouts, components, auth, profile, admin, etc.)
├── routes/               # Definição das rotas
│   ├── api.php
│   ├── auth.php          # Rotas de autenticação (Breeze e customizadas)
│   ├── channels.php
│   ├── console.php       # Comandos Artisan
│   ├── socialite.php     # Rotas do Senha Única (se separadas)
│   └── web.php           # Rotas Web (inclui /admin)
├── storage/              # Arquivos gerados pela aplicação
│   ├── app/
│   │   ├── private/      # Diretório para uploads/arquivos privados (exemplo)
│   │   └── public/       # Arquivos acessíveis publicamente via /storage link
│   ├── framework/        # Arquivos de cache, sessions, views compiladas
│   └── logs/             # Arquivos de log
├── tests/                # Testes automatizados
│   ├── Browser/          # Testes Dusk (End-to-End)
│   ├── Feature/          # Testes de Funcionalidade (HTTP)
│   ├── Unit/             # Testes Unitários
│   ├── CreatesApplication.php
│   ├── DuskTestCase.php  # TestCase base para Dusk (customizado)
│   └── TestCase.php      # TestCase base para PHPUnit
├── vendor/               # Dependências do Composer (gerenciado automaticamente)
├── .editorconfig         # Configuração de estilo para editores
├── .env                  # Arquivo de configuração do ambiente (NÃO versionar!)
├── .env.dusk.local       # Configuração específica para testes Dusk
├── .env.example          # Exemplo de arquivo .env
├── .env.testing          # Configuração específica para testes PHPUnit
├── .gitattributes        # Configurações do Git
├── .gitignore            # Arquivos/pastas ignorados pelo Git
├── artisan               # Utilitário de linha de comando do Laravel
├── composer.json         # Dependências PHP (Composer)
├── composer.lock         # Lockfile do Composer
├── package-lock.json     # Lockfile do NPM
├── package.json          # Dependências Node.js (NPM)
├── phpunit.xml           # Configuração do PHPUnit
├── postcss.config.js     # Configuração do PostCSS
├── tailwind.config.js    # Configuração do Tailwind CSS
└── vite.config.js        # Configuração do Vite

Localização dos Componentes Chave

• Models: app/Models/
  • User.php: Modelo principal de usuário, com traits para Senha Única e Permissões (Spatie).
• Controllers: app/Http/Controllers/
  • Auth/: Controllers relacionados à autenticação (Login, Registro, Reset de Senha, Verificação de Email, Senha Única, Senha Local USP).
  • Admin/: Controllers específicos da área administrativa (ex: UserController.php).
  • ProfileController.php: Gerencia a edição do perfil do usuário.
  • Controller.php: Controller base da aplicação.
• Requests (Validação): app/Http/Requests/
  • Auth/: Requests para validação de formulários de autenticação e registro.
  • Admin/: Requests para validação de formulários administrativos (ex: criação de usuário).
  • ProfileUpdateRequest.php: Validação da atualização do perfil.
• Views (Blade Templates): resources/views/
  • layouts/: Layouts base da aplicação (app.blade.php que estende o laravel-usp-theme, guest.blade.php).
  • components/: Componentes Blade reutilizáveis (gerados pelo Breeze, ex: botões, inputs, modal).
  • auth/: Views relacionadas à autenticação (login, register, forgot-password, verify-email, etc.).
  • profile/: Views para edição do perfil do usuário (incluindo parciais para cada seção).
  • admin/: Views específicas da área administrativa (dashboard, lista/criação de usuários).
  • dashboard.blade.php: View principal do painel do usuário.
  • welcome.blade.php: Página inicial da aplicação.
  • vendor/: Views publicadas por pacotes (ex: notifications/email.blade.php customizada).
• Rotas: routes/
  • web.php: Rotas principais da aplicação web (inclui dashboard, profile e grupo /admin).
  • auth.php: Rotas de autenticação geradas pelo Breeze e customizadas (ex: verificação, senha local).
  • console.php: Comandos Artisan customizados.
  • socialite.php: (Importante) Rotas específicas para o fluxo OAuth da Senha Única (login, callback, logout, loginAs). Nota: Verificar se este arquivo é criado separadamente ou se as rotas estão em web.php no projeto final.
• Migrations: database/migrations/
  • Arquivos para criar e modificar a estrutura do banco de dados (tabelas users, password_reset_tokens, sessions, cache, jobs, failed_jobs, tabelas do spatie/laravel-permission, modificações na users para codpes e password nullable).
• Seeders: database/seeders/
  • DatabaseSeeder.php: Seeder principal que chama outros seeders.
  • RolesAndPermissionsSeeder.php: Cria os papéis e permissões iniciais.
• Configurações: config/
  • app.php: Configurações gerais (nome, env, debug, locale pt_BR, timezone).
  • auth.php: Configuração dos guards e providers de autenticação.
  • database.php: Conexões com banco de dados.
  • filesystems.php: Discos de armazenamento (local, public, s3).
  • logging.php: Canais de log.
  • mail.php: Configurações de envio de email.
  • queue.php: Conexões de fila.
  • services.php: Credenciais para serviços de terceiros (usado implicitamente pelo Socialite).
  • session.php: Configurações de sessão.
  • laravel-usp-theme.php: Configuração do menu e aparência do tema USP.
  • permission.php: Configuração do spatie/laravel-permission (nomes de tabela, cache, etc.).
  • senhaunica.php: Configuração do uspdev/senhaunica-socialite (rotas, permissões, admins, etc.).
• Assets Frontend:
  • resources/css/app.css: Arquivo principal CSS (importa Tailwind).
  • resources/js/app.js: Arquivo principal JavaScript (importa bootstrap.js e inicializa Alpine.js).
  • resources/js/bootstrap.js: Configuração inicial do Axios.
• Helpers: app/Helpers/helpers.php
  • Contém funções auxiliares globais, como disableValidationIfTesting. É carregado automaticamente via composer.json (seção autoload.files).
• Testes: tests/
  • Feature/: Testes que simulam requisições HTTP e verificam respostas e estado da aplicação.
  • Unit/: Testes para unidades isoladas de código (classes, métodos).
  • Browser/: Testes End-to-End usando Laravel Dusk.
  • DuskTestCase.php: Classe base para testes Dusk, customizada para capturar HTML em falhas.
  • TestCase.php: Classe base para testes PHPUnit.