# CLAUDE.md

Documentación específica por capa:
- Backend: `@backend/CLAUDE.md`
- Frontend: `@frontend/CLAUDE.md`
- Mobile: `@movil/CLAUDE.md`

Estándares de código:
- `@docs/standards/BACKEND_STANDARDS.md`
- `@docs/standards/FRONTEND_STANDARDS.md`
- `@docs/standards/MOBILE_STANDARDS.md`

## Comando para módulos nuevos

Para crear cualquier módulo nuevo, usar siempre el slash command:

```
/nuevo-modulo
```

Este comando guía el proceso en 5 pasos: captura de contexto → verificación de duplicados → lectura de estándares de las capas involucradas → plan de entregables con checklist → implementación paso a paso.

**Regla:** antes de crear migraciones, controladores, servicios, pantallas o servicios de módulos nuevos, los estándares de las capas involucradas deben estar leídos en la sesión activa.

---

## Project Overview

LafortunaApp es un sistema de gestión ganadera para **Rancho La Fortuna**, enfocado en el manejo de especies cinegéticas: **Venados Bura**, **Venados Cola Blanca** y **Borregos Cimarrones**.

---

## Tech Stack

| Capa     | Tecnología                                          |
|----------|-----------------------------------------------------|
| Backend  | Laravel 12 (PHP 8.2+) + JWT via tymon/jwt-auth     |
| Frontend | React + Vite + Bootstrap 5                          |
| Mobile   | React Native 0.70.6 + TypeScript (offline-first)   |
| Base de datos | MySQL 8.0 (principal) + Firebird (Microsip)   |
| Caché    | Redis                                               |

### Estructura del proyecto
```
LafortunaApp/
├── backend/           # Laravel API
├── frontend/          # React + Vite
├── movil/             # React Native
└── docs/
    └── standards/     # Estándares de arquitectura por capa
```

---

## Development Commands

### Quick Start (recomendado)
```bash
cd backend && composer run dev
```
Inicia: Laravel server, queue worker, logs (pail) y Vite dev server.

### Servicios individuales
```bash
# Backend
cd backend
php artisan serve          # :8000
php artisan migrate
php artisan db:seed

# Frontend
cd frontend
npm run dev                # :5173
npm run lint

# Mobile
cd movil
npm run android
npm run ios
npm start                  # Metro bundler
```

### Testing y verificación
```bash
cd backend  && composer run test
cd frontend && npm run lint
cd movil    && npx tsc --noEmit
```

**Backend — configuración de `composer run test` (sin CI, ejecución manual):**
El proyecto usa triggers y stored procedures exclusivos de MySQL (ver
`database/migrations/2025_08_29_000005_create_movimiento_inventario_table.php`,
`2025_12_17_144835_create_sp_simular_alimentacion_procedure.php`,
`2026_06_23_000001_create_sp_distribuir_rechazo.php`) que no corren en SQLite.
Por eso los tests apuntan a un schema **MySQL real y separado** del de desarrollo:

1. Copiar `backend/.env.testing.example` a `backend/.env.testing`.
2. Generar `APP_KEY` y `JWT_SECRET` propios: `php artisan key:generate --env=testing` y `php artisan jwt:secret --env=testing`.
3. Crear el schema una sola vez: `CREATE DATABASE rlf_app_testing;` (o el nombre que se use en `DB_DATABASE`).
4. Correr `composer run test` — `RefreshDatabase` migra automáticamente en cada corrida.

**Nunca** apuntar `DB_DATABASE` de `.env.testing` a la misma base que `.env` (desarrollo) —
`RefreshDatabase`/`migrate:fresh` hacen `DROP` de todas las tablas.

---

## Convenciones Transversales

### UUID como Primary Key

Todas las tablas en MySQL y SQLite usan **UUID string** como PK. Nunca auto-increment.

```php
// ✅ Correcto
$table->uuid('id')->primary();

// ❌ Incorrecto
$table->id();
```

- El UUID lo genera el **cliente** (mobile) al crear un registro offline.
- El mismo UUID se usa en SQLite y MySQL — no se necesita mapeo de IDs.
- Nunca agregar campo `server_id` — el campo `id` es consistente en ambas bases.
- Detección de duplicados: combinación `created_by_device` + `local_id`.

---

## Business Domain

### Especies manejadas
1. **Venado Bura** (Odocoileus hemionus)
2. **Venado Cola Blanca** (Odocoileus virginianus)
3. **Borrego Cimarrón** (Ovis canadensis)

### Gestión de animales
- Genealogía con relaciones padre/madre/crías
- Características físicas: color, peso, medidas
- Historial de corrales y movimientos
- Estado reproductivo (reproductor élite, gestante, etc.)

### Productos — tabla unificada por `tipo`
La tabla `productos` unifica alimentos y medicamentos diferenciados por el campo `tipo`:
- `tipo = 'ALIMENTOS'` → gestionado por `ProductoController`
- `tipo = 'MEDICAMENTO'` → gestionado por `MedicamentoController`

### Objetivo estratégico: Kardex de animales

