@jmruthers/pace-core 0.5.190 → 0.5.193

package/docs/migration/database-changes-december-2025.md

@@ -0,0 +1,768 @@
+# Database Changes - December 2025
+
+**Version:** 0.5.190+  
+**Migration Date:** 2025-12-06  
+**Breaking Changes:** Yes
+
+## Overview
+
+This document details the database schema changes made in December 2025 that affect consuming applications. There are two major changes:
+
+1. **Table Naming Standardization** (2025-12-06) - All tables renamed to follow `app_entity` pattern
+2. **Person-Scoped Profiles Migration** (2025-12-05) - Profiles migrated from organisation-scoped to person-scoped
+
+**⚠️ CRITICAL**: Both changes are **breaking changes** and require code updates in consuming applications.
+
+---
+
+## Change 1: Table Naming Standardization
+
+**Migration:** `20251206111258_standardize_table_naming_app_entity.sql`  
+**Date:** 2025-12-06
+
+### Purpose
+
+All tables have been renamed to follow the `app_entity` naming convention:
+- **Core infrastructure tables** → `core_*` prefix
+- **Application-specific tables** → `{app}_*` prefix (e.g., `cake_*`, `trac_*`, `medi_*`)
+- **Shared PACE tables** → `core_*` prefix (since PACE is the overall suite)
+
+### Table Renames
+
+#### Core Infrastructure Tables
+
+| Old Name | New Name | Notes |
+|----------|----------|-------|
+| `organisations` | `core_organisations` | Core organisation table |
+| `event` | `core_events` | Core event table |
+| `file_references` | `core_file_references` | File reference system |
+| `form_context_types` | `core_form_context_types` | Form system |
+| `form_field_config` | `core_form_field_config` | Form system |
+| `form_fields` | `core_form_fields` | Form system |
+| `form_response_values` | `core_form_response_values` | Form system |
+| `form_responses` | `core_form_responses` | Form system |
+| `forms` | `core_forms` | Form system |
+| `event_app_access` | `core_event_app_access` | Event access control |
+| `organisation_app_access` | `core_organisation_app_access` | Organisation access control |
+| `organisation_audit_log` | `core_organisation_audit_log` | Audit logging |
+
+#### PACE Tables (Renamed to `core_*`)
+
+| Old Name | New Name | Notes |
+|----------|----------|-------|
+| `pace_person` | `core_person` | Person records |
+| `pace_member` | `core_member` | Membership profiles |
+| `pace_contact` | `core_contact` | Contact profiles |
+| `pace_address` | `core_address` | Address records |
+| `pace_phone` | `core_phone` | Phone records |
+| `pace_consent` | `core_consent` | Consent records |
+| `pace_consent_type` | `core_consent_type` | Consent types |
+| `pace_contact_type` | `core_contact_type` | Contact types |
+| `pace_field_list` | `core_field_list` | Field lists |
+| `pace_gender_type` | `core_gender_type` | Gender types |
+| `pace_identification` | `core_identification` | Identification records |
+| `pace_identification_type` | `core_identification_type` | Identification types |
+| `pace_member_role` | `core_member_role` | Member roles |
+| `pace_membership_type` | `core_membership_type` | Membership types |
+| `pace_merchandise` | `core_merchandise` | Merchandise records |
+| `pace_phone_type` | `core_phone_type` | Phone types |
+| `pace_pronoun_type` | `core_pronoun_type` | Pronoun types |
+| `pace_qualification` | `core_qualification` | Qualification records |
+| `pace_role_type` | `core_role_type` | Role types |
+
+### View Changes
+
+#### Membership Views
+
+| Old Name | New Name | Notes |
+|----------|----------|-------|
+| `organisation_memberships` | **DROPPED** | Merged into `core_organisation_memberships` |
+| `user_organisation_memberships` | **DROPPED** | Merged into `core_organisation_memberships` |
+| - | `core_organisation_memberships` | **NEW** - Unified membership view |
+
+**New View Details:**
+
+The `core_organisation_memberships` view provides a unified view of organisation memberships:
+
+```sql
+CREATE VIEW core_organisation_memberships AS
+SELECT 
+    id,
+    user_id,
+    organisation_id,
+    role,
+    (role = ANY (ARRAY['org_admin'::rbac_organisation_role, 'leader'::rbac_organisation_role])) AS is_primary,
+    granted_at AS joined_at,
+    status,
+    created_at,
+    updated_at,
+    granted_by AS created_by,
+    revoked_by AS updated_by,
+    granted_at,
+    revoked_at,
+    valid_from,
+    valid_to,
+    notes
+FROM rbac_organisation_roles ror
+WHERE ror.status = 'active'::text 
+  AND ror.revoked_at IS NULL 
+  AND ror.valid_from <= NOW()
+  AND (ror.valid_to IS NULL OR ror.valid_to >= NOW())
+  AND ror.role IN (
+    'org_admin'::rbac_organisation_role, 
+    'leader'::rbac_organisation_role, 
+    'member'::rbac_organisation_role, 
+    'supporter'::rbac_organisation_role
+  );
+```
+
+**Key Features:**
+- Returns only active, non-revoked memberships
+- Includes all membership roles (org_admin, leader, member, supporter)
+- Respects valid time windows (valid_from/valid_to)
+- Optimized for RLS policies with `security_barrier=true` and `security_invoker=true`
+
+#### Application-Specific Views
+
+| Old Name | New Name | Notes |
+|----------|----------|-------|
+| `public_recipe_details` | `cake_public_recipe_details` | CAKE app public recipe view |
+
+### Breaking Changes
+
+#### 1. Direct Table Queries
+
+**Before:**
+```typescript
+// ❌ This will fail - table name changed
+const { data } = await supabase
+  .from('organisations')
+  .select('*');
+```
+
+**After:**
+```typescript
+// ✅ Use new table name
+const { data } = await supabase
+  .from('core_organisations')
+  .select('*');
+```
+
+#### 2. View Queries
+
+**Before:**
+```typescript
+// ❌ This will fail - view dropped
+const { data } = await supabase
+  .from('organisation_memberships')
+  .select('*')
+  .eq('organisation_id', orgId);
+```
+
+**After:**
+```typescript
+// ✅ Use new unified view
+const { data } = await supabase
+  .from('core_organisation_memberships')
+  .select('*')
+  .eq('organisation_id', orgId);
+```
+
+#### 3. Joins and Relationships
+
+**Before:**
+```typescript
+// ❌ This will fail - table names changed
+const { data } = await supabase
+  .from('pace_person')
+  .select('*, pace_member(*), organisations(*)')
+  .eq('id', personId);
+```
+
+**After:**
+```typescript
+// ✅ Use new table names
+const { data } = await supabase
+  .from('core_person')
+  .select('*, core_member(*), core_organisations(*)')
+  .eq('id', personId);
+```
+
+#### 4. File References
+
+**Before:**
+```typescript
+// ❌ This will fail - table name changed
+const { data } = await supabase
+  .from('file_references')
+  .select('*')
+  .eq('table_name', 'pace_person')
+  .eq('record_id', personId);
+```
+
+**After:**
+```typescript
+// ✅ Use new table names
+const { data } = await supabase
+  .from('core_file_references')
+  .select('*')
+  .eq('table_name', 'core_person')  // Also update table_name values
+  .eq('record_id', personId);
+```
+
+**Important**: The `table_name` column in `core_file_references` has been updated to use new table names. If you're querying by `table_name`, ensure you use the new names:
+- `'pace_person'` → `'core_person'`
+- `'event'` → `'core_events'`
+- `'pace_member'` → `'core_member'`
+- `'pace_contact'` → `'core_contact'`
+- etc.
+
+#### 5. Event Queries
+
+**Before:**
+```typescript
+// ❌ This will fail - table name changed
+const { data } = await supabase
+  .from('event')
+  .select('*')
+  .eq('event_id', eventId);
+```
+
+**After:**
+```typescript
+// ✅ Use new table name
+const { data } = await supabase
+  .from('core_events')
+  .select('*')
+  .eq('event_id', eventId);
+```
+
+### RPC Functions Updated
+
+The following RPC functions have been updated to use the new table names:
+
+- `data_file_reference_url_get` - Now queries `core_file_references`
+- `data_file_reference_get` - Now queries `core_file_references`
+- `data_file_reference_delete` - Now queries `core_file_references`
+- `check_user_pace_member_access` - Now queries `core_person` and `core_member`
+- `check_user_medi_profile_access` - Now queries `core_member`
+- `check_user_pace_contact_access` - Now queries `core_person` and `core_contact`
+- `check_user_event_access` - Now queries `core_events`
+- `check_public_event_visible` - Now queries `core_events`
+- `get_event_organisation_id` - Now queries `core_events`
+- `is_event_visible` - Now queries `core_events`
+- `data_user_events_get` - Now queries `core_events`
+- `data_user_organisation_roles_get` - Now queries `core_organisations`
+- `data_user_organisations_get` - Now queries `core_organisations`
+- `get_public_event_by_code` - Now queries `core_events` and `core_file_references`
+- `app_cake_dish_create` - Now queries `core_events`
+- `app_cake_dish_update` - Now queries `core_events`
+- `app_cake_unit_create` - Now queries `core_events`
+- `app_base_application_create` - Now queries `core_person` and `core_events`
+- `app_pace_contact_update` - Now queries `core_contact`, `core_person`, `core_member`, `core_phone`
+- `get_organisation_members` - Now uses `core_organisation_memberships` view
+
+**Note**: `set_super_admin_override` function has been **removed** (as of migration `20251208133718_remove_super_admin_override_mechanism.sql`). Super admin access is now determined solely by the `is_super_admin()` function in RLS policies. If you were using this function, remove those calls as they are no longer needed or available.
+
+**Note**: RPC function signatures have not changed - only internal table references. Your RPC calls should continue to work, but ensure you're using the correct table names in any direct queries.
+
+### TypeScript Type Updates
+
+After applying migrations, **regenerate your database types**:
+
+```bash
+npx supabase gen types typescript --project-id <your-project-id> > src/types/database.generated.ts
+```
+
+The updated types will reflect:
+- All table names changed to `core_*` or `{app}_*` prefixes
+- View names updated
+- Relationship types updated
+
+### Migration Checklist
+
+Use this checklist to identify areas in your app that need updates:
+
+#### Database Queries
+- [ ] Search codebase for `from('organisations')` → Update to `from('core_organisations')`
+- [ ] Search codebase for `from('event')` → Update to `from('core_events')`
+- [ ] Search codebase for `from('file_references')` → Update to `from('core_file_references')`
+- [ ] Search codebase for `from('pace_*')` → Update to `from('core_*')`
+- [ ] Search codebase for `from('organisation_memberships')` → Update to `from('core_organisation_memberships')`
+- [ ] Search codebase for `from('user_organisation_memberships')` → Update to `from('core_organisation_memberships')`
+- [ ] Search codebase for `from('public_recipe_details')` → Update to `from('cake_public_recipe_details')`
+
+#### TypeScript Types
+- [ ] Regenerate database types from current schema
+- [ ] Update all type references to use new table names
+- [ ] Update interface definitions that reference old table names
+
+#### File References
+- [ ] Update `table_name` values in file reference queries to use new table names
+- [ ] Review file upload code that sets `table_name`
+- [ ] Update file reference display components
+
+#### Joins and Relationships
+- [ ] Update all `.select()` statements with joins to use new table names
+- [ ] Review relationship queries (e.g., `pace_person(*)` → `core_person(*)`)
+- [ ] Update foreign key lookups
+
+#### RLS Policies
+- [ ] Review any custom RLS policies that reference old table names
+- [ ] Update policy definitions if you have custom policies
+
+### Code Migration Examples
+
+#### Example 1: Organisation Query
+
+**Before:**
+```typescript
+const { data: organisations } = await supabase
+  .from('organisations')
+  .select('*')
+  .eq('is_active', true);
+```
+
+**After:**
+```typescript
+const { data: organisations } = await supabase
+  .from('core_organisations')
+  .select('*')
+  .eq('is_active', true);
+```
+
+#### Example 2: Event Query with Joins
+
+**Before:**
+```typescript
+const { data: events } = await supabase
+  .from('event')
+  .select(`
+    *,
+    organisations(*)
+  `)
+  .eq('organisation_id', orgId);
+```
+
+**After:**
+```typescript
+const { data: events } = await supabase
+  .from('core_events')
+  .select(`
+    *,
+    core_organisations(*)
+  `)
+  .eq('organisation_id', orgId);
+```
+
+#### Example 3: Person with Member Profile
+
+**Before:**
+```typescript
+const { data: person } = await supabase
+  .from('pace_person')
+  .select(`
+    *,
+    pace_member(*)
+  `)
+  .eq('id', personId)
+  .single();
+```
+
+**After:**
+```typescript
+const { data: person } = await supabase
+  .from('core_person')
+  .select(`
+    *,
+    core_member(*)
+  `)
+  .eq('id', personId)
+  .single();
+```
+
+#### Example 4: Organisation Memberships
+
+**Before:**
+```typescript
+const { data: memberships } = await supabase
+  .from('organisation_memberships')
+  .select('*')
+  .eq('organisation_id', orgId)
+  .eq('user_id', userId);
+```
+
+**After:**
+```typescript
+const { data: memberships } = await supabase
+  .from('core_organisation_memberships')
+  .select('*')
+  .eq('organisation_id', orgId)
+  .eq('user_id', userId);
+```
+
+#### Example 5: File References
+
+**Before:**
+```typescript
+const { data: files } = await supabase
+  .from('file_references')
+  .select('*')
+  .eq('table_name', 'pace_person')
+  .eq('record_id', personId);
+```
+
+**After:**
+```typescript
+const { data: files } = await supabase
+  .from('core_file_references')
+  .select('*')
+  .eq('table_name', 'core_person')  // Updated table_name value
+  .eq('record_id', personId);
+```
+
+---
+
+## Change 2: Person-Scoped Profiles Migration
+
+**Migration:** `20251205211120_migrate_profiles_to_person_scoped.sql` + related migrations  
+**Date:** 2025-12-05  
+**Documentation:** See [Person-Scoped Profiles Migration Guide](./person-scoped-profiles-migration-guide.md)
+
+### Quick Summary
+
+Profiles have been migrated from **organisation-scoped** to **person-scoped**:
+
+- **One membership profile** (`core_member`) per person (regardless of organisation)
+- **One medical profile** (`medi_profile`) per person
+- **Multiple contact profiles** (`core_contact`) per person
+
+### Key Changes
+
+1. **Removed `organisation_id`** from:
+   - `core_member` (was `pace_member`)
+   - `medi_profile`
+   - `core_contact` (was `pace_contact`)
+   - Related tables: `medi_condition`, `medi_diet`, `medi_action_plan`, `core_consent`, `core_identification`, `core_qualification`
+
+2. **Removed `member_id`** from `core_contact` (now uses `person_id` directly)
+
+3. **Added unique constraint** on `core_member.person_id` (one membership per person)
+
+### Impact on Table Naming
+
+Note that the person-scoped profiles migration happened **before** the table naming standardization. The tables were renamed as part of the standardization:
+
+- `pace_member` → `core_member` (person-scoped, no `organisation_id`)
+- `pace_contact` → `core_contact` (person-scoped, uses `person_id` instead of `member_id`)
+- `pace_person` → `core_person`
+
+### Combined Migration Example
+
+**Before (Old Schema):**
+```typescript
+// ❌ Old table names + organisation-scoped
+const { data } = await supabase
+  .from('pace_member')
+  .select('*')
+  .eq('person_id', personId)
+  .eq('organisation_id', orgId);  // ❌ organisation_id no longer exists
+```
+
+**After (New Schema):**
+```typescript
+// ✅ New table names + person-scoped
+const { data } = await supabase
+  .from('core_member')
+  .select('*')
+  .eq('person_id', personId);  // ✅ No organisation_id needed
+```
+
+---
+
+## Complete Migration Checklist
+
+### Phase 1: Table Naming Updates
+
+- [ ] Update all `from('organisations')` → `from('core_organisations')`
+- [ ] Update all `from('event')` → `from('core_events')`
+- [ ] Update all `from('file_references')` → `from('core_file_references')`
+- [ ] Update all `from('pace_*')` → `from('core_*')`
+- [ ] Update all `from('organisation_memberships')` → `from('core_organisation_memberships')`
+- [ ] Update all `from('user_organisation_memberships')` → `from('core_organisation_memberships')`
+- [ ] Update all `from('public_recipe_details')` → `from('cake_public_recipe_details')`
+- [ ] Update all `.select()` joins to use new table names
+- [ ] Update `table_name` values in file reference queries
+- [ ] Regenerate TypeScript types
+
+### Phase 2: Person-Scoped Profiles Updates
+
+- [ ] Remove `organisation_id` filters from profile table queries
+- [ ] Update `pace_contact` queries to use `person_id` instead of `member_id`
+- [ ] Update profile creation logic (no `organisation_id` needed)
+- [ ] Review profile access patterns (person-scoped, not org-scoped)
+- [ ] See [Person-Scoped Profiles Migration Guide](./person-scoped-profiles-migration-guide.md) for detailed checklist
+
+### Phase 3: Testing
+
+- [ ] Test all database queries with new table names
+- [ ] Test profile queries (person-scoped)
+- [ ] Test file reference queries
+- [ ] Test organisation membership queries
+- [ ] Test event queries
+- [ ] Verify RLS policies work correctly
+- [ ] Test cross-organisation scenarios
+
+### Phase 4: Type Updates
+
+- [ ] Regenerate TypeScript types from current schema
+- [ ] Update all type references
+- [ ] Fix TypeScript compilation errors
+- [ ] Update interface definitions
+
+---
+
+## RPC Functions Reference
+
+All RPC functions have been updated internally to use the new table names. Function signatures remain the same, so your RPC calls should continue to work without changes.
+
+However, if you're using RPC functions that return data with table names (e.g., in `table_name` columns), ensure you handle the new table names correctly.
+
+### Updated RPC Functions
+
+The following RPC functions now use new table names internally:
+
+**File Reference Functions:**
+- `data_file_reference_url_get`
+- `data_file_reference_get`
+- `data_file_reference_delete`
+- `data_file_reference_create`
+
+**Profile Functions:**
+- `data_pace_member_profile_get`
+- `data_pace_linked_profiles_list`
+- `data_pace_contacts_list`
+- `data_pace_contact_get`
+- `app_pace_contact_update`
+
+**Event Functions:**
+- `data_user_events_get`
+- `get_public_event_by_code`
+- `check_user_event_access`
+- `check_public_event_visible`
+
+**Organisation Functions:**
+- `data_user_organisations_get`
+- `data_user_organisation_roles_get`
+- `get_organisation_members`
+
+**Application Functions:**
+- `app_cake_dish_create`
+- `app_cake_dish_update`
+- `app_cake_unit_create`
+- `app_base_application_create`
+
+---
+
+## Common Issues and Solutions
+
+### Issue 1: "relation does not exist"
+
+**Error:**
+```
+relation "organisations" does not exist
+```
+
+**Solution:**
+Update table name to `core_organisations`:
+```typescript
+// ❌ Old
+.from('organisations')
+
+// ✅ New
+.from('core_organisations')
+```
+
+### Issue 2: "column does not exist"
+
+**Error:**
+```
+column "organisation_id" does not exist in table "core_member"
+```
+
+**Solution:**
+Remove `organisation_id` filters from profile table queries. Profiles are now person-scoped:
+```typescript
+// ❌ Old
+.from('core_member')
+.eq('organisation_id', orgId)  // ❌ Column doesn't exist
+
+// ✅ New
+.from('core_member')
+.eq('person_id', personId)  // ✅ Person-scoped
+```
+
+### Issue 3: View not found
+
+**Error:**
+```
+relation "organisation_memberships" does not exist
+```
+
+**Solution:**
+Use the new unified view:
+```typescript
+// ❌ Old
+.from('organisation_memberships')
+
+// ✅ New
+.from('core_organisation_memberships')
+```
+
+### Issue 4: File reference table_name mismatch
+
+**Error:**
+```
+No file references found (table_name mismatch)
+```
+
+**Solution:**
+Update `table_name` values to use new table names:
+```typescript
+// ❌ Old
+.eq('table_name', 'pace_person')
+
+// ✅ New
+.eq('table_name', 'core_person')
+```
+
+---
+
+## Testing Recommendations
+
+### 1. Search and Replace Strategy
+
+Use your IDE's search and replace to update table names:
+
+1. **Search for old table names:**
+   - `'organisations'` → `'core_organisations'`
+   - `'event'` → `'core_events'`
+   - `'pace_person'` → `'core_person'`
+   - `'pace_member'` → `'core_member'`
+   - etc.
+
+2. **Update view references:**
+   - `'organisation_memberships'` → `'core_organisation_memberships'`
+   - `'user_organisation_memberships'` → `'core_organisation_memberships'`
+
+3. **Update file reference table_name values:**
+   - `'pace_person'` → `'core_person'`
+   - `'event'` → `'core_events'`
+   - etc.
+
+### 2. TypeScript Type Regeneration
+
+After migrations are applied:
+
+```bash
+# Regenerate types from current schema
+npx supabase gen types typescript --project-id <your-project-id> > src/types/database.generated.ts
+
+# Fix any TypeScript errors
+npm run type-check
+```
+
+### 3. Integration Testing
+
+Test the following scenarios:
+
+- [ ] Organisation queries
+- [ ] Event queries
+- [ ] Person/profile queries
+- [ ] File reference queries
+- [ ] Organisation membership queries
+- [ ] Cross-organisation profile access
+- [ ] RPC function calls
+
+### 4. RLS Policy Verification
+
+Verify RLS policies work correctly:
+
+- [ ] Organisation access checks
+- [ ] Event access checks
+- [ ] Person/profile access checks
+- [ ] File reference access checks
+- [ ] Membership view access
+
+---
+
+## Support and Questions
+
+### Migration Files
+
+All migration files are located in:
+- `supabase/migrations/20251206111258_standardize_table_naming_app_entity.sql`
+- `supabase/migrations/20251205211120_migrate_profiles_to_person_scoped.sql`
+- `supabase/migrations/20251205211121_schema_changes_person_scoped_profiles.sql`
+- Related migration files in `supabase/migrations/`
+
+### Documentation
+
+- [Person-Scoped Profiles Migration Guide](./person-scoped-profiles-migration-guide.md)
+- [API & RPC Standard](../standards/02-api-and-rpc-standard.md)
+- [Database Schema Requirements](../architecture/database-schema-requirements.md)
+
+### Getting Help
+
+If you encounter issues:
+
+1. **Check Migration Status**: Verify all migrations are applied
+2. **Verify Types**: Regenerate TypeScript types from current schema
+3. **Review RLS**: Ensure RLS policies are correctly applied
+4. **Check Logs**: Review Supabase logs for errors
+5. **Search Codebase**: Use search to find all references to old table names
+
+---
+
+## Summary
+
+**Key Takeaways:**
+
+1. **Table Naming:**
+   - All core tables → `core_*` prefix
+   - All PACE tables → `core_*` prefix
+   - Application tables → `{app}_*` prefix
+   - Update all queries to use new table names
+
+2. **Views:**
+   - `organisation_memberships` and `user_organisation_memberships` → `core_organisation_memberships`
+   - `public_recipe_details` → `cake_public_recipe_details`
+
+3. **Profiles:**
+   - Person-scoped (not organisation-scoped)
+   - Remove `organisation_id` from profile queries
+   - Use `person_id` instead of `member_id` for contacts
+
+4. **File References:**
+   - Update `table_name` values to use new table names
+
+5. **Types:**
+   - Regenerate TypeScript types after migrations
+
+6. **Testing:**
+   - Test all database queries
+   - Test profile access patterns
+   - Verify RLS policies work correctly
+
+**Migration Order:**
+1. Apply person-scoped profiles migrations (Dec 5)
+2. Apply table naming standardization (Dec 6)
+3. Update code to use new table names
+4. Regenerate TypeScript types
+5. Test thoroughly
+
+---
+
+**Last Updated:** 2025-12-06  
+**Version:** 0.5.190+
+