bloque 1: anticipo al reservar en linea y cobro automatico de membresias con enlace de pago (modulo skeen_cobros: enlaces con token firmado, webhooks de Stripe/MercadoPago, modo simulado para pruebas, pagina publica de pago, expiracion automatica y reembolso, reintentos de cobro, permisos y reporte); apagado por defecto

docs/producto/configuracion-cliente.md

@@ -123,6 +123,27 @@ Procedimiento, Paquete) se pueden renombrar y se pueden crear más (p. ej.
 - El cliente recibe un enlace propio para consultar o cancelar su cita. Las
   reservas que llegan por el portal se distinguen en la agenda.
 
+### 7.1 Anticipo (depósito) al reservar — apagado por defecto
+
+Dentro del mismo bloque, la llave `reservas_online.anticipo`. Con `activo = true`:
+
+- **Opciones** (defaults entre paréntesis): `tipo` (`porcentaje` | `monto_fijo`),
+  `valor` (0; el % sobre el precio del servicio o el monto fijo), `moneda`
+  (`MXN`), `horas_para_pagar` (24), `reembolsable` (sí), `texto_aviso` (''), y
+  `permitir_simulado` (no, ver más abajo).
+- Al reservar, la cita queda **retenida sin confirmar** (badge **"Esperando
+  anticipo"** en la agenda y en el detalle) y el portal muestra el monto y el
+  botón para pagar. Al pagarse, la cita pasa a **confirmada** y se avisa por el
+  motor de notificaciones.
+- Si no se paga dentro de `horas_para_pagar`, un proceso automático cancela la
+  cita y **libera el horario**.
+- El anticipo se registra como pago real (`skeen.pago`) ligado a la cita y a la
+  venta, por lo que aparece en cortes de caja y reportes; no se duplica con el
+  resto que el cliente pague después en caja.
+- **Reembolso**: con `reembolsable = true`, al cancelar una cita con anticipo
+  pagado, el pago se marca como reembolsado y la cita como "Anticipo
+  reembolsado". Con `false`, el anticipo se retiene.
+
 ## 8. Recursos (cabinas, salas y equipos)
 
 **Configuración → Recursos** (apagado por defecto)
@@ -161,13 +182,17 @@ generar visitas, ver todas, bloquear).
    fin de semana), renombrar, ajustar jerarquía y activar/desactivar. Vienen 10
    roles base (admin, médico, recepción, enfermería, cosmetología, psicóloga,
    farmacia, gerencia, marketing, lectura).
-2. **Permisos**: **71 permisos por acción agrupados en 16 grupos** (Agenda,
+2. **Permisos**: **75 permisos por acción agrupados en 17 grupos** (Agenda,
    Recursos, Pacientes, Visitas, Ventas, Inventario, Servicios, Reportes,
    WhatsApp, Notificaciones, Formularios, Membresías, Compras, Comisiones,
-   Configuración, Plataforma), con botones todo/ninguno. El backend los hace
-   cumplir aunque el usuario manipule la interfaz.
+   Cobros y enlaces de pago, Configuración, Plataforma), con botones todo/ninguno.
+   El backend los hace cumplir aunque el usuario manipule la interfaz.
 3. **Menús**: qué sección ve cada rol.
 
+Los permisos de **Cobros** (defaults): `cobros.ver` (todos), `cobros.administrar`
+(admin/gerencia), `cobros.forzar` (admin/recepción/gerencia) y `cobros.cancelar`
+(admin/gerencia).
+
 Recomendación: partir del rol más parecido, ajustar y guardar.
 
 ## 10. Notificaciones
@@ -218,6 +243,60 @@ sesiones incluidas, cobro periódico, congelamiento y renovación.
   envía avisos de renovación en cada ventana y descongela al terminar la ventana.
 - **Reporte**: **Membresías → reporte** con ingreso recurrente por periodo.
 
