# CLAUDE.md — Plazas AI

> **Contexto vivo (estado, entorno local, decisiones de desarrollo):** @.claude/contexto-proyecto.md — actualizarlo al cerrar cada módulo.

## ⚠️ Alcance actual (leer antes de trabajar en cualquier tarea)

Los siguientes Bounded Contexts están **diferidos** — no se construyen en este MVP:
- Prediales y catastro (ADR-010)
- Documentación de plazas (ADR-010)
- Conciliación contable (CONTPAQi) (ADR-010)
- Persona física del licenciado (ADR-010)

El código y la documentación de estos contextos, si llegan a existir, se quedan tal
cual — no se borran. Pero a partir de ahora:

- No los tomes en cuenta al planear, sugerir, refactorizar o documentar trabajo nuevo.
- No los extiendas ni los repares, aunque los veas mencionados en otros documentos.
- No los menciones como contexto relevante salvo que el usuario pregunte explícitamente.
- Son alcance en pausa, no eliminado — el usuario dirá explícitamente cuándo se retoman.

Ver ADR-010 en `docs/fase-4-arquitectura/decisions/` para el motivo de la pausa y la
condición bajo la que se retoman.

---

## 1. Contexto del Proyecto

Plazas AI es el panel web con que el equipo del Lic. Salvador C. Gutiérrez González (GCS Terra S. de R.L. de C.V., Plaza Amistad AC y las razones sociales que dé de alta) administra los arrendamientos de sus plazas comerciales. Reemplaza más de 10 Excel alimentados a mano: genera los cobros del mes desde los contratos, concilia los pagos contra el estado de cuenta del banco, calcula intereses moratorios, propone incrementos con el INPC, registra gastos desde el CFDI y arma el cashflow y el reporte para el despacho. **La plataforma propone; el equipo confirma y decide.** El timbrado de facturas y la contabilidad siguen fuera.

Documentación completa: `docs/` (Fases 1-6). Material de levantamiento: `../admon-arrendamientos-plazas/`.

## 2. Stack Técnico

- PHP 8.5 · Laravel (última estable al bootstrap; versión real la escribe `bootstrap.mjs`) · MySQL 8 (InnoDB, utf8mb4)
- Filament ^5.0 · Livewire · Tailwind CSS · tema Orbit canónico de `laravel-ai-template`
- `bezhansalleh/filament-shield` (roles/permisos por sección) · `codeat3/blade-ikonate` · `laravel/boost`
- `brick/math` (dinero exacto) · `phpoffice/phpspreadsheet` (Excel de bancos, importación y exportación) · lector CFDI (`eclipxe/cfdiutils` o `phpcfdi/cfdi-to-json`) · `barryvdh/laravel-dompdf` (cartas y tablas PDF)
- Claude API (Anthropic) con credenciales del cliente · INEGI API · Banxico SIE · SMTP
- Cola `database` procesada por `schedule:run` vía cron de cPanel
- PHPUnit 12 (SQLite en memoria) · Laravel Pint · Bitbucket Pipelines → VPS cPanel/WHM

## 3. Arquitectura de Código

Monolito Laravel, solo panel (sin API REST). `/` redirige a `/admin`. Estructura de `laravel-ai-template` (skills `actions-and-dtos` y `filament-resources`):

```
app/
├── Models/                         — todos los Eloquent models, planos (sin subcarpetas por contexto)
├── Enums/                          — enums (string-backed, keys TitleCase)
├── ValueObjects/                   — VOs inmutables de docs/fase-3-dominio/value-objects.md (Dinero, Periodo, RFC…) + sus casts
├── Actions/{Contexto}/             — una clase por operación de negocio, método execute()
├── DTOs/{Contexto}/                — espejo de Actions/, readonly + fromArray()
├── Services/{Contexto}/            — Domain Services de docs/fase-3-dominio/domain-services.md (lógica compartida por 2+ Actions o que coordina varios aggregates)
├── Infrastructure/                 — adaptadores a sistemas externos detrás de interfaces (parsers de banco, Claude, CFDI, INEGI, Banxico)
├── Jobs/, Events/, Listeners/, Exceptions/{Contexto}/
├── Models/Scopes/AlcanceScope.php  — global scope de alcance
└── Filament/Resources/, Filament/Pages/, Filament/Widgets/
```

