mitgliederverwaltung/docs/email-sync.md

Core Rules

1. User.email is source of truth - Always overrides member email when linking
2. DB constraints - Prevent duplicates within same table (users.email, members.email)
3. Custom validations - Prevent cross-table conflicts only for linked entities
4. Sync is bidirectional: User ↔ Member (but User always wins on link)
5. Linked member email change - When a member is linked, only administrators or the linked user may change that member's email (Member resource validation EmailChangePermission). Because User.email wins on link and changes sync Member → User, allowing anyone to change a linked member's email would overwrite that user's account email; this rule keeps sync under control.

---

Decision Tree

Action: Create/Update/Link Entity with Email X
│
├─ Does Email X violate DB constraint (same table)?
│  └─ YES → ❌ FAIL (two users or two members with same email)
│
├─ Is Entity currently linked? (or being linked?)
│  │
│  ├─ NO (unlinked entity)
│  │  └─ ✅ SUCCESS (no custom validation)
│  │
│  └─ YES (linked or linking)
│     │
│     ├─ Action: Update Linked User Email
│     │  ├─ Email used by other member? → ❌ FAIL (validation)
│     │  └─ Email unique? → ✅ SUCCESS + sync to member
│     │
│     ├─ Action: Update Linked Member Email  
│     │  ├─ Email used by other user? → ❌ FAIL (validation)
│     │  └─ Email unique? → ✅ SUCCESS + sync to user
│     │
│     ├─ Action: Link User to Member (both directions)
│     │  ├─ User email used by other member? → ❌ FAIL (validation)
│     │  └─ Otherwise → ✅ SUCCESS + override member email

Sync Triggers

Action	Sync Direction	When
Update linked user email	User → Member	Email changed
Update linked member email	Member → User	Email changed
Link user to member	User → Member	Always (override)
Link member to user	User → Member	Always (override)
Unlink	None	Emails stay as-is