monacousa-portal/SNAKE_CASE_FIELD_MIGRATION_GUIDE.md

# MonacoUSA Portal - Snake Case Field Migration Guide

## 🎯 Overview

This document provides complete instructions for migrating from space-separated field names (e.g., "First Name") to snake_case field names (e.g., "first_name") to eliminate data corruption issues when editing records directly in NocoDB.

## 📊 Required NocoDB Field Name Changes

You need to rename the following fields in your NocoDB Members table:

| **Current Field Name**      | **New Snake Case Name**     | **Type**    |
|----------------------------|----------------------------|-------------|
| `First Name`               | `first_name`               | Text        |
| `Last Name`                | `last_name`                | Text        |
| `Email`                    | `email`                    | Email       |
| `Phone`                    | `phone`                    | Text        |
| `Date of Birth`            | `date_of_birth`            | Date        |
| `Nationality`              | `nationality`              | Text        |
| `Address`                  | `address`                  | LongText    |
| `Membership Status`        | `membership_status`        | SingleSelect|
| `Member Since`             | `member_since`             | Date        |
| `Current Year Dues Paid`   | `current_year_dues_paid`   | Text        |
| `Membership Date Paid`     | `membership_date_paid`     | Date        |
| `Payment Due Date`         | `payment_due_date`         | Date        |

### 🔧 How to Rename Fields in NocoDB

1. **Open your NocoDB Members table**
2. **For each field above:**
   - Click on the field header
   - Select "Edit" or click the gear icon
   - Change the field name from the old name to the new snake_case name
   - Click "Save"

⚠️ **Important**: Do NOT change the field types, only the names.

## 🏗️ Backend Files Updated

The following files have been completely updated to use snake_case field names:

### Type Definitions
- ✅ `utils/types.ts` - Member interface updated

### NocoDB Utilities
- ✅ `server/utils/nocodb.ts` - All CRUD operations updated

### API Endpoints
- ✅ `server/api/members/index.get.ts` - List members API
- ✅ `server/api/members/[id].get.ts` - Get single member API
- ✅ `server/api/members/index.post.ts` - Create member API
- ✅ `server/api/members/[id].put.ts` - Update member API

## 🎨 Frontend Files That Need Updates

The following frontend components still reference the old field names and need to be updated:

### Vue Components
- `components/ViewMemberDialog.vue`
- `components/MemberCard.vue` 
- `components/EditMemberDialog.vue`
- `components/AddMemberDialog.vue`
- `pages/dashboard/member-list.vue`

## 🔄 Complete Field Mapping Reference

### Data Access Patterns

**Before (❌ Old)**:
```javascript
member['First Name']
member['Last Name']
member['Membership Status']
member['Current Year Dues Paid']
```

**After (✅ New)**:
```javascript
member.first_name
member.last_name  
member.membership_status
member.current_year_dues_paid
```

### API Request/Response Format

**Create/Update Member Payload**:
```json
{
  "first_name": "John",
  "last_name": "Doe", 
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "nationality": "US",
  "membership_status": "Active",
  "current_year_dues_paid": "true",
  "date_of_birth": "1990-01-15",
  "member_since": "2023-01-01",
  "membership_date_paid": "2024-01-15",
  "payment_due_date": "2025-01-15",
  "address": "123 Main St, City, State"
}
```

## 🧪 Testing Checklist

After making the NocoDB field changes, test the following:

### Backend API Testing
- [ ] `GET /api/members` - List all members
- [ ] `GET /api/members/{id}` - Get single member  
- [ ] `POST /api/members` - Create new member
- [ ] `PUT /api/members/{id}` - Update existing member
- [ ] `DELETE /api/members/{id}` - Delete member

### Data Integrity Testing  
- [ ] Create member via portal → Verify in NocoDB
- [ ] Edit member via portal → Verify in NocoDB  
- [ ] Edit member in NocoDB directly → Verify portal displays correctly
- [ ] All fields display properly (names, flags, contact info)

### Frontend Display Testing
- [ ] Member list page loads and displays all members
- [ ] Member cards show correct information
- [ ] Country flags display properly  
- [ ] Search and filtering work correctly
- [ ] Add member dialog works
- [ ] Edit member dialog works and pre-populates correctly
- [ ] View member dialog shows all details

## 🚨 Critical Success Criteria  

The migration is successful when:

1. ✅ **No "undefined undefined" names appear** in member cards
2. ✅ **Country flags display properly** for all nationalities  
3. ✅ **Direct NocoDB edits sync properly** with portal display
4. ✅ **All CRUD operations work** through the portal
5. ✅ **No TypeScript errors** in the console
6. ✅ **No API errors** in browser network tab

## 🔧 Rollback Plan

If issues occur, you can temporarily rollback by:

1. **Revert NocoDB field names** back to the original space-separated format
2. **Revert the backend files** using git:
   ```bash
   git checkout HEAD~1 -- utils/types.ts server/utils/nocodb.ts server/api/members/
   ```

## 📈 Next Steps After Migration

1. **Update frontend components** to use snake_case field names
2. **Test thoroughly** across all functionality
3. **Update any documentation** that references old field names
4. **Consider adding validation** to prevent future field name inconsistencies

## 💡 Benefits After Migration

- ✅ **Consistent data display** regardless of edit source (portal vs NocoDB)
- ✅ **No more "undefined undefined" member names**
- ✅ **Proper country flag rendering**
- ✅ **Standard database naming conventions**
- ✅ **Easier debugging and maintenance**
- ✅ **Better API consistency**

## 🆘 Troubleshooting

### Issue: Members showing "undefined undefined"
- **Cause**: NocoDB field names don't match backend expectations
- **Solution**: Verify all field names in NocoDB match the snake_case format exactly

### Issue: Country flags not displaying
- **Cause**: Nationality field not properly mapped
- **Solution**: Ensure `Nationality` field is renamed to `nationality` in NocoDB

### Issue: API errors in console
- **Cause**: Field name mismatch between frontend and backend
- **Solution**: Update frontend components to use snake_case field names

### Issue: Direct NocoDB edits causing corruption
- **Cause**: This was the original problem - should be fixed after migration
- **Solution**: This migration specifically addresses this issue

---

**🎉 Once you complete the NocoDB field renaming, the backend will be fully compatible with snake_case field names and the data corruption issue should be completely resolved!**