# Plan de Migración: Arquitectura Hexagonal, DDD Táctico y Symfony UX

Este documento resume la estrategia técnica, arquitectura de software, reglas de negocio y hoja de ruta para la evolución y refactorización del sistema de gestión para el estudio jurídico.

---

## 1. Stack Tecnológico

* **Backend Framework:** Symfony 7.x / 8.x + PHP 8.3+
* **Persistencia:** Doctrine ORM 3.x con Mapeo en **XML** (`.orm.xml`).
* **Frontend:** **Symfony UX** (`Twig` + `Stimulus` + `Turbo` + `LiveComponents`).
* **Inteligencia Artificial:** `symfony/ai-agent` + `symfony/ai-ollama-platform` con modelo local open-source (**Ollama** corriendo en DDEV / Servidor).

---

## 2. Arquitectura de Software: Hexagonal Plana + DDD Táctico

Adoptamos una **Arquitectura Hexagonal Plana** en la raíz de `src/`, protegiendo la capa de `Domain/` para que sea **100% PHP Puro** (sin dependencias ni anotaciones de Doctrine o Symfony).

```text
src/
├── Domain/                             <-- DOMINIO PURO (Clases PHP puras / POPOs)
│   ├── Model/                          (Agregados y Entidades: Caso, Cliente, CobroCaso, ConvenioCliente)
│   ├── ValueObject/                    (Monto, PorcentajePacto, EstadoCobroCaso, Email, Cuit)
│   ├── Event/                          (Eventos de Dominio: CasoLiquidadoEvent, CobroCasoRecibidoEvent)
│   └── Repository/                     (Contratos/Interfaces: CasoRepositoryInterface)
│
├── Application/                        <-- CASOS DE USO Y SERVICIOS DE APLICACIÓN
│   ├── UseCase/                        (LiquidarCapitalCliente, RegistrarCobroAseguradora, PCL)
│   ├── Dto/                            (Data Transfer Objects para transferencia entre capas)
│   └── CommandHandler/                 (Manejadores de Comandos/Bus)
│
└── Infrastructure/                     <-- TECNOLOGÍA, ADAPTADORES Y FRAMEWORK
    ├── Persistence/
    │   ├── Doctrine/
    │   │   ├── Mapping/                <-- Archivos .orm.xml (Mapeo limpio de Doctrine 3)
    │   │   └── Repository/             (Implementaciones concretas de Repositorios)
    ├── Controller/                     (Controladores HTTP / Web endpoints)
    ├── Twig/                           (Componentes reactivos Symfony UX LiveComponent)
    └── ExternalServices/               (Adaptadores de Ollama, Sendgrid, WhatsApp)
```

---

## 3. Reglas de Negocio del Dominio Financiero

### A. Distribución del Capital y Liquidaciones
1. **Acuerdo Manual:** Cada `ConvenioCliente` especifica el monto acordado individual que le corresponde a cada cliente dentro del Caso.
2. **Registro de Cobro Aseguradora (`CobroCaso`):** Los cobros de la aseguradora ingresan de forma global al Caso (CAPITAL u HONORARIOS) y no se distribuyen al cliente al momento del ingreso.
3. **Historial de Pagos de Capital (`PagoCapitalCliente`):** Cada entrega parcial de capital al cliente se registra como una entidad/tabla de detalle (Fecha, Monto, Medio de Pago: Efectivo/Transferencia, Movimiento de Caja).
4. **Cálculo de Saldo Pendiente:**
   $$\text{Saldo Pendiente} = \text{Monto Acordado Cliente} - \sum(\text{Pagos de Capital Realizados})$$

### B. Pacto Cuota Litis (PCL) y Gastos
1. **Historial de Cobros PCL (`PagoPactoCliente`):** Registra cada pago parcial que realiza el cliente para cancelar su Pacto Cuota Litis y Gastos del estudio.
2. **Pago Directo del Seguro al Cliente:** Si la aseguradora paga directo al cliente, este abona luego su PCL/Gastos en el estudio. Al registrar este cobro, el `CobroCaso` pasa automáticamente al estado `PAGADO AL CLIENTE`.

### C. Estados Automáticos del `CobroCaso`
* `COBRADO PARCIAL`: Monto cobrado a aseguradora < Monto a cobrar.
* `COBRADO`: Pago total de aseguradora recibido o retención de honorarios mínima alcanzada.
* `PAGADO AL CLIENTE`: Todos los clientes del caso recibieron su capital o abonaron sus PCL/Gastos.

---

## 4. Hoja de Ruta de Migración: Por "Rebanadas Verticales" (Vertical Slices)

* [ ] **Fase 1: Esqueleto Base e Infraestructura**
  * Crear carpetas `src/Domain`, `src/Application`, `src/Infrastructure`.
  * Configurar `config/packages/doctrine.yaml` para mapeo XML.
  * Instalar Symfony UX y verificar assets.
* [ ] **Fase 2: Slice 1 - Liquidación de Capital a Clientes**
  * Entidades de Dominio puras (`Caso`, `Cliente`, `ConvenioCliente`, `PagoCapitalCliente`).
  * Repositorio e interfaz de persistencia XML.
  * Caso de Uso `PagarCapitalACliente`.
  * Componente `Symfony UX LiveComponent` para la interfaz de liquidaciones.
* [ ] **Fase 3: Slice 2 - Cobro de Pacto Cuota Litis y Gastos**
  * Entidad `PagoPactoCliente`.
  * Caso de uso `RegistrarCobroPclCliente`.
* [ ] **Fase 4: Slice 3 - Cobro General a Aseguradoras**
  * Refactorización de `CobroCaso` y automatización de estados.
* [ ] **Fase 5: Módulo de Comunicaciones & IA Local**
  * Configuración del contenedor Ollama en DDEV.
  * Instalación de `symfony/ai-agent` + `symfony/ai-ollama-platform`.
  * Lectura de emails y vinculación automática a Casos.