docs: payment concept
This commit is contained in:
parent
422cf37a1e
commit
a5aeef3e27
2 changed files with 1178 additions and 0 deletions
527
docs/contributions-overview.md
Normal file
527
docs/contributions-overview.md
Normal file
|
|
@ -0,0 +1,527 @@
|
|||
# Membership Contributions - Overview
|
||||
|
||||
**Project:** Mila - Membership Management System
|
||||
**Feature:** Membership Contribution Management
|
||||
**Version:** 1.0
|
||||
**Last Updated:** 2025-11-27
|
||||
**Status:** Concept - Ready for Review
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
**For detailed implementation:** See [contributions-implementation-plan.md](./contributions-implementation-plan.md) (created after concept iterations)
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Core Principle](#core-principle)
|
||||
2. [Terminology](#terminology)
|
||||
3. [Data Model](#data-model)
|
||||
4. [Business Logic](#business-logic)
|
||||
5. [UI/UX Design](#uiux-design)
|
||||
6. [Edge Cases](#edge-cases)
|
||||
7. [Technical Integration](#technical-integration)
|
||||
8. [Implementation Scope](#implementation-scope)
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Maximum Simplicity:**
|
||||
|
||||
- Minimal complexity
|
||||
- Clear data model without redundancies
|
||||
- Intuitive operation
|
||||
- Calendar period-based (Month/Quarter/Half-Year/Year)
|
||||
|
||||
---
|
||||
|
||||
## Terminology
|
||||
|
||||
### German ↔ English
|
||||
|
||||
**Core Entities:**
|
||||
|
||||
- Beitragsart ↔ Contribution Type / Membership Fee Type
|
||||
- Beitragsintervall ↔ Contribution Period
|
||||
- Mitgliedsbeitrag ↔ Membership Fee / Contribution
|
||||
|
||||
**Status:**
|
||||
|
||||
- bezahlt ↔ paid
|
||||
- unbezahlt ↔ unpaid
|
||||
- ausgesetzt ↔ suspended / waived
|
||||
|
||||
**Intervals:**
|
||||
|
||||
- monatlich ↔ monthly
|
||||
- quartalsweise ↔ quarterly
|
||||
- halbjährlich ↔ half-yearly / semi-annually
|
||||
- jährlich ↔ yearly / annually
|
||||
|
||||
**UI Elements:**
|
||||
|
||||
- "Letztes Intervall" ↔ "Last Period" (e.g., 2023 when in 2024)
|
||||
- "Aktuelles Intervall" ↔ "Current Period" (e.g., 2024)
|
||||
- "Als bezahlt markieren" ↔ "Mark as paid"
|
||||
- "Aussetzen" ↔ "Suspend" / "Waive"
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
### Contribution Type (ContributionType)
|
||||
|
||||
```
|
||||
- id (UUID)
|
||||
- name (String) - e.g., "Regular", "Reduced", "Student"
|
||||
- amount (Decimal) - Contribution 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
|
||||
|
||||
### Contribution Period (ContributionPeriod)
|
||||
|
||||
```
|
||||
- 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.)
|
||||
- status (Enum) - :unpaid (default), :paid, :suspended
|
||||
- amount (Decimal) - 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`
|
||||
- Avoids redundancy and inconsistencies!
|
||||
|
||||
**Calendar Period 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.
|
||||
- Half-yearly: 01.01. - 30.06., 01.07. - 31.12.
|
||||
- Yearly: 01.01. - 31.12.
|
||||
|
||||
### 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)
|
||||
```
|
||||
|
||||
**Logic for contribution_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
|
||||
- Can be manually overridden by admin
|
||||
|
||||
**NO** `include_joining_period` field on Member - unnecessary due to `contribution_start_date`!
|
||||
|
||||
### Global Settings
|
||||
|
||||
```
|
||||
key: "contributions.include_joining_period"
|
||||
value: Boolean (Default: true)
|
||||
|
||||
key: "contributions.default_contribution_type_id"
|
||||
value: UUID (Required) - Default contribution type for new members
|
||||
```
|
||||
|
||||
**Meaning include_joining_period:**
|
||||
|
||||
- `true`: Joining period is included (member pays from joining period)
|
||||
- `false`: Only from next full period after joining
|
||||
|
||||
**Meaning default_contribution_type_id:**
|
||||
|
||||
- Every new member automatically gets this contribution type
|
||||
- Must be configured in admin settings
|
||||
- Prevents: Members without contribution type
|
||||
|
||||
---
|
||||
|
||||
## Business Logic
|
||||
|
||||
### Period Generation
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- Member gets contribution type assigned (also during member creation)
|
||||
- New period 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`
|
||||
|
||||
**Example (Yearly):**
|
||||
|
||||
```
|
||||
Joining date: 15.03.2023
|
||||
include_joining_period: true
|
||||
→ contribution_start_date: 01.01.2023
|
||||
|
||||
Generated periods:
|
||||
- 01.01.2023 - 31.12.2023 (joining period)
|
||||
- 01.01.2024 - 31.12.2024
|
||||
- 01.01.2025 - 31.12.2025 (current year)
|
||||
```
|
||||
|
||||
**Example (Quarterly):**
|
||||
|
||||
```
|
||||
Joining date: 15.03.2023
|
||||
include_joining_period: false
|
||||
→ contribution_start_date: 01.04.2023
|
||||
|
||||
Generated periods:
|
||||
- 01.04.2023 - 30.06.2023 (first full quarter)
|
||||
- 01.07.2023 - 30.09.2023
|
||||
- 01.10.2023 - 31.12.2023
|
||||
- 01.01.2024 - 31.03.2024
|
||||
- ...
|
||||
```
|
||||
|
||||
### Status Transitions
|
||||
|
||||
```
|
||||
unpaid → paid
|
||||
unpaid → suspended
|
||||
paid → unpaid
|
||||
suspended → paid
|
||||
suspended → unpaid
|
||||
```
|
||||
|
||||
**Permissions:**
|
||||
|
||||
- Admin + Treasurer (Kassenwart) can change status
|
||||
- Uses existing permission system
|
||||
|
||||
### Contribution Type Change
|
||||
|
||||
**MVP - Same Interval Only:**
|
||||
|
||||
- Member can only choose contribution type with **same interval**
|
||||
- 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)
|
||||
|
||||
**Future - Different Intervals:**
|
||||
|
||||
- Enable interval switching (e.g., yearly → monthly)
|
||||
- More complex logic for period 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"
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
Exit: 15.08.2024
|
||||
Yearly period: 01.01.2024 - 31.12.2024
|
||||
|
||||
→ Period 2024 is shown (Status: unpaid)
|
||||
→ Admin can set to "suspended"
|
||||
→ No periods for 2025+ generated
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## UI/UX Design
|
||||
|
||||
### Member List View
|
||||
|
||||
**New Column: "Contribution Status"**
|
||||
|
||||
**Default Display (Last Period):**
|
||||
|
||||
- Shows status of **last completed** period
|
||||
- Example in 2024: Shows contribution for 2023
|
||||
- Color coding:
|
||||
- Green: paid ✓
|
||||
- Red: unpaid ✗
|
||||
- Gray: suspended ⊘
|
||||
|
||||
**Optional: Show Current Period**
|
||||
|
||||
- Toggle: "Show current period" (2024)
|
||||
- Admin decides what to display
|
||||
|
||||
**Filters:**
|
||||
|
||||
- "Unpaid contributions in last period"
|
||||
- "Unpaid contributions in current period"
|
||||
|
||||
### Member Detail View
|
||||
|
||||
**Section: "Contributions"**
|
||||
|
||||
**Contribution Type Assignment:**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Contribution Type: [Dropdown] │
|
||||
│ ⚠ Only types with same interval │
|
||||
│ can be selected │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Period Table:**
|
||||
|
||||
```
|
||||
┌───────────────┬──────────┬────────┬──────────┬─────────┐
|
||||
│ Period │ Interval │ Amount │ Status │ Action │
|
||||
├───────────────┼──────────┼────────┼──────────┼─────────┤
|
||||
│ 01.01.2023- │ Yearly │ 50 € │ ☑ Paid │ │
|
||||
│ 31.12.2023 │ │ │ │ │
|
||||
├───────────────┼──────────┼────────┼──────────┼─────────┤
|
||||
│ 01.01.2024- │ Yearly │ 60 € │ ☐ Open │ [Mark │
|
||||
│ 31.12.2024 │ │ │ │ as paid]│
|
||||
├───────────────┼──────────┼────────┼──────────┼─────────┤
|
||||
│ 01.01.2025- │ Yearly │ 60 € │ ☐ Open │ [Mark │
|
||||
│ 31.12.2025 │ │ │ │ as paid]│
|
||||
└───────────────┴──────────┴────────┴──────────┴─────────┘
|
||||
|
||||
Legend: ☑ = paid | ☐ = unpaid | ⊘ = suspended
|
||||
```
|
||||
|
||||
**Quick Marking:**
|
||||
|
||||
- Checkbox in each row for fast marking
|
||||
- Button: "Mark selected as paid"
|
||||
- Bulk action for multiple periods
|
||||
|
||||
### Admin: Contribution Types Management
|
||||
|
||||
**List:**
|
||||
|
||||
```
|
||||
┌────────────┬──────────┬──────────┬────────────┬─────────┐
|
||||
│ Name │ Amount │ Interval │ Members │ Actions │
|
||||
├────────────┼──────────┼──────────┼────────────┼─────────┤
|
||||
│ Regular │ 60 € │ Yearly │ 45 │ [Edit] │
|
||||
│ Reduced │ 30 € │ Yearly │ 12 │ [Edit] │
|
||||
│ Student │ 20 € │ Monthly │ 8 │ [Edit] │
|
||||
└────────────┴──────────┴──────────┴────────────┴─────────┘
|
||||
```
|
||||
|
||||
**Edit:**
|
||||
|
||||
- Name: ✓ editable
|
||||
- Amount: ✓ editable
|
||||
- Description: ✓ editable
|
||||
- Interval: ✗ **NOT** editable (grayed out)
|
||||
|
||||
**Warning on Amount Change:**
|
||||
|
||||
```
|
||||
⚠ Change amount to 65 €?
|
||||
|
||||
Impact:
|
||||
- 45 members affected
|
||||
- Future unpaid periods will be generated with 65 €
|
||||
- Already paid periods remain with old amount
|
||||
|
||||
[Cancel] [Confirm]
|
||||
```
|
||||
|
||||
### Admin: Settings
|
||||
|
||||
**Contribution Configuration:**
|
||||
|
||||
```
|
||||
Default Contribution Type: [Dropdown: Contribution Types]
|
||||
|
||||
Selected: "Regular (60 €, Yearly)"
|
||||
|
||||
This contribution type is automatically assigned to all new members.
|
||||
Can be changed individually per member.
|
||||
|
||||
---
|
||||
|
||||
☐ Include joining period
|
||||
|
||||
When active:
|
||||
Members pay from the period of their joining.
|
||||
|
||||
Example (Yearly):
|
||||
Joining: 15.03.2023
|
||||
→ Pays from 2023
|
||||
|
||||
When inactive:
|
||||
Members pay from the next full period.
|
||||
|
||||
Example (Yearly):
|
||||
Joining: 15.03.2023
|
||||
→ Pays from 2024
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### 1. Contribution Type Change with Different Interval
|
||||
|
||||
**MVP:** Blocked (only same interval allowed)
|
||||
|
||||
**UI:**
|
||||
|
||||
```
|
||||
Error: Interval change not possible
|
||||
|
||||
Current contribution type: "Regular (Yearly)"
|
||||
Selected contribution type: "Student (Monthly)"
|
||||
|
||||
Changing the interval is currently not possible.
|
||||
Please select a contribution type with interval "Yearly".
|
||||
|
||||
[OK]
|
||||
```
|
||||
|
||||
**Future:**
|
||||
|
||||
- Allow interval switching
|
||||
- Calculate overlaps
|
||||
- Generate new periods without duplicates
|
||||
|
||||
### 2. Exit with Unpaid Contributions
|
||||
|
||||
**Scenario:**
|
||||
|
||||
```
|
||||
Member exits: 15.08.2024
|
||||
Yearly period 2024: unpaid
|
||||
```
|
||||
|
||||
**UI Notice on Exit:**
|
||||
|
||||
```
|
||||
⚠ Unpaid contributions present
|
||||
|
||||
This member has 1 unpaid period(s):
|
||||
- 2024: 60 € (unpaid)
|
||||
|
||||
Do you want to continue?
|
||||
|
||||
[ ] Mark contribution as "suspended"
|
||||
[Cancel] [Confirm Exit]
|
||||
```
|
||||
|
||||
### 3. Multiple Unpaid Periods
|
||||
|
||||
**Scenario:** Member hasn't paid for 2 years
|
||||
|
||||
**Display:**
|
||||
|
||||
```
|
||||
┌───────────────┬──────────┬────────┬──────────┬─────────┐
|
||||
│ 2023 │ Yearly │ 50 € │ ☐ Open │ [✓] │
|
||||
│ 2024 │ Yearly │ 60 € │ ☐ Open │ [✓] │
|
||||
│ 2025 │ Yearly │ 60 € │ ☐ Open │ [ ] │
|
||||
└───────────────┴──────────┴────────┴──────────┴─────────┘
|
||||
|
||||
[Mark selected as paid] (2 selected)
|
||||
```
|
||||
|
||||
### 4. Amount Changes
|
||||
|
||||
**Scenario:**
|
||||
|
||||
```
|
||||
2023: Regular = 50 €
|
||||
2024: Regular = 60 € (increase)
|
||||
```
|
||||
|
||||
**Result:**
|
||||
|
||||
- Period 2023: Saved with 50 € (history)
|
||||
- Period 2024: Generated with 60 € (current)
|
||||
- Both periods show correct historical amount
|
||||
|
||||
### 5. Date Boundaries
|
||||
|
||||
**Problem:** What if today = 01.01.2025?
|
||||
|
||||
**Solution:**
|
||||
|
||||
- Current period (2025) is generated
|
||||
- Status: unpaid (open)
|
||||
- Shown in overview
|
||||
|
||||
---
|
||||
|
||||
## Implementation Scope
|
||||
|
||||
### MVP (Phase 1)
|
||||
|
||||
**Included:**
|
||||
|
||||
- ✓ Contribution types (CRUD)
|
||||
- ✓ Automatic period generation
|
||||
- ✓ Status management (paid/unpaid/suspended)
|
||||
- ✓ Member overview with contribution status
|
||||
- ✓ Period view per member
|
||||
- ✓ Quick checkbox marking
|
||||
- ✓ Bulk actions
|
||||
- ✓ Amount history
|
||||
- ✓ Same-interval type change
|
||||
- ✓ Default contribution type
|
||||
- ✓ Joining period configuration
|
||||
|
||||
**NOT Included:**
|
||||
|
||||
- ✗ Interval change (only same interval)
|
||||
- ✗ Payment details (date, method)
|
||||
- ✗ Automatic integration (vereinfacht.digital)
|
||||
- ✗ Prorata calculation
|
||||
- ✗ Reports/statistics
|
||||
- ✗ Reminders/dunning (manual via filters)
|
||||
|
||||
### Future Enhancements
|
||||
|
||||
**Phase 2:**
|
||||
|
||||
- Payment details (date, amount, method)
|
||||
- Interval change for future unpaid periods
|
||||
- Manual vereinfacht.digital links per member
|
||||
- Extended filter options
|
||||
|
||||
**Phase 3:**
|
||||
|
||||
- Automated vereinfacht.digital integration
|
||||
- Automatic payment matching
|
||||
- SEPA integration
|
||||
- Advanced reports
|
||||
Loading…
Add table
Add a link
Reference in a new issue