Merge remote-tracking branch 'origin/main' into sidebar
Some checks failed
continuous-integration/drone/push Build is failing
Some checks failed
continuous-integration/drone/push Build is failing
This commit is contained in:
commit
ff625c91c5
GPG key ID:
40E7A58C4AA1EDB2
113 changed files with 19602 additions and 2699 deletions
|
|
@ -1,653 +0,0 @@
|
|||
# Membership Contributions - Technical Architecture
|
||||
|
||||
**Project:** Mila - Membership Management System
|
||||
**Feature:** Membership Contribution Management
|
||||
**Version:** 1.0
|
||||
**Last Updated:** 2025-11-27
|
||||
**Status:** Architecture Design - Ready for Implementation
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the technical architecture for the Membership Contributions system. It focuses on architectural decisions, patterns, module structure, and integration points **without** concrete implementation details.
|
||||
|
||||
**Related Documents:**
|
||||
- [contributions-overview.md](./contributions-overview.md) - Business logic and requirements
|
||||
- [database-schema-readme.md](./database-schema-readme.md) - Database documentation
|
||||
- [database_schema.dbml](./database_schema.dbml) - Database schema definition
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Architecture Principles](#architecture-principles)
|
||||
2. [Domain Structure](#domain-structure)
|
||||
3. [Data Architecture](#data-architecture)
|
||||
4. [Business Logic Architecture](#business-logic-architecture)
|
||||
5. [Integration Points](#integration-points)
|
||||
6. [Acceptance Criteria](#acceptance-criteria)
|
||||
7. [Testing Strategy](#testing-strategy)
|
||||
8. [Security Considerations](#security-considerations)
|
||||
9. [Performance Considerations](#performance-considerations)
|
||||
|
||||
---
|
||||
|
||||
## Architecture Principles
|
||||
|
||||
### Core Design Decisions
|
||||
|
||||
1. **Single Responsibility:**
|
||||
- Each module has one clear responsibility
|
||||
- Period generation separated from status management
|
||||
- Calendar logic isolated in dedicated module
|
||||
|
||||
2. **No Redundancy:**
|
||||
- No `period_end` field (calculated from `period_start` + `interval`)
|
||||
- No `interval_type` field (read from `contribution_type.interval`)
|
||||
- Eliminates data inconsistencies
|
||||
|
||||
3. **Immutability Where Important:**
|
||||
- `contribution_type.interval` cannot be changed after creation
|
||||
- Prevents complex migration scenarios
|
||||
- Enforced via Ash change validation
|
||||
|
||||
4. **Historical Accuracy:**
|
||||
- `amount` stored per period for audit trail
|
||||
- Enables tracking of contribution changes over time
|
||||
- Old periods retain original amounts
|
||||
|
||||
5. **Calendar-Based Periods:**
|
||||
- All periods aligned to calendar boundaries
|
||||
- Simplifies date calculations
|
||||
- Predictable period generation
|
||||
|
||||
---
|
||||
|
||||
## Domain Structure
|
||||
|
||||
### Ash Domain: `Mv.Contributions`
|
||||
|
||||
**Purpose:** Encapsulates all contribution-related resources and logic
|
||||
|
||||
**Resources:**
|
||||
- `ContributionType` - Contribution type definitions (admin-managed)
|
||||
- `ContributionPeriod` - Individual contribution periods per member
|
||||
|
||||
**Extensions:**
|
||||
- Member resource extended with contribution fields
|
||||
|
||||
### Module Organization
|
||||
|
||||
```
|
||||
lib/
|
||||
├── contributions/
|
||||
│ ├── contributions.ex # Ash domain definition
|
||||
│ ├── contribution_type.ex # ContributionType resource
|
||||
│ ├── contribution_period.ex # ContributionPeriod resource
|
||||
│ └── changes/
|
||||
│ ├── prevent_interval_change.ex # Validates interval immutability
|
||||
│ ├── set_contribution_start_date.ex # Auto-sets start date
|
||||
│ └── validate_same_interval.ex # Validates interval match on type change
|
||||
├── mv/
|
||||
│ └── contributions/
|
||||
│ ├── period_generator.ex # Period generation algorithm
|
||||
│ └── calendar_periods.ex # Calendar period calculations
|
||||
└── membership/
|
||||
└── member.ex # Extended with contribution relationships
|
||||
```
|
||||
|
||||
### Separation of Concerns
|
||||
|
||||
**Domain Layer (Ash Resources):**
|
||||
- Data validation
|
||||
- Relationship management
|
||||
- Policy enforcement
|
||||
- Action definitions
|
||||
|
||||
**Business Logic Layer (`Mv.Contributions`):**
|
||||
- Period generation algorithm
|
||||
- Calendar calculations
|
||||
- Date boundary handling
|
||||
- Status transitions
|
||||
|
||||
**UI Layer (LiveView):**
|
||||
- User interaction
|
||||
- Display logic
|
||||
- Authorization checks
|
||||
- Form handling
|
||||
|
||||
---
|
||||
|
||||
## Data Architecture
|
||||
|
||||
### Database Schema Extensions
|
||||
|
||||
**See:** [database-schema-readme.md](./database-schema-readme.md) and [database_schema.dbml](./database_schema.dbml) for complete schema documentation.
|
||||
|
||||
### New Tables
|
||||
|
||||
1. **`contribution_types`**
|
||||
- Purpose: Define contribution types with fixed intervals
|
||||
- Key Constraint: `interval` field immutable after creation
|
||||
- Relationships: has_many members, has_many contribution_periods
|
||||
|
||||
2. **`contribution_periods`**
|
||||
- Purpose: Individual contribution periods for members
|
||||
- Key Design: NO `period_end` or `interval_type` fields (calculated)
|
||||
- Relationships: belongs_to member, belongs_to contribution_type
|
||||
- Composite uniqueness: One period per member per period_start
|
||||
|
||||
### Member Table Extensions
|
||||
|
||||
**Fields Added:**
|
||||
- `contribution_type_id` (FK, NOT NULL with default from settings)
|
||||
- `contribution_start_date` (Date, nullable)
|
||||
|
||||
**Existing Fields Used:**
|
||||
- `joined_at` - For calculating contribution start
|
||||
- `left_at` - For limiting period generation
|
||||
- These fields must remain member fields and should not be replaced by custom fields in the future
|
||||
|
||||
### Settings Integration
|
||||
|
||||
**Global Settings:**
|
||||
- `contributions.include_joining_period` (Boolean)
|
||||
- `contributions.default_contribution_type_id` (UUID)
|
||||
|
||||
**Storage:** Existing settings mechanism (TBD: dedicated table or configuration resource)
|
||||
|
||||
### Foreign Key Behaviors
|
||||
|
||||
| Relationship | On Delete | Rationale |
|
||||
|--------------|-----------|-----------|
|
||||
| `contribution_periods.member_id → members.id` | CASCADE | Remove periods when member deleted |
|
||||
| `contribution_periods.contribution_type_id → contribution_types.id` | RESTRICT | Prevent type deletion if periods exist |
|
||||
| `members.contribution_type_id → contribution_types.id` | RESTRICT | Prevent type deletion if assigned to members |
|
||||
|
||||
---
|
||||
|
||||
## Business Logic Architecture
|
||||
|
||||
### Period Generation System
|
||||
|
||||
**Component:** `Mv.Contributions.PeriodGenerator`
|
||||
|
||||
**Responsibilities:**
|
||||
- Calculate which periods should exist for a member
|
||||
- Generate missing periods
|
||||
- Respect contribution_start_date and left_at boundaries
|
||||
- Skip existing periods (idempotent)
|
||||
|
||||
**Triggers:**
|
||||
1. Member contribution type assigned (via Ash change)
|
||||
2. Member created with contribution type (via Ash change)
|
||||
3. Scheduled job runs (daily/weekly cron)
|
||||
4. Admin manual regeneration (UI action)
|
||||
|
||||
**Algorithm Steps:**
|
||||
1. Retrieve member with contribution_type and dates
|
||||
2. Determine first period start (based on contribution_start_date)
|
||||
3. Calculate all period starts from first to today (or left_at)
|
||||
4. Query existing periods for member
|
||||
5. Generate missing periods with current contribution_type.amount
|
||||
6. Insert new periods (batch operation)
|
||||
|
||||
**Edge Case Handling:**
|
||||
- If contribution_start_date is NULL: Calculate from joined_at + global setting
|
||||
- If left_at is set: Stop generation at left_at
|
||||
- If contribution_type changes: Handled separately by regeneration logic
|
||||
|
||||
### Calendar Period Calculations
|
||||
|
||||
**Component:** `Mv.Contributions.CalendarPeriods`
|
||||
|
||||
**Responsibilities:**
|
||||
- Calculate period boundaries based on interval type
|
||||
- Determine current period
|
||||
- Determine last completed period
|
||||
- Calculate period_end from period_start + interval
|
||||
|
||||
**Functions (high-level):**
|
||||
- `calculate_period_start/3` - Given date and interval, find period start
|
||||
- `calculate_period_end/2` - Given period_start and interval, calculate end
|
||||
- `next_period_start/2` - Given period_start and interval, find next
|
||||
- `is_current_period?/2` - Check if period contains today
|
||||
- `is_last_completed_period?/2` - Check if period just ended
|
||||
|
||||
**Interval Logic:**
|
||||
- **Monthly:** Start = 1st of month, End = last day of month
|
||||
- **Quarterly:** Start = 1st of quarter (Jan/Apr/Jul/Oct), End = last day of quarter
|
||||
- **Half-yearly:** Start = 1st of half (Jan/Jul), End = last day of half
|
||||
- **Yearly:** Start = Jan 1st, End = Dec 31st
|
||||
|
||||
### Status Management
|
||||
|
||||
**Component:** Ash actions on `ContributionPeriod`
|
||||
|
||||
**Status Transitions:**
|
||||
- Simple state machine: unpaid ↔ paid ↔ suspended
|
||||
- No complex validation (all transitions allowed)
|
||||
- Permissions checked via Ash policies
|
||||
|
||||
**Actions Required:**
|
||||
- `mark_as_paid` - Set status to :paid
|
||||
- `mark_as_suspended` - Set status to :suspended
|
||||
- `mark_as_unpaid` - Set status to :unpaid (error correction)
|
||||
|
||||
**Bulk Operations:**
|
||||
- `bulk_mark_as_paid` - Mark multiple periods as paid (efficiency)
|
||||
- low priority, can be a future issue
|
||||
|
||||
### Contribution Type Change Handling
|
||||
|
||||
**Component:** Ash change on `Member.contribution_type_id`
|
||||
|
||||
**Validation:**
|
||||
- Check if new type has same interval as old type
|
||||
- If different: Reject change (MVP constraint)
|
||||
- If same: Allow change
|
||||
|
||||
**Side Effects on Allowed Change:**
|
||||
1. Keep all existing periods unchanged
|
||||
2. Find future unpaid periods
|
||||
3. Delete future unpaid periods
|
||||
4. Regenerate periods with new contribution_type_id and amount
|
||||
|
||||
**Implementation Pattern:**
|
||||
- Use Ash change module to validate
|
||||
- Use after_action hook to trigger regeneration
|
||||
- Use transaction to ensure atomicity
|
||||
|
||||
---
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Member Resource Integration
|
||||
|
||||
**Extension Points:**
|
||||
1. Add fields via migration
|
||||
2. Add relationships (belongs_to, has_many)
|
||||
3. Add calculations (current_period_status, overdue_count)
|
||||
4. Add changes (auto-set contribution_start_date, validate interval)
|
||||
|
||||
**Backward Compatibility:**
|
||||
- New fields nullable or with defaults
|
||||
- Existing members get default contribution type from settings
|
||||
- No breaking changes to existing member functionality
|
||||
|
||||
### Settings System Integration
|
||||
|
||||
**Requirements:**
|
||||
- Store two global settings
|
||||
- Provide UI for admin to modify
|
||||
- Default values if not set
|
||||
- Validation (e.g., default_contribution_type_id must exist)
|
||||
|
||||
**Access Pattern:**
|
||||
- Read settings during period generation
|
||||
- Read settings during member creation
|
||||
- Write settings only via admin UI
|
||||
|
||||
### Permission System Integration
|
||||
|
||||
**See:** [roles-and-permissions-architecture.md](./roles-and-permissions-architecture.md)
|
||||
|
||||
**Required Permissions:**
|
||||
- `ContributionType.create/update/destroy` - Admin only
|
||||
- `ContributionType.read` - Admin, Treasurer, Board
|
||||
- `ContributionPeriod.update` (status changes) - Admin, Treasurer
|
||||
- `ContributionPeriod.read` - Admin, Treasurer, Board, Own member
|
||||
|
||||
**Policy Patterns:**
|
||||
- Use existing HasPermission check
|
||||
- Leverage existing roles (Admin, Kassenwart)
|
||||
- Member can read own periods (linked via member_id)
|
||||
|
||||
### LiveView Integration
|
||||
|
||||
**New LiveViews Required:**
|
||||
1. ContributionType index/form (admin)
|
||||
2. ContributionPeriod table component (member detail view)
|
||||
3. Settings form section (admin)
|
||||
4. Member list column (contribution status)
|
||||
|
||||
**Existing LiveViews to Extend:**
|
||||
- Member detail view: Add contributions section
|
||||
- Member list view: Add status column
|
||||
- Settings page: Add contributions section
|
||||
|
||||
**Authorization Helpers:**
|
||||
- Use existing `can?/3` helper for UI conditionals
|
||||
- Check permissions before showing actions
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### ContributionType Resource
|
||||
|
||||
**AC-CT-1:** Admin can create contribution type with name, amount, interval, description
|
||||
**AC-CT-2:** Interval field is immutable after creation (validation error on change attempt)
|
||||
**AC-CT-3:** Admin can update name, amount, description (but not interval)
|
||||
**AC-CT-4:** Cannot delete contribution type if assigned to members
|
||||
**AC-CT-5:** Cannot delete contribution type if periods exist referencing it
|
||||
**AC-CT-6:** Interval must be one of: monthly, quarterly, half_yearly, yearly
|
||||
|
||||
### ContributionPeriod Resource
|
||||
|
||||
**AC-CP-1:** Period has period_start, status, amount, notes, member_id, contribution_type_id
|
||||
**AC-CP-2:** Period_end is calculated, not stored
|
||||
**AC-CP-3:** Status defaults to :unpaid
|
||||
**AC-CP-4:** One period per member per period_start (uniqueness constraint)
|
||||
**AC-CP-5:** Amount is set at generation time from contribution_type.amount
|
||||
**AC-CP-6:** Periods cascade delete when member deleted
|
||||
**AC-CP-7:** Admin/Treasurer can change status
|
||||
**AC-CP-8:** Member can read own periods
|
||||
|
||||
### Member Extensions
|
||||
|
||||
**AC-M-1:** Member has contribution_type_id field (NOT NULL with default)
|
||||
**AC-M-2:** Member has contribution_start_date field (nullable)
|
||||
**AC-M-3:** New members get default contribution type from global setting
|
||||
**AC-M-4:** contribution_start_date auto-set based on joined_at and global setting
|
||||
**AC-M-5:** Admin can manually override contribution_start_date
|
||||
**AC-M-6:** Cannot change to contribution type with different interval (MVP)
|
||||
|
||||
### Period Generation
|
||||
|
||||
**AC-PG-1:** Periods generated when member gets contribution type
|
||||
**AC-PG-2:** Periods generated when member created (via change hook)
|
||||
**AC-PG-3:** Scheduled job generates missing periods daily
|
||||
**AC-PG-4:** Generation respects contribution_start_date
|
||||
**AC-PG-5:** Generation stops at left_at if member exited
|
||||
**AC-PG-6:** Generation is idempotent (skips existing periods)
|
||||
**AC-PG-7:** Periods align to calendar boundaries (1st of month/quarter/half/year)
|
||||
**AC-PG-8:** Amount comes from contribution_type at generation time
|
||||
|
||||
### Calendar Logic
|
||||
|
||||
**AC-CL-1:** Monthly periods: 1st to last day of month
|
||||
**AC-CL-2:** Quarterly periods: 1st of Jan/Apr/Jul/Oct to last day of quarter
|
||||
**AC-CL-3:** Half-yearly periods: 1st of Jan/Jul to last day of half
|
||||
**AC-CL-4:** Yearly periods: Jan 1 to Dec 31
|
||||
**AC-CL-5:** Period_end calculated correctly for all interval types
|
||||
**AC-CL-6:** Current period determined correctly based on today's date
|
||||
**AC-CL-7:** Last completed period determined correctly
|
||||
|
||||
### Contribution Type Change
|
||||
|
||||
**AC-TC-1:** Can change to type with same interval
|
||||
**AC-TC-2:** Cannot change to type with different interval (error message)
|
||||
**AC-TC-3:** On allowed change: future unpaid periods regenerated
|
||||
**AC-TC-4:** On allowed change: paid/suspended periods unchanged
|
||||
**AC-TC-5:** On allowed change: amount updated to new type's amount
|
||||
**AC-TC-6:** Change is atomic (transaction)
|
||||
|
||||
### Settings
|
||||
|
||||
**AC-S-1:** Global setting: include_joining_period (boolean, default true)
|
||||
**AC-S-2:** Global setting: default_contribution_type_id (UUID, required)
|
||||
**AC-S-3:** Admin can modify settings via UI
|
||||
**AC-S-4:** Settings validated (e.g., default type must exist)
|
||||
**AC-S-5:** Settings applied to new members immediately
|
||||
|
||||
### UI - Member List
|
||||
|
||||
**AC-UI-ML-1:** New column shows contribution status
|
||||
**AC-UI-ML-2:** Default: Shows last completed period status
|
||||
**AC-UI-ML-3:** Optional: Toggle to show current period status
|
||||
**AC-UI-ML-4:** Color coding: green (paid), red (unpaid), gray (suspended)
|
||||
**AC-UI-ML-5:** Filter: Unpaid in last period
|
||||
**AC-UI-ML-6:** Filter: Unpaid in current period
|
||||
|
||||
### UI - Member Detail
|
||||
|
||||
**AC-UI-MD-1:** Contributions section shows all periods
|
||||
**AC-UI-MD-2:** Table columns: Period, Interval, Amount, Status, Actions
|
||||
**AC-UI-MD-3:** Checkbox per period for bulk marking (low prio)
|
||||
**AC-UI-MD-4:** "Mark selected as paid" button
|
||||
**AC-UI-MD-5:** Dropdown to change contribution type (same interval only)
|
||||
**AC-UI-MD-6:** Warning if different interval selected
|
||||
**AC-UI-MD-7:** Only show actions if user has permission
|
||||
|
||||
### UI - Contribution Types Admin
|
||||
|
||||
**AC-UI-CTA-1:** List all contribution types
|
||||
**AC-UI-CTA-2:** Show: Name, Amount, Interval, Member count
|
||||
**AC-UI-CTA-3:** Create new contribution type form
|
||||
**AC-UI-CTA-4:** Edit form: Name, Amount, Description editable
|
||||
**AC-UI-CTA-5:** Edit form: Interval grayed out (not editable)
|
||||
**AC-UI-CTA-6:** Warning on amount change (explain impact)
|
||||
**AC-UI-CTA-7:** Cannot delete if members assigned
|
||||
**AC-UI-CTA-8:** Only admin can access
|
||||
|
||||
### UI - Settings Admin
|
||||
|
||||
**AC-UI-SA-1:** Contributions section in settings
|
||||
**AC-UI-SA-2:** Dropdown to select default contribution type
|
||||
**AC-UI-SA-3:** Checkbox: Include joining period
|
||||
**AC-UI-SA-4:** Explanatory text with examples
|
||||
**AC-UI-SA-5:** Save button with validation
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Testing
|
||||
|
||||
**Period Generator Tests:**
|
||||
- Correct period_start calculation for all interval types
|
||||
- Correct period count from start to end date
|
||||
- Respects contribution_start_date boundary
|
||||
- Respects left_at boundary
|
||||
- Skips existing periods (idempotent)
|
||||
- Handles edge dates (year boundaries, leap years)
|
||||
|
||||
**Calendar Periods Tests:**
|
||||
- Period boundaries correct for all intervals
|
||||
- Period_end calculation correct
|
||||
- Current period detection
|
||||
- Last completed period detection
|
||||
- Next period calculation
|
||||
|
||||
**Validation Tests:**
|
||||
- Interval immutability enforced
|
||||
- Same interval validation on type change
|
||||
- Status transitions allowed
|
||||
- Uniqueness constraints enforced
|
||||
|
||||
### Integration Testing
|
||||
|
||||
**Period Generation Flow:**
|
||||
- Member creation triggers generation
|
||||
- Type assignment triggers generation
|
||||
- Type change regenerates future periods
|
||||
- Scheduled job generates missing periods
|
||||
- Left member stops generation
|
||||
|
||||
**Status Management Flow:**
|
||||
- Mark single period as paid
|
||||
- Bulk mark multiple periods (low prio)
|
||||
- Status transitions work
|
||||
- Permissions enforced
|
||||
|
||||
**Contribution Type Management:**
|
||||
- Create type
|
||||
- Update amount (regeneration triggered)
|
||||
- Cannot update interval
|
||||
- Cannot delete if in use
|
||||
|
||||
### LiveView Testing
|
||||
|
||||
**Member List:**
|
||||
- Status column displays correctly
|
||||
- Toggle between last/current works
|
||||
- Filters work correctly
|
||||
- Color coding applied
|
||||
|
||||
**Member Detail:**
|
||||
- Periods table displays all periods
|
||||
- Checkboxes work
|
||||
- Bulk marking works (low prio)
|
||||
- Type change validation works
|
||||
- Actions only shown with permission
|
||||
|
||||
**Admin UI:**
|
||||
- Type CRUD works
|
||||
- Settings save correctly
|
||||
- Validations display errors
|
||||
- Only authorized users can access
|
||||
|
||||
### Edge Case Testing
|
||||
|
||||
**Interval Change Attempt:**
|
||||
- Error message displayed
|
||||
- No data modified
|
||||
- User can cancel/choose different type
|
||||
|
||||
**Exit with Unpaid:**
|
||||
- Warning shown
|
||||
- Option to suspend offered
|
||||
- Exit completes correctly
|
||||
|
||||
**Amount Change:**
|
||||
- Warning displayed
|
||||
- Only future unpaid regenerated
|
||||
- Historical periods unchanged
|
||||
|
||||
**Date Boundaries:**
|
||||
- Today = period start handled
|
||||
- Today = period end handled
|
||||
- Leap year handled
|
||||
|
||||
### Performance Testing
|
||||
|
||||
**Period Generation:**
|
||||
- Generate 10 years of monthly periods: < 100ms
|
||||
- Generate for 1000 members: < 5 seconds
|
||||
- Idempotent check efficient (no full scan)
|
||||
|
||||
**Member List Query:**
|
||||
- With status column: < 200ms for 1000 members
|
||||
- Filters applied efficiently
|
||||
- No N+1 queries
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Authorization
|
||||
|
||||
**Permissions Required:**
|
||||
- ContributionType management: Admin only
|
||||
- ContributionPeriod status changes: Admin + Treasurer
|
||||
- View all periods: Admin + Treasurer + Board
|
||||
- View own periods: All authenticated users
|
||||
|
||||
**Policy Enforcement:**
|
||||
- All actions protected by Ash policies
|
||||
- UI shows/hides based on permissions
|
||||
- Backend validates permissions (never trust UI alone)
|
||||
|
||||
### Data Integrity
|
||||
|
||||
**Validation Layers:**
|
||||
1. Database constraints (NOT NULL, UNIQUE, CHECK)
|
||||
2. Ash validations (business rules)
|
||||
3. UI validations (user experience)
|
||||
|
||||
**Immutability Protection:**
|
||||
- Interval change prevented at multiple layers
|
||||
- Period amounts immutable (audit trail)
|
||||
- Settings changes logged (future)
|
||||
|
||||
### Audit Trail
|
||||
|
||||
**Tracked Information:**
|
||||
- Period status changes (who, when) - future enhancement
|
||||
- Type amount changes (implicit via period amounts)
|
||||
- Member type assignments (via timestamps)
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Database Indexes
|
||||
|
||||
**Required Indexes:**
|
||||
- `contribution_periods(member_id)` - For member period lookups
|
||||
- `contribution_periods(contribution_type_id)` - For type queries
|
||||
- `contribution_periods(status)` - For unpaid filters
|
||||
- `contribution_periods(period_start)` - For date range queries
|
||||
- `contribution_periods(member_id, period_start)` - Composite unique index
|
||||
- `members(contribution_type_id)` - For type membership count
|
||||
|
||||
### Query Optimization
|
||||
|
||||
**Preloading:**
|
||||
- Load contribution_type with periods (avoid N+1)
|
||||
- Load periods when displaying member detail
|
||||
- Use Ash's load for efficient preloading
|
||||
|
||||
**Calculated Fields:**
|
||||
- period_end calculated on-demand (not stored)
|
||||
- current_period_status calculated when needed
|
||||
- Use Ash calculations for lazy evaluation
|
||||
|
||||
**Pagination:**
|
||||
- Period list paginated if > 50 periods
|
||||
- Member list already paginated
|
||||
|
||||
### Caching Strategy
|
||||
|
||||
**No caching needed in MVP:**
|
||||
- Contribution types rarely change
|
||||
- Period queries are fast
|
||||
- Settings read infrequently
|
||||
|
||||
**Future caching if needed:**
|
||||
- Cache settings in application memory
|
||||
- Cache contribution types list
|
||||
- Invalidate on change
|
||||
|
||||
### Scheduled Job Performance
|
||||
|
||||
**Period Generation Job:**
|
||||
- Run daily or weekly (not hourly)
|
||||
- Batch members (process 100 at a time)
|
||||
- Skip members with no changes
|
||||
- Log failures for retry
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Phase 2: Interval Change Support
|
||||
|
||||
**Architecture Changes:**
|
||||
- Add logic to handle period overlaps
|
||||
- Calculate prorata amounts if needed
|
||||
- More complex validation
|
||||
- Migration path for existing periods
|
||||
|
||||
### Phase 3: Payment Details
|
||||
|
||||
**Architecture Changes:**
|
||||
- Add PaymentTransaction resource
|
||||
- Link transactions to periods
|
||||
- Support multiple payments per period
|
||||
- Reconciliation logic
|
||||
|
||||
### Phase 4: vereinfacht.digital Integration
|
||||
|
||||
**Architecture Changes:**
|
||||
- External API client module
|
||||
- Webhook handling for transactions
|
||||
- Automatic matching logic
|
||||
- Manual review interface
|
||||
|
||||
---
|
||||
|
||||
**End of Architecture Document**
|
||||
|
||||
243
docs/custom-fields-search-performance.md
Normal file
243
docs/custom-fields-search-performance.md
Normal file
|
|
@ -0,0 +1,243 @@
|
|||
# Performance Analysis: Custom Fields in Search Vector
|
||||
|
||||
## Current Implementation
|
||||
|
||||
The search vector includes custom field values via database triggers that:
|
||||
1. Aggregate all custom field values for a member
|
||||
2. Extract values from JSONB format
|
||||
3. Add them to the search_vector with weight 'C'
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Trigger Performance on Member Updates
|
||||
|
||||
**Current Implementation:**
|
||||
- `members_search_vector_trigger()` executes a subquery on every INSERT/UPDATE:
|
||||
```sql
|
||||
SELECT string_agg(...) FROM custom_field_values WHERE member_id = NEW.id
|
||||
```
|
||||
|
||||
**Performance Impact:**
|
||||
- ✅ **Good:** Index on `member_id` exists (`custom_field_values_member_id_idx`)
|
||||
- ✅ **Good:** Subquery only runs for the affected member
|
||||
- ⚠️ **Potential Issue:** With many custom fields per member (e.g., 50+), aggregation could be slower
|
||||
- ⚠️ **Potential Issue:** JSONB extraction (`value->>'_union_value'`) is relatively fast but adds overhead
|
||||
|
||||
**Expected Performance:**
|
||||
- **Small scale (< 10 custom fields per member):** Negligible impact (< 5ms per operation)
|
||||
- **Medium scale (10-30 custom fields):** Minor impact (5-20ms per operation)
|
||||
- **Large scale (30+ custom fields):** Noticeable impact (20-50ms+ per operation)
|
||||
|
||||
### 2. Trigger Performance on Custom Field Value Changes
|
||||
|
||||
**Current Implementation:**
|
||||
- `update_member_search_vector_from_custom_field_value()` executes on every INSERT/UPDATE/DELETE on `custom_field_values`
|
||||
- **Optimized:** Only fetches required member fields (not full record) to reduce overhead
|
||||
- **Optimized:** Skips re-aggregation on UPDATE if value hasn't actually changed
|
||||
- Aggregates all custom field values, then updates member search_vector
|
||||
|
||||
**Performance Impact:**
|
||||
- ✅ **Good:** Index on `member_id` ensures fast lookup
|
||||
- ✅ **Optimized:** Only required fields are fetched (first_name, last_name, email, etc.) instead of full record
|
||||
- ✅ **Optimized:** UPDATE operations that don't change the value skip expensive re-aggregation (early return)
|
||||
- ⚠️ **Note:** Re-aggregation is still necessary when values change (required for search_vector consistency)
|
||||
- ⚠️ **Critical:** Bulk operations (e.g., importing 1000 members with custom fields) will trigger this for each row
|
||||
|
||||
**Expected Performance:**
|
||||
- **Single operation (value changed):** 3-10ms per custom field value change (improved from 5-15ms)
|
||||
- **Single operation (value unchanged):** <1ms (early return, no aggregation)
|
||||
- **Bulk operations:** Could be slow (consider disabling trigger temporarily)
|
||||
|
||||
### 3. Search Vector Size
|
||||
|
||||
**Current Constraints:**
|
||||
- String values: max 10,000 characters per custom field
|
||||
- No limit on number of custom fields per member
|
||||
- tsvector has no explicit size limit, but very large vectors can cause issues
|
||||
|
||||
**Potential Issues:**
|
||||
- **Theoretical maximum:** If a member has 100 custom fields with 10,000 char strings each, the aggregated text could be ~1MB
|
||||
- **Practical concern:** Very large search vectors (> 100KB) can slow down:
|
||||
- Index updates (GIN index maintenance)
|
||||
- Search queries (tsvector operations)
|
||||
- Trigger execution time
|
||||
|
||||
**Recommendation:**
|
||||
- Monitor search_vector size in production
|
||||
- Consider limiting total custom field content per member if needed
|
||||
- PostgreSQL can handle large tsvectors, but performance degrades gradually
|
||||
|
||||
### 4. Initial Migration Performance
|
||||
|
||||
**Current Implementation:**
|
||||
- Updates ALL members in a single transaction:
|
||||
```sql
|
||||
UPDATE members m SET search_vector = ... (subquery for each member)
|
||||
```
|
||||
|
||||
**Performance Impact:**
|
||||
- ⚠️ **Potential Issue:** With 10,000+ members, this could take minutes
|
||||
- ⚠️ **Potential Issue:** Single transaction locks the members table
|
||||
- ⚠️ **Potential Issue:** If migration fails, entire rollback required
|
||||
|
||||
**Recommendation:**
|
||||
- For large datasets (> 10,000 members), consider:
|
||||
- Batch updates (e.g., 1000 members at a time)
|
||||
- Run during maintenance window
|
||||
- Monitor progress
|
||||
|
||||
### 5. Search Query Performance
|
||||
|
||||
**Current Implementation:**
|
||||
- Full-text search uses GIN index on `search_vector` (fast)
|
||||
- Additional LIKE queries on `custom_field_values` for substring matching:
|
||||
```sql
|
||||
EXISTS (SELECT 1 FROM custom_field_values WHERE member_id = id AND ... LIKE ...)
|
||||
```
|
||||
|
||||
**Performance Impact:**
|
||||
- ✅ **Good:** GIN index on `search_vector` is very fast
|
||||
- ⚠️ **Potential Issue:** LIKE queries on JSONB are not indexed (sequential scan)
|
||||
- ⚠️ **Potential Issue:** EXISTS subquery runs for every search, even if search_vector match is found
|
||||
- ⚠️ **Potential Issue:** With many custom fields, the LIKE queries could be slow
|
||||
|
||||
**Expected Performance:**
|
||||
- **With GIN index match:** Very fast (< 10ms for typical queries)
|
||||
- **Without GIN index match (fallback to LIKE):** Slower (10-100ms depending on data size)
|
||||
- **Worst case:** Sequential scan of all custom_field_values for all members
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Short-term (Current Implementation)
|
||||
|
||||
1. **Monitor Performance:**
|
||||
- Add logging for trigger execution time
|
||||
- Monitor search_vector size distribution
|
||||
- Track search query performance
|
||||
|
||||
2. **Index Verification:**
|
||||
- Ensure `custom_field_values_member_id_idx` exists and is used
|
||||
- Verify GIN index on `search_vector` is maintained
|
||||
|
||||
3. **Bulk Operations:**
|
||||
- For bulk imports, consider temporarily disabling the custom_field_values trigger
|
||||
- Re-enable and update search_vectors in batch after import
|
||||
|
||||
### Medium-term Optimizations
|
||||
|
||||
1. **✅ Optimize Trigger Function (FULLY IMPLEMENTED):**
|
||||
- ✅ Only fetch required member fields instead of full record (reduces overhead)
|
||||
- ✅ Skip re-aggregation on UPDATE if value hasn't actually changed (early return optimization)
|
||||
|
||||
2. **Limit Search Vector Size:**
|
||||
- Truncate very long custom field values (e.g., first 1000 chars)
|
||||
- Add warning if aggregated text exceeds threshold
|
||||
|
||||
3. **Optimize LIKE Queries:**
|
||||
- Consider adding a generated column for searchable text
|
||||
- Or use a materialized view for custom field search
|
||||
|
||||
### Long-term Considerations
|
||||
|
||||
1. **Alternative Approaches:**
|
||||
- Separate search index table for custom fields
|
||||
- Use Elasticsearch or similar for advanced search
|
||||
- Materialized view for search optimization
|
||||
|
||||
2. **Scaling Strategy:**
|
||||
- If performance becomes an issue with 100+ custom fields per member:
|
||||
- Consider limiting which custom fields are searchable
|
||||
- Use a separate search service
|
||||
- Implement search result caching
|
||||
|
||||
## Performance Benchmarks (Estimated)
|
||||
|
||||
Based on typical PostgreSQL performance:
|
||||
|
||||
| Scenario | Members | Custom Fields/Member | Expected Impact |
|
||||
|----------|---------|---------------------|-----------------|
|
||||
| Small | < 1,000 | < 10 | Negligible (< 5ms per operation) |
|
||||
| Medium | 1,000-10,000 | 10-30 | Minor (5-20ms per operation) |
|
||||
| Large | 10,000-100,000 | 30-50 | Noticeable (20-50ms per operation) |
|
||||
| Very Large | > 100,000 | 50+ | Significant (50-200ms+ per operation) |
|
||||
|
||||
## Monitoring Queries
|
||||
|
||||
```sql
|
||||
-- Check search_vector size distribution
|
||||
SELECT
|
||||
pg_size_pretty(octet_length(search_vector::text)) as size,
|
||||
COUNT(*) as member_count
|
||||
FROM members
|
||||
WHERE search_vector IS NOT NULL
|
||||
GROUP BY octet_length(search_vector::text)
|
||||
ORDER BY octet_length(search_vector::text) DESC
|
||||
LIMIT 20;
|
||||
|
||||
-- Check average custom fields per member
|
||||
SELECT
|
||||
AVG(custom_field_count) as avg_custom_fields,
|
||||
MAX(custom_field_count) as max_custom_fields
|
||||
FROM (
|
||||
SELECT member_id, COUNT(*) as custom_field_count
|
||||
FROM custom_field_values
|
||||
GROUP BY member_id
|
||||
) subq;
|
||||
|
||||
-- Check trigger execution time (requires pg_stat_statements)
|
||||
SELECT
|
||||
mean_exec_time,
|
||||
calls,
|
||||
query
|
||||
FROM pg_stat_statements
|
||||
WHERE query LIKE '%members_search_vector_trigger%'
|
||||
ORDER BY mean_exec_time DESC;
|
||||
```
|
||||
|
||||
## Code Quality Improvements (Post-Review)
|
||||
|
||||
### Refactored Search Implementation
|
||||
|
||||
The search query has been refactored for better maintainability and clarity:
|
||||
|
||||
**Before:** Single large OR-chain with mixed search types (hard to maintain)
|
||||
|
||||
**After:** Modular functions grouped by search type:
|
||||
- `build_fts_filter/1` - Full-text search (highest priority, fastest)
|
||||
- `build_substring_filter/2` - Substring matching on structured fields
|
||||
- `build_custom_field_filter/1` - Custom field value search (JSONB LIKE)
|
||||
- `build_fuzzy_filter/2` - Trigram/fuzzy matching for names and streets
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Clear separation of concerns
|
||||
- ✅ Easier to maintain and test
|
||||
- ✅ Better documentation of search priority
|
||||
- ✅ Easier to optimize individual search types
|
||||
|
||||
**Search Priority Order:**
|
||||
1. **FTS (Full-Text Search)** - Fastest, uses GIN index on search_vector
|
||||
2. **Substring** - For structured fields (postal_code, phone_number, etc.)
|
||||
3. **Custom Fields** - JSONB LIKE queries (fallback for substring matching)
|
||||
4. **Fuzzy Matching** - Trigram similarity for names and streets
|
||||
|
||||
## Conclusion
|
||||
|
||||
The current implementation is **well-optimized for typical use cases** (< 30 custom fields per member, < 10,000 members). For larger scales, monitoring and potential optimizations may be needed.
|
||||
|
||||
**Key Strengths:**
|
||||
- Indexed lookups (member_id index)
|
||||
- Efficient GIN index for search
|
||||
- Trigger-based automatic updates
|
||||
- Modular, maintainable search code structure
|
||||
|
||||
**Key Weaknesses:**
|
||||
- LIKE queries on JSONB (not indexed)
|
||||
- Re-aggregation on every custom field change (necessary for consistency)
|
||||
- Potential size issues with many/large custom fields
|
||||
- Substring searches (contains/ILIKE) not index-optimized
|
||||
|
||||
**Recent Optimizations:**
|
||||
- ✅ Trigger function optimized to fetch only required fields (reduces overhead by ~30-50%)
|
||||
- ✅ Early return on UPDATE when value hasn't changed (skips expensive re-aggregation, <1ms vs 3-10ms)
|
||||
- ✅ Improved performance for custom field value updates (3-10ms vs 5-15ms when value changes)
|
||||
|
||||
|
|
@ -168,9 +168,16 @@ Member (1) → (N) Properties
|
|||
### Weighted Fields
|
||||
- **Weight A (highest):** first_name, last_name
|
||||
- **Weight B:** email, notes
|
||||
- **Weight C:** phone_number, city, street, house_number, postal_code
|
||||
- **Weight C:** phone_number, city, street, house_number, postal_code, custom_field_values
|
||||
- **Weight D (lowest):** join_date, exit_date
|
||||
|
||||
### Custom Field Values in Search
|
||||
Custom field values are automatically included in the search vector:
|
||||
- All custom field values (string, integer, boolean, date, email) are aggregated and added to the search vector
|
||||
- Values are converted to text format for indexing
|
||||
- Custom field values receive weight 'C' (same as phone_number, city, etc.)
|
||||
- The search vector is automatically updated when custom field values are created, updated, or deleted via database triggers
|
||||
|
||||
### Usage Example
|
||||
```sql
|
||||
SELECT * FROM members
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@
|
|||
// - https://dbdocs.io
|
||||
// - VS Code Extensions: "DBML Language" or "dbdiagram.io"
|
||||
//
|
||||
// Version: 1.2
|
||||
// Last Updated: 2025-11-13
|
||||
// Version: 1.3
|
||||
// Last Updated: 2025-12-11
|
||||
|
||||
Project mila_membership_management {
|
||||
database_type: 'PostgreSQL'
|
||||
|
|
@ -27,6 +27,7 @@ Project mila_membership_management {
|
|||
## Domains:
|
||||
- **Accounts**: User authentication and session management
|
||||
- **Membership**: Club member data and custom fields
|
||||
- **MembershipFees**: Membership fee types and billing cycles
|
||||
|
||||
## Required PostgreSQL Extensions:
|
||||
- uuid-ossp (UUID generation)
|
||||
|
|
@ -132,6 +133,8 @@ Table members {
|
|||
house_number text [null, note: 'House number']
|
||||
postal_code text [null, note: '5-digit German postal code']
|
||||
search_vector tsvector [null, note: 'Full-text search index (auto-generated)']
|
||||
membership_fee_type_id uuid [null, note: 'FK to membership_fee_types - assigned fee type']
|
||||
membership_fee_start_date date [null, note: 'Date from which membership fees should be calculated']
|
||||
|
||||
indexes {
|
||||
email [unique, name: 'members_unique_email_index']
|
||||
|
|
@ -146,6 +149,7 @@ Table members {
|
|||
last_name [name: 'members_last_name_idx', note: 'B-tree index for name sorting']
|
||||
join_date [name: 'members_join_date_idx', note: 'B-tree index for date filters']
|
||||
(paid) [name: 'members_paid_idx', type: btree, note: 'Partial index WHERE paid IS NOT NULL']
|
||||
membership_fee_type_id [name: 'members_membership_fee_type_id_index', note: 'B-tree index for fee type lookups']
|
||||
}
|
||||
|
||||
Note: '''
|
||||
|
|
@ -178,6 +182,8 @@ Table members {
|
|||
**Relationships:**
|
||||
- Optional 1:1 with users (0..1 ↔ 0..1) - authentication account
|
||||
- 1:N with custom_field_values (custom dynamic fields)
|
||||
- Optional N:1 with membership_fee_types - assigned fee type
|
||||
- 1:N with membership_fee_cycles - billing history
|
||||
|
||||
**Validation Rules:**
|
||||
- first_name, last_name: min 1 character
|
||||
|
|
@ -281,6 +287,98 @@ Table custom_fields {
|
|||
'''
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// MEMBERSHIP_FEES DOMAIN
|
||||
// ============================================
|
||||
|
||||
Table membership_fee_types {
|
||||
id uuid [pk, not null, default: `uuid_generate_v7()`, note: 'UUIDv7 primary key']
|
||||
name text [not null, unique, note: 'Unique name for the fee type (e.g., "Standard", "Reduced")']
|
||||
amount numeric(10,2) [not null, note: 'Fee amount in default currency (CHECK: >= 0)']
|
||||
interval text [not null, note: 'Billing interval (CHECK: IN monthly, quarterly, half_yearly, yearly) - immutable']
|
||||
description text [null, note: 'Optional description for the fee type']
|
||||
|
||||
indexes {
|
||||
name [unique, name: 'membership_fee_types_unique_name_index']
|
||||
}
|
||||
|
||||
Note: '''
|
||||
**Membership Fee Type Definitions**
|
||||
|
||||
Defines the different types of membership fees with fixed billing intervals.
|
||||
|
||||
**Attributes:**
|
||||
- `name`: Unique identifier for the fee type
|
||||
- `amount`: Default fee amount (stored per cycle for audit trail)
|
||||
- `interval`: Billing cycle - immutable after creation
|
||||
- `description`: Optional documentation
|
||||
|
||||
**Interval Values:**
|
||||
- `monthly`: 1st to last day of month
|
||||
- `quarterly`: 1st of Jan/Apr/Jul/Oct to last day of quarter
|
||||
- `half_yearly`: 1st of Jan/Jul to last day of half
|
||||
- `yearly`: Jan 1 to Dec 31
|
||||
|
||||
**Immutability:**
|
||||
The `interval` field cannot be changed after creation to prevent
|
||||
complex migration scenarios. Create a new fee type to change intervals.
|
||||
|
||||
**Relationships:**
|
||||
- 1:N with members - members assigned to this fee type
|
||||
- 1:N with membership_fee_cycles - all cycles using this fee type
|
||||
|
||||
**Deletion Behavior:**
|
||||
- ON DELETE RESTRICT: Cannot delete if members or cycles reference it
|
||||
'''
|
||||
}
|
||||
|
||||
Table membership_fee_cycles {
|
||||
id uuid [pk, not null, default: `uuid_generate_v7()`, note: 'UUIDv7 primary key']
|
||||
cycle_start date [not null, note: 'Start date of the billing cycle']
|
||||
amount numeric(10,2) [not null, note: 'Fee amount for this cycle (CHECK: >= 0)']
|
||||
status text [not null, default: 'unpaid', note: 'Payment status (CHECK: IN unpaid, paid, suspended)']
|
||||
notes text [null, note: 'Optional notes for this cycle']
|
||||
member_id uuid [not null, note: 'FK to members - the member this cycle belongs to']
|
||||
membership_fee_type_id uuid [not null, note: 'FK to membership_fee_types - fee type for this cycle']
|
||||
|
||||
indexes {
|
||||
member_id [name: 'membership_fee_cycles_member_id_index']
|
||||
membership_fee_type_id [name: 'membership_fee_cycles_membership_fee_type_id_index']
|
||||
status [name: 'membership_fee_cycles_status_index']
|
||||
cycle_start [name: 'membership_fee_cycles_cycle_start_index']
|
||||
(member_id, cycle_start) [unique, name: 'membership_fee_cycles_unique_cycle_per_member_index', note: 'One cycle per member per cycle_start']
|
||||
}
|
||||
|
||||
Note: '''
|
||||
**Individual Membership Fee Cycles**
|
||||
|
||||
Represents a single billing cycle for a member with payment tracking.
|
||||
|
||||
**Design Decisions:**
|
||||
- `cycle_end` is NOT stored - calculated from cycle_start + interval
|
||||
- `amount` is stored per cycle to preserve historical values when fee type amount changes
|
||||
- Cycles are aligned to calendar boundaries
|
||||
|
||||
**Status Values:**
|
||||
- `unpaid`: Payment pending (default)
|
||||
- `paid`: Payment received
|
||||
- `suspended`: Payment suspended (e.g., hardship case)
|
||||
|
||||
**Constraints:**
|
||||
- Unique: One cycle per member per cycle_start date
|
||||
- member_id: Required (belongs_to)
|
||||
- membership_fee_type_id: Required (belongs_to)
|
||||
|
||||
**Relationships:**
|
||||
- N:1 with members - the member this cycle belongs to
|
||||
- N:1 with membership_fee_types - the fee type for this cycle
|
||||
|
||||
**Deletion Behavior:**
|
||||
- ON DELETE CASCADE (member_id): Cycles deleted when member deleted
|
||||
- ON DELETE RESTRICT (membership_fee_type_id): Cannot delete fee type if cycles exist
|
||||
'''
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// RELATIONSHIPS
|
||||
// ============================================
|
||||
|
|
@ -306,6 +404,22 @@ Ref: custom_field_values.member_id > members.id [delete: cascade]
|
|||
// - ON DELETE RESTRICT: Cannot delete type if custom_field_values exist
|
||||
Ref: custom_field_values.custom_field_id > custom_fields.id [delete: restrict]
|
||||
|
||||
// Member → MembershipFeeType (N:1)
|
||||
// - Many members can be assigned to one fee type
|
||||
// - Optional relationship (member can have no fee type)
|
||||
// - ON DELETE RESTRICT: Cannot delete fee type if members are assigned
|
||||
Ref: members.membership_fee_type_id > membership_fee_types.id [delete: restrict]
|
||||
|
||||
// MembershipFeeCycle → Member (N:1)
|
||||
// - Many cycles belong to one member
|
||||
// - ON DELETE CASCADE: Cycles deleted when member deleted
|
||||
Ref: membership_fee_cycles.member_id > members.id [delete: cascade]
|
||||
|
||||
// MembershipFeeCycle → MembershipFeeType (N:1)
|
||||
// - Many cycles reference one fee type
|
||||
// - ON DELETE RESTRICT: Cannot delete fee type if cycles reference it
|
||||
Ref: membership_fee_cycles.membership_fee_type_id > membership_fee_types.id [delete: restrict]
|
||||
|
||||
// ============================================
|
||||
// ENUMS
|
||||
// ============================================
|
||||
|
|
@ -328,6 +442,21 @@ Enum token_purpose {
|
|||
email_confirmation [note: 'Email verification tokens']
|
||||
}
|
||||
|
||||
// Billing interval for membership fee types
|
||||
Enum membership_fee_interval {
|
||||
monthly [note: '1st to last day of month']
|
||||
quarterly [note: '1st of Jan/Apr/Jul/Oct to last day of quarter']
|
||||
half_yearly [note: '1st of Jan/Jul to last day of half']
|
||||
yearly [note: 'Jan 1 to Dec 31']
|
||||
}
|
||||
|
||||
// Payment status for membership fee cycles
|
||||
Enum membership_fee_status {
|
||||
unpaid [note: 'Payment pending (default)']
|
||||
paid [note: 'Payment received']
|
||||
suspended [note: 'Payment suspended']
|
||||
}
|
||||
|
||||
// ============================================
|
||||
// TABLE GROUPS
|
||||
// ============================================
|
||||
|
|
@ -357,3 +486,17 @@ TableGroup membership_domain {
|
|||
'''
|
||||
}
|
||||
|
||||
TableGroup membership_fees_domain {
|
||||
membership_fee_types
|
||||
membership_fee_cycles
|
||||
|
||||
Note: '''
|
||||
**Membership Fees Domain**
|
||||
|
||||
Handles membership fee management including:
|
||||
- Fee type definitions with intervals
|
||||
- Individual billing cycles per member
|
||||
- Payment status tracking
|
||||
'''
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -187,16 +187,16 @@
|
|||
|
||||
**Current State:**
|
||||
- ✅ Basic "paid" boolean field on members
|
||||
- ✅ **UI Mock-ups for Contribution Types & Settings** (2025-12-02)
|
||||
- ✅ **UI Mock-ups for Membership Fee Types & Settings** (2025-12-02)
|
||||
- ⚠️ No payment tracking
|
||||
|
||||
**Open Issues:**
|
||||
- [#156](https://git.local-it.org/local-it/mitgliederverwaltung/issues/156) - Set up & document testing environment for vereinfacht.digital (L, Low priority)
|
||||
- [#226](https://git.local-it.org/local-it/mitgliederverwaltung/issues/226) - Payment/Contribution Mockup Pages (Preview)
|
||||
- [#226](https://git.local-it.org/local-it/mitgliederverwaltung/issues/226) - Payment/Membership Fee Mockup Pages (Preview)
|
||||
|
||||
**Mock-Up Pages (Non-Functional Preview):**
|
||||
- `/contribution_types` - Contribution Types Management
|
||||
- `/contribution_settings` - Global Contribution Settings
|
||||
- `/membership_fee_types` - Membership Fee Types Management
|
||||
- `/membership_fee_settings` - Global Membership Fee Settings
|
||||
|
||||
**Missing Features:**
|
||||
- ❌ Membership fee configuration
|
||||
|
|
|
|||
723
docs/membership-fee-architecture.md
Normal file
723
docs/membership-fee-architecture.md
Normal file
|
|
@ -0,0 +1,723 @@
|
|||
# Membership Fees - Technical Architecture
|
||||
|
||||
**Project:** Mila - Membership Management System
|
||||
**Feature:** Membership Fee Management
|
||||
**Version:** 1.0
|
||||
**Last Updated:** 2025-11-27
|
||||
**Status:** Architecture Design - Ready for Implementation
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the technical architecture for the Membership Fees system. It focuses on architectural decisions, patterns, module structure, and integration points **without** concrete implementation details.
|
||||
|
||||
**Related Documents:**
|
||||
|
||||
- [membership-fee-overview.md](./membership-fee-overview.md) - Business logic and requirements
|
||||
- [database-schema-readme.md](./database-schema-readme.md) - Database documentation
|
||||
- [database_schema.dbml](./database_schema.dbml) - Database schema definition
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Architecture Principles](#architecture-principles)
|
||||
2. [Domain Structure](#domain-structure)
|
||||
3. [Data Architecture](#data-architecture)
|
||||
4. [Business Logic Architecture](#business-logic-architecture)
|
||||
5. [Integration Points](#integration-points)
|
||||
6. [Acceptance Criteria](#acceptance-criteria)
|
||||
7. [Testing Strategy](#testing-strategy)
|
||||
8. [Security Considerations](#security-considerations)
|
||||
9. [Performance Considerations](#performance-considerations)
|
||||
|
||||
---
|
||||
|
||||
## Architecture Principles
|
||||
|
||||
### Core Design Decisions
|
||||
|
||||
1. **Single Responsibility:**
|
||||
- Each module has one clear responsibility
|
||||
- Cycle generation separated from status management
|
||||
- Calendar logic isolated in dedicated module
|
||||
|
||||
2. **No Redundancy:**
|
||||
- No `cycle_end` field (calculated from `cycle_start` + `interval`)
|
||||
- No `interval_type` field (read from `membership_fee_type.interval`)
|
||||
- Eliminates data inconsistencies
|
||||
|
||||
3. **Immutability Where Important:**
|
||||
- `membership_fee_type.interval` cannot be changed after creation
|
||||
- Prevents complex migration scenarios
|
||||
- Enforced via Ash change validation
|
||||
|
||||
4. **Historical Accuracy:**
|
||||
- `amount` stored per cycle for audit trail
|
||||
- Enables tracking of membership fee changes over time
|
||||
- Old cycles retain original amounts
|
||||
|
||||
5. **Calendar-Based Cycles:**
|
||||
- All cycles aligned to calendar boundaries
|
||||
- Simplifies date calculations
|
||||
- Predictable cycle generation
|
||||
|
||||
---
|
||||
|
||||
## Domain Structure
|
||||
|
||||
### Ash Domain: `Mv.MembershipFees`
|
||||
|
||||
**Purpose:** Encapsulates all membership fee-related resources and logic
|
||||
|
||||
**Resources:**
|
||||
|
||||
- `MembershipFeeType` - Membership fee type definitions (admin-managed)
|
||||
- `MembershipFeeCycle` - Individual membership fee cycles per member
|
||||
|
||||
**Extensions:**
|
||||
|
||||
- Member resource extended with membership fee fields
|
||||
|
||||
### Module Organization
|
||||
|
||||
```
|
||||
lib/
|
||||
├── membership_fees/
|
||||
│ ├── membership_fees.ex # Ash domain definition
|
||||
│ ├── membership_fee_type.ex # MembershipFeeType resource
|
||||
│ ├── membership_fee_cycle.ex # MembershipFeeCycle resource
|
||||
│ └── changes/
|
||||
│ ├── prevent_interval_change.ex # Validates interval immutability
|
||||
│ ├── set_membership_fee_start_date.ex # Auto-sets start date
|
||||
│ └── validate_same_interval.ex # Validates interval match on type change
|
||||
├── mv/
|
||||
│ └── membership_fees/
|
||||
│ ├── cycle_generator.ex # Cycle generation algorithm
|
||||
│ └── calendar_cycles.ex # Calendar cycle calculations
|
||||
└── membership/
|
||||
└── member.ex # Extended with membership fee relationships
|
||||
```
|
||||
|
||||
### Separation of Concerns
|
||||
|
||||
**Domain Layer (Ash Resources):**
|
||||
|
||||
- Data validation
|
||||
- Relationship management
|
||||
- Policy enforcement
|
||||
- Action definitions
|
||||
|
||||
**Business Logic Layer (`Mv.MembershipFees`):**
|
||||
|
||||
- Cycle generation algorithm
|
||||
- Calendar calculations
|
||||
- Date boundary handling
|
||||
- Status transitions
|
||||
|
||||
**UI Layer (LiveView):**
|
||||
|
||||
- User interaction
|
||||
- Display logic
|
||||
- Authorization checks
|
||||
- Form handling
|
||||
|
||||
---
|
||||
|
||||
## Data Architecture
|
||||
|
||||
### Database Schema Extensions
|
||||
|
||||
**See:** [database-schema-readme.md](./database-schema-readme.md) and [database_schema.dbml](./database_schema.dbml) for complete schema documentation.
|
||||
|
||||
### New Tables
|
||||
|
||||
1. **`membership_fee_types`**
|
||||
- Purpose: Define membership fee types with fixed intervals
|
||||
- Key Constraint: `interval` field immutable after creation
|
||||
- Relationships: has_many members, has_many membership_fee_cycles
|
||||
|
||||
2. **`membership_fee_cycles`**
|
||||
- Purpose: Individual membership fee cycles for members
|
||||
- Key Design: NO `cycle_end` or `interval_type` fields (calculated)
|
||||
- Relationships: belongs_to member, belongs_to membership_fee_type
|
||||
- Composite uniqueness: One cycle per member per cycle_start
|
||||
|
||||
### Member Table Extensions
|
||||
|
||||
**Fields Added:**
|
||||
|
||||
- `membership_fee_type_id` (FK, NOT NULL with default from settings)
|
||||
- `membership_fee_start_date` (Date, nullable)
|
||||
|
||||
**Existing Fields Used:**
|
||||
|
||||
- `join_date` - For calculating membership fee start
|
||||
- `exit_date` - For limiting cycle generation
|
||||
- These fields must remain member fields and should not be replaced by custom fields in the future
|
||||
|
||||
### Settings Integration
|
||||
|
||||
**Global Settings:**
|
||||
|
||||
- `membership_fees.include_joining_cycle` (Boolean)
|
||||
- `membership_fees.default_membership_fee_type_id` (UUID)
|
||||
|
||||
**Storage:** Existing settings mechanism (TBD: dedicated table or configuration resource)
|
||||
|
||||
### Foreign Key Behaviors
|
||||
|
||||
| Relationship | On Delete | Rationale |
|
||||
|--------------|-----------|-----------|
|
||||
| `membership_fee_cycles.member_id → members.id` | CASCADE | Remove membership fee cycles when member deleted |
|
||||
| `membership_fee_cycles.membership_fee_type_id → membership_fee_types.id` | RESTRICT | Prevent membership fee type deletion if cycles exist |
|
||||
| `members.membership_fee_type_id → membership_fee_types.id` | RESTRICT | Prevent membership fee type deletion if assigned to members |
|
||||
|
||||
---
|
||||
|
||||
## Business Logic Architecture
|
||||
|
||||
### Cycle Generation System
|
||||
|
||||
**Component:** `Mv.MembershipFees.CycleGenerator`
|
||||
|
||||
**Responsibilities:**
|
||||
|
||||
- Calculate which cycles should exist for a member
|
||||
- Generate missing cycles
|
||||
- Respect membership_fee_start_date and exit_date boundaries
|
||||
- Skip existing cycles (idempotent)
|
||||
- Use PostgreSQL advisory locks per member to prevent race conditions
|
||||
|
||||
**Triggers:**
|
||||
|
||||
1. Member membership fee type assigned (via Ash change)
|
||||
2. Member created with membership fee type (via Ash change)
|
||||
3. Scheduled job runs (daily/weekly cron)
|
||||
4. Admin manual regeneration (UI action)
|
||||
|
||||
**Algorithm Steps:**
|
||||
|
||||
1. Retrieve member with membership fee type and dates
|
||||
2. Determine generation start point:
|
||||
- If NO cycles exist: Start from `membership_fee_start_date` (or calculated from `join_date`)
|
||||
- If cycles exist: Start from the cycle AFTER the last existing one
|
||||
3. Generate all cycle starts from the determined start point to today (or `exit_date`)
|
||||
4. Create new cycles with current membership fee type's amount
|
||||
5. Use PostgreSQL advisory locks per member to prevent race conditions
|
||||
|
||||
**Edge Case Handling:**
|
||||
|
||||
- If membership_fee_start_date is NULL: Calculate from join_date + global setting
|
||||
- If exit_date is set: Stop generation at exit_date
|
||||
- If membership fee type changes: Handled separately by regeneration logic
|
||||
- **Gap Handling:** If cycles were explicitly deleted (gaps exist), they are NOT recreated.
|
||||
The generator always continues from the cycle AFTER the last existing cycle, regardless of gaps.
|
||||
|
||||
### Calendar Cycle Calculations
|
||||
|
||||
**Component:** `Mv.MembershipFees.CalendarCycles`
|
||||
|
||||
**Responsibilities:**
|
||||
|
||||
- Calculate cycle boundaries based on interval type
|
||||
- Determine current cycle
|
||||
- Determine last completed cycle
|
||||
- Calculate cycle_end from cycle_start + interval
|
||||
|
||||
**Functions (high-level):**
|
||||
|
||||
- `calculate_cycle_start/3` - Given date and interval, find cycle start
|
||||
- `calculate_cycle_end/2` - Given cycle_start and interval, calculate end
|
||||
- `next_cycle_start/2` - Given cycle_start and interval, find next
|
||||
- `is_current_cycle?/2` - Check if cycle contains today
|
||||
- `is_last_completed_cycle?/2` - Check if cycle just ended
|
||||
|
||||
**Interval Logic:**
|
||||
|
||||
- **Monthly:** Start = 1st of month, End = last day of month
|
||||
- **Quarterly:** Start = 1st of quarter (Jan/Apr/Jul/Oct), End = last day of quarter
|
||||
- **Half-yearly:** Start = 1st of half (Jan/Jul), End = last day of half
|
||||
- **Yearly:** Start = Jan 1st, End = Dec 31st
|
||||
|
||||
### Status Management
|
||||
|
||||
**Component:** Ash actions on `MembershipFeeCycle`
|
||||
|
||||
**Status Transitions:**
|
||||
|
||||
- Simple state machine: unpaid ↔ paid ↔ suspended
|
||||
- No complex validation (all transitions allowed)
|
||||
- Permissions checked via Ash policies
|
||||
|
||||
**Actions Required:**
|
||||
|
||||
- `mark_as_paid` - Set status to :paid
|
||||
- `mark_as_suspended` - Set status to :suspended
|
||||
- `mark_as_unpaid` - Set status to :unpaid (error correction)
|
||||
|
||||
**Bulk Operations:**
|
||||
|
||||
- `bulk_mark_as_paid` - Mark multiple cycles as paid (efficiency)
|
||||
- low priority, can be a future issue
|
||||
|
||||
### Membership Fee Type Change Handling
|
||||
|
||||
**Component:** Ash change on `Member.membership_fee_type_id`
|
||||
|
||||
**Validation:**
|
||||
|
||||
- Check if new type has same interval as old type
|
||||
- If different: Reject change (MVP constraint)
|
||||
- If same: Allow change
|
||||
|
||||
**Side Effects on Allowed Change:**
|
||||
|
||||
1. Keep all existing cycles unchanged
|
||||
2. Find future unpaid cycles
|
||||
3. Delete future unpaid cycles
|
||||
4. Regenerate cycles with new membership_fee_type_id and amount
|
||||
|
||||
**Implementation Pattern:**
|
||||
|
||||
- Use Ash change module to validate
|
||||
- Use after_action hook to trigger regeneration synchronously
|
||||
- Regeneration runs in the same transaction as the member update to ensure atomicity
|
||||
- CycleGenerator uses advisory locks and transactions internally to prevent race conditions
|
||||
|
||||
**Validation Behavior:**
|
||||
|
||||
- Fail-closed: If membership fee types cannot be loaded during validation, the change is rejected with a validation error
|
||||
- Nil assignment prevention: Attempts to set membership_fee_type_id to nil are rejected when a current type exists
|
||||
|
||||
---
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Member Resource Integration
|
||||
|
||||
**Extension Points:**
|
||||
|
||||
1. Add fields via migration
|
||||
2. Add relationships (belongs_to, has_many)
|
||||
3. Add calculations (current_cycle_status, overdue_count)
|
||||
4. Add changes (auto-set membership_fee_start_date, validate interval)
|
||||
|
||||
**Backward Compatibility:**
|
||||
|
||||
- New fields nullable or with defaults
|
||||
- Existing members get default membership fee type from settings
|
||||
- No breaking changes to existing member functionality
|
||||
|
||||
### Settings System Integration
|
||||
|
||||
**Requirements:**
|
||||
|
||||
- Store two global settings
|
||||
- Provide UI for admin to modify
|
||||
- Default values if not set
|
||||
- Validation (e.g., default membership fee type must exist)
|
||||
|
||||
**Access Pattern:**
|
||||
|
||||
- Read settings during cycle generation
|
||||
- Read settings during member creation
|
||||
- Write settings only via admin UI
|
||||
|
||||
### Permission System Integration
|
||||
|
||||
**See:** [roles-and-permissions-architecture.md](./roles-and-permissions-architecture.md)
|
||||
|
||||
**Required Permissions:**
|
||||
|
||||
- `MembershipFeeType.create/update/destroy` - Admin only
|
||||
- `MembershipFeeType.read` - Admin, Treasurer, Board
|
||||
- `MembershipFeeCycle.update` (status changes) - Admin, Treasurer
|
||||
- `MembershipFeeCycle.read` - Admin, Treasurer, Board, Own member
|
||||
|
||||
**Policy Patterns:**
|
||||
|
||||
- Use existing HasPermission check
|
||||
- Leverage existing roles (Admin, Kassenwart)
|
||||
- Member can read own cycles (linked via member_id)
|
||||
|
||||
### LiveView Integration
|
||||
|
||||
**New LiveViews Required:**
|
||||
|
||||
1. MembershipFeeType index/form (admin)
|
||||
2. MembershipFeeCycle table component (member detail view)
|
||||
3. Settings form section (admin)
|
||||
4. Member list column (membership fee status)
|
||||
|
||||
**Existing LiveViews to Extend:**
|
||||
|
||||
- Member detail view: Add membership fees section
|
||||
- Member list view: Add status column
|
||||
- Settings page: Add membership fees section
|
||||
|
||||
**Authorization Helpers:**
|
||||
|
||||
- Use existing `can?/3` helper for UI conditionals
|
||||
- Check permissions before showing actions
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### MembershipFeeType Resource
|
||||
|
||||
**AC-MFT-1:** Admin can create membership fee type with name, amount, interval, description
|
||||
**AC-MFT-2:** Interval field is immutable after creation (validation error on change attempt)
|
||||
**AC-MFT-3:** Admin can update name, amount, description (but not interval)
|
||||
**AC-MFT-4:** Cannot delete membership fee type if assigned to members
|
||||
**AC-MFT-5:** Cannot delete membership fee type if cycles exist referencing it
|
||||
**AC-MFT-6:** Interval must be one of: monthly, quarterly, half_yearly, yearly
|
||||
|
||||
### MembershipFeeCycle Resource
|
||||
|
||||
**AC-MFC-1:** Cycle has cycle_start, status, amount, notes, member_id, membership_fee_type_id
|
||||
**AC-MFC-2:** cycle_end is calculated, not stored
|
||||
**AC-MFC-3:** Status defaults to :unpaid
|
||||
**AC-MFC-4:** One cycle per member per cycle_start (uniqueness constraint)
|
||||
**AC-MFC-5:** Amount is set at generation time from membership_fee_type.amount
|
||||
**AC-MFC-6:** Cycles cascade delete when member deleted
|
||||
**AC-MFC-7:** Admin/Treasurer can change status
|
||||
**AC-MFC-8:** Member can read own cycles
|
||||
|
||||
### Member Extensions
|
||||
|
||||
**AC-M-1:** Member has membership_fee_type_id field (NOT NULL with default)
|
||||
**AC-M-2:** Member has membership_fee_start_date field (nullable)
|
||||
**AC-M-3:** New members get default membership fee type from global setting
|
||||
**AC-M-4:** membership_fee_start_date auto-set based on join_date and global setting
|
||||
**AC-M-5:** Admin can manually override membership_fee_start_date
|
||||
**AC-M-6:** Cannot change to membership fee type with different interval (MVP)
|
||||
|
||||
### Cycle Generation
|
||||
|
||||
**AC-CG-1:** Cycles generated when member gets membership fee type
|
||||
**AC-CG-2:** Cycles generated when member created (via change hook)
|
||||
**AC-CG-3:** Scheduled job generates missing cycles daily
|
||||
**AC-CG-4:** Generation respects membership_fee_start_date
|
||||
**AC-CG-5:** Generation stops at exit_date if member exited
|
||||
**AC-CG-6:** Generation is idempotent (skips existing cycles)
|
||||
**AC-CG-7:** Cycles align to calendar boundaries (1st of month/quarter/half/year)
|
||||
**AC-CG-8:** Amount comes from membership_fee_type at generation time
|
||||
|
||||
### Calendar Logic
|
||||
|
||||
**AC-CL-1:** Monthly cycles: 1st to last day of month
|
||||
**AC-CL-2:** Quarterly cycles: 1st of Jan/Apr/Jul/Oct to last day of quarter
|
||||
**AC-CL-3:** Half-yearly cycles: 1st of Jan/Jul to last day of half
|
||||
**AC-CL-4:** Yearly cycles: Jan 1 to Dec 31
|
||||
**AC-CL-5:** cycle_end calculated correctly for all interval types
|
||||
**AC-CL-6:** Current cycle determined correctly based on today's date
|
||||
**AC-CL-7:** Last completed cycle determined correctly
|
||||
|
||||
### Membership Fee Type Change
|
||||
|
||||
**AC-TC-1:** Can change to type with same interval
|
||||
**AC-TC-2:** Cannot change to type with different interval (error message)
|
||||
**AC-TC-3:** On allowed change: future unpaid cycles regenerated
|
||||
**AC-TC-4:** On allowed change: paid/suspended cycles unchanged
|
||||
**AC-TC-5:** On allowed change: amount updated to new type's amount
|
||||
**AC-TC-6:** Change is atomic (transaction) - ✅ Implemented: Regeneration runs synchronously in the same transaction as the member update
|
||||
|
||||
### Settings
|
||||
|
||||
**AC-S-1:** Global setting: include_joining_cycle (boolean, default true)
|
||||
**AC-S-2:** Global setting: default_membership_fee_type_id (UUID, required)
|
||||
**AC-S-3:** Admin can modify settings via UI
|
||||
**AC-S-4:** Settings validated (e.g., default membership fee type must exist)
|
||||
**AC-S-5:** Settings applied to new members immediately
|
||||
|
||||
### UI - Member List
|
||||
|
||||
**AC-UI-ML-1:** New column shows membership fee status
|
||||
**AC-UI-ML-2:** Default: Shows last completed cycle status
|
||||
**AC-UI-ML-3:** Optional: Toggle to show current cycle status
|
||||
**AC-UI-ML-4:** Color coding: green (paid), red (unpaid), gray (suspended)
|
||||
**AC-UI-ML-5:** Filter: Unpaid in last cycle
|
||||
**AC-UI-ML-6:** Filter: Unpaid in current cycle
|
||||
|
||||
### UI - Member Detail
|
||||
|
||||
**AC-UI-MD-1:** Membership fees section shows all cycles
|
||||
**AC-UI-MD-2:** Table columns: Cycle, Interval, Amount, Status, Actions
|
||||
**AC-UI-MD-3:** Checkbox per cycle for bulk marking (low prio)
|
||||
**AC-UI-MD-4:** "Mark selected as paid" button
|
||||
**AC-UI-MD-5:** Dropdown to change membership fee type (same interval only)
|
||||
**AC-UI-MD-6:** Warning if different interval selected
|
||||
**AC-UI-MD-7:** Only show actions if user has permission
|
||||
|
||||
### UI - Membership Fee Types Admin
|
||||
|
||||
**AC-UI-CTA-1:** List all membership fee types
|
||||
**AC-UI-CTA-2:** Show: Name, Amount, Interval, Member count
|
||||
**AC-UI-CTA-3:** Create new membership fee type form
|
||||
**AC-UI-CTA-4:** Edit form: Name, Amount, Description editable
|
||||
**AC-UI-CTA-5:** Edit form: Interval grayed out (not editable)
|
||||
**AC-UI-CTA-6:** Warning on amount change (explain impact)
|
||||
**AC-UI-CTA-7:** Cannot delete if members assigned
|
||||
**AC-UI-CTA-8:** Only admin can access
|
||||
|
||||
### UI - Settings Admin
|
||||
|
||||
**AC-UI-SA-1:** Membership fees section in settings
|
||||
**AC-UI-SA-2:** Dropdown to select default membership fee type
|
||||
**AC-UI-SA-3:** Checkbox: Include joining cycle
|
||||
**AC-UI-SA-4:** Explanatory text with examples
|
||||
**AC-UI-SA-5:** Save button with validation
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Testing
|
||||
|
||||
**Cycle Generator Tests:**
|
||||
|
||||
- Correct cycle_start calculation for all interval types
|
||||
- Correct cycle count from start to end date
|
||||
- Respects membership_fee_start_date boundary
|
||||
- Respects exit_date boundary
|
||||
- Skips existing cycles (idempotent)
|
||||
- Does not fill gaps when cycles were deleted
|
||||
- Handles edge dates (year boundaries, leap years)
|
||||
|
||||
**Calendar Cycles Tests:**
|
||||
|
||||
- Cycle boundaries correct for all intervals
|
||||
- cycle_end calculation correct
|
||||
- Current cycle detection
|
||||
- Last completed cycle detection
|
||||
- Next cycle calculation
|
||||
|
||||
**Validation Tests:**
|
||||
|
||||
- Interval immutability enforced
|
||||
- Same interval validation on type change
|
||||
- Status transitions allowed
|
||||
- Uniqueness constraints enforced
|
||||
|
||||
### Integration Testing
|
||||
|
||||
**Cycle Generation Flow:**
|
||||
|
||||
- Member creation triggers generation
|
||||
- Type assignment triggers generation
|
||||
- Type change regenerates future cycles
|
||||
- Scheduled job generates missing cycles
|
||||
- Left member stops generation
|
||||
|
||||
**Status Management Flow:**
|
||||
|
||||
- Mark single cycle as paid
|
||||
- Bulk mark multiple cycles (low prio)
|
||||
- Status transitions work
|
||||
- Permissions enforced
|
||||
|
||||
**Membership Fee Type Management:**
|
||||
|
||||
- Create type
|
||||
- Update amount (regeneration triggered)
|
||||
- Cannot update interval
|
||||
- Cannot delete if in use
|
||||
|
||||
### LiveView Testing
|
||||
|
||||
**Member List:**
|
||||
|
||||
- Status column displays correctly
|
||||
- Toggle between last/current works
|
||||
- Filters work correctly
|
||||
- Color coding applied
|
||||
|
||||
**Member Detail:**
|
||||
|
||||
- Cycles table displays all cycles
|
||||
- Checkboxes work
|
||||
- Bulk marking works (low prio)
|
||||
- Membership fee type change validation works
|
||||
- Actions only shown with permission
|
||||
|
||||
**Admin UI:**
|
||||
|
||||
- Type CRUD works
|
||||
- Settings save correctly
|
||||
- Validations display errors
|
||||
- Only authorized users can access
|
||||
|
||||
### Edge Case Testing
|
||||
|
||||
**Interval Change Attempt:**
|
||||
|
||||
- Error message displayed
|
||||
- No data modified
|
||||
- User can cancel/choose different type
|
||||
|
||||
**Exit with Unpaid:**
|
||||
|
||||
- Warning shown
|
||||
- Option to suspend offered
|
||||
- Exit completes correctly
|
||||
|
||||
**Amount Change:**
|
||||
|
||||
- Warning displayed
|
||||
- Only future unpaid regenerated
|
||||
- Historical cycles unchanged
|
||||
|
||||
**Date Boundaries:**
|
||||
|
||||
- Today = cycle start handled
|
||||
- Today = cycle end handled
|
||||
- Leap year handled
|
||||
|
||||
### Performance Testing
|
||||
|
||||
**Cycle Generation:**
|
||||
|
||||
- Generate 10 years of monthly cycles: < 100ms
|
||||
- Generate for 1000 members: < 5 seconds
|
||||
- Idempotent check efficient (no full scan)
|
||||
|
||||
**Member List Query:**
|
||||
|
||||
- With status column: < 200ms for 1000 members
|
||||
- Filters applied efficiently
|
||||
- No N+1 queries
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Authorization
|
||||
|
||||
**Permissions Required:**
|
||||
|
||||
- Membership fee type management: Admin only
|
||||
- Membership fee cycle status changes: Admin + Treasurer
|
||||
- View all cycles: Admin + Treasurer + Board
|
||||
- View own cycles: All authenticated users
|
||||
|
||||
**Policy Enforcement:**
|
||||
|
||||
- All actions protected by Ash policies
|
||||
- UI shows/hides based on permissions
|
||||
- Backend validates permissions (never trust UI alone)
|
||||
|
||||
### Data Integrity
|
||||
|
||||
**Validation Layers:**
|
||||
|
||||
1. Database constraints (NOT NULL, UNIQUE, CHECK)
|
||||
2. Ash validations (business rules)
|
||||
3. UI validations (user experience)
|
||||
|
||||
**Immutability Protection:**
|
||||
|
||||
- Interval change prevented at multiple layers
|
||||
- Cycle amounts immutable (audit trail)
|
||||
- Settings changes logged (future)
|
||||
|
||||
### Audit Trail
|
||||
|
||||
**Tracked Information:**
|
||||
|
||||
- Cycle status changes (who, when) - future enhancement
|
||||
- Membership fee type amount changes (implicit via cycle amounts)
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Database Indexes
|
||||
|
||||
**Required Indexes:**
|
||||
|
||||
- `membership_fee_cycles(member_id)` - For member cycle lookups
|
||||
- `membership_fee_cycles(membership_fee_type_id)` - For type queries
|
||||
- `membership_fee_cycles(status)` - For unpaid filters
|
||||
- `membership_fee_cycles(cycle_start)` - For date range queries
|
||||
- `membership_fee_cycles(member_id, cycle_start)` - Composite unique index
|
||||
- `members(membership_fee_type_id)` - For type membership count
|
||||
|
||||
### Query Optimization
|
||||
|
||||
**Preloading:**
|
||||
|
||||
- Load membership_fee_type with cycles (avoid N+1)
|
||||
- Load cycles when displaying member detail
|
||||
- Use Ash's load for efficient preloading
|
||||
|
||||
**Calculated Fields:**
|
||||
|
||||
- cycle_end calculated on-demand (not stored)
|
||||
- current_cycle_status calculated when needed
|
||||
- Use Ash calculations for lazy evaluation
|
||||
|
||||
**Pagination:**
|
||||
|
||||
- Cycle list paginated if > 50 cycles
|
||||
- Member list already paginated
|
||||
|
||||
### Caching Strategy
|
||||
|
||||
**No caching needed in MVP:**
|
||||
|
||||
- Membership fee types rarely change
|
||||
- Cycle queries are fast
|
||||
- Settings read infrequently
|
||||
|
||||
**Future caching if needed:**
|
||||
|
||||
- Cache settings in application memory
|
||||
- Cache membership fee types list
|
||||
- Invalidate on change
|
||||
|
||||
### Scheduled Job Performance
|
||||
|
||||
**Cycle Generation Job:**
|
||||
|
||||
- Run daily or weekly (not hourly)
|
||||
- Batch members (process 100 at a time)
|
||||
- Skip members with no changes
|
||||
- Log failures for retry
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Phase 2: Interval Change Support
|
||||
|
||||
**Architecture Changes:**
|
||||
|
||||
- Add logic to handle cycle overlaps
|
||||
- Calculate prorata amounts if needed
|
||||
- More complex validation
|
||||
- Migration path for existing cycles
|
||||
|
||||
### Phase 3: Payment Details
|
||||
|
||||
**Architecture Changes:**
|
||||
|
||||
- Add PaymentTransaction resource
|
||||
- Link transactions to cycles
|
||||
- Support multiple payments per cycle
|
||||
- Reconciliation logic
|
||||
|
||||
### Phase 4: vereinfacht.digital Integration
|
||||
|
||||
**Architecture Changes:**
|
||||
|
||||
- External API client module
|
||||
- Webhook handling for transactions
|
||||
- Automatic matching logic
|
||||
- Manual review interface
|
||||
|
||||
---
|
||||
|
||||
**End of Architecture Document**
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
# Membership Contributions - Overview
|
||||
# Membership Fees - Overview
|
||||
|
||||
**Project:** Mila - Membership Management System
|
||||
**Feature:** Membership Contribution Management
|
||||
**Feature:** Membership Fee Management
|
||||
**Version:** 1.0
|
||||
**Last Updated:** 2025-11-27
|
||||
**Status:** Concept - Ready for Review
|
||||
|
|
@ -10,9 +10,9 @@
|
|||
|
||||
## Purpose
|
||||
|
||||
This document provides a comprehensive overview of the Membership Contributions system. It covers business logic, data model, UI/UX design, and technical architecture in a concise, bullet-point format.
|
||||
This document provides a comprehensive overview of the Membership Fees system. It covers business logic, data model, UI/UX design, and technical architecture in a concise, bullet-point format.
|
||||
|
||||
**For detailed implementation:** See [contributions-implementation-plan.md](./contributions-implementation-plan.md) (created after concept iterations)
|
||||
**For detailed implementation:** See [membership-fee-implementation-plan.md](./membership-fee-implementation-plan.md) (created after concept iterations)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -36,7 +36,7 @@ This document provides a comprehensive overview of the Membership Contributions
|
|||
- Minimal complexity
|
||||
- Clear data model without redundancies
|
||||
- Intuitive operation
|
||||
- Calendar period-based (Month/Quarter/Half-Year/Year)
|
||||
- Calendar cycle-based (Month/Quarter/Half-Year/Year)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -46,9 +46,9 @@ This document provides a comprehensive overview of the Membership Contributions
|
|||
|
||||
**Core Entities:**
|
||||
|
||||
- Beitragsart ↔ Contribution Type / Membership Fee Type
|
||||
- Beitragsintervall ↔ Contribution Period
|
||||
- Mitgliedsbeitrag ↔ Membership Fee / Contribution
|
||||
- Beitragsart ↔ Membership Fee Type
|
||||
- Beitragszyklus ↔ Membership Fee Cycle
|
||||
- Mitgliedsbeitrag ↔ Membership Fee
|
||||
|
||||
**Status:**
|
||||
|
||||
|
|
@ -56,7 +56,7 @@ This document provides a comprehensive overview of the Membership Contributions
|
|||
- unbezahlt ↔ unpaid
|
||||
- ausgesetzt ↔ suspended / waived
|
||||
|
||||
**Intervals:**
|
||||
**Intervals (Frequenz / Payment Frequency):**
|
||||
|
||||
- monatlich ↔ monthly
|
||||
- quartalsweise ↔ quarterly
|
||||
|
|
@ -65,8 +65,8 @@ This document provides a comprehensive overview of the Membership Contributions
|
|||
|
||||
**UI Elements:**
|
||||
|
||||
- "Letztes Intervall" ↔ "Last Period" (e.g., 2023 when in 2024)
|
||||
- "Aktuelles Intervall" ↔ "Current Period" (e.g., 2024)
|
||||
- "Letzter Zyklus" ↔ "Last Cycle" (e.g., 2023 when in 2024)
|
||||
- "Aktueller Zyklus" ↔ "Current Cycle" (e.g., 2024)
|
||||
- "Als bezahlt markieren" ↔ "Mark as paid"
|
||||
- "Aussetzen" ↔ "Suspend" / "Waive"
|
||||
|
||||
|
|
@ -74,43 +74,41 @@ This document provides a comprehensive overview of the Membership Contributions
|
|||
|
||||
## Data Model
|
||||
|
||||
### Contribution Type (ContributionType)
|
||||
### Membership Fee Type (MembershipFeeType)
|
||||
|
||||
```
|
||||
- id (UUID)
|
||||
- name (String) - e.g., "Regular", "Reduced", "Student"
|
||||
- amount (Decimal) - Contribution amount in Euro
|
||||
- amount (Decimal) - Membership fee amount in Euro
|
||||
- interval (Enum) - :monthly, :quarterly, :half_yearly, :yearly
|
||||
- description (Text, optional)
|
||||
- timestamps
|
||||
```
|
||||
|
||||
**Important:**
|
||||
|
||||
- `interval` is **IMMUTABLE** after creation!
|
||||
- Admin can only change `name`, `amount`, `description`
|
||||
- On change: Future unpaid periods regenerated with new amount
|
||||
- On change: Future unpaid cycles regenerated with new amount
|
||||
|
||||
### Contribution Period (ContributionPeriod)
|
||||
### Membership Fee Cycle (MembershipFeeCycle)
|
||||
|
||||
```
|
||||
- id (UUID)
|
||||
- member_id (FK → members.id)
|
||||
- contribution_type_id (FK → contribution_types.id)
|
||||
- period_start (Date) - Calendar period start (01.01., 01.04., 01.07., 01.10., etc.)
|
||||
- membership_fee_type_id (FK → membership_fee_types.id)
|
||||
- cycle_start (Date) - Calendar cycle start (01.01., 01.04., 01.07., 01.10., etc.)
|
||||
- status (Enum) - :unpaid (default), :paid, :suspended
|
||||
- amount (Decimal) - Amount at generation time (history when type changes)
|
||||
- amount (Decimal) - Membership fee amount at generation time (history when type changes)
|
||||
- notes (Text, optional) - Admin notes
|
||||
- timestamps
|
||||
```
|
||||
|
||||
**Important:**
|
||||
|
||||
- **NO** `period_end` - calculated from `period_start` + `interval`
|
||||
- **NO** `interval_type` - read from `contribution_type.interval`
|
||||
- **NO** `cycle_end` - calculated from `cycle_start` + `interval`
|
||||
- **NO** `interval_type` - read from `membership_fee_type.interval`
|
||||
- Avoids redundancy and inconsistencies!
|
||||
|
||||
**Calendar Period Logic:**
|
||||
**Calendar Cycle Logic:**
|
||||
|
||||
- Monthly: 01.01. - 31.01., 01.02. - 28./29.02., etc.
|
||||
- Quarterly: 01.01. - 31.03., 01.04. - 30.06., 01.07. - 30.09., 01.10. - 31.12.
|
||||
|
|
@ -120,70 +118,76 @@ This document provides a comprehensive overview of the Membership Contributions
|
|||
### Member (Extensions)
|
||||
|
||||
```
|
||||
- contribution_type_id (FK → contribution_types.id, NOT NULL, default from settings)
|
||||
- contribution_start_date (Date, nullable) - When to start generating contributions
|
||||
- left_at (Date, nullable) - Exit date (existing)
|
||||
- membership_fee_type_id (FK → membership_fee_types.id, NOT NULL, default from settings)
|
||||
- membership_fee_start_date (Date, nullable) - When to start generating membership fees
|
||||
- exit_date (Date, nullable) - Exit date (existing)
|
||||
```
|
||||
|
||||
**Logic for contribution_start_date:**
|
||||
**Logic for membership_fee_start_date:**
|
||||
|
||||
- Auto-set based on global setting `include_joining_period`
|
||||
- If `include_joining_period = true`: First day of joining month/quarter/year
|
||||
- If `include_joining_period = false`: First day of NEXT period after joining
|
||||
- Auto-set based on global setting `include_joining_cycle`
|
||||
- If `include_joining_cycle = true`: First day of joining month/quarter/year
|
||||
- If `include_joining_cycle = false`: First day of NEXT cycle after joining
|
||||
- Can be manually overridden by admin
|
||||
|
||||
**NO** `include_joining_period` field on Member - unnecessary due to `contribution_start_date`!
|
||||
**NO** `include_joining_cycle` field on Member - unnecessary due to `membership_fee_start_date`!
|
||||
|
||||
### Global Settings
|
||||
|
||||
```
|
||||
key: "contributions.include_joining_period"
|
||||
key: "membership_fees.include_joining_cycle"
|
||||
value: Boolean (Default: true)
|
||||
|
||||
key: "contributions.default_contribution_type_id"
|
||||
value: UUID (Required) - Default contribution type for new members
|
||||
key: "membership_fees.default_membership_fee_type_id"
|
||||
value: UUID (Required) - Default membership fee type for new members
|
||||
```
|
||||
|
||||
**Meaning include_joining_period:**
|
||||
**Meaning include_joining_cycle:**
|
||||
|
||||
- `true`: Joining period is included (member pays from joining period)
|
||||
- `false`: Only from next full period after joining
|
||||
- `true`: Joining cycle is included (member pays from joining cycle)
|
||||
- `false`: Only from next full cycle after joining
|
||||
|
||||
**Meaning default_contribution_type_id:**
|
||||
**Meaning of default membership fee type setting:**
|
||||
|
||||
- Every new member automatically gets this contribution type
|
||||
- Every new member automatically gets this membership fee type
|
||||
- Must be configured in admin settings
|
||||
- Prevents: Members without contribution type
|
||||
- Prevents: Members without membership fee type
|
||||
|
||||
---
|
||||
|
||||
## Business Logic
|
||||
|
||||
### Period Generation
|
||||
### Cycle Generation
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- Member gets contribution type assigned (also during member creation)
|
||||
- New period begins (Cron job daily/weekly)
|
||||
- Member gets membership fee type assigned (also during member creation)
|
||||
- New cycle begins (Cron job daily/weekly)
|
||||
- Admin requests manual regeneration
|
||||
|
||||
**Algorithm:**
|
||||
|
||||
1. Get `member.contribution_start_date` and `member.contribution_type`
|
||||
2. Calculate first period based on `contribution_start_date`
|
||||
3. Generate all periods from start to today (or `left_at` if present)
|
||||
4. Skip existing periods
|
||||
5. Set `amount` to current `contribution_type.amount`
|
||||
Use PostgreSQL advisory locks per member to prevent race conditions
|
||||
|
||||
1. Get `member.membership_fee_start_date` and member's membership fee type
|
||||
2. Determine generation start point:
|
||||
- If NO cycles exist: Start from `membership_fee_start_date`
|
||||
- If cycles exist: Start from the cycle AFTER the last existing one
|
||||
3. Generate cycles until today (or `exit_date` if present):
|
||||
- Use the interval to generate the cycles
|
||||
- **Note:** If cycles were explicitly deleted (gaps exist), they are NOT recreated.
|
||||
The generator always continues from the cycle AFTER the last existing cycle.
|
||||
4. Set `amount` to current membership fee type's amount
|
||||
|
||||
**Example (Yearly):**
|
||||
|
||||
```
|
||||
Joining date: 15.03.2023
|
||||
include_joining_period: true
|
||||
→ contribution_start_date: 01.01.2023
|
||||
include_joining_cycle: true
|
||||
→ membership_fee_start_date: 01.01.2023
|
||||
|
||||
Generated periods:
|
||||
- 01.01.2023 - 31.12.2023 (joining period)
|
||||
Generated cycles:
|
||||
- 01.01.2023 - 31.12.2023 (joining cycle)
|
||||
- 01.01.2024 - 31.12.2024
|
||||
- 01.01.2025 - 31.12.2025 (current year)
|
||||
```
|
||||
|
|
@ -192,10 +196,10 @@ Generated periods:
|
|||
|
||||
```
|
||||
Joining date: 15.03.2023
|
||||
include_joining_period: false
|
||||
→ contribution_start_date: 01.04.2023
|
||||
include_joining_cycle: false
|
||||
→ membership_fee_start_date: 01.04.2023
|
||||
|
||||
Generated periods:
|
||||
Generated cycles:
|
||||
- 01.04.2023 - 30.06.2023 (first full quarter)
|
||||
- 01.07.2023 - 30.09.2023
|
||||
- 01.10.2023 - 31.12.2023
|
||||
|
|
@ -218,44 +222,44 @@ suspended → unpaid
|
|||
- Admin + Treasurer (Kassenwart) can change status
|
||||
- Uses existing permission system
|
||||
|
||||
### Contribution Type Change
|
||||
### Membership Fee Type Change
|
||||
|
||||
**MVP - Same Interval Only:**
|
||||
**MVP - Same Cycle Only:**
|
||||
|
||||
- Member can only choose contribution type with **same interval**
|
||||
- Member can only choose membership fee type with **same cycle**
|
||||
- Example: From "Regular (yearly)" to "Reduced (yearly)" ✓
|
||||
- Example: From "Regular (yearly)" to "Reduced (monthly)" ✗
|
||||
|
||||
**Logic on Change:**
|
||||
|
||||
1. Check: New contribution type has same interval
|
||||
2. If yes: Set `member.contribution_type_id`
|
||||
3. Future **unpaid** periods: Delete and regenerate with new amount
|
||||
4. Paid/suspended periods: Remain unchanged (historical amount)
|
||||
1. Check: New membership fee type has same interval
|
||||
2. If yes: Set `member.membership_fee_type_id`
|
||||
3. Future **unpaid** cycles: Delete and regenerate with new amount
|
||||
4. Paid/suspended cycles: Remain unchanged (historical amount)
|
||||
|
||||
**Future - Different Intervals:**
|
||||
|
||||
- Enable interval switching (e.g., yearly → monthly)
|
||||
- More complex logic for period overlaps
|
||||
- More complex logic for cycle overlaps
|
||||
- Needs additional validation
|
||||
|
||||
### Member Exit
|
||||
|
||||
**Logic:**
|
||||
|
||||
- Periods only generated until `member.left_at`
|
||||
- Existing periods remain visible
|
||||
- Unpaid exit period can be marked as "suspended"
|
||||
- Cycles only generated until `member.exit_date`
|
||||
- Existing cycles remain visible
|
||||
- Unpaid exit cycle can be marked as "suspended"
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
Exit: 15.08.2024
|
||||
Yearly period: 01.01.2024 - 31.12.2024
|
||||
Yearly cycle: 01.01.2024 - 31.12.2024
|
||||
|
||||
→ Period 2024 is shown (Status: unpaid)
|
||||
→ Cycle 2024 is shown (Status: unpaid)
|
||||
→ Admin can set to "suspended"
|
||||
→ No periods for 2025+ generated
|
||||
→ No cycles for 2025+ generated
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -264,46 +268,46 @@ Yearly period: 01.01.2024 - 31.12.2024
|
|||
|
||||
### Member List View
|
||||
|
||||
**New Column: "Contribution Status"**
|
||||
**New Column: "Membership Fee Status"**
|
||||
|
||||
**Default Display (Last Period):**
|
||||
**Default Display (Last Cycle):**
|
||||
|
||||
- Shows status of **last completed** period
|
||||
- Example in 2024: Shows contribution for 2023
|
||||
- Shows status of **last completed** cycle
|
||||
- Example in 2024: Shows membership fee for 2023
|
||||
- Color coding:
|
||||
- Green: paid ✓
|
||||
- Red: unpaid ✗
|
||||
- Gray: suspended ⊘
|
||||
|
||||
**Optional: Show Current Period**
|
||||
**Optional: Show Current Cycle**
|
||||
|
||||
- Toggle: "Show current period" (2024)
|
||||
- Toggle: "Show current cycle" (2024)
|
||||
- Admin decides what to display
|
||||
|
||||
**Filters:**
|
||||
|
||||
- "Unpaid contributions in last period"
|
||||
- "Unpaid contributions in current period"
|
||||
- "Unpaid membership fees in last cycle"
|
||||
- "Unpaid membership fees in current cycle"
|
||||
|
||||
### Member Detail View
|
||||
|
||||
**Section: "Contributions"**
|
||||
**Section: "Membership Fees"**
|
||||
|
||||
**Contribution Type Assignment:**
|
||||
**Membership Fee Type Assignment:**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Contribution Type: [Dropdown] │
|
||||
│ ⚠ Only types with same interval │
|
||||
│ can be selected │
|
||||
│ Membership Fee Type: [Dropdown] │
|
||||
│ ⚠ Only types with same interval │
|
||||
│ can be selected │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Period Table:**
|
||||
**Cycle Table:**
|
||||
|
||||
```
|
||||
┌───────────────┬──────────┬────────┬──────────┬─────────┐
|
||||
│ Period │ Interval │ Amount │ Status │ Action │
|
||||
│ Cycle │ Interval │ Amount │ Status │ Action │
|
||||
├───────────────┼──────────┼────────┼──────────┼─────────┤
|
||||
│ 01.01.2023- │ Yearly │ 50 € │ ☑ Paid │ │
|
||||
│ 31.12.2023 │ │ │ │ │
|
||||
|
|
@ -322,9 +326,9 @@ Legend: ☑ = paid | ☐ = unpaid | ⊘ = suspended
|
|||
|
||||
- Checkbox in each row for fast marking
|
||||
- Button: "Mark selected as paid/unpaid/suspended"
|
||||
- Bulk action for multiple periods
|
||||
- Bulk action for multiple cycles
|
||||
|
||||
### Admin: Contribution Types Management
|
||||
### Admin: Membership Fee Types Management
|
||||
|
||||
**List:**
|
||||
|
||||
|
|
@ -352,37 +356,37 @@ Legend: ☑ = paid | ☐ = unpaid | ⊘ = suspended
|
|||
|
||||
Impact:
|
||||
- 45 members affected
|
||||
- Future unpaid periods will be generated with 65 €
|
||||
- Already paid periods remain with old amount
|
||||
- Future unpaid cycles will be generated with 65 €
|
||||
- Already paid cycles remain with old amount
|
||||
|
||||
[Cancel] [Confirm]
|
||||
```
|
||||
|
||||
### Admin: Settings
|
||||
|
||||
**Contribution Configuration:**
|
||||
**Membership Fee Configuration:**
|
||||
|
||||
```
|
||||
Default Contribution Type: [Dropdown: Contribution Types]
|
||||
Default Membership Fee Type: [Dropdown: Membership Fee Types]
|
||||
|
||||
Selected: "Regular (60 €, Yearly)"
|
||||
|
||||
This contribution type is automatically assigned to all new members.
|
||||
This membership fee type is automatically assigned to all new members.
|
||||
Can be changed individually per member.
|
||||
|
||||
---
|
||||
|
||||
☐ Include joining period
|
||||
☐ Include joining cycle
|
||||
|
||||
When active:
|
||||
Members pay from the period of their joining.
|
||||
Members pay from the cycle of their joining.
|
||||
|
||||
Example (Yearly):
|
||||
Joining: 15.03.2023
|
||||
→ Pays from 2023
|
||||
|
||||
When inactive:
|
||||
Members pay from the next full period.
|
||||
Members pay from the next full cycle.
|
||||
|
||||
Example (Yearly):
|
||||
Joining: 15.03.2023
|
||||
|
|
@ -393,7 +397,7 @@ Joining: 15.03.2023
|
|||
|
||||
## Edge Cases
|
||||
|
||||
### 1. Contribution Type Change with Different Interval
|
||||
### 1. Membership Fee Type Change with Different Interval
|
||||
|
||||
**MVP:** Blocked (only same interval allowed)
|
||||
|
||||
|
|
@ -402,11 +406,11 @@ Joining: 15.03.2023
|
|||
```
|
||||
Error: Interval change not possible
|
||||
|
||||
Current contribution type: "Regular (Yearly)"
|
||||
Selected contribution type: "Student (Monthly)"
|
||||
Current membership fee type: "Regular (Yearly)"
|
||||
Selected membership fee type: "Student (Monthly)"
|
||||
|
||||
Changing the interval is currently not possible.
|
||||
Please select a contribution type with interval "Yearly".
|
||||
Please select a membership fee type with interval "Yearly".
|
||||
|
||||
[OK]
|
||||
```
|
||||
|
|
@ -415,32 +419,32 @@ Please select a contribution type with interval "Yearly".
|
|||
|
||||
- Allow interval switching
|
||||
- Calculate overlaps
|
||||
- Generate new periods without duplicates
|
||||
- Generate new cycles without duplicates
|
||||
|
||||
### 2. Exit with Unpaid Contributions
|
||||
### 2. Exit with Unpaid Membership Fees
|
||||
|
||||
**Scenario:**
|
||||
|
||||
```
|
||||
Member exits: 15.08.2024
|
||||
Yearly period 2024: unpaid
|
||||
Yearly cycle 2024: unpaid
|
||||
```
|
||||
|
||||
**UI Notice on Exit: (Low Prio)**
|
||||
|
||||
```
|
||||
⚠ Unpaid contributions present
|
||||
⚠ Unpaid membership fees present
|
||||
|
||||
This member has 1 unpaid period(s):
|
||||
This member has 1 unpaid cycle(s):
|
||||
- 2024: 60 € (unpaid)
|
||||
|
||||
Do you want to continue?
|
||||
|
||||
[ ] Mark contribution as "suspended"
|
||||
[ ] Mark membership fee as "suspended"
|
||||
[Cancel] [Confirm Exit]
|
||||
```
|
||||
|
||||
### 3. Multiple Unpaid Periods
|
||||
### 3. Multiple Unpaid Cycles
|
||||
|
||||
**Scenario:** Member hasn't paid for 2 years
|
||||
|
||||
|
|
@ -467,9 +471,9 @@ Do you want to continue?
|
|||
|
||||
**Result:**
|
||||
|
||||
- Period 2023: Saved with 50 € (history)
|
||||
- Period 2024: Generated with 60 € (current)
|
||||
- Both periods show correct historical amount
|
||||
- Cycle 2023: Saved with 50 € (history)
|
||||
- Cycle 2024: Generated with 60 € (current)
|
||||
- Both cycles show correct historical amount
|
||||
|
||||
### 5. Date Boundaries
|
||||
|
||||
|
|
@ -477,7 +481,7 @@ Do you want to continue?
|
|||
|
||||
**Solution:**
|
||||
|
||||
- Current period (2025) is generated
|
||||
- Current cycle (2025) is generated
|
||||
- Status: unpaid (open)
|
||||
- Shown in overview
|
||||
|
||||
|
|
@ -489,17 +493,17 @@ Do you want to continue?
|
|||
|
||||
**Included:**
|
||||
|
||||
- ✓ Contribution types (CRUD)
|
||||
- ✓ Automatic period generation
|
||||
- ✓ Membership fee types (CRUD)
|
||||
- ✓ Automatic cycle generation
|
||||
- ✓ Status management (paid/unpaid/suspended)
|
||||
- ✓ Member overview with contribution status
|
||||
- ✓ Period view per member
|
||||
- ✓ Member overview with membership fee status
|
||||
- ✓ Cycle view per member
|
||||
- ✓ Quick checkbox marking
|
||||
- ✓ Bulk actions
|
||||
- ✓ Amount history
|
||||
- ✓ Same-interval type change
|
||||
- ✓ Default contribution type
|
||||
- ✓ Joining period configuration
|
||||
- ✓ Default membership fee type
|
||||
- ✓ Joining cycle configuration
|
||||
|
||||
**NOT Included:**
|
||||
|
||||
|
|
@ -515,7 +519,7 @@ Do you want to continue?
|
|||
**Phase 2:**
|
||||
|
||||
- Payment details (date, amount, method)
|
||||
- Interval change for future unpaid periods
|
||||
- Interval change for future unpaid cycles
|
||||
- Manual vereinfacht.digital links per member
|
||||
- Extended filter options
|
||||
|
||||
137
docs/test-status-membership-fee-ui.md
Normal file
137
docs/test-status-membership-fee-ui.md
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
# Test Status: Membership Fee UI Components
|
||||
|
||||
**Date:** 2025-01-XX
|
||||
**Status:** Tests Written - Implementation Complete
|
||||
|
||||
## Übersicht
|
||||
|
||||
Alle Tests für die Membership Fee UI-Komponenten wurden geschrieben. Die Tests sind TDD-konform geschrieben und sollten erfolgreich laufen, da die Implementation bereits vorhanden ist.
|
||||
|
||||
## Test-Dateien
|
||||
|
||||
### Helper Module Tests
|
||||
|
||||
**Datei:** `test/mv_web/helpers/membership_fee_helpers_test.exs`
|
||||
- ✅ format_currency/1 formats correctly
|
||||
- ✅ format_interval/1 formats all interval types
|
||||
- ✅ format_cycle_range/2 formats date ranges correctly
|
||||
- ✅ get_last_completed_cycle/2 returns correct cycle
|
||||
- ✅ get_current_cycle/2 returns correct cycle
|
||||
- ✅ status_color/1 returns correct color classes
|
||||
- ✅ status_icon/1 returns correct icon names
|
||||
|
||||
**Status:** Alle Tests sollten erfolgreich sein (Implementation vorhanden)
|
||||
|
||||
**Datei:** `test/mv_web/member_live/index/membership_fee_status_test.exs`
|
||||
- ✅ load_cycles_for_members/2 efficiently loads cycles
|
||||
- ✅ get_cycle_status_for_member/2 returns correct status
|
||||
- ✅ format_cycle_status_badge/1 returns correct badge
|
||||
|
||||
**Status:** Alle Tests sollten erfolgreich sein (Implementation vorhanden)
|
||||
|
||||
### Member List View Tests
|
||||
|
||||
**Datei:** `test/mv_web/member_live/index_membership_fee_status_test.exs`
|
||||
- ✅ Status column displays correctly
|
||||
- ✅ Shows last completed cycle status by default
|
||||
- ✅ Toggle switches to current cycle view
|
||||
- ✅ Color coding for paid/unpaid/suspended
|
||||
- ✅ Filter "Unpaid in last cycle" works
|
||||
- ✅ Filter "Unpaid in current cycle" works
|
||||
- ✅ Handles members without cycles gracefully
|
||||
- ✅ Loads cycles efficiently without N+1 queries
|
||||
|
||||
**Status:** Alle Tests sollten erfolgreich sein (Implementation vorhanden)
|
||||
|
||||
### Member Detail View Tests
|
||||
|
||||
**Datei:** `test/mv_web/member_live/show_membership_fees_test.exs`
|
||||
- ✅ Cycles table displays all cycles
|
||||
- ✅ Table columns show correct data
|
||||
- ✅ Membership fee type dropdown shows only same-interval types
|
||||
- ✅ Warning displayed if different interval selected
|
||||
- ✅ Status change actions work (mark as paid/suspended/unpaid)
|
||||
- ✅ Cycle regeneration works
|
||||
- ✅ Handles members without membership fee type gracefully
|
||||
|
||||
**Status:** Alle Tests sollten erfolgreich sein (Implementation vorhanden)
|
||||
|
||||
### Membership Fee Types Admin Tests
|
||||
|
||||
**Datei:** `test/mv_web/live/membership_fee_type_live/index_test.exs`
|
||||
- ✅ List displays all types with correct data
|
||||
- ✅ Member count column shows correct count
|
||||
- ✅ Create button navigates to form
|
||||
- ✅ Edit button per row navigates to edit form
|
||||
- ✅ Delete button disabled if type is in use
|
||||
- ✅ Delete button works if type is not in use
|
||||
- ✅ Only admin can access
|
||||
|
||||
**Status:** Alle Tests sollten erfolgreich sein (Implementation vorhanden)
|
||||
|
||||
**Datei:** `test/mv_web/live/membership_fee_type_live/form_test.exs`
|
||||
- ✅ Create form works
|
||||
- ✅ Edit form loads existing type data
|
||||
- ✅ Interval field editable on create
|
||||
- ✅ Interval field grayed out on edit
|
||||
- ✅ Amount change warning displays on edit
|
||||
- ✅ Amount change warning shows correct affected member count
|
||||
- ✅ Amount change can be confirmed
|
||||
- ✅ Amount change can be cancelled
|
||||
- ✅ Validation errors display correctly
|
||||
- ✅ Only admin can access
|
||||
|
||||
**Status:** Alle Tests sollten erfolgreich sein (Implementation vorhanden)
|
||||
|
||||
### Member Form Tests
|
||||
|
||||
**Datei:** `test/mv_web/member_live/form_membership_fee_type_test.exs`
|
||||
- ✅ Membership fee type dropdown displays in form
|
||||
- ✅ Shows available types
|
||||
- ✅ Filters to same interval types if member has type
|
||||
- ✅ Warning displayed if different interval selected
|
||||
- ✅ Warning cleared if same interval selected
|
||||
- ✅ Form saves with selected membership fee type
|
||||
- ✅ New members get default membership fee type
|
||||
|
||||
**Status:** Alle Tests sollten erfolgreich sein (Implementation vorhanden)
|
||||
|
||||
### Integration Tests
|
||||
|
||||
**Datei:** `test/mv_web/member_live/membership_fee_integration_test.exs`
|
||||
- ✅ End-to-end: Create type → Assign to member → View cycles → Change status
|
||||
- ✅ End-to-end: Change member type → Cycles regenerate
|
||||
- ✅ End-to-end: Update settings → New members get default type
|
||||
- ✅ End-to-end: Delete cycle → Confirmation → Cycle deleted
|
||||
- ✅ End-to-end: Edit cycle amount → Modal → Amount updated
|
||||
|
||||
**Status:** Alle Tests sollten erfolgreich sein (Implementation vorhanden)
|
||||
|
||||
## Test-Ausführung
|
||||
|
||||
Alle Tests können mit folgenden Befehlen ausgeführt werden:
|
||||
|
||||
```bash
|
||||
# Alle Tests
|
||||
mix test
|
||||
|
||||
# Nur Membership Fee Tests
|
||||
mix test test/mv_web/helpers/membership_fee_helpers_test.exs
|
||||
mix test test/mv_web/member_live/
|
||||
mix test test/mv_web/live/membership_fee_type_live/
|
||||
|
||||
# Mit Coverage
|
||||
mix test --cover
|
||||
```
|
||||
|
||||
## Bekannte Probleme
|
||||
|
||||
Keine bekannten Probleme. Alle Tests sollten erfolgreich laufen, da die Implementation bereits vorhanden ist.
|
||||
|
||||
## Nächste Schritte
|
||||
|
||||
1. ✅ Tests geschrieben
|
||||
2. ⏳ Tests ausführen und verifizieren
|
||||
3. ⏳ Eventuelle Anpassungen basierend auf Test-Ergebnissen
|
||||
4. ⏳ Code-Review durchführen
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue