# 14. Family Plan Member Management, Billing Proration, and Multi-User Dashboard

meta:
  id: core-services-14
  feature: core-services-implementation
  priority: P2
  depends_on: [core-services-01]
  tags: [billing, family-plans, multi-user, proration, dashboard, member-management]

objective:
- Implement family plan support: invite family members, manage their access, prorate billing on member changes, and provide a multi-user dashboard showing consolidated family security status.

deliverables:
- Family member invitation system (email invites with acceptance flow)
- Role-based access control (primary account holder vs. member)
- Billing proration for adding/removing family members mid-cycle
- Family dashboard showing all members' threat scores and alerts
- Per-member service configuration (what each member monitors)

steps:
1. Extend database schema:
   - Add `familyGroups` table: id, primaryUserId, planTier, maxMembers, createdAt
   - Add `familyMembers` table: id, familyGroupId, userId, role (primary/member), status (pending/active/removed), invitedAt, joinedAt
   - Add `familyInvitations` table: id, familyGroupId, email, token, expiresAt, acceptedAt
2. Implement invitation flow:
   - Primary user sends invite by email → generates signed token
   - Invitee clicks link → creates account (if new) or links existing account
   - Invitation expires after 7 days
   - Send reminder email after 3 days if not accepted
3. Implement member management:
   - Primary user can view all members, their active services, and threat scores
   - Primary user can remove members (prorated refund or credit)
   - Members can leave family group voluntarily
   - Members cannot see other members' sensitive data (SSN, specific breach details)
4. Implement billing proration:
   - Add member mid-cycle: charge prorated amount for remaining days via Stripe
   - Remove member mid-cycle: credit prorated amount to account balance
   - Change plan tier: prorate difference, apply to next invoice
   - Use Stripe's `proration_behavior: 'create_prorations'` for all changes
5. Implement family dashboard:
   - Sidebar shows family group name and member count
   - Main view: cards for each member with photo, name, threat score, recent alert count
   - Click member → detailed view with their services, alerts, and settings
   - Consolidated family threat score (from correlation engine)
6. Implement per-member service configuration:
   - Primary user assigns which services each member gets
   - Default: all members get DarkWatch + SpamShield + RemoveBrokers
   - HomeTitle and VoicePrint limited by property/voice enrollment slots
   - Members can configure their own watchlist items within assigned services
7. Implement notification routing:
   - Critical alerts notify primary user AND affected member
   - Billing notifications go to primary user only
   - Member can opt into/off specific alert types
8. Add family plan tiers:
   - Family Fortress: 5 adults + unlimited children, $45/mo
   - Family Guard: 3 adults + unlimited children, $35/mo
   - Enforce max member limits at invitation time

tests:
- Unit: Proration calculation for add/remove/upgrade scenarios
- Integration: Full invitation flow from email to account linking
- E2E: Create family plan → invite 2 members → verify billing → remove member → verify prorated credit

acceptance_criteria:
- [ ] Primary user can send email invitations to family members
- [ ] Invitations expire after 7 days and can be resent
- [ ] Members can accept invitations and join family group
- [ ] Adding member mid-cycle creates prorated charge on next invoice
- [ ] Removing member mid-cycle creates prorated credit on next invoice
- [ ] Family dashboard shows all members with threat scores and alert counts
- [ ] Primary user can configure which services each member has access to
- [ ] Members cannot see other members' sensitive breach details (only score + summary)
- [ ] Billing notifications route to primary user; security alerts route to affected member
- [ ] Max member limits enforced at invitation (5 for Fortress, 3 for Guard)
- [ ] Plan downgrade prevents inviting beyond new tier's member limit
- [ ] All family plan changes handled via Stripe proration (no manual calculations)

validation:
- Run `vitest run billing.test.ts` — extended tests for family proration
- Manual: Send invitation to test email, click link, verify member joins family
- Stripe Dashboard: Verify proration items appear on invoices after member changes
- Dashboard: Family view shows 3 member cards with individual threat scores

notes:
- Family plans have 30–50% lower churn than individual plans — this is a critical retention driver
- Stripe's `proration_behavior` handles most math automatically — trust it
- Children's accounts should be restricted: no dark web monitoring for minors, only spam/basic alerts
- Consider adding "family safety alerts" — notify primary user if child receives suspicious contact
- The existing `invitation.ts` schema may need extension for family-specific invitation tokens
- Member removal should not delete their account — just unlink from family group
- Children (under 18) should have simplified dashboard — no breach details, only "safe/attention needed"