Todo módulo que involucre animales debe mantener FK directa al animal (`id_animal`). No asumir que la relación indirecta es suficiente. El objetivo final es un perfil completo por animal que agregue eventos, salud, astas, pesajes, reproducción, corrales y alimentación.

**Relaciones ya existentes — no romper ni ignorar:**
- `registro_astas.id_animal` ✅
- `pesaje_animales.id_animal` ✅
- `movimiento_animales.id_animal` ✅
- `venta_animal_detalles.id_animal` ✅
- `asignacion_corrales.id_animal` ✅
- `gestaciones.id_hembra` ✅
- `plan_cruces.id_hembra` + `id_macho` ✅
- `reproductores.id_animal` ✅
- `eventos.id_animal` + `evento_animales.animal_id` ✅

---

## Important Notes

- **Auth**: JWT middleware actualmente **deshabilitado en desarrollo**
- **Base de datos**: MySQL con UTF-8 completo para contenido en español
- **File Uploads**: No implementado aún (planeado para fotos de animales)
- **Redis**: Listo para WebSocket en el futuro

## Troubleshooting

| Problema | Solución |
|---|---|
| CORS errors | Revisar `backend/config/cors.php` |
| DB connection | Verificar credenciales en `.env` |
| JWT errors | Ejecutar `php artisan jwt:secret` |
| Node modules | Borrar `node_modules` y `npm install` |
| Laravel cache | `php artisan config:clear` |
| Logs Laravel | `backend/storage/logs/laravel.log` o `php artisan pail` |
| Frontend | Consola del browser y output de Vite |

---

## Principios de Desarrollo

Aplicar siempre al generar código:

- **SOLID**: Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion
- **DRY**: No repetir lógica — usar helpers, traits o servicios si algo se usa más de dos veces
- **MVC**: Controladores delgados — la lógica de negocio va en servicios, nunca en controllers ni vistas

---

## INSTRUCCIONES DE COMPORTAMIENTO OBLIGATORIAS

Aplican a todo trabajo en este repositorio, sin excepción.

### 1. Analiza primero, escribe después

Lee los archivos relevantes con `Read` o `Glob` antes de proponer cualquier cambio. Nunca asumas que un archivo existe, que un campo tiene cierto nombre, o que una clase ya está implementada.

### 2. Implementa un paso a la vez

Después de completar cada paso, detente y entrega:
- Resumen de qué archivos se leyeron y qué se encontró
- Qué se modificó o creó y por qué
- Explicación técnica del mecanismo implementado (nivel senior: patrones, trade-offs, decisiones de diseño)
- Comando de verificación que el desarrollador puede correr antes de continuar

### 3. Valida y prueba antes de dar por terminado

La verificación tiene dos niveles — ambos obligatorios:

**Nivel 1 — Sintaxis** (después de modificar cualquier archivo):
```bash
# PHP
php -l <archivo>

# TypeScript / TSX / JSX
npx tsc --noEmit
npx eslint <archivo>
```

**Nivel 2 — Funcionalidad** (antes de reportar la tarea como completa):
- Ejecuta el test o comando relevante y confirma que pasa
- Si hay un flujo de usuario involucrado, recórrelo mentalmente paso a paso
- Pregúntate: *"¿Aprobaría esto un desarrollador senior?"*
- Si la respuesta es dudosa, itera antes de entregar

Si el lint falla o el comportamiento es incorrecto, corrige antes de continuar. No avances con archivos rotos ni con lógica incompleta.

### 4. No reimplementes lo que ya existe

Si encuentras que un servicio, método o migración ya cubre el caso, documéntalo y adapta en lugar de duplicar.

### 5. Verifica fuentes de verdad entre capas

Antes de implementar lógica en móvil o frontend, verifica que el backend ya la expone correctamente.

### 6. Detecta lógica reutilizable antes de encapsularla

Si al implementar identificas que la lógica podría aplicar a otros módulos:

1. Documenta el hallazgo y en qué módulos podría reutilizarse
2. Sugiere extraerla al nivel correcto:
   - **Backend**: `app/Services/`, `app/Helpers/`, o `app/Traits/`
   - **Frontend**: `src/core/hooks/` o `src/core/components/`
   - **Mobile**: `src/core/services/` o `src/core/hooks/`
3. Espera confirmación — el desarrollador decide si abstraer ahora o registrar como deuda técnica

### 7. Elegancia balanceada

Para cambios no triviales, antes de entregar pregúntate: *"¿Hay una solución más limpia?"*

- Si el código se siente hacky o forzado → implementa la solución elegante desde el inicio
- Si es un fix obvio y simple → no sobre-ingenieres, entrégalo directo
- El objetivo es código que no necesite disculpas ni comentarios que expliquen por qué está así

### 8. Captura de lecciones aprendidas

Después de cualquier corrección del desarrollador (cambio de enfoque, error detectado, patrón incorrecto):

1. Registra la lección en `docs/lessons.md` con el formato:
   ```
   ## [fecha] — [título corto]
   **Error:** qué se hizo mal
   **Corrección:** qué debe hacerse en su lugar
   **Aplica a:** backend / frontend / mobile / todos
   ```
2. Revisa `docs/lessons.md` al inicio de cada sesión para no repetir los mismos errores