shortcommings

tasks/core-services-implementation/14-family-plans.md

@@ -0,0 +1,91 @@
+# 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"