Subdirectorios de contexto (`Actions/`, `DTOs/`, `Services/`, `Exceptions/`):
`Acceso`, `Configuracion`, `Estructura`, `Contratos`, `Indicadores`, `Cobranza`, `Conciliacion`, `Morosidad`, `Gastos`, `Flujo`, `Avisos`.
Contextos diferidos (carpetas vacías creadas en el bootstrap): `Prediales`, `DocumentacionPlazas`, `ConciliacionContable`, `PersonaFisica`.

> **Regla:** Las clases en `app/Actions/`, `app/DTOs/`, `app/Services/` y `app/ValueObjects/` no importan clases de Filament ni de HTTP. La UI depende de la lógica de negocio, nunca al revés.

> **Regla de escritura entre módulos:** un módulo escribe solo sus propias tablas. Para cambiar datos de otro contexto llama a su Action o Domain Service (ej. Conciliación nunca hace `$cobro->update([...])`; llama a `AplicacionPagoService`).

## 4. Patrones de Código

*Actions:*
- Una clase por operación de negocio con método único `execute()`
- Retorna el Model o void
- Todos los side effects dentro de `execute()` — sin hooks `afterCreate`
- Sin acceso a `request()`, `auth()`, `session()` — recibe parámetros explícitos (incluido el `User` que actúa, para bitácora y alcance)
- Inyección de dependencias vía constructor o `app()`
- Operaciones de dinero o multi-aggregate envueltas en `DB::transaction()` dentro de la Action

*DTOs:*
- `readonly class` — inmutables
- Constructor nombrado estático: `fromArray(array $data): self`
- Tipos fuertes — Enums y Value Objects sobre strings crudos
- Sin lógica adicional

*Models:*
- `$fillable` con todos los campos escribibles **por formularios**. Campos que solo escribe un Domain Service (`estatus_pago`, `fecha_pago`, `huella`, `estatus` de movimientos, montos originales) no van en `$fillable` (INV-04, INV-08)
- `casts()` method (nunca `$casts` array property)
- Enums y Value Objects como casts
- Solo relaciones, scopes y helpers de lectura — sin lógica de negocio
- Tablas con nombre en español: declarar `protected $table` explícito (Laravel pluraliza en inglés: `RazonSocial` → `razones_sociales`, no `razon_socials`)
- Modelos con alcance usan el trait `HasAlcance` (registra `AlcanceScope`)

*Dinero:*
- Montos `decimal(14,2)`, tasas `decimal(7,4)`, tipo de cambio `decimal(12,6)`. Nunca `float`
- Aritmética solo con el VO `Dinero` (`brick/math`), redondeo half-up a 2 decimales al final de cada cálculo de impuesto o interés (ADR-008)

*Filament Resources:*
- `formSchema()` estático en Resource, reutilizado por Create y Edit pages
- `handleRecordCreation()` delega a la Action correspondiente
- `handleRecordUpdate()` delega a Action solo si hay side effects
- Shield genera las Policies — nunca strings hardcodeados en `can()`
- Ejecutar `php artisan shield:generate --all` después de cada Resource o Page nuevo
- Pantallas que siguen el prototipo: leer su imagen en `docs/fase-4-arquitectura/design-references/` antes de escribir `table()`/`formSchema()`

