FamilyMealPlanner/docs/household-sync.md

Hogar compartido (2.2) — diseño

Colaboración entre cuentas distintas y acceso desde Android. Issue #33.

Por qué no CloudKit

El store es hoy NSPersistentCloudKitContainer (SwiftData con cloudKitDatabase: .automatic), que sincroniza la base de datos privada de un Apple ID entre los dispositivos de esa persona. Dos cosas lo descartan aquí:

• No existe en Android.
• Compartir entre cuentas exige CKShare, que SwiftData no expone (ya se intentó en la 2.0 y se aparcó a la 2.1).

Arquitectura

                 ┌──────────────────────────┐
  iOS / iPadOS   │  SwiftData (store local) │  ← toda la UI sigue leyendo de aquí (@Query)
                 └────────────┬─────────────┘
                              │  HouseholdSyncService (espejo bidireccional)
                 ┌────────────┴─────────────┐
                 │   Firestore (el hogar)   │  ← fuente de verdad cuando hay hogar
                 └────────────┬─────────────┘
                              │
  Android / web  │  PWA (fase 2), lee y escribe el mismo hogar

SwiftData no se sustituye: sigue siendo el store local y el modo offline. Firestore es la fuente de verdad del contenido del hogar, y el servicio de sync mantiene ambos lados alineados.

CloudKit y Firestore no conviven

Dos sincronizaciones sobre los mismos objetos se pelean — ya pasó con el sync por iCloud KV, y por eso existe CloudSyncRuntime.isCloudKitActive. Regla:

• Sin hogar → como hoy: CloudKit activo, Firestore inactivo.
• Con hogar → contenedor local (cloudKitDatabase: .none) y Firestore manda.

El contenedor se decide en el arranque, así que al entrar o salir de un hogar la app pide relanzarse. Es un corte visible, pero la alternativa (dos orígenes escribiendo los mismos objetos, con ecos entre ellos) es una fuente de pérdida de datos.

Modelo en Firestore

users/{uid}
  householdId, displayName, updatedAt

invites/{code}                      ← resuelve código → hogar sin leer todos los hogares
  householdId, createdBy, expiresAt

households/{householdId}
  name, createdAt, createdBy, memberIds: [uid], ownerId
  members/{uid}          displayName, role: owner|member, joinedAt
  dishes/{uuid}          name, descriptionText, tagIds[], ingredients[], isPriority,
                         fixedDayOfWeek, fixedMealType, updatedAt, updatedBy, deletedAt?
  tags/{uuid}            name, nameEN, color, reglas…, updatedAt, updatedBy, deletedAt?
  weekPlans/{yyyy-MM-dd} weekStartDate, userRating, includeWeekendsOverride,
                         mealTypesOverrideRaw, updatedAt, updatedBy
    slots/{day}-{meal}   dishId, secondaryDishId, isEatingOut, isSkipped,
                         isRuleOverridden, isRuleIgnored, updatedAt, updatedBy
  shoppingItems/{uuid}   weekStartDate, title, dishId, isChecked, isDismissed,
                         sortOrder, updatedAt, updatedBy, deletedAt?

IDs deterministas donde importa

Semanas y slots usan id derivado del contenido (2026-09-14, 5-dinner) en vez de UUID. Si dos miembros abren la misma semana a la vez, ambos escriben el mismo documento en lugar de crear dos. Es la misma clase de duplicado que costó el crash de arranque de la 2.0, pero resuelta en el origen.

Platos, etiquetas y líneas de la compra conservan su UUID: los crea una persona concreta y no hay id natural.

Conflictos

Last-write-wins por documento, con updatedAt de servidor (FieldValue.serverTimestamp()) y updatedBy para poder depurar. La granularidad importa: el documento es el slot, no la semana, así que dos personas pueden rellenar martes y jueves a la vez sin pisarse.

Los borrados son tombstones (deletedAt), no borrados duros: sin ellos, un dispositivo offline que no vio el borrado recrearía el plato al volver.

Alcance de la fase 1

Dentro:

• Cuentas (Sign in with Apple + Google) y hogar con invitación por código.
• Sync de platos, etiquetas, semanas, slots y lista de la compra.
• Desactivación de CloudKit al entrar en un hogar.

Fuera, a propósito:

• Fotos de platos: photoData va a @Attribute(.externalStorage) y un documento de Firestore tope a 1 MB. Van a Firebase Storage en fase 2.
• Ajustes personales (AppSettings): no se comparten. Idioma, horas de calendario o estilo de export son de cada persona. Lo que sí es del hogar (días y comidas planificadas) viaja en el propio weekPlan.
• PWA de Android: fase 2, sobre este mismo modelo.

Premium

Crear un hogar requiere premium. Los invitados entran sin premium — es el gancho del plan familiar, y quien invita ya paga. El resto de features premium siguen bloqueadas para el invitado.

isPremium sigue viniendo solo de StoreKit y nunca se sincroniza, igual que hoy.