Cibello-app/docs/FAS4-HOUSEHOLD-COLLAB-AUDIT.md

Fas 4 – Hushållssamarbete: REUSE/GAP-matris och stegplan

Levereras före kod. Styrande dokument: utbyggnadsdokumentet §7 + docs/03-funktionskatalog.md + docs/07-datamodell.md + docs/12-sakerhet-gdpr.md + docs/19-beslutslogg.md.

Audit först, ingen kod. Invänta godkännande innan 4a påbörjas.

---

Hermetiska testregler (samma som Fas 3)

Alla integrationstester ska vara hermetiska:

• De får inte bero på innehållet i .env (värden som AAMOS_MODE, EMAIL_MODE, S3_MODE skrivs över i setup-env.ts).
• De får inte bero på förkonfigurerad konfiguration eller externa tjänster.
• De får inte bero på databasinnehåll som skapats utanför testet. Testkörningen ansvarar själv för att testdatabasen är migrerad och seedad innan testerna startar; seeden är idempotent.
• Körning: pnpm --filter @app/database run db:test-setup (migrate + seed) ska alltid föregå API-testerna.

---

1. REUSE/GAP-matris mot befintligt hushållsflöde

§7-krav / område	Befintlig implementation	Status	Rekommenderad åtgärd
Hushållsgrundstruktur	Tabellerna households och household_members finns. households.invite_code är unik. Roller: owner, adult, member, child.	Finns	Återanvänd oförändrat. Utöka med tidsbunden inbjudanslänk, inte ny inbjudningsmodell.
Gå med via kod	POST /v1/households/join med { inviteCode }. Nya medlemmar får roll adult. Plan-gräns maxHouseholdMembers kontrolleras.	Finns	Återanvänd. Utöka med djuplänk + QR så att koden kan fyllas i automatiskt, men backend-logiken är densamma.
Medlemslista	GET /v1/households/:id returnerar medlemmar med userId, displayName, role, portionFactor, joinedAt.	Finns	Återanvänd. Lägg till UI för att visa/ändra.
Ändra roll	PATCH /v1/households/:id/members/:userId med role. Endast owner får ändra roller.	Finns	Återanvänd. Säkerställ att child inte kan upphöjas till owner.
Ta bort medlem	DELETE /v1/households/:id/members/:userId. Endast owner kan ta bort andra; själv kan lämna.	Finns	Återanvänd. GDPR: avgöra om matdata ska behållas eller anonymiseras (se avsnitt 4).
Portionsfaktor	household_members.portion_factor per medlem, default 1, validerat 0.1–3.	Finns	Återanvänd. Exponera i mobil-UI för ägare/vuxna.
Delade vs privata data	Lager, plan, inköpslista, matlådor, budget är hushållsdelat. Mål, allergier, smakprofil, måltidshistorik är individuellt (§7/§56).	Finns	Fortsätt. Inga ändringar.
Länkinbjudan / djuplänk	Saknas. Idag måste användaren manuellt skriva in inviteCode.	Saknas	Inför tidsbunden inbjudnings-token (household_invite_links) med djuplänk via brand.config.json urlScheme.
QR-inbjudan	Saknas.	Saknas	Generera QR-kod i mobilen som kodar samma djuplänk. Ingen ny backend-modell.
Återkalla inbjudan	Saknas. När en kod/länk delats finns den kvar tills hushållet byter kod.	Saknas	Lägg till revoked_at på inbjudningslänk och/eller invite_code_expires_at på hushållet.
Anti-dubblettkartan: inga parallella invite- eller medlemsmodeller	households.invite_code + household_members är navet.	OK	Behåll. Alla inbjudningsvägar ska peka mot samma households.invite_code.
Händelsespårning	HOUSEHOLD_MEMBER_ADDED finns i EVENT_TYPES.	Finns	Lägg till HOUSEHOLD_MEMBER_REMOVED, HOUSEHOLD_MEMBER_ROLE_CHANGED, HOUSEHOLD_INVITE_LINK_CREATED, HOUSEHOLD_INVITE_LINK_REVOKED.
Analytics	Analytics-events är consent-gatade via trackProductAnalytics.	Finns	Lägg till household_member_added, household_member_removed, household_invite_link_used (inga PII, inga fritext-fält).
Notifieringar till medlemmar	notifications-tabell + push_tokens finns.	Delvis	Återanvänd. Skicka push när någon går med eller lämnar (opt-in via notis-samtycke).
Plan-gränser	loadEntitlements(app.db, owner.userId) ger maxHouseholdMembers.	Finns	Återanvänd vid både kod- och länkinbjudan.