+### 11.1 Cobro automático de membresías — apagado por defecto
+
+Dentro del bloque, la llave `membresias.cobro_automatico`. Con `activo = true`:
+
+- **Opciones** (defaults entre paréntesis): `dias_antes` (3), `metodo`
+  (`enlace` | `tarjeta_guardada`), `reintentos_dias` (`[1, 3, 7]`),
+  `cancelar_si_no_paga` (no), `dias_gracia` (5) y `permitir_simulado` (no).
+- **Método `enlace`**: al acercarse el vencimiento el cron genera el **enlace de
+  pago del periodo** y lo envía al paciente por el motor de notificaciones
+  (plantilla `plantilla_cobro_membresia`, variable `{enlace}`). El periodo queda
+  **pendiente** hasta que se pague; al pagarse pasa a **pagado** y la membresía
+  **se renueva sola**. Reintentos: se vuelve a avisar en los días indicados
+  respecto al vencimiento. Al agotarse los reintentos y los días de gracia, con
+  `cancelar_si_no_paga` la membresía pasa a **vencida**; apagado, solo se marca
+  el periodo y es el proceso normal de vencimiento el que la vence.
+- **Método `tarjeta_guardada`**: cargo sin presencia del cliente. **Requiere
+  credenciales reales de Stripe y tarjetas guardadas** (que hoy no se persisten);
+  sin ellas queda **inerte** (no cobra ni marca nada como pagado).
+
+## 11 bis. Cobros en línea y pasarelas de pago
+
+Los anticipos de reservas y el cobro automático de membresías usan un mismo
+objeto, el **enlace de cobro** (`skeen.cobro.enlace`): origen (reserva,
+membresía o venta), monto y moneda, token firmado con caducidad, estado
+(pendiente/pagado/expirado/cancelado), proveedor (Stripe, MercadoPago o
+**simulado**) y bitácora. Al pagarse se registra un `skeen.pago` real ligado a
+la cita y a la venta.
+
+- **Página pública de pago**: `/pagar/<token>` (sin sesión). Muestra concepto,
+  monto, estado y el botón de pago; tras pagar muestra el comprobante. Respeta
+  marca, glosario e idioma y funciona en celular.
+- **Proveedor `simulado`**: cuando no hay credenciales de pasarela, el enlace
+  nace `simulado`. Para poder probar el flujo completo sin dinero real hay que
+  encender `reservas_online.anticipo.permitir_simulado` y/o
+  `membresias.cobro_automatico.permitir_simulado`. En producción déjalos
+  **apagados**: nunca se simula un pago sin permiso explícito.
+- **Configurar Stripe** (Odoo → Ajustes técnicos → Parámetros del sistema):
+  - `skeen.stripe_secret_key`: llave secreta (`sk_live_…`/`sk_test_…`).
+  - `skeen.stripe_webhook_secret`: secreto del endpoint de webhook (`whsec_…`).
+  - Webhook a `https://<url-pública>/skeen/frontend/v1/public/cobro/webhook/stripe`
+    con los eventos `checkout.session.completed` y `payment_intent.succeeded`.
+    La firma (`Stripe-Signature`) se verifica; sin secreto el webhook responde 400.
+- **Configurar MercadoPago** (mismos parámetros):
+  - `skeen.mercadopago_access_token`: access token de producción/prueba.
+  - `skeen.mercadopago_webhook_secret` (opcional): si se define, se verifica la
+    firma `x-signature`; si no, se confirma consultando el pago con el token.
+  - Webhook a `https://<url-pública>/skeen/frontend/v1/public/cobro/webhook/mercadopago`.
+- **Sin credenciales**: ambos webhooks existen pero rechazan la notificación
+  (400) y el checkout real no se crea; el flujo queda inerte salvo el modo
+  simulado explicado arriba.
+- **Reporte**: **Reportes → Cobros** lista enlaces pendientes y expirados
+  (anticipos y membresías), con totales, exportable a Excel, y permite **forzar**
+  el cobro o **cancelar** la retención según los permisos de Cobros.
+
 ## 12. Compras y proveedores
 
 **Configuración → Compras** (apagado por defecto) y **Compras** (menú).