420 lines
9.4 KiB
Markdown
420 lines
9.4 KiB
Markdown
|
|
# 📥 Import Existing Chit Group - Complete Guide
|
|
|
|
## Overview
|
|
|
|
Import chit funds that have already started running (e.g., 6 months ago) and backfill past data.
|
|
|
|
---
|
|
|
|
## 🎯 Use Case
|
|
|
|
You have an offline chit fund running for 6 months and want to bring it online:
|
|
- Started: June 2024
|
|
- Currently: December 2024 (Month 7)
|
|
- Need to enter: Past draws, past payments
|
|
|
|
---
|
|
|
|
## 🚀 Step-by-Step Process
|
|
|
|
### Step 1: Import the Group
|
|
|
|
**Manager Dashboard → "Import Existing Group" button**
|
|
|
|
Fill in details:
|
|
1. **Group Name**: e.g., "January 2024 Batch"
|
|
2. **Start Date**: Select when it actually started (e.g., June 1, 2024)
|
|
3. **Current Month**: Auto-calculated (e.g., 7 if 6 months passed)
|
|
4. **Financial Details**:
|
|
- Total Value: e.g., ₹1,00,000
|
|
- Duration: e.g., 20 months
|
|
- Max Members: e.g., 20
|
|
- Monthly Installment: e.g., ₹5,250
|
|
- Commission: e.g., ₹250
|
|
- Draw Date: e.g., 15th
|
|
|
|
**Click "Import Group"**
|
|
|
|
Result: Group created with `status: 'active'` and past start date
|
|
|
|
---
|
|
|
|
### Step 2: Add All Members
|
|
|
|
**Group Details → Add Members**
|
|
|
|
Add all members who are/were part of the group:
|
|
1. Click "Add Member"
|
|
2. Select from existing users OR create new users
|
|
3. Add all members (current and past)
|
|
4. Set their join dates if different from group start
|
|
|
|
---
|
|
|
|
### Step 3: Backfill Past Draw Results
|
|
|
|
**For each past month (e.g., Months 1-6):**
|
|
|
|
1. Click "Add Past Draw" button
|
|
2. Select Month number (1, 2, 3, etc.)
|
|
3. Select who won that month
|
|
4. Enter prize amount they received
|
|
5. Click "Add Draw"
|
|
|
|
**Repeat for all past months**
|
|
|
|
---
|
|
|
|
### Step 4: Backfill Past Payments
|
|
|
|
**For each past month (e.g., Months 1-6):**
|
|
|
|
1. Click "Add Past Payments" button
|
|
2. Select Month number
|
|
3. Check all members who PAID for that month
|
|
4. Click "Add Payments"
|
|
|
|
**Repeat for all past months**
|
|
|
|
---
|
|
|
|
### Step 5: Continue Regular Operations
|
|
|
|
Now the group is up to date!
|
|
- Future draws: Use regular draw button
|
|
- Future payments: Record as they happen
|
|
- All history is captured
|
|
|
|
---
|
|
|
|
## 📊 Example Scenario
|
|
|
|
### Existing Group Details:
|
|
- Name: "June 2024 Batch"
|
|
- Started: June 1, 2024
|
|
- Current: December 15, 2024 (7 months running)
|
|
- Total Value: ₹1,00,000
|
|
- Duration: 20 months
|
|
- Members: 20 people
|
|
- Monthly: ₹5,250
|
|
|
|
### Backfill Data:
|
|
|
|
**Month 1 (June 2024):**
|
|
- Winner: John Doe (₹99,000)
|
|
- Paid: 18/20 members
|
|
|
|
**Month 2 (July 2024):**
|
|
- Winner: Jane Smith (₹98,500)
|
|
- Paid: 19/20 members
|
|
|
|
**Month 3 (August 2024):**
|
|
- Winner: Bob Johnson (₹98,000)
|
|
- Paid: 20/20 members
|
|
|
|
...and so on for all 6 past months.
|
|
|
|
---
|
|
|
|
## 🔧 Backend Changes
|
|
|
|
### API Endpoint: POST /api/chit-groups
|
|
|
|
**New Parameters:**
|
|
- `start_date` (optional) - Custom start date for existing groups
|
|
- `current_month` (optional) - Which month the group is currently on
|
|
- `is_import` (boolean) - Flag to indicate this is an existing group
|
|
- `status` (optional) - Can be 'active' for imported groups
|
|
|
|
**Behavior:**
|
|
- If `is_import = true` and `status = 'active'`:
|
|
- Uses provided `start_date` instead of current date
|
|
- Sets status to 'active' (not 'forming')
|
|
- Calculates end date from start date
|
|
|
|
---
|
|
|
|
### API Endpoint: POST /api/monthly-draws
|
|
|
|
**New Parameters:**
|
|
- `winner_id` (optional) - Manual winner selection for past draws
|
|
- `prize_amount` (optional) - Custom prize amount
|
|
- `is_past_draw` (boolean) - Flag for past draw results
|
|
|
|
**Behavior:**
|
|
- If `is_past_draw = true`:
|
|
- Uses provided `winner_id` instead of random selection
|
|
- Uses provided `prize_amount`
|
|
- Marks as "Past draw result (imported)" in notes
|
|
|
|
---
|
|
|
|
## 📱 Frontend Components
|
|
|
|
### 1. Import Existing Group Dialog
|
|
**File**: `luckychit/lib/interfaces/manager/import_existing_group_dialog.dart`
|
|
|
|
Features:
|
|
- ✅ Start date picker (can select past dates)
|
|
- ✅ Auto-calculates current month from start date
|
|
- ✅ All standard group fields
|
|
- ✅ Info box with next steps
|
|
- ✅ Creates group as 'active' directly
|
|
|
|
### 2. Add Past Draw Dialog
|
|
**File**: `luckychit/lib/interfaces/manager/add_past_draw_dialog.dart`
|
|
|
|
Features:
|
|
- ✅ Select month number (1, 2, 3, etc.)
|
|
- ✅ Auto-calculates actual month/year from group start date
|
|
- ✅ Select winner from member list
|
|
- ✅ Enter prize amount
|
|
- ✅ Marks draw as past result
|
|
|
|
### 3. Add Past Payments Dialog
|
|
**File**: `luckychit/lib/interfaces/manager/add_past_payments_dialog.dart`
|
|
|
|
Features:
|
|
- ✅ Select month number
|
|
- ✅ Checkbox list of all members
|
|
- ✅ Select who paid
|
|
- ✅ Bulk create payments
|
|
- ✅ Shows summary count
|
|
|
|
---
|
|
|
|
## 🎨 User Interface
|
|
|
|
### Import Button Location
|
|
**Manager Dashboard** or **Chit Groups Page**
|
|
|
|
```dart
|
|
FloatingActionButton.extended(
|
|
onPressed: () => Get.dialog(ImportExistingGroupDialog()),
|
|
icon: Icon(Icons.upload),
|
|
label: Text('Import Existing Group'),
|
|
)
|
|
```
|
|
|
|
### Backfill Buttons Location
|
|
**Group Details Page → Actions Menu**
|
|
|
|
```dart
|
|
PopupMenuButton(
|
|
items: [
|
|
PopupMenuItem(
|
|
value: 'add_past_draw',
|
|
child: Text('Add Past Draw Result'),
|
|
),
|
|
PopupMenuItem(
|
|
value: 'add_past_payments',
|
|
child: Text('Add Past Payments'),
|
|
),
|
|
],
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## ⚠️ Important Considerations
|
|
|
|
### Data Accuracy
|
|
- ✅ Enter data carefully - this is historical data
|
|
- ✅ Verify winner names match exactly
|
|
- ✅ Double-check payment records
|
|
- ✅ Confirm amounts are correct
|
|
|
|
### Order of Operations
|
|
1. **First**: Import group
|
|
2. **Second**: Add all members
|
|
3. **Third**: Add past draws (in order)
|
|
4. **Fourth**: Add past payments (in order)
|
|
|
|
### Validation
|
|
- ✅ Can't add draw for future months
|
|
- ✅ Can't add payments without members
|
|
- ✅ Winner must be a member of the group
|
|
- ✅ Prize amounts should be reasonable
|
|
|
|
---
|
|
|
|
## 🧪 Testing Scenario
|
|
|
|
### Test Import Flow:
|
|
|
|
```bash
|
|
# 1. Import Group
|
|
Group: "Test Import June 2024"
|
|
Started: June 1, 2024
|
|
Current Month: 7
|
|
Total Value: ₹1,00,000
|
|
Duration: 20 months
|
|
Members: 20
|
|
Installment: ₹5,250
|
|
|
|
# 2. Add 20 members
|
|
Member 1: John Doe (9876543210)
|
|
Member 2: Jane Smith (9876543211)
|
|
...
|
|
Member 20: Bob Wilson (9876543229)
|
|
|
|
# 3. Add Past Draws
|
|
Month 1: Winner = John Doe, Prize = ₹99,000
|
|
Month 2: Winner = Jane Smith, Prize = ₹98,500
|
|
Month 3: Winner = Bob Johnson, Prize = ₹98,000
|
|
Month 4: Winner = Alice Brown, Prize = ₹97,500
|
|
Month 5: Winner = Charlie Davis, Prize = ₹97,000
|
|
Month 6: Winner = David Wilson, Prize = ₹96,500
|
|
|
|
# 4. Add Past Payments
|
|
Month 1: 18/20 paid (John & Jane absent)
|
|
Month 2: 19/20 paid (Bob absent)
|
|
Month 3: 20/20 paid
|
|
Month 4: 20/20 paid
|
|
Month 5: 19/20 paid (Alice absent)
|
|
Month 6: 20/20 paid
|
|
|
|
# 5. Current Operations
|
|
Month 7: Continue normally
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Data Verification
|
|
|
|
### After Backfilling:
|
|
|
|
**Check Group Stats:**
|
|
- [ ] Total draws = 6
|
|
- [ ] Total payments recorded correctly
|
|
- [ ] Member payment totals correct
|
|
- [ ] Winner amounts recorded
|
|
|
|
**Check Member Dashboards:**
|
|
- [ ] Members see their payment history
|
|
- [ ] Winners see their wins
|
|
- [ ] Totals add up correctly
|
|
|
|
**Check Financial Table:**
|
|
- [ ] All months accounted for
|
|
- [ ] Prize amounts correct
|
|
- [ ] Payment status accurate
|
|
|
|
---
|
|
|
|
## 🔒 Security & Permissions
|
|
|
|
- ✅ Only **managers** can import groups
|
|
- ✅ Only **group manager** can add past data
|
|
- ✅ Cannot modify data after entering (integrity)
|
|
- ✅ All actions logged
|
|
|
|
---
|
|
|
|
## 🎯 Benefits
|
|
|
|
### For Managers:
|
|
- ✅ Migrate existing offline groups
|
|
- ✅ Keep historical records
|
|
- ✅ Don't lose past data
|
|
- ✅ Smooth transition to digital
|
|
|
|
### For Members:
|
|
- ✅ See complete history
|
|
- ✅ Track all payments
|
|
- ✅ View all wins
|
|
- ✅ No data loss
|
|
|
|
---
|
|
|
|
## 💡 Best Practices
|
|
|
|
### 1. Gather All Data First
|
|
Before starting import:
|
|
- Member list with phone numbers
|
|
- Past draw results (who won each month)
|
|
- Past payment records (who paid each month)
|
|
- Prize amounts for each draw
|
|
|
|
### 2. Import in One Session
|
|
- Complete the entire backfill process
|
|
- Don't leave partial data
|
|
- Verify everything before closing
|
|
|
|
### 3. Double-Check
|
|
- Review all entered data
|
|
- Compare with offline records
|
|
- Test member view
|
|
- Verify calculations
|
|
|
|
### 4. Communicate with Members
|
|
- Inform them about the migration
|
|
- Ask them to verify their data
|
|
- Provide support for questions
|
|
- Celebrate the digital transition!
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Issue: Can't select past start date
|
|
**Fix**: Make sure date picker allows past dates (configured in dialog)
|
|
|
|
### Issue: Current month calculation wrong
|
|
**Fix**: Manually enter correct month number
|
|
|
|
### Issue: Can't find member in winner list
|
|
**Fix**: Add the member first, then add draw
|
|
|
|
### Issue: Payment already exists error
|
|
**Fix**: Check if payment was already entered for that member/month
|
|
|
|
---
|
|
|
|
## 📚 Related Files
|
|
|
|
### Frontend:
|
|
- `luckychit/lib/interfaces/manager/import_existing_group_dialog.dart` ✅ New
|
|
- `luckychit/lib/interfaces/manager/add_past_draw_dialog.dart` ✅ New
|
|
- `luckychit/lib/interfaces/manager/add_past_payments_dialog.dart` ✅ New
|
|
|
|
### Backend:
|
|
- `backend/src/controllers/chitGroupController.js` ✅ Updated
|
|
- `backend/src/controllers/monthlyDrawController.js` ✅ Updated
|
|
|
|
---
|
|
|
|
## 🚀 Deployment
|
|
|
|
```bash
|
|
# 1. Commit all changes
|
|
git add .
|
|
git commit -m "Add import existing group feature with backfill support"
|
|
git push origin prodnew
|
|
|
|
# 2. Deploy
|
|
./scripts/deploy.sh
|
|
|
|
# 3. Test
|
|
# Try importing a test group with past data
|
|
```
|
|
|
|
---
|
|
|
|
## ✅ Feature Checklist
|
|
|
|
- [ ] Import existing group dialog created
|
|
- [ ] Backend supports custom start dates
|
|
- [ ] Backend supports past draw entry
|
|
- [ ] Add past draw dialog created
|
|
- [ ] Add past payments dialog created
|
|
- [ ] Documentation complete
|
|
- [ ] Testing completed
|
|
- [ ] Deployed to production
|
|
|
|
---
|
|
|
|
**You can now migrate existing offline chit funds to the digital system!** 🎉
|
|
|