282 lines
6.8 KiB
Markdown
282 lines
6.8 KiB
Markdown
# 🎉 Custom Recurring Expenses - Feature Summary
|
||
|
||
## What's New
|
||
|
||
### ✨ Custom Frequency Intervals
|
||
- **Any interval you want**: Not limited to weekly/monthly
|
||
- **Examples**: Every 45 days, every 10 days, every 3 days
|
||
- **Perfect for**: Unusual billing cycles, medication refills, custom contracts
|
||
|
||
### 📅 Advanced Scheduling
|
||
- **Start Date**: When subscription begins
|
||
- **End Date**: Automatic deactivation after date
|
||
- **Total Payments**: Limit number of occurrences
|
||
- **Occurrence Counter**: Track how many times paid
|
||
|
||
### ⚡ Auto-Create Expenses
|
||
- **Automatic**: Creates expenses on due date
|
||
- **Manual Control**: Click button to trigger
|
||
- **Safe**: Only creates once per day, respects limits
|
||
- **Convenient**: No more forgetting to log recurring expenses
|
||
|
||
## Quick Comparison
|
||
|
||
### Before (Basic Subscriptions)
|
||
```
|
||
✗ Only weekly/monthly/quarterly/yearly
|
||
✗ Manual expense creation required
|
||
✗ No end dates
|
||
✗ No payment limits
|
||
✗ Basic tracking only
|
||
```
|
||
|
||
### After (Custom Recurring)
|
||
```
|
||
✓ Any custom interval (in days)
|
||
✓ Auto-create expenses on due date
|
||
✓ Set start and end dates
|
||
✓ Limit total number of payments
|
||
✓ Full automation with occurrence tracking
|
||
```
|
||
|
||
## Real-World Examples
|
||
|
||
### Medication Refill
|
||
```
|
||
💊 Name: Blood Pressure Meds
|
||
Amount: $25
|
||
Every: 30 days
|
||
Limit: 6 refills
|
||
Auto-Create: ON ⚡
|
||
```
|
||
|
||
### Gym Membership (12 months)
|
||
```
|
||
💪 Name: Fitness Center
|
||
Amount: $50
|
||
Every: Monthly
|
||
Total Payments: 12
|
||
End Date: Dec 31, 2025
|
||
Auto-Create: ON ⚡
|
||
```
|
||
|
||
### Car Maintenance
|
||
```
|
||
🚗 Name: Oil Change
|
||
Amount: $75
|
||
Every: 90 days (Custom)
|
||
Start: Today
|
||
Auto-Create: OFF (manual reminder)
|
||
```
|
||
|
||
### Subscription Trial
|
||
```
|
||
📺 Name: Streaming Service
|
||
Amount: $14.99
|
||
Every: Monthly
|
||
End Date: Mar 31, 2025
|
||
Auto-Create: ON ⚡
|
||
```
|
||
|
||
## How to Use
|
||
|
||
### Create Custom Subscription
|
||
1. Navigate to **Subscriptions** page
|
||
2. Click **➕ Add Subscription**
|
||
3. Fill in details:
|
||
- Name & Amount
|
||
- Choose "Custom" frequency (or standard)
|
||
- Enter custom interval (if custom selected)
|
||
- Set start date
|
||
- Optional: Set end date or total payments
|
||
- Check "Auto-Create Expenses" if desired
|
||
4. Click **Save**
|
||
|
||
### Auto-Create Expenses
|
||
**Option 1 - Manual**:
|
||
- Visit Subscriptions page
|
||
- Click **⚡ Create Due Expenses** button
|
||
- Expenses created instantly for today's due dates
|
||
|
||
**Option 2 - Automation**:
|
||
- Set up cron job (see guide)
|
||
- Runs automatically daily
|
||
- Zero manual effort
|
||
|
||
### Edit Existing Subscription
|
||
1. Click **Edit** on any subscription
|
||
2. Modify any field
|
||
3. Add/remove auto-create
|
||
4. Update dates or limits
|
||
5. Click **Save**
|
||
|
||
## New UI Elements
|
||
|
||
### Subscription List
|
||
```
|
||
🔄 Netflix Premium ⚡ AUTO
|
||
💰 $19.99 / Monthly
|
||
📅 Next: Jan 15, 2025
|
||
📊 Annual: $239.88
|
||
[Edit] [Delete]
|
||
```
|
||
|
||
### Custom Frequency Display
|
||
```
|
||
💰 $75 / Every 45 days
|
||
```
|
||
|
||
### Occurrence Counter
|
||
```
|
||
🔢 8/12 times (4 remaining)
|
||
```
|
||
|
||
### Auto-Create Indicator
|
||
```
|
||
⚡ AUTO badge - Green highlight
|
||
Tooltip: "Expenses will be created automatically"
|
||
```
|
||
|
||
## Database Changes
|
||
|
||
### New Fields
|
||
| Field | Type | Purpose |
|
||
|-------|------|---------|
|
||
| `custom_interval_days` | INTEGER | Days between payments (for custom) |
|
||
| `start_date` | DATE | First occurrence date |
|
||
| `end_date` | DATE | Last allowed date (optional) |
|
||
| `total_occurrences` | INTEGER | Payment limit (optional) |
|
||
| `occurrences_count` | INTEGER | Current count |
|
||
| `auto_create_expense` | BOOLEAN | Enable auto-creation |
|
||
| `last_auto_created` | DATE | Last auto-create date |
|
||
|
||
### Migration Required
|
||
```bash
|
||
# Run this to add new fields
|
||
python migrate_custom_recurring.py
|
||
|
||
# Or use full migration
|
||
./migrate_smart_features.sh
|
||
```
|
||
|
||
## Translation Support
|
||
|
||
All new features translated in:
|
||
- 🇬🇧 **English**: "Auto-Create Expenses", "Custom Interval"
|
||
- 🇷🇴 **Romanian**: "Creare automată cheltuieli", "Interval personalizat"
|
||
- 🇪🇸 **Spanish**: "Auto-crear gastos", "Intervalo personalizado"
|
||
|
||
## Key Benefits
|
||
|
||
### 🎯 Flexibility
|
||
- Handle ANY recurring payment schedule
|
||
- Not limited to standard frequencies
|
||
- Perfect for unusual billing cycles
|
||
|
||
### ⏱️ Time Saving
|
||
- Auto-create expenses on due date
|
||
- No manual logging needed
|
||
- Set it and forget it
|
||
|
||
### 📊 Better Tracking
|
||
- See occurrence count in real-time
|
||
- Know when subscriptions will end
|
||
- Track remaining payments
|
||
|
||
### 💰 Budget Control
|
||
- Set payment limits for fixed terms
|
||
- Automatic end dates
|
||
- Annual cost calculations
|
||
|
||
### 🌐 Multi-Language
|
||
- Fully translated interface
|
||
- Consistent experience worldwide
|
||
- Easy language switching
|
||
|
||
## Technical Details
|
||
|
||
### Auto-Create Logic
|
||
```python
|
||
def should_create_expense_today():
|
||
- Check if today == next_due_date ✓
|
||
- Check if already created today ✗
|
||
- Check if within occurrence limits ✓
|
||
- Check if before end date ✓
|
||
- Check if subscription active ✓
|
||
return True/False
|
||
```
|
||
|
||
### Next Payment Calculation
|
||
```python
|
||
next_payment = current_payment + interval_days
|
||
if occurrences_count >= total_occurrences:
|
||
deactivate()
|
||
if next_payment > end_date:
|
||
deactivate()
|
||
```
|
||
|
||
### Frequency Resolution
|
||
```python
|
||
if frequency == "custom":
|
||
interval = custom_interval_days
|
||
else:
|
||
interval = frequency_map[frequency] # 7, 14, 30, 90, 365
|
||
```
|
||
|
||
## Files Modified
|
||
|
||
### Models
|
||
- `app/models/subscription.py` - Added 7 new fields + methods
|
||
|
||
### Routes
|
||
- `app/routes/subscriptions.py` - Added auto-create endpoint
|
||
|
||
### Templates
|
||
- `app/templates/subscriptions/create.html` - Custom frequency form
|
||
- `app/templates/subscriptions/edit.html` - Edit custom fields
|
||
- `app/templates/subscriptions/index.html` - Display AUTO badge
|
||
|
||
### Translations
|
||
- `app/translations.py` - 15+ new translation keys (3 languages)
|
||
|
||
### Migration
|
||
- `migrate_custom_recurring.py` - Database upgrade script
|
||
|
||
## Testing Checklist
|
||
|
||
- [ ] Create subscription with custom interval (e.g., 45 days)
|
||
- [ ] Create subscription with end date
|
||
- [ ] Create subscription with total payments limit
|
||
- [ ] Enable auto-create and trigger creation
|
||
- [ ] Verify occurrence counter increments
|
||
- [ ] Verify subscription deactivates at limit
|
||
- [ ] Verify subscription deactivates after end date
|
||
- [ ] Edit custom interval on existing subscription
|
||
- [ ] Test in Romanian language
|
||
- [ ] Test in Spanish language
|
||
- [ ] Verify AUTO badge displays correctly
|
||
- [ ] Check dashboard widget shows custom intervals
|
||
|
||
## Next Steps
|
||
|
||
1. **Run Migration**: `python migrate_custom_recurring.py`
|
||
2. **Restart App**: `docker compose restart`
|
||
3. **Test Feature**: Create custom subscription
|
||
4. **Enable Auto-Create**: Check the box on important subscriptions
|
||
5. **Set Up Automation**: (Optional) Configure cron job
|
||
|
||
## Support
|
||
|
||
See full documentation: `CUSTOM_RECURRING_GUIDE.md`
|
||
|
||
## Version Info
|
||
|
||
- **Feature**: Custom Recurring Expenses
|
||
- **Version**: 1.0
|
||
- **Date**: December 2025
|
||
- **Languages**: EN, RO, ES
|
||
- **Status**: ✅ Ready for Production
|
||
|
||
---
|
||
|
||
**Enjoy your new smart subscription management! 🎉**
|