Slutsats av matrisen

Hushållssamarbete är en utbyggnad, inte ett parallellsystem:

• Kärnan (households, household_members, invite_code, roller, plan-gränser) finns redan.
• Det som saknas är (a) djuplänk/QR för smidigare inbjudan, (b) tidsstyrning/återkallning av inbjudningar, (c) medlemskaps-händelser och analytics, (d) GDPR-klar hantering när medlem lämnar.

---

2. Anti-dubblettkartan – varför INGA nya parallella modeller

2.1 Varför inte en separat household_invites-tabell med egen kod?

households.invite_code är redan unik och fungerar. Att skapa en separat tabell med egna koder skulle ge:

• Dubbla källor på sanning: vilken kod gäller?
• Dubbla join-endpoints och valideringar.
• Risk att gamla och nya inbjudningar krockar.

Beslut: Använd households.invite_code som kanonisk permanent kod (multi-use fallback). En separat household_invite_links-tabell får endast lagra metadata om länken: tokenHash, createdBy, expiresAt, revokedAt, usedAt. Själva inbjudningskoden hämtas alltid från households.invite_code när länken löses in.

2.2 Varför inte en separat household_member_history-tabell?

Medlemskapet är PK på (household_id, user_id). Aktuellt medlemskap finns i household_members. Om vi behöver historik (vem var medlem när?) kan vi använda:

• audit_logs (som redan loggar household.member_removed)
• domain_events (HOUSEHOLD_MEMBER_ADDED, HOUSEHOLD_MEMBER_REMOVED)

Ingen ytterligare tabell behövs i Fas 4.

2.3 Varför inte en separat household_permissions-tabell?

Rollerna owner, adult, member, child är tillräckligt granulära för Fas 4. Rollbaserade behörigheter hårdkodas i routes (som idag). Om vi senare behöver finare rättigheter kan vi migrera då.

---

3. STEGPLAN

Steg 4a – Djuplänk/QR för inbjudan

Mål: En användare kan trycka på en länk/QR och automatiskt hamna i appen med inbjudningskoden ifylld.

Ändringar:

1. Ny tabell household_invite_links:
   • id uuid PK
   • householdId FK → households
   • tokenHash text unik, sha256 av slumpmässigt token (≥128 bitar, base64url)
   • createdBy FK → users
   • expiresAt timestamp with time zone (default nu()+7 dagar)
   • revokedAt timestamp with time zone nullable
   • usedAt timestamp with time zone nullable
   • createdAt, updatedAt
   • Token lagras ALDRIG i klartext i DB. Uppslag görs via sha256(token).
2. Djuplänk: <urlScheme>://households/join?token=<token> där urlScheme läses ur brand.config.json (aldrig hårdkodat).
3. Ny endpoint POST /v1/households/join-link:
   • Tar { token }.
   • Slår upp household_invite_links → hushåll via tokenHash = sha256(token).
   • Kontrollerar expiresAt, revokedAt, usedAt.
   • Återanvänder samma plan-gräns- och join-logik som /v1/households/join.
   • Efter lyckad join: markera länken usedAt.
4. Ny endpoint POST /v1/households/:id/invite-links (owner/adult):
   • Skapar en ny länk med 7 dagars giltighet.
   • Begränsa antalet aktiva länkar per hushåll (t.ex. max 10).
   • Returnerar endast token EN GÅNG (i svaret). Servern sparar bara hash.
   • Roll vid join via länk är alltid adult — aldrig owner.
   • Owner-transfer ingår INTE i Fas 4.
5. GET /v1/households/:id/invite-links (owner/adult): lista aktiva länkar med expiresAt (utan token, såklart).
6. DELETE /v1/households/:id/invite-links/:linkId (owner/adult): återkalla (sätt revokedAt).

Berörda filer:

• packages/database/src/schema/households.ts (household_invite_links)
• packages/validation/src/household.ts (nya schemas)
• apps/api/src/routes/households.ts
• apps/api/src/lib/helpers.ts (generateInviteLinkToken, hashInviteLinkToken)
• apps/mobile/src/app/household.tsx (QR + dela-länk)
• apps/mobile/src/app/household-join.tsx (ny skärm för att ta emot länk)
• apps/mobile/app.json / deep-linking-konfiguration
• apps/mobile/src/locales/*/common.json (+12)

Migration: 0019_household_invite_links.sql

Testplan:

• Skapa länk → token returneras EN gång.
• Länk med giltig token → användare blir medlem med roll adult.
• Utgången länk → 410 Gone med i18n-nyckel household.inviteExpired.
• Återkallad länk → 410 Gone med i18n-nyckel household.inviteRevoked.
• Redan använd länk → 410 Gone med i18n-nyckel household.inviteUsed. Länkar är engångsbruk (usedAt).
• Plan-gräns nådd → 402 Payment Required (samma som kod).maxHouseholdMembers.
• Max aktiva länkar överskridet → 429.
• Token återfinns inte i DB i klartext.

---

Steg 4b – Medlemshantering i mobilen

Mål: Ägare/vuxna kan se medlemmar, ändra roll, ta bort medlem; alla kan lämna hushållet.

Ändringar:

1. Uppdatera apps/mobile/src/app/household.tsx:
   • Visa medlemmar med roll och portionsfaktor.
   • Ägare kan ändra roll och ta bort (utom sig själv om enda ägaren).
   • Varje medlem kan lämna hushållet.
2. Lägg till bekräftelsedialoger för borttag/rolländring.
3. Använd befintliga endpoints:
   • PATCH /v1/households/:id/members/:userId
   • DELETE /v1/households/:id/members/:userId

Berörda filer:

• apps/mobile/src/app/household.tsx
• apps/mobile/src/locales/*/common.json (+12)

Migration: ingen.

Testplan:

• Ägare ändrar member → adult.
• Ägare tar bort medlem → medlem försvinner.
• Enda ägaren kan inte ta bort sig själv (409).
• child kan inte ändra andras roller (403).

---

Steg 4c – Händelser, analytics och notiser

Mål: Hushållsförändringar syns i domain_events, analytics och (opt-in) push-notiser.

Ändringar:

1. Lägg till i EVENT_TYPES:
   • HOUSEHOLD_MEMBER_REMOVED
   • HOUSEHOLD_MEMBER_ROLE_CHANGED
   • HOUSEHOLD_INVITE_LINK_CREATED
   • HOUSEHOLD_INVITE_LINK_REVOKED
2. Lägg till analytics-events (inga PII, inga fritext-fält):
   • household_member_added
   • household_member_removed
   • household_invite_link_used
3. Emit events vid:
   • join (både kod och länk)
   • borttag
   • rolländring
   • länk skapad/återkallad
4. Push-notis (opt-in via notis-samtycke) till övriga medlemmar när någon går med eller lämnar.

Berörda filer:

• packages/shared-types/src/enums.ts
• packages/events/src/index.ts
• packages/analytics/src/builders.ts
• apps/api/src/routes/households.ts
• apps/api/src/lib/notifications.ts (om sådan finns)

Migration: 0020_expand_event_types_household.sql

Testplan:

• Efter join: HOUSEHOLD_MEMBER_ADDED + analytics.
• Efter borttag: HOUSEHOLD_MEMBER_REMOVED + audit-log.
• Efter rolländring: HOUSEHOLD_MEMBER_ROLE_CHANGED.
• Consent-gate: analytics skickas bara om användaren samtyckt.

---

4. RISKER

Risk	Påverkan	Minskning
GDPR: data när medlem lämnar	Hög	Att lämna/tas bort ur ett hushåll är inte kontoradering. Vid borttag av household_members-raden tas endast åtkomsten bort. Personens meals, taste_signals, memory_items, user_health_profiles och push_tokens tillhör kontot och rörs inte — användaren kan gå med i ett annat hushåll. Hushållets historiska aggregat (budget, svinn, gemensamma matlådor, inventory-transaktioner) ändras inte retroaktivt. Radering av persondata sker endast via den befintliga kontoraderingsprocessen (DELETE /v1/me, dokumenterad i docs/12). Beslutet skrivs in explicit innan 4b kodas.
Behörigheter: vem får bjuda in/ta bort	Hög	Bjud in: owner och adult. Ta bort andra: endast owner. Ta bort sig själv: alla utom enda ägaren. Ändra roller: endast owner. child får aldrig bjuda in eller ta bort.
Inbjudningslänkar läcker	Medel	Token är slumpmässig ≥128 bitar, tidsbegränsad, engångsbruk. Servern lagrar endast sha256(token). Återkallning sätts omedelbart. Inga PII i länken.
Parallella inbjudningsmodeller	Hög	Enda kanoniska koden är households.invite_code. household_invite_links är endast metadata. /v1/households/join och /v1/households/join-link konvergerar till samma join-kärna.
Plan-gränser kringgås	Medel	Både kod- och länkinbjudan kontrollerar maxHouseholdMembers mot ägarens entitlements före insert.
i18n-paritet fallerar	Låg	Alla nya nycklar läggs i samtliga 12 locales och testas med apps/mobile/test/i18n.test.ts.
Djuplänk hårdkodar app-namn	Medel	urlScheme läses dynamiskt från brand.config.json. Ingen hårdkodning av app-namn.
Testdata läcker mellan tester	Låg	Hermetiska tester skapar egna hushåll per test; invite_code genereras unikt.

