feat(club-001): club core backend: anonymous members, devices, ledger, cashback config

work/artifacts/SHIPPING-ZONES/architect.md

@@ -0,0 +1,44 @@
+# Arquitectura — SHIPPING-ZONES
+
+## Problema detectado
+El sistema actual de envíos solo soporta zonas por `country + postal_code_prefix` y tiene dos limitaciones:
+
+1. Una zona genérica de España con `postal_code_prefix = null` también matchea Baleares/Canarias.
+2. El endpoint público `/shipping/methods` devuelve métodos de todas las zonas compatibles en vez de resolver la **mejor zona** como sí hace `ShippingService.calculate()`.
+3. El checkout frontend carga métodos sin contexto de `country/postalCode`, así que la UI puede enseñar opciones no válidas para la dirección real.
+
+## Diseño propuesto
+
+### 1) Extender zonas con exclusiones
+Añadir a `shipping_zones` un campo:
+- `excluded_postal_code_prefixes text[]`
+
+Con esto una zona "España peninsular" puede excluir:
+- `07` (Baleares)
+- `35`, `38` (Canarias)
+- opcionalmente `51`, `52` si se quiere mantener también fuera Ceuta/Melilla
+
+### 2) Unificar matching de zona
+Hacer que el listado público de métodos use la misma resolución de mejor zona que el cálculo de shipping:
+- misma lógica de prefijo más específico
+- respetando exclusiones
+- evitando devolver simultáneamente métodos de la zona genérica y de una zona específica
+
+### 3) Admin shipping UI
+Actualizar admin shipping para editar el nuevo campo como CSV legible.
+
+### 4) Frontend checkout
+Actualizar la obtención de métodos de envío para que use `country` y `postalCode` reales del formulario/dirección seleccionada.
+
+## Alcance
+- Sí entra:
+  - exclusiones por prefijo postal
+  - mejor matching de zona en backend
+  - checkout contextual por país/código postal
+  - soporte admin para editar exclusiones
+- No entra:
+  - rediseño completo del motor de campañas/logística
+  - nuevas tarifas complejas por operador
+
+## Nota
+Con este enfoque el sistema ya soporta zonas continentales por país y además permite que una zona genérica excluya archipiélagos/territorios especiales sin romper la arquitectura actual.