*Texto visible al usuario final (labels, `description()`, `helperText()`, `placeholder()`, notificaciones, mensajes de validación):*
- Nunca referencia un código de la documentación interna (`ADR-*`, `RF-*`, `RNF-*`, `BR-*`, `INV-*`, `US-*`, `CU-*`) — el cliente no sabe qué es un ADR ni le interesa. Esas referencias van en comentarios de código/docblocks, nunca en un string que el framework de UI renderiza.
- Redactado en el lenguaje llano del cliente (el qué/por qué en sus propios términos), nunca la justificación arquitectónica — "Se guarda cifrada", no "ADR-007".
- `../admon-arrendamientos-plazas/prompt-lovable.md` y las capturas del prototipo modelan el tono correcto por pantalla (ej. "Pagado lo marca la conciliación bancaria; Timbrado y Entregado los marcas tú"). Si el texto de una pantalla nueva no suena como algo que Diana o Maria entenderían sin contexto técnico, hay que reescribirlo.

## 5. Decisiones Técnicas Clave

- ADR-001 — Monolito Laravel + Filament + MySQL: todo es panel; pantallas especiales como Pages custom de Livewire.
- ADR-002 — Login de Filament + Shield + `AlcanceScope`: toda consulta, job y exportación se filtra por alcance; las tareas de sistema lo desactivan explícitamente con `withoutGlobalScope(AlcanceScope::class)`.
- ADR-003 — Avisos en base de datos + notificaciones de Filament con polling: sin WebSockets; correo solo hacia inquilinos.
- ADR-004 — Cola `database` procesada por `schedule:run` cada minuto: jobs idempotentes; la UI muestra "En cola…" y refresca por polling.
- ADR-005 — Un panel `admin`: Resources para catálogos, Pages custom para tablero, estructura, bandeja, matrices y cashflow.
- ADR-006 — VPS cPanel + Bitbucket Pipelines estándar: sin procesos persistentes; PR gate con Pint + PHPUnit.
- ADR-007 — IA solo como respaldo detrás de `LectorDocumentosIA`, con la API key del cliente: el camino principal es Excel/XML; la IA extrae, nunca concilia.
- ADR-008 — Dinero exacto + invariantes en dos capas (código probado en SQLite + índices en MySQL): no depender de `CHECK` ni de bloqueos para que pasen las pruebas.
- ADR-009 — Conciliación automática solo con folio, alias o el inquilino identificado (RFC, local o nombre con concepto) + su renta o mantenimiento + monto exacto, y se anuncia a quién se aplicó: todo lo demás va a la bandeja.
- ADR-010 — Contextos diferidos: no construir prediales, documentación de plazas, CONTPAQi ni persona física.

## 6. Contextos del Dominio

- **Acceso:** usuarios, roles, permisos por sección y alcance por razón social / centro de costo, aplicados en servidor.
- **Configuración:** parámetros globales que el cliente cambia sin desarrollador (gracia, base del interés, tolerancia, semáforo, tasas) y credenciales de integraciones.
- **Estructura:** catálogo razón social → cuentas → centro de costo → local → inquilino, con expediente, condiciones de cobro, ocupación e importación inicial.
- **Contratos:** vigencias, montos por concepto, incrementos por INPC y renovaciones, semáforo, cierre y cartas de aviso.
- **Indicadores externos:** INPC del INEGI y tipo de cambio FIX de Banxico, con fecha y origen.
- **Cobranza:** cobros del mes por contrato y concepto, impuestos, marcas Timbrado/Entregado, abonos, adelantos y facturas pendientes.
- **Conciliación bancaria:** carga de estados de cuenta, huella anti-duplicados, motor de empate, bandeja de revisión, alias aprendidos y categorías de no cobranza.
- **Morosidad:** interés moratorio diario, tablas de intereses, condonación y línea de intereses al liquidar.
- **Gastos:** conceptos de gasto fijo, lectura de CFDI, clasificación, gastos varios y mejoras, conciliación del gasto y saldo de cierre.
- **Flujo y reportes:** rubros padre/hijo, cashflow, reporte para el despacho y exportaciones (solo lectura).
- **Tablero y avisos:** indicadores, avisos internos y bitácora inmutable (transversal).

## 7. Restricciones de Seguridad

- Permisos por sección (Shield) **y** alcance (`AlcanceScope` + policies) en servidor: fuera de alcance o sin permiso → HTTP 403. Ocultar en la UI no basta (INV-18).
- Toda consulta agregada o cruda (`DB::table`, widgets, exportaciones, jobs) aplica el alcance del usuario que la origina.
- Archivos del cliente (expediente, estados de cuenta, facturas, PDFs, exportaciones) solo en el disco `local` privado; descarga por controlador con policy. Nunca disco `public` ni URL directa (INV-17).
- API key de IA, token de INEGI, token de Banxico y credenciales SMTP: cast `encrypted` o `.env`; nunca se muestran completas ni se escriben en logs.
- Bitácora: solo inserción; el modelo bloquea `update` y `delete` (INV-16).
- Ninguna entidad con historial tiene `DeleteAction`: se desactiva, se da de baja o se cierra (INV-15).
- Pagado solo lo escribe `AplicacionPagoService`; ninguna acción de UI lo expone (INV-04).
- Contraseñas con hash de Laravel; sesión de 120 min; usuarios inactivos bloqueados en `canAccessPanel()`.
- Datos reales del cliente (archivos de muestra) solo como fixtures **anonimizados**; nunca en seeders ni en el manual.

## 8. Integraciones Externas

- Estados de cuenta Banregio / BBVA / Scotiabank → archivo Excel subido (PDF con IA de respaldo) → `LectorEstadoCuenta` (un parser por banco, mapeo de columnas) en `ProcesarEstadoCuentaJob`
- Claude API (Anthropic) → HTTPS REST, salida JSON con esquema → `LectorDocumentosIA` / `ClaudeDocumentReader`, en jobs, con la API key del cliente
- Facturas CFDI de proveedores → XML (PDF con IA) → `LectorCFDI` en `ProcesarLoteFacturasJob`
- INEGI (INPC) → REST con token → `FuenteINPC` / `InegiApiClient` en tarea diaria `inpc:sincronizar`
- Banxico SIE (FIX, serie SF43718) → REST con token → `FuenteTipoCambio` / `BanxicoSieClient` bajo demanda con caché en BD
- SMTP → Mailables en cola → cartas de incremento y tablas de intereses, registradas en `EnvioCorreo`
- Sistema de timbrado del cliente → sin integración (captura manual de folio, F.P., M.P.)

Todas con timeout, reintentos con backoff y comportamiento de fallo documentado en `docs/fase-4-arquitectura/integrations.md`.

## 9. Convenciones de Nomenclatura

- Model: sustantivo de negocio en español, singular, PascalCase — `RazonSocial`, `CentroCosto`, `Cobro`, `MovimientoBancario` (tabla: plural español snake_case declarada en `$table` — `razones_sociales`, `centros_costo`, `cobros`, `movimientos_bancarios`)
- Columnas de entidades de negocio: español snake_case — `razon_social_emisora_id`, `saldo_no_cuadra`, `fecha_vencimiento`
- Action: `{Verbo}{Entidad}Action`, verbo en infinitivo español — `RegistrarContratoAction`, `ConfirmarIncrementoAction`, `GenerarCobrosMesAction`
- DTO: `{Verbo}{Entidad}Data` — `RegistrarContratoData`
- Domain Service: nombre de Fase 3 — `MotorEmpate`, `CalculadoraIntereses`, `AplicacionPagoService`
- Value Object: nombre de Fase 3 — `Dinero`, `Periodo`, `RangoVigencia`, `HuellaMovimiento`
- Enum: sustantivo español — `ConceptoCobro`, `EstatusPago`, `EstatusMovimiento`, `ReglaEmpate`, `TipoCobro`, `Moneda` (casos en TitleCase: `ConceptoCobro::Renta`)
- Resource / Page: `{Entidad}Resource`, `{Nombre}Page` — `CobroResource`, `BandejaRevisionPage`
- Job: `{Verbo}{Objeto}Job` en español para procesos de negocio — `ProcesarEstadoCuentaJob`
- Evento de dominio: participio en español — `CobroLiquidado`, `IncrementoConfirmado`, `EstadoCuentaProcesado`
- Excepción de dominio: `{Problema}` en español — `TraslapeDeContrato`, `CuentaNoCoincide`, `NotaRequerida`
- Adaptador de infraestructura: `{Proveedor}{Formato}{Rol}` en inglés técnico — `BanregioExcelParser`, `ClaudeDocumentReader`, `InegiApiClient`, `BanxicoSieClient`, `Cfdi40XmlReader`; interfaces (puertos) con el nombre de Fase 3 — `LectorEstadoCuenta`, `LectorDocumentosIA`, `FuenteINPC`
- Tests: `{Action}Test`, `{Resource}Test`, `{Service}Test` — `ConfirmarIncrementoActionTest`
- Comandos de consola: `contexto:verbo` — `cobros:generar`, `intereses:recalcular`, `inpc:sincronizar`

> **Español vs. inglés en identificadores de código — nunca mezclar los dos dentro
> del mismo nombre.** Las convenciones de arriba cubren el vocabulario de negocio.
> Cualquier otra clase que NO sea ese vocabulario — módulos técnicos/de plataforma
> (branding/apariencia, credenciales de integraciones externas, auditoría, Commands,
> Listeners, Jobs, Policies) — va completamente en inglés: clases, namespaces,
> métodos, propiedades, variables, y también las tablas/columnas de BD y los campos
> de formulario. Nunca una mezcla como `TemaPanelPage`/`ActualizarTemaPanelAction`
> (correcto: `ThemePanelPage`/`UpdateThemePanelAction`) ni una tabla en español
> bajo un Model en inglés. La única excepción es el texto visible al usuario
> final y los comentarios/docblocks, que siguen en español — ver
> "Texto visible al usuario final" arriba.
>
> En este proyecto: `User`, `Role`/permisos de Shield, `ThemePanel`, `IntegrationCredential` (API key de IA, tokens INEGI/Banxico) y los Listeners/Policies/Commands técnicos van en inglés. `EntradaBitacora`, `Aviso` y `Parametro` quedaron fijados en Fase 3 como vocabulario del cliente ("bitácora", "avisos", "parámetros" están en el glosario) y van en español. Los Jobs y Eventos que nombran una operación de negocio (`ProcesarEstadoCuentaJob`, `CobroLiquidado`) van en español, completos.
>
> **Un Value Object/enum nuevo no hereda la excepción del idioma del cliente solo por
> ser VO.** Lo que decide es si el término ya estaba fijado como vocabulario de
> negocio en Fase 3 **antes** de esta decisión, no si la clase técnicamente "es un
> VO". Un VO que se introduce después del cierre de Fase 3 para resolver un detalle
> técnico de parseo/derivación de datos — algo que el sistema infiere o calcula,
> nunca un término que el cliente ya usa — sigue la regla de módulos técnicos
> (inglés), aunque viva junto a VOs de negocio en español. Antes de
> nombrar un VO nuevo durante el desarrollo, vale la
> pena confirmar en cuál de los dos casos cae.

> **Idioma de los mensajes de validación del framework.** `APP_LOCALE=es` y
> `APP_FALLBACK_LOCALE=es` en `.env`, y debe existir `lang/es/validation.php`
> (`composer require laravel-lang/lang --dev` + `php artisan lang:add es`) — si no, las
> reglas nativas (`required`, `extensions`, `string`, etc.) se renderizan en inglés aunque
> el label del campo esté traducido, contradiciendo la regla de "texto visible al usuario
> final". Confirmar el locale y las traducciones antes de construir el primer
> formulario/Resource, no descubrirlo hasta que alguien vea un error en inglés en
> producción. Zona horaria: `APP_TIMEZONE=America/Tijuana` (las tareas del día 1 y los días
> de atraso dependen de la fecha local del cliente).