---

5. Översiktliga berörda tabeller

Tabell	Förändring
households	Ingen schemaändring. invite_code fortsätter vara kanonisk.
household_members	Ingen schemaändring. Befintlig roll- och delete-logik återanvänds.
household_invite_links	Ny (metadata om djuplänkar).
users	Ingen ändring, men vid kontoradering används befintligt GDPR-flöde (docs/12).
domain_events	Nya event-typer: HOUSEHOLD_MEMBER_REMOVED, HOUSEHOLD_MEMBER_ROLE_CHANGED, HOUSEHOLD_INVITE_LINK_CREATED, HOUSEHOLD_INVITE_LINK_REVOKED.
audit_logs	Återanvänds för household.member_removed (finns redan).
notifications / push_tokens	Återanvänds för opt-in-notiser.

---

6. Leveransordning

1. Steg 4a: djuplänk/QR för inbjudan (household_invite_links).
2. Steg 4b: medlemshantering i mobilen.
3. Steg 4c: händelser, analytics och notiser.

Per steg: brand-guard, typecheck, test, build, first-deploy staging, patch + bundle.

---

7. Länk-invites – detaljerade regler

7.1 Token och djuplänk

• Token: slumpmässig ≥128 bitar, base64url → 22 tecken. Skickas endast till klienten vid skapande.
• Servern lagrar sha256(token) i household_invite_links.tokenHash; uppslag vid inbjudan görs via hash.
• Djuplänk: <urlScheme>://households/join?token=<token> där urlScheme kommer från brand.config.json.
• Giltighet: 7 dagar (expiresAt).
• Engångsbruk: efter lyckad join sätts usedAt. Länkar är single-use by design.
• Återkallning: owner eller adult sätter revokedAt.
• Max 10 aktiva länkar per hushåll.
• Roll vid join: alltid adult — aldrig owner.
• Owner-transfer ingår inte i Fas 4.

7.2 Ingen PII i länken

Länken innehåller endast token. Inget hushållsnamn, ingen e-post, inga medlemsnamn. Den som har länken kan gå med, därför ska användare dela den via säkra kanaler.

7.3 Token-säkerhet och användningsregler

• Token genereras slumpmässigt med ≥128 bitar.
• Servern lagrar endast sha256(token) i tokenHash; klartext-token returneras bara vid skapande.
• Länkar är single-use by design: usedAt sätts vid lyckad join.
• Giltighetstid: 7 dagar.
• Max 10 aktiva länkar per hushåll.
• Roll vid join via länk: alltid adult — aldrig owner.
• Owner-transfer ingår inte i Fas 4.

7.4 Konvergens med kod-inbjudan

Både POST /v1/households/join (kod) och POST /v1/households/join-link (token) ska i slutändan anropa samma interna joinHouseholdCore(db, householdId, userId, role) som:

• kontrollerar plan-gräns,
• sätter in household_members med angiven roll (adult för länk),
• emittar HOUSEHOLD_MEMBER_ADDED,
• loggar analytics (consent-gatat),
• skickar notis till övriga medlemmar (opt-in).

7.5 i18n

Nya nycklar för 4a:

• household.inviteLink, household.inviteLinkShare, household.inviteLinkCopied
• household.inviteExpired, household.inviteRevoked, household.inviteUsed
• household.qrScanHint

Nya nycklar för 4b:

• household.leaveConfirmTitle, household.leaveConfirmBody
• household.removeMemberConfirmTitle, household.removeMemberConfirmBody
• household.changeRoleConfirmTitle

Alla läggs i samtliga 12 locales och testas med apps/mobile/test/i18n.test.ts.

7.6 Analytics

• household_member_added: { household_id_hash, role, via: 'code' | 'link' } — hashat hushålls-id, inga personuppgifter.
• household_member_removed: { household_id_hash }.
• household_invite_link_used: { household_id_hash, link_id } — aldrig token eller invite_code.

Alla går via trackProductAnalytics och är därmed consent-gatade.

7.7 Webbfallback

Om mottagaren inte har appen installerad och trycker på länken i en webbläsare krävs en associerad domän + universal link / app link. Detta är ett fas-1-spår som ligger utanför Fas 4. I Fas 4 förutsätts att mottagaren har Expo Go/appen installerad.

---

Rapport färdig. Inväntar godkännande innan kod påbörjas.