docs(integration): explicar instancias, endpoints y despliegue

Documenta la prioridad cliente a tipo de sitio, la edicion compartida, los permisos y los contratos de la API. Aclara la migracion del requisito de configuracion y la asociacion directa requerida por el webhook de Telepagos.

app/Domains/Integration/documentacion/README.md

@@ -1,33 +1,53 @@
 # Dominio Integration
 
-## Propósito
+## Modelo
 
-Gestiona integraciones externas disponibles y su configuración por cliente. Un cliente puede agrupar múltiples tenants que comparten las mismas credenciales. Incluye correo y pagos mediante Telepagos.
+- `Integration`: catálogo, URL base, `integration_data_schema` y `requires_configuration`.
+- `IntegrationInstance`: configuración concreta con nombre. `integration_data` se cifra con `EncryptedIntegrationData`, se almacena en `longText` y nunca se devuelve en la API.
+- `ClientIntegration` y `WebsiteTypeIntegration`: asociaciones a instancias. La clave compuesta verifica el código de la instancia y la unicidad permite una instancia por integración y propietario.
 
-## Modelo y seguridad
+Editar una instancia compartida afecta a todos sus consumidores. Desvincularla solo elimina la asociación. Las instancias vinculadas no se pueden eliminar (HTTP 409); las instancias sin asociaciones se conservan hasta su eliminación explícita. El código de una integración o instancia no cambia después de crearla.
 
-- `Integration`: definición global de una integración.
-- `ClientIntegration`: configuración y credenciales de una integración para un cliente.
-- `EncryptedIntegrationData`: cast que protege los datos sensibles persistidos.
-- `ClientIntegrationService`: consulta y configura integraciones del cliente.
+## Resolución
 
-## Servicios externos
+`BaseIntegrationService::forTenant()` busca primero la asociación del cliente y después la del tipo de sitio del tenant. Selecciona una configuración completa, sin mezclar credenciales entre niveles. Si una configuración está presente pero es inválida, produce un error en vez de recurrir a otra instancia.
 
-- `BaseIntegrationService`: resuelve el cliente desde el tenant operativo y carga exclusivamente la configuración del cliente.
-- `MailService`: envío de correo usando la integración configurada.
-- `TelepagosIntegrationService`: autenticación, caché de token, generación de QR y consulta de cobros.
-- `TelepagosWebhookService`: procesa notificaciones recibidas desde Telepagos.
+`forClient()` usa únicamente la asociación del cliente: sin un tenant concreto no se elige un tipo de sitio. Si no existe una instancia y `requires_configuration` es verdadero, se genera un error. Para correo opcional, `MailService` usa el mailer global si no encuentra una instancia; cuando la encuentra, construye un transporte SMTP aislado identificado como `integration-smtp`.
 
-## Endpoints
+Telepagos utiliza una clave de caché basada en el ID de instancia y una huella del texto cifrado. Compartir instancia permite reutilizar el token. Guardar otras credenciales cambia la clave; la edición explícita elimina la anterior después del commit. Volver a configurar el servicio con `forClient()` o `forTenant()` carga la configuración actual.
 
-- CRUD global bajo `/integrations`.
-- Consulta y configuración por cliente bajo `/clients/{client}/integrations`.
-- `POST /webhooks/telepagos/{client}` para notificaciones del proveedor.
+## Administración
 
-## Logging de Telepagos
+Todas estas rutas llevan el prefijo `/api`, requieren `auth:sanctum` y el rol global `admin` mediante `IntegrationPolicy`. Los roles `adminapp`, `scanner` y `user` no administran credenciales compartidas.
 
-Los eventos de autenticación, QR, consultas de cuenta y procesamiento de webhooks se escriben en el canal diario `telepagos`, separado del log general. Los archivos se generan en `storage/logs/telepagos/telepagos-YYYY-MM-DD.log`; el nivel y la retención se configuran con `TELEPAGOS_LOG_LEVEL` y `TELEPAGOS_LOG_DAYS`. Tokens y credenciales se eliminan del contexto antes de registrar respuestas del proveedor.
+| Método | Ruta | Operación |
+| --- | --- | --- |
+| CRUD | `/integrations` | Catálogo. |
+| GET, POST | `/integration-instances` | Listar con paginación o crear. |
+| GET, PUT, PATCH, DELETE | `/integration-instances/{id}` | Consultar, editar o eliminar. |
+| GET | `/clients/{client}/integrations[/{integration_code}]` | Consultar asociaciones directas. |
+| PUT | `/clients/{client}/integrations/{integration_code}` | Guardado compatible: crea una instancia nueva y reemplaza solo la asociación del cliente. Ejecuta el hook de configuración existente. |
+| PUT | `/clients/{client}/integrations/{integration_code}/instance` | Asociar una instancia existente. |
+| DELETE | `/clients/{client}/integrations/{integration_code}` | Desvincular. |
+| GET | `/website-types/{codigo}/integrations[/{integration_code}]` | Consultar asociaciones del tipo de sitio. |
+| PUT, DELETE | `/website-types/{codigo}/integrations/{integration_code}` | Asociar una instancia existente o desvincular. |
 
-## Dependencias y reglas
+Crear una instancia requiere `integration_code`, `name` e `integration_data` (objeto validado según el esquema del catálogo). Editar solo `name` conserva las credenciales. Enviar `integration_data` reemplaza el objeto completo y valida todo el esquema. El código de la instancia es inmutable.
 
-Se integra con `Client`, `Tenant` y con el checkout de `Purchase`. `Notification` utiliza `MailService`. El tenant conserva el contexto operativo y de branding, pero nunca es dueño de credenciales. Las credenciales no se exponen en respuestas ni logs; los webhooks deben validar su contrato antes de alterar una compra.
+Asociar requiere un payload como `{"integration_instance_id": 12}`. Se verifica que exista y pertenezca al código solicitado. La creación y edición explícita de instancias validan el esquema sin enviar mensajes ni llamar al proveedor. Para editar una configuración compartida se utiliza explícitamente el endpoint de la instancia.
+
+Los nuevos endpoints usan resources con envoltorio `data`, sin credenciales. Las consultas históricas de cliente conservan su formato JSON e incluyen `integration_instance` sin credenciales.
+
+## Webhooks y contexto operativo
+
+`POST /webhooks/telepagos/{client}` conserva su contrato público con el proveedor y la validación de pertenencia de las compras al cliente. Como no recibe un tenant, requiere una asociación directa al cliente. Para usar una instancia compartida en ese flujo, asociarla también al cliente; la herencia por tipo de sitio no se aplica a esa URL.
+
+`Notification` consume `MailService`; `Purchase` consume Telepagos. Los tenants mantienen el contexto operativo y el branding.
+
+## Despliegue
+
+Ejecutar `php artisan migrate` junto con este código. La migración `2026_09_04_000003` renombra `requires_client_configuration` a `requires_configuration` conservando sus valores. Los payloads del catálogo deben usar el nuevo nombre. Las migraciones previas trasladan el texto cifrado sin descifrarlo y no comparten instancias automáticamente.
+
+## Logging
+
+Telepagos registra eventos en el canal diario `telepagos`. El nivel y la retención se configuran con `TELEPAGOS_LOG_LEVEL` y `TELEPAGOS_LOG_DAYS`. Se eliminan tokens y credenciales de las estructuras registradas.