Member Management

Phase 2 of Club Wilo implements the full member lifecycle — from enrollment through cancellation — including subscription plans, promotions, referrals, and background automation.

Member Lifecycle

A member passes through a defined set of statuses:

Status	Code	Description
Active	active	Member has an active subscription
Payment Pending	payment_pending	Subscription expired, payment awaited
Suspended	suspended	Manually suspended by staff or automated (unpaid)
Canceled	canceled	Membership terminated

Status Transitions

                  ┌─────────────────┐
                  │   enrollment    │
                  └────────┬────────┘
                           ▼
                       ┌────────┐
                ┌─────►│ ACTIVE │◄────────────────────┐
                │      └───┬────┘                     │
                │          │ expiry / no auto-renew    │
                │          ▼                           │
                │  ┌─────────────────┐                 │
                │  │ PAYMENT_PENDING │                 │ renew
                │  └───────┬─────────┘                 │
                │          │ manual suspend             │
                │  payment ▼ / auto-suspend             │
                │     ┌───────────┐                    │
                │     │ SUSPENDED │────────────────────┘
                │     └─────┬─────┘
                │           │ terminate
                │           ▼
                │      ┌──────────┐
                └──────│ CANCELED │
                       └──────────┘

Enrollment Flow

A new member is enrolled via POST /api/members/enroll which atomically:

1. Creates the Member entity
2. Creates an initial Subscription linked to a SubscriptionPlan
3. Applies any promotion or referral discount to the first month
4. Generates a ReferralCode for the new member
5. Publishes MemberCreatedEvent (integration event via outbox)
6. Sends a welcome notification

Status History

Every status change is recorded in MemberStatusHistory with:

• Previous and new status
• Actor (who made the change)
• Optional reason

This provides a full audit trail accessible at /api/members/{id}/status-history.

Key Entities

Entity	Purpose
Member	Core aggregate root — personal data, status, member number
Subscription	Active subscription with plan, billing period, dates
SubscriptionPlan	Plan definition — price, benefits, billing options
MemberStatusHistory	Immutable log of all status changes
ReferralCode	Unique code generated at enrollment, used to invite others
Referral	Record of a successful referral (referrer → referee)
Promotion	Discount rule (percentage or fixed amount) with conditions
PromotionUsage	Tracks per-member usage of a promotion
UserPreferences	Member notification and app preferences

API Endpoints

Member CRUD

Method	Path	Permission	Description
GET	/api/members	members:read	List members (paginated, filterable)
POST	/api/members/enroll	enrollment:write	Enroll a new member
GET	/api/members/{id}	members:read	Get member details
PUT	/api/members/{id}	members:write	Update member data
DELETE	/api/members/{id}	members:write	Soft-delete member

Status Management

Method	Path	Permission	Description
POST	/api/members/{id}/activate	members:status:write	Activate member
POST	/api/members/{id}/suspend	members:status:write	Suspend member
POST	/api/members/{id}/cancel	members:status:write	Cancel membership
GET	/api/members/{id}/status-history	members:status_history:read	View status history

Self-Service

Method	Path	Permission	Description
GET	/api/users/me/subscription	members:subscription:read	View own subscription
GET	/api/users/me/preferences	preferences:read	View own preferences
PUT	/api/users/me/preferences	preferences:write	Update own preferences

Export

Method	Path	Permission	Description
GET	/api/members/export	members:export	Export to CSV/XLSX

Frontend Routes

Route	View	Permission
/club	ClubDashboardView	members:read
/club/members	MembersView	members:read
/club/members/new	MemberCreateView	members:write
/club/members/:id	MemberDetailView	members:read
/club/members/:id/subscription	MemberSubscriptionView	subscriptions:read
/club/members/:id/history	MemberHistoryView	members:read