# regexp.ro rewrite — project rules **Acest proiect este o rescriere 1:1 a unei aplicatii existente din productie.** Proiectul vechi (CodeIgniter 3) se afla la `C:\xampp\htdocs\regexp\`. Proiectul nou (Laravel 12 + Vue 3 + Inertia + TypeScript) este acest director. Ambele impart aceeasi baza de date: `regexpro_registru1` (MySQL, `utf8_romanian_ci`). Platforma: Registrul Expertilor Atestati de Mediu (regexp.ro), operata de Asociatia Romana de Mediu. Limba UI: romana fara diacritice. ## Dimensiunile platformei Orice feature din PAS 2 si PAS 3 se comporta dinamic in functie de 3 dimensiuni combinate: - `tip_persoana`: 1 = PFA, 2 = PF, 3 = PJ - `tip_nivel`: 1..5 - `solicitare_tip`: `initiala`, `aplicare_dubla`, `reinnorie_certificat`, `modificare_loc_de_munca`, `extindere_tipuri_studi`, `extinderea_domeniilor`, `reluare_interviu` **Starea curenta:** implementarea si documentatia acopera doar `solicitare_tip = initiala`. Infrastructura dinamica (tabelele `documente_catalog` + `reguli_documente`, UI `/admin/configurare-documente`) este pregatita pentru toate variantele, dar regulile nu sunt seed-uite decat pentru `initiala`. Nu presupune ca alte `solicitare_tip`-uri se comporta la fel — vor fi tratate separat. ## Protocol obligatoriu: inventar inainte de cod Userul nu-si aminteste toate amanuntele proiectului vechi. Deci **inventarul este sursa de adevar**, nu memoria niciunuia dintre noi. Inainte de a rescrie orice feature (sau chiar o bucata dintr-un feature): 1. **Lanseaza un agent `Explore`** (thoroughness: very thorough) care sa mapeze exhaustiv feature-ul in CI3. Nu face inventarul inline in contextul principal — ocupa prea mult spatiu si duce la omisiuni. 2. **Agent-ul trebuie sa porneasca de la ruta si sa coboare prin toate dependintele, IN ORDINE:** 1. **Ruta** (`application/config/routes.php` + conventia CI de routing implicit `controller/method`). Noteaza pattern-ul URL complet. 2. **Controller** — metoda mapata la ruta. Toate parametrii, validarile, branch-urile `if/elseif`, flash messages, redirect-urile, side-effects. NOTEAZA ce metode apeleaza pe models, ce view-uri incarca, ce libraries foloseste. 3. **Model(e)** — fiecare metoda apelata de controller. Query-urile SQL exacte (joins, where-uri, ordering, group by), tabelele atinse, ce coloane citeste/scrie. 4. **View(s)** — fiecare view incarcat de controller (inclusiv view-uri nested prin `include`). Toate campurile afisate, label-urile in romana (exact), textele cu rosu, hint-urile in paranteze, butoanele (text + clase CSS + href-uri), modal-urile, starile conditionale. 5. **Dependinte colaterale** descoperite pe parcurs: - JS aferent (AJAX handlers, confirm-uri, validari client-side) — caut in views si in `assets/js/` - Email-urile declansate (destinatari, subject, template, conditii de trimitere) - Scrieri in DB in afara modelului principal (insert-uri in `actions_admins`, `actions_users`, update-uri colaterale) - Upload-uri de fisiere (path, denumire, permisiuni) - Permisiuni/guard-uri (ce user/admin poate accesa, conditii extra) - Edge cases vizibile: ce se afiseaza cand lista e goala, cand userul nu are drept, cand fisierul lipseste, cand statusul e X vs Y **Nu sari peste lant.** Daca descoperi ca view-ul apeleaza o metoda de model care n-a fost listata in controller → investigheaza, adauga in inventar. Daca descoperi `$this->load->view('x', $y)` dar n-ai lista-o → adauga. 3. **Returneaza un checklist structurat** pe care userul il poate aproba/corecta punct cu punct. 4. **Marcheaza explicit "nu stiu" / "ambiguu" / "necesita confirmare"** cand ceva nu e clar din cod (ex: un flag pe care il citesti dar nu stii cand e setat). Nu ghici si nu tacea despre ambiguitati. 5. **Abia dupa confirmarea userului, scrii cod.** Implementarea bifeaza elementele din checklist. 6. La final, **verifica fiecare punct din checklist** impotriva implementarii noi inainte de a raporta "gata". ## Ce inseamna "1:1 parity" Fiecare comportament observabil din proiectul vechi (UI, email, insert in DB, redirect, validare, mesaj de eroare, status, ordine de sortare, etichete) trebuie sa existe si in cel nou. Design-ul UI poate fi modernizat, dar nu si comportamentul. Abaterile permise (trebuie mentionate explicit userului cand le faci): - Imbunatatiri de securitate (bcrypt in loc de MD5, CSRF, escape-uri, middleware) - Anti-spam decis impreuna (ex: fara buton "retrimite documente" — cerinta userului) - Permisiuni granulare (super-admin vs admin — cerinta userului) - Design vizual modernizat Orice alta abatere functionala e un bug, nu o imbunatatire. ## Anti-patterns (lucruri pe care le-am gresit inainte) - Sa presupun ca stiu fluxul din proiectul vechi fara sa-l citesc → produce omisiuni. - Sa rescriu "pe bucati" un controller fara sa am harta intregului feature → se pierd branch-urile din `if/elseif` si redirect-urile. - Sa tratez similar diferite `solicitare_tip` → sunt dinamice si diferite. - Sa ignor email-urile sau insert-urile in `actions_admins`/`actions_users` — sunt parte din feature. - Sa las ambiguitati nemarcate — userul nu le poate confirma daca nu i le spun. ## Locatii cheie proiect vechi (pentru Explore agent) - Controllers: `C:\xampp\htdocs\regexp\application\controllers\` (Admin.php ~200KB, Users.php ~115KB, Pregatire.php ~70KB, Tests.php, Applications.php, Pages.php, Lists_admin.php, Lists_public.php, Sesiuni.php, Status_users.php, MyAnaf.php, SendEmailsFromPubList.php) - Models: `C:\xampp\htdocs\regexp\application\models\` - Views: `C:\xampp\htdocs\regexp\application\views\` (admin_views, user_views, aplica_views, pages_views, test_views, templates_views, email_template.html) - Rute explicite: `C:\xampp\htdocs\regexp\application\config\routes.php` - Fisiere uploadate (pt structura): `C:\xampp\htdocs\regexp\userfiles\` --- === foundation rules === # Laravel Boost Guidelines The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to ensure the best experience when building Laravel applications. ## Foundational Context This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions. - php - 8.2 - inertiajs/inertia-laravel (INERTIA_LARAVEL) - v2 - laravel/framework (LARAVEL) - v12 - laravel/prompts (PROMPTS) - v0 - tightenco/ziggy (ZIGGY) - v2 - laravel/boost (BOOST) - v2 - laravel/mcp (MCP) - v0 - laravel/pail (PAIL) - v1 - laravel/pint (PINT) - v1 - laravel/sail (SAIL) - v1 - pestphp/pest (PEST) - v3 - phpunit/phpunit (PHPUNIT) - v11 - @inertiajs/vue3 (INERTIA_VUE) - v2 - tailwindcss (TAILWINDCSS) - v3 - vue (VUE) - v3 - eslint (ESLINT) - v9 - prettier (PRETTIER) - v3 ## Conventions - You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming. - Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`. - Check for existing components to reuse before writing a new one. ## Verification Scripts - Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important. ## Application Structure & Architecture - Stick to existing directory structure; don't create new base folders without approval. - Do not change the application's dependencies without approval. ## Frontend Bundling - If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them. ## Documentation Files - You must only create documentation files if explicitly requested by the user. ## Replies - Be concise in your explanations - focus on what's important rather than explaining obvious details. === boost rules === # Laravel Boost ## Artisan - Run Artisan commands directly via the command line (e.g., `php artisan route:list`). Use `php artisan list` to discover available commands and `php artisan [command] --help` to check parameters. - Inspect routes with `php artisan route:list`. Filter with: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`. - Read configuration values using dot notation: `php artisan config:show app.name`, `php artisan config:show database.default`. Or read config files directly from the `config/` directory. - To check environment variables, read the `.env` file directly. ## Tinker - Execute PHP in app context for debugging and testing code. Do not create models without user approval, prefer tests with factories instead. Prefer existing Artisan commands over custom tinker code. - Always use single quotes to prevent shell expansion: `php artisan tinker --execute 'Your::code();'` - Double quotes for PHP strings inside: `php artisan tinker --execute 'User::where("active", true)->count();'` === php rules === # PHP - Always use curly braces for control structures, even for single-line bodies. - Use PHP 8 constructor property promotion: `public function __construct(public GitHub $github) { }`. Do not leave empty zero-parameter `__construct()` methods unless the constructor is private. - Use explicit return type declarations and type hints for all method parameters: `function isAccessible(User $user, ?string $path = null): bool` - Use TitleCase for Enum keys: `FavoritePerson`, `BestLake`, `Monthly`. - Prefer PHPDoc blocks over inline comments. Only add inline comments for exceptionally complex logic. - Use array shape type definitions in PHPDoc blocks. === tests rules === # Test Enforcement - Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass. - Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test --compact` with a specific filename or filter. === inertia-laravel/core rules === # Inertia - Inertia creates fully client-side rendered SPAs without modern SPA complexity, leveraging existing server-side patterns. - Components live in `resources/js/pages` (unless specified in `vite.config.js`). Use `Inertia::render()` for server-side routing instead of Blade views. - ALWAYS use `search-docs` tool for version-specific Inertia documentation and updated code examples. - IMPORTANT: Activate `inertia-vue-development` when working with Inertia Vue client-side patterns. # Inertia v2 - Use all Inertia features from v1 and v2. Check the documentation before making changes to ensure the correct approach. - New features: deferred props, infinite scroll, merging props, polling, prefetching, once props, flash data. - When using deferred props, add an empty state with a pulsing or animated skeleton. === laravel/core rules === # Do Things the Laravel Way - Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using `php artisan list` and check their parameters with `php artisan [command] --help`. - If you're creating a generic PHP class, use `php artisan make:class`. - Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior. ### Model Creation - When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `php artisan make:model --help` to check the available options. ## APIs & Eloquent Resources - For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention. ## URL Generation - When generating links to other pages, prefer named routes and the `route()` function. ## Testing - When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model. - Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`. - When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. ## Vite Error - If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`. ## Deployment - Laravel can be deployed using [Laravel Cloud](https://cloud.laravel.com/), which is the fastest way to deploy and scale production Laravel applications. === laravel/v12 rules === # Laravel 12 - Since Laravel 11, Laravel has a new streamlined file structure which this project uses. ## Laravel 12 Structure - In Laravel 12, middleware are no longer registered in `app\Http/Kernel.php`. - Middleware are configured declaratively in `bootstrap/app.php` using `Application::configure()->withMiddleware()`. - `bootstrap/app.php` is the file to register middleware, exceptions, and routing files. - `bootstrap/providers.php` contains application specific service providers. - The `app\Console/Kernel.php` file no longer exists; use `bootstrap/app.php` or `routes/console.php` for console configuration. - Console commands in `app\Console/Commands/` are automatically available and do not require manual registration. ## Database - When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost. - Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`. ### Models - Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models. === pint/core rules === # Laravel Pint Code Formatter - If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style. - Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues. === pest/core rules === ## Pest - This project uses Pest for testing. Create tests: `php artisan make:test --pest {name}`. - Run tests: `php artisan test --compact` or filter: `php artisan test --compact --filter=testName`. - Do NOT delete tests without approval. === inertia-vue/core rules === # Inertia + Vue Vue components must have a single root element. - IMPORTANT: Activate `inertia-vue-development` when working with Inertia Vue client-side patterns.