67 lines
3.6 KiB
Markdown
67 lines
3.6 KiB
Markdown
---
|
|
name: project-route-structure
|
|
description: "Always apply in this project when creating, moving, or refactoring Laravel route definitions in routes/*.php; changing route prefixes, names, middleware, scoped bindings, or route files; or adding frontend-facing endpoints that Wayfinder generates. Documents the KanbanGit route-file layout and grouping conventions."
|
|
---
|
|
|
|
# Project Route Structure
|
|
|
|
## When to Apply
|
|
|
|
Activate this skill whenever work in this project changes:
|
|
|
|
- `routes/*.php`
|
|
- Route names, URI prefixes, middleware groups, scoped bindings, or controller route registrations
|
|
- Frontend-facing endpoints that require regenerated Wayfinder output
|
|
|
|
Use this together with `laravel-best-practices`. Also activate `wayfinder-development` when route changes affect generated frontend route/action imports.
|
|
|
|
## Route Files
|
|
|
|
- `routes/web.php` is the web entry point only. Keep public shell routes here, such as `home` and `dashboard`, then require domain route files.
|
|
- `routes/projects.php` owns all `projects.*` routes.
|
|
- `routes/admin.php` owns all `admin.*` routes.
|
|
- `routes/teams.php` owns all `teams.*` routes.
|
|
- `routes/settings.php` owns account settings routes, but keeps their existing route names such as `profile.edit`, `security.edit`, and `git-connections.edit`.
|
|
|
|
Add a new route file only when a domain gets large enough to stand alone. Otherwise, extend the existing domain file.
|
|
|
|
## Grouping Pattern
|
|
|
|
- Put shared middleware, URI prefixes, route name prefixes, and controller declarations on groups instead of repeating them on each route.
|
|
- Prefer this nesting order when it reads naturally: `middleware(...)`, `prefix(...)`, `name(...)`, `controller(...)`, then `group(...)`.
|
|
- Keep public route names stable unless the user explicitly asks for a public interface change.
|
|
- Keep route URIs stable when reorganizing route files; this kind of change should be structural.
|
|
- Use `function (): void` for route group closures.
|
|
|
|
## Project Routes
|
|
|
|
Project routes should follow this shape:
|
|
|
|
- Top-level group: `middleware(['auth', 'verified'])`, `prefix('projects')`, `name('projects.')`.
|
|
- Project create/store routes live under `can:create-project`.
|
|
- Routes under `{project}` use project gates by capability:
|
|
- Read pages: `can:view-project,project`
|
|
- Mutations: `can:write-project,project`
|
|
- Project settings and access management: `can:admin-project,project`
|
|
- Project delete: `can:access-admin`
|
|
- `projects/{project}/permissions/...` must not be inside `Route::scopeBindings()`, because `Project` does not define `users()` or `teams()` child relationships.
|
|
- Use `Route::scopeBindings()` only around nested project resources that should bind through project-owned relationships, such as tickets and project settings children.
|
|
- Keep ticket subroutes grouped under `tickets.` and settings subroutes grouped under `settings.`.
|
|
|
|
## Settings Routes
|
|
|
|
- Keep the `settings` URI prefix grouped.
|
|
- Keep profile edit/update behind `auth` only.
|
|
- Keep profile deletion, security, git connections, and appearance behind `auth` plus `verified`.
|
|
- Do not rename settings routes to a `settings.*` namespace unless the frontend/tests are intentionally updated.
|
|
|
|
## Verification
|
|
|
|
After changing route files:
|
|
|
|
1. Run `php artisan route:list --except-vendor`.
|
|
2. Run `php artisan wayfinder:generate --with-form --no-interaction` when any route signature, name, method, or controller action changed.
|
|
3. Run `vendor/bin/pint --dirty --format agent` for PHP route formatting.
|
|
4. Run the affected feature tests, usually `php artisan test --compact tests/Feature/Projects tests/Feature/Teams tests/Feature/Admin tests/Feature/Settings`.
|
|
5. Run `git diff --check` before finalizing.
|