# Reglas de proyecto: Laravel + Vue 3 (SPA)

## 1. Contexto técnico

- **Backend**: Laravel 9.x (PHP ^8.0.2), API REST en `routes/api.php` con **Laravel Sanctum** (`auth:sanctum` en rutas protegidas).
- **Frontend**: Vue 3 (Composition API), empaquetado con **Laravel Mix** (`webpack.mix.js`); entrada `resources/js/src/main.js` → salida `public/js`.
- **SPA**: `routes/web.php` delega en `AppController` la vista única; el enrutado de pantallas lo define **Vue Router** en `resources/js/src/router/index.js`.
- **Permisos**: Spatie `laravel-permission` (backend) y `laravel-permission-to-vuejs` (frontend) donde aplique.
- **Estado global**: Pinia — `resources/js/src/store/` (`StateStore.js`, etc.).

## 2. Estructura del repositorio (referencia)

```
app/
  Http/Controllers/     # Lógica HTTP; mantener controladores delgados
  Http/Middleware/
  Models/               # Eloquent: $fillable, relaciones
  Mail/                 # Mailables y notificaciones por correo
  Helpers/              # Helpers cargados vía composer (ej. FormatoFecha)
  Providers/
bootstrap/
config/
database/
  migrations/           # No es el flujo habitual de despliegue de esquema en este proyecto
  seeders/
  sql/                  # Scripts SQL manuales (ver §4.1)
lang/                   # Traducciones Laravel (es/en, …)
resources/
  js/src/               # Código fuente Vue (ver §3)
  views/                # Blade mínimo (SPA + mails en resources/views/mails/)
routes/
  api.php               # Endpoints JSON consumidos por Axios
  web.php               # Catch-all hacia la SPA
public/                 # Assets compilados (js, …)
tests/
```

## 3. Frontend (`resources/js/src/`)

- **Alias Webpack**: `@` → `resources/js/src/`; `@themeConfig` → `resources/js/theme.config.js`.
- **Carpetas habituales**:
  - `components/` — UI reutilizable (incl. `components/layout/`).
  - `views/` — páginas por dominio (clientes, citas, ventas, configuración, auth, …).
  - `layouts/` — `app-layout.vue`, `auth-layout.vue`.
  - `repositories/` — llamadas API (patrón tipo `ClienteRepository.js`).
  - `services/` — `ApiService.js` (Axios + token), `ApiServiceFile.js` (multipart).
  - `composables/` — lógica reutilizable (ej. `use-meta.js`).
  - `store/` — Pinia.
  - `locales/` + `i18n.js` — **vue-i18n** (`$t()` en plantillas).
- **API HTTP**: JSON con `@/services/ApiService`; archivos con `@/services/ApiServiceFile`. Token: `localStorage` gestionado en interceptores (alineado con el código existente).
- **Componentes**: Preferir `<script setup>` y composables para lógica reactiva.
- **Patrón repositorios JS** (imitar `ClienteRepository.js`): importar `ApiService`, `const baseUrl = "recurso";`, funciones `async` que devuelvan `response.data`, CRUD coherente con el backend.

## 4. Backend

### 4.1 Base de datos (sin migraciones Laravel como vía principal)

- **No** se usa el ciclo típico de migraciones para aplicar cambios de esquema en producción: los cambios van en **SQL manual** bajo `database/sql/`.
- **`database/sql/actualizaciones.sql`**: historial acumulado de `ALTER`/`CREATE` y notas; conviene seguir añadiendo al final con comentario de fecha o contexto cuando se quiera un solo archivo de referencia.
- **Archivos aparte**: para un despliegue, feature o entorno concreto, crear **otro `.sql`** en la misma carpeta (p. ej. `database/sql/cambios_pendientes.sql` o `cambios_YYYY_MM_DD_descripcion.sql`) con solo lo que hay que ejecutar; evita mezclar en `actualizaciones.sql` hasta que decidas consolidar.
- Tras ejecutar en la BD, opcionalmente **copiar** esas sentencias al final de `actualizaciones.sql` para dejar un historial único en el repo.
- Los modelos Eloquent deben reflejar columnas/tablas nuevas (`$fillable`, casts, etc.).

### 4.2 Resto

- **Rutas API**: Registrar en `routes/api.php`; agrupar con middleware Sanctum cuando la ruta sea para usuarios autenticados.
- **Validación**: Este proyecto valida muchas veces en controladores; para código nuevo se puede introducir `FormRequest` en `app/Http/Requests/` si se desea separar reglas sin romper el estilo existente.
- **Modelos**: `$fillable`, casts y relaciones Eloquent explícitas.
- **Correo**: Clases en `app/Mail/` y vistas en `resources/views/mails/`.

## 5. Estilo y convenciones

- **Nomenclatura**: JS/Vue: `camelCase`; PHP: `PascalCase` clases, `snake_case` BD; componentes Vue: `PascalCase` en archivos donde ya se use así.
- **Idioma**: Identificadores de código en **inglés**; comentarios y explicaciones al usuario en **español** cuando corresponda.
- **i18n UI**: Cadenas visibles vía `vue-i18n` / `$t()` y archivos en `locales/`.

## 6. Generación de código (nuevas funcionalidades / CRUD)

1. **Esquema BD**: SQL en `database/sql/` — archivo dedicado incremental o líneas nuevas en `actualizaciones.sql` según convengas; actualizar el **Modelo** Eloquent (sin depender de migraciones para desplegar el cambio).
2. Controlador + rutas en `routes/api.php`.
3. Repositorio JS (`repositories/`) usando `ApiService` y `baseUrl`.
4. Vista(es) en `views/` y ruta en `router/index.js`; estado en Pinia solo si hace falta compartir datos.

Al implementar, reutilizar patrones existentes en el mismo dominio (nombres de rutas API, forma de paginación, etc.) en lugar de inventar convenciones nuevas.
