update the metadata field in all tables to additional_metadata

docs/dev/METADATA_MIGRATION.md

@@ -0,0 +1,188 @@
+# Metadata Column Migration Guide
+
+## Problem
+
+The column name `metadata` conflicts with SQLAlchemy's internal `metadata` attribute, causing this error:
+
+```
+sqlalchemy.exc.InvalidRequestError: Attribute name 'metadata' is reserved when using the Declarative API.
+```
+
+## Solution
+
+Rename `metadata` → `additional_metadata` across all tables.
+
+## Migration Steps
+
+### 1. Run SQL Migration
+
+**Location:** `migrations/001_rename_metadata_to_additional_metadata.sql`
+
+**How to run:**
+1. Open Supabase Dashboard
+2. Go to SQL Editor
+3. Copy the migration file content
+4. Execute the SQL
+5. Verify success
+
+**Verification query:**
+```sql
+SELECT 
+    table_name,
+    column_name,
+    data_type
+FROM information_schema.columns
+WHERE table_schema = 'public'
+    AND column_name IN ('metadata', 'additional_metadata')
+ORDER BY 
+    CASE WHEN column_name = 'metadata' THEN 0 ELSE 1 END,
+    table_name;
+```
+
+**Expected result:**
+- 0 rows with `metadata`
+- 32 rows with `additional_metadata`
+
+### 2. Update Application Code
+
+**Before:**
+```python
+# Workaround (don't use this)
+user_metadata = Column('metadata', JSONB, default={})
+```
+
+**After:**
+```python
+# Clean approach
+additional_metadata = Column(JSONB, default={})
+```
+
+### 3. Update All Models
+
+When creating new models, use `additional_metadata`:
+
+```python
+from sqlalchemy import Column
+from sqlalchemy.dialects.postgresql import JSONB
+from app.models.base import BaseModel
+
+class MyModel(BaseModel):
+    __tablename__ = "my_table"
+    
+    # ... other columns ...
+    
+    # Use additional_metadata (not metadata!)
+    additional_metadata = Column(JSONB, default={})
+```
+
+### 4. Usage in Code
+
+```python
+# Create user with metadata
+user = User(
+    name="John Doe",
+    email="john@example.com",
+    additional_metadata={
+        "source": "mobile_app",
+        "referral_code": "ABC123"
+    }
+)
+
+# Access metadata
+print(user.additional_metadata)
+# Output: {"source": "mobile_app", "referral_code": "ABC123"}
+
+# Update metadata
+user.additional_metadata["last_login"] = "2025-11-15"
+db.commit()
+```
+
+## Tables Affected
+
+32 tables have the `additional_metadata` column:
+
+**Organizations & Users:**
+- clients
+- contractors
+- users
+- user_financial_accounts
+- user_asset_assignments
+- user_document_links
+
+**Projects & Teams:**
+- projects
+- project_regions
+- project_subcontractors
+- timesheets
+
+**Customers & Sales:**
+- customers
+- sales_orders
+- subscriptions
+- incidents
+
+**Tickets & Work:**
+- tickets
+- ticket_status_history
+- ticket_expenses
+- ticket_comments
+- customer_communications
+
+**Tasks:**
+- tasks
+
+**Inventory:**
+- inventory_assignments
+
+**Financial:**
+- project_finance
+- payment_logs
+- user_payroll
+
+**Documents & Notifications:**
+- documents
+- notifications
+
+**System & Audit:**
+- audit_logs
+
+**Platform Billing:**
+- organization_subscriptions
+- usage_metrics
+
+## Rollback
+
+If you need to rollback (not recommended):
+
+```sql
+BEGIN;
+
+-- Reverse all renames
+ALTER TABLE clients RENAME COLUMN additional_metadata TO metadata;
+-- ... (repeat for all tables)
+
+COMMIT;
+```
+
+## Benefits
+
+1. ✅ **No SQLAlchemy Conflicts** - Clean model definitions
+2. ✅ **Better Naming** - More descriptive column name
+3. ✅ **Consistent** - All tables follow same pattern
+4. ✅ **Future-Proof** - No workarounds needed
+
+## Checklist
+
+- [ ] Run SQL migration in Supabase
+- [ ] Verify all columns renamed (0 `metadata`, 32 `additional_metadata`)
+- [ ] Update User model (already done)
+- [ ] Test application startup
+- [ ] Update schema.sql documentation
+- [ ] Create future models with `additional_metadata`
+
+## Notes
+
+- This is a **one-time migration**
+- Run it **before** you have production data
+- The migration is **transactional** (all or nothing)
+- **No data loss** - just column rename

docs/schema/schema.sql

@@ -138,7 +138,7 @@ CREATE TABLE clients (
     website TEXT,
     is_active BOOLEAN DEFAULT TRUE,
     default_sla_days INTEGER,               -- Default SLA window (days) for jobs under this client
-    metadata JSONB DEFAULT '{}',            -- Flexible storage for additional fields
+    additional_metadata JSONB DEFAULT '{}',            -- Flexible storage for additional fields
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     deleted_at TIMESTAMP WITH TIME ZONE NULL
@@ -156,7 +156,7 @@ CREATE TABLE contractors (
     main_phone TEXT,
     is_active BOOLEAN DEFAULT TRUE,
     competencies JSONB DEFAULT '{}',        -- Array of specializations (e.g., ["FTTH", "Fixed Wireless", "Fiber Splicing"])
-    metadata JSONB DEFAULT '{}',            -- Flexible storage for additional fields
+    additional_metadata JSONB DEFAULT '{}',            -- Flexible storage for additional fields
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     deleted_at TIMESTAMP WITH TIME ZONE NULL,
@@ -216,7 +216,7 @@ CREATE TABLE users (
     current_location_updated_at TIMESTAMP WITH TIME ZONE,
 
     -- Additional metadata for future flexibility
-    metadata JSONB DEFAULT '{}',
+    additional_metadata JSONB DEFAULT '{}',
 
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -480,7 +480,7 @@ CREATE TABLE projects (
     activation_requirements JSONB DEFAULT '[]',
 
     -- Additional metadata for future flexibility
-    metadata JSONB DEFAULT '{}',
+    additional_metadata JSONB DEFAULT '{}',
 
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -531,7 +531,7 @@ CREATE TABLE project_subcontractors (
     
     -- Metadata
     notes TEXT,
-    metadata JSONB DEFAULT '{}',
+    additional_metadata JSONB DEFAULT '{}',
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     deleted_at TIMESTAMP WITH TIME ZONE NULL
@@ -580,7 +580,7 @@ CREATE TABLE project_regions (
 
     -- Metadata
     notes TEXT,
-    metadata JSONB DEFAULT '{}',
+    additional_metadata JSONB DEFAULT '{}',
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     deleted_at TIMESTAMP WITH TIME ZONE NULL
@@ -696,7 +696,7 @@ CREATE TABLE timesheets (
 
     -- Metadata
     notes TEXT,
-    metadata JSONB DEFAULT '{}',        -- Additional data (e.g., device info, ticket IDs worked on)
+    additional_metadata JSONB DEFAULT '{}',        -- Additional data (e.g., device info, ticket IDs worked on)
 
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -767,7 +767,7 @@ CREATE TABLE customers (
     is_active BOOLEAN DEFAULT TRUE,
 
     -- Additional metadata for future flexibility
-    metadata JSONB DEFAULT '{}',
+    additional_metadata JSONB DEFAULT '{}',
 
     -- Timestamps
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -845,7 +845,7 @@ CREATE TABLE sales_orders (
 
     -- Metadata
     notes TEXT,
-    metadata JSONB DEFAULT '{}',            -- Additional metadata for future flexibility
+    additional_metadata JSONB DEFAULT '{}',            -- Additional metadata for future flexibility
     submitted_by_user_id UUID REFERENCES users (id) ON DELETE SET NULL,
     submitted_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -932,7 +932,7 @@ CREATE TABLE subscriptions (
 
     -- Metadata
     notes TEXT,
-    metadata JSONB DEFAULT '{}',        -- Additional metadata for future flexibility
+    additional_metadata JSONB DEFAULT '{}',        -- Additional metadata for future flexibility
     activated_by_user_id UUID REFERENCES users (id) ON DELETE SET NULL,
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -987,7 +987,7 @@ CREATE TABLE incidents (
     cancellation_reason TEXT,           -- Why incident was cancelled (if status='cancelled')
 
     -- Metadata
-    metadata JSONB DEFAULT '{}',        -- Additional metadata for future flexibility
+    additional_metadata JSONB DEFAULT '{}',        -- Additional metadata for future flexibility
 
     -- Timestamps
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -1129,7 +1129,7 @@ CREATE TABLE tickets (
 
     -- Metadata
     notes TEXT,
-    metadata JSONB DEFAULT '{}',        -- Additional metadata for future flexibility
+    additional_metadata JSONB DEFAULT '{}',        -- Additional metadata for future flexibility
 
     -- Concurrency Control (Optimistic Locking)
     version INTEGER DEFAULT 1 NOT NULL,
@@ -1350,7 +1350,7 @@ CREATE TABLE ticket_status_history (
 
     -- Metadata
     notes TEXT,
-    metadata JSONB DEFAULT '{}',                    -- Device info, IP address, etc.
+    additional_metadata JSONB DEFAULT '{}',                    -- Device info, IP address, etc.
 
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     deleted_at TIMESTAMP WITH TIME ZONE NULL,
@@ -1401,7 +1401,7 @@ CREATE TABLE ticket_comments (
     edited_by_user_id UUID REFERENCES users (id) ON DELETE SET NULL,
     
     -- Metadata
-    metadata JSONB DEFAULT '{}',
+    additional_metadata JSONB DEFAULT '{}',
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     deleted_at TIMESTAMP WITH TIME ZONE NULL,
@@ -1455,7 +1455,7 @@ CREATE TABLE customer_communications (
     followup_notes TEXT,
     
     -- Metadata
-    metadata JSONB DEFAULT '{}',        -- Additional data (call duration, recording URL, etc.)
+    additional_metadata JSONB DEFAULT '{}',        -- Additional data (call duration, recording URL, etc.)
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     
@@ -1542,7 +1542,7 @@ CREATE TABLE ticket_expenses (
 
     -- Metadata
     notes TEXT,
-    metadata JSONB DEFAULT '{}',        -- Can store split details: {"split_with": ["user-id-1", "user-id-2"], "split_amount": 500}
+    additional_metadata JSONB DEFAULT '{}',        -- Can store split details: {"split_with": ["user-id-1", "user-id-2"], "split_amount": 500}
 
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -1612,7 +1612,7 @@ CREATE TABLE tasks (
 
     -- Metadata
     notes TEXT,
-    metadata JSONB DEFAULT '{}',        -- Additional metadata for future flexibility
+    additional_metadata JSONB DEFAULT '{}',        -- Additional metadata for future flexibility
     created_by_user_id UUID REFERENCES users (id) ON DELETE SET NULL,
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -1838,7 +1838,7 @@ CREATE TABLE inventory_assignments (
 
     -- Notes (optional)
     notes TEXT,
-    metadata JSONB DEFAULT '{}',
+    additional_metadata JSONB DEFAULT '{}',
 
     -- Concurrency Control (Optimistic Locking)
     version INTEGER DEFAULT 1 NOT NULL,
@@ -2001,7 +2001,7 @@ CREATE TABLE project_finance (
 
     -- Metadata
     notes TEXT,
-    metadata JSONB DEFAULT '{}',                                       -- Additional data (e.g., split payments, installment info)
+    additional_metadata JSONB DEFAULT '{}',                                       -- Additional data (e.g., split payments, installment info)
 
     -- Concurrency Control (Optimistic Locking)
     version INTEGER DEFAULT 1 NOT NULL,
@@ -2127,7 +2127,7 @@ CREATE TABLE payment_logs (
 
     -- Additional context
     notes TEXT,                                             -- Admin notes
-    metadata JSONB DEFAULT '{}',                            -- Additional data (webhook headers, etc.)
+    additional_metadata JSONB DEFAULT '{}',                            -- Additional data (webhook headers, etc.)
 
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
 
@@ -2189,7 +2189,7 @@ CREATE TABLE user_payroll (
     paid_by_user_id UUID REFERENCES users (id) ON DELETE SET NULL,
 
     -- Metadata
-    metadata JSONB DEFAULT '{}',                    -- Additional data (e.g., ticket IDs, bonus reasons)
+    additional_metadata JSONB DEFAULT '{}',                    -- Additional data (e.g., ticket IDs, bonus reasons)
 
     -- Concurrency Control (Optimistic Locking)
     version INTEGER DEFAULT 1 NOT NULL,
@@ -2272,7 +2272,7 @@ CREATE TABLE documents (
     -- Metadata
     description TEXT,
     tags JSONB DEFAULT '[]',            -- Array of tags for search
-    metadata JSONB DEFAULT '{}',        -- Additional metadata (e.g., GPS coordinates for photos, OCR text)
+    additional_metadata JSONB DEFAULT '{}',        -- Additional metadata (e.g., GPS coordinates for photos, OCR text)
 
     -- Access Control
     uploaded_by_user_id UUID REFERENCES users (id) ON DELETE SET NULL,
@@ -2322,7 +2322,7 @@ CREATE TABLE user_document_links (
     issued_at DATE,
     expires_at DATE,
     notes TEXT,
-    metadata JSONB DEFAULT '{}',        -- Additional metadata (e.g., GPS coordinates for photos, OCR text)
+    additional_metadata JSONB DEFAULT '{}',        -- Additional metadata (e.g., GPS coordinates for photos, OCR text)
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
 
@@ -2364,7 +2364,7 @@ CREATE TABLE notifications (
     failure_reason TEXT,
 
     -- Metadata
-    metadata JSONB DEFAULT '{}',        -- Additional data (e.g., action buttons, deep links)
+    additional_metadata JSONB DEFAULT '{}',        -- Additional data (e.g., action buttons, deep links)
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now())
 );
 
@@ -2459,7 +2459,7 @@ CREATE TABLE audit_logs (
     longitude DOUBLE PRECISION,
 
     -- Metadata
-    metadata JSONB DEFAULT '{}',            -- Additional context
+    additional_metadata JSONB DEFAULT '{}',            -- Additional context
 
     -- Timestamp
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -2550,7 +2550,7 @@ CREATE TABLE contractor_invoices (
     -- Metadata
     notes TEXT,
     terms_and_conditions TEXT,
-    metadata JSONB DEFAULT '{}',        -- Additional metadata for future flexibility
+    additional_metadata JSONB DEFAULT '{}',        -- Additional metadata for future flexibility
     created_by_user_id UUID REFERENCES users (id) ON DELETE SET NULL,
     created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
@@ -2957,14 +2957,14 @@ ON CONFLICT (config_key) DO NOTHING;
 -- These are critical for performance when filtering or searching within JSONB data
 
 -- clients & contractors
-CREATE INDEX idx_clients_metadata_gin ON clients USING GIN(metadata);
+CREATE INDEX idx_clients_metadata_gin ON clients USING GIN(additional_metadata);
 CREATE INDEX idx_contractors_competencies_gin ON contractors USING GIN(competencies);
-CREATE INDEX idx_contractors_metadata_gin ON contractors USING GIN(metadata);
+CREATE INDEX idx_contractors_metadata_gin ON contractors USING GIN(additional_metadata);
 
 -- users
 CREATE INDEX idx_users_health_info_gin ON users USING GIN(health_info);
 CREATE INDEX idx_users_ppe_sizes_gin ON users USING GIN(ppe_sizes);
-CREATE INDEX idx_users_metadata_gin ON users USING GIN(metadata);
+CREATE INDEX idx_users_metadata_gin ON users USING GIN(additional_metadata);
 
 -- User Preferences
 CREATE INDEX idx_user_preferences_additional_settings_gin ON user_preferences USING GIN(additional_settings);
@@ -2974,39 +2974,39 @@ CREATE INDEX idx_projects_budget_gin ON projects USING GIN(budget);
 CREATE INDEX idx_projects_inventory_requirements_gin ON projects USING GIN(inventory_requirements);
 CREATE INDEX idx_projects_photo_requirements_gin ON projects USING GIN(photo_requirements);
 CREATE INDEX idx_projects_activation_requirements_gin ON projects USING GIN(activation_requirements);
-CREATE INDEX idx_projects_metadata_gin ON projects USING GIN(metadata);
+CREATE INDEX idx_projects_metadata_gin ON projects USING GIN(additional_metadata);
 
 -- Project Regions
-CREATE INDEX idx_project_regions_metadata_gin ON project_regions USING GIN(metadata);
+CREATE INDEX idx_project_regions_metadata_gin ON project_regions USING GIN(additional_metadata);
 
 -- timesheets
-CREATE INDEX idx_timesheets_metadata_gin ON timesheets USING GIN(metadata);
+CREATE INDEX idx_timesheets_metadata_gin ON timesheets USING GIN(additional_metadata);
 
 -- customers
-CREATE INDEX idx_customers_metadata_gin ON customers USING GIN(metadata);
+CREATE INDEX idx_customers_metadata_gin ON customers USING GIN(additional_metadata);
 
 -- Sales Orders
-CREATE INDEX idx_sales_orders_metadata_gin ON sales_orders USING GIN(metadata);
+CREATE INDEX idx_sales_orders_metadata_gin ON sales_orders USING GIN(additional_metadata);
 
 -- subscriptions
 CREATE INDEX idx_subscriptions_equipment_details_gin ON subscriptions USING GIN(equipment_details);
 CREATE INDEX idx_subscriptions_activation_details_gin ON subscriptions USING GIN(activation_details);
-CREATE INDEX idx_subscriptions_metadata_gin ON subscriptions USING GIN(metadata);
+CREATE INDEX idx_subscriptions_metadata_gin ON subscriptions USING GIN(additional_metadata);
 
 -- incidents
-CREATE INDEX idx_incidents_metadata_gin ON incidents USING GIN(metadata);
+CREATE INDEX idx_incidents_metadata_gin ON incidents USING GIN(additional_metadata);
 
 -- tickets
-CREATE INDEX idx_tickets_metadata_gin ON tickets USING GIN(metadata);
+CREATE INDEX idx_tickets_metadata_gin ON tickets USING GIN(additional_metadata);
 
 -- Ticket Status History
-CREATE INDEX idx_ticket_status_history_metadata_gin ON ticket_status_history USING GIN(metadata);
+CREATE INDEX idx_ticket_status_history_metadata_gin ON ticket_status_history USING GIN(additional_metadata);
 
 -- Ticket Expenses
-CREATE INDEX idx_ticket_expenses_metadata_gin ON ticket_expenses USING GIN(metadata);
+CREATE INDEX idx_ticket_expenses_metadata_gin ON ticket_expenses USING GIN(additional_metadata);
 
 -- tasks
-CREATE INDEX idx_tasks_metadata_gin ON tasks USING GIN(metadata);
+CREATE INDEX idx_tasks_metadata_gin ON tasks USING GIN(additional_metadata);
 
 -- Project Inventory
 CREATE INDEX idx_project_inventory_serial_numbers_gin ON project_inventory USING GIN(serial_numbers);
@@ -3016,29 +3016,29 @@ CREATE INDEX idx_inventory_distribution_serial_numbers_gin ON project_inventory_
 
 -- Inventory Assignments
 CREATE INDEX idx_inventory_assignments_unit_contents_gin ON inventory_assignments USING GIN(unit_contents);
-CREATE INDEX idx_inventory_assignments_metadata_gin ON inventory_assignments USING GIN(metadata);
+CREATE INDEX idx_inventory_assignments_metadata_gin ON inventory_assignments USING GIN(additional_metadata);
 
 -- Project Finance
-CREATE INDEX idx_project_finance_metadata_gin ON project_finance USING GIN(metadata);
+CREATE INDEX idx_project_finance_metadata_gin ON project_finance USING GIN(additional_metadata);
 
 -- Payment Logs
 CREATE INDEX idx_payment_logs_request_payload_gin ON payment_logs USING GIN(request_payload);
 CREATE INDEX idx_payment_logs_response_payload_gin ON payment_logs USING GIN(response_payload);
 CREATE INDEX idx_payment_logs_device_info_gin ON payment_logs USING GIN(device_info);
-CREATE INDEX idx_payment_logs_metadata_gin ON payment_logs USING GIN(metadata);
+CREATE INDEX idx_payment_logs_metadata_gin ON payment_logs USING GIN(additional_metadata);
 
 -- documents
-CREATE INDEX idx_documents_metadata_gin ON documents USING GIN(metadata);
+CREATE INDEX idx_documents_metadata_gin ON documents USING GIN(additional_metadata);
 
 -- notifications
-CREATE INDEX idx_notifications_metadata_gin ON notifications USING GIN(metadata);
+CREATE INDEX idx_notifications_metadata_gin ON notifications USING GIN(additional_metadata);
 
 -- System Configuration
 CREATE INDEX idx_system_configuration_validation_rules_gin ON system_configuration USING GIN(validation_rules);
 
 -- Audit Logs
 CREATE INDEX idx_audit_logs_changes_gin ON audit_logs USING GIN(changes);
-CREATE INDEX idx_audit_logs_metadata_gin ON audit_logs USING GIN(metadata);
+CREATE INDEX idx_audit_logs_metadata_gin ON audit_logs USING GIN(additional_metadata);
 
 -- External Integrations: REMOVED (over-engineering for MVP)
 
@@ -3046,13 +3046,13 @@ CREATE INDEX idx_audit_logs_metadata_gin ON audit_logs USING GIN(metadata);
 CREATE INDEX idx_billing_plans_features_gin ON billing_plans USING GIN(features);
 
 -- Organization subscriptions
-CREATE INDEX idx_org_subscriptions_metadata_gin ON organization_subscriptions USING GIN(metadata);
+CREATE INDEX idx_org_subscriptions_metadata_gin ON organization_subscriptions USING GIN(additional_metadata);
 
 -- invoices
 CREATE INDEX idx_invoices_line_items_gin ON invoices USING GIN(line_items);
 
 -- Usage Metrics
-CREATE INDEX idx_usage_metrics_metadata_gin ON usage_metrics USING GIN(metadata);
+CREATE INDEX idx_usage_metrics_metadata_gin ON usage_metrics USING GIN(additional_metadata);
 
 COMMENT ON INDEX idx_clients_metadata_gin IS 'GIN index for fast JSONB queries on clients.metadata';
 COMMENT ON INDEX idx_projects_activation_requirements_gin IS 'GIN index for querying dynamic activation requirements per project';

migrations/001_rename_metadata_to_additional_metadata.sql

@@ -0,0 +1,100 @@
+-- ============================================
+-- Migration: Rename 'metadata' to 'additional_metadata'
+-- Date: 2025-11-15
+-- Reason: 'metadata' is a reserved word in SQLAlchemy ORM
+-- ============================================
+-- This migration renames the 'metadata' JSONB column to 'additional_metadata'
+-- across all tables to avoid conflicts with SQLAlchemy's internal metadata attribute.
+--
+-- INSTRUCTIONS:
+-- 1. Review this migration carefully
+-- 2. Run in Supabase SQL Editor
+-- 3. Verify all tables updated successfully
+-- 4. Update application code to use 'additional_metadata'
+--
+-- ROLLBACK:
+-- To rollback, replace 'additional_metadata' with 'metadata' in all ALTER statements below
+-- ============================================
+
+-- Start transaction
+BEGIN;
+
+-- 1. ORGANIZATIONS & USERS
+ALTER TABLE clients RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE contractors RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE users RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE user_financial_accounts RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE user_asset_assignments RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE user_document_links RENAME COLUMN metadata TO additional_metadata;
+
+-- 2. PROJECTS & TEAMS
+ALTER TABLE projects RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE project_regions RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE project_subcontractors RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE timesheets RENAME COLUMN metadata TO additional_metadata;
+
+-- 3. CUSTOMERS & SALES
+ALTER TABLE customers RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE sales_orders RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE subscriptions RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE incidents RENAME COLUMN metadata TO additional_metadata;
+
+-- 4. TICKETS & WORK ORDERS
+ALTER TABLE tickets RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE ticket_status_history RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE ticket_expenses RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE ticket_comments RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE customer_communications RENAME COLUMN metadata TO additional_metadata;
+
+-- 5. TASKS
+ALTER TABLE tasks RENAME COLUMN metadata TO additional_metadata;
+
+-- 6. INVENTORY
+ALTER TABLE inventory_assignments RENAME COLUMN metadata TO additional_metadata;
+
+-- 7. FINANCIAL MANAGEMENT
+ALTER TABLE project_finance RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE payment_logs RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE user_payroll RENAME COLUMN metadata TO additional_metadata;
+
+-- 8. DOCUMENTS & NOTIFICATIONS
+ALTER TABLE documents RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE notifications RENAME COLUMN metadata TO additional_metadata;
+
+-- 9. SYSTEM & AUDIT
+ALTER TABLE audit_logs RENAME COLUMN metadata TO additional_metadata;
+
+-- 10. PLATFORM BILLING
+ALTER TABLE organization_subscriptions RENAME COLUMN metadata TO additional_metadata;
+ALTER TABLE usage_metrics RENAME COLUMN metadata TO additional_metadata;
+
+-- Commit transaction
+COMMIT;
+
+-- ============================================
+-- Verification Query
+-- ============================================
+-- Run this to verify all columns were renamed:
+/*
+SELECT 
+    table_name,
+    column_name,
+    data_type
+FROM information_schema.columns
+WHERE table_schema = 'public'
+    AND column_name IN ('metadata', 'additional_metadata')
+ORDER BY 
+    CASE WHEN column_name = 'metadata' THEN 0 ELSE 1 END,
+    table_name;
+
+-- Expected: 0 rows with 'metadata', 32 rows with 'additional_metadata'
+*/
+
+-- ============================================
+-- Migration Complete
+-- ============================================
+-- Next steps:
+-- 1. Update schema.sql documentation
+-- 2. Update SQLAlchemy models to use 'additional_metadata'
+-- 3. Test application startup
+-- ============================================

migrations/001_rename_metadata_to_additional_metadata_safe.sql

@@ -0,0 +1,95 @@
+-- ============================================
+-- Migration: Rename 'metadata' to 'additional_metadata' (SAFE VERSION)
+-- Date: 2025-11-15
+-- Reason: 'metadata' is a reserved word in SQLAlchemy ORM
+-- ============================================
+-- This migration safely renames the 'metadata' JSONB column to 'additional_metadata'
+-- It only attempts to rename columns that actually exist in the database.
+--
+-- INSTRUCTIONS:
+-- 1. Run this in Supabase SQL Editor
+-- 2. Check the output to see which tables were updated
+-- 3. Verify with the verification query at the end
+-- ============================================
+
+-- Start transaction
+BEGIN;
+
+-- Use DO block to safely rename columns only if they exist
+DO $$
+DECLARE
+    table_record RECORD;
+    tables_to_check TEXT[] := ARRAY[
+        'clients',
+        'contractors', 
+        'users',
+        'user_financial_accounts',
+        'user_asset_assignments',
+        'user_document_links',
+        'projects',
+        'project_regions',
+        'project_subcontractors',
+        'timesheets',
+        'customers',
+        'sales_orders',
+        'subscriptions',
+        'incidents',
+        'tickets',
+        'ticket_status_history',
+        'ticket_expenses',
+        'ticket_comments',
+        'customer_communications',
+        'tasks',
+        'inventory_assignments',
+        'project_finance',
+        'payment_logs',
+        'user_payroll',
+        'documents',
+        'notifications',
+        'audit_logs',
+        'organization_subscriptions',
+        'usage_metrics'
+    ];
+    current_table TEXT;
+    column_exists BOOLEAN;
+BEGIN
+    FOREACH current_table IN ARRAY tables_to_check
+    LOOP
+        -- Check if table exists and has metadata column
+        SELECT EXISTS (
+            SELECT 1 
+            FROM information_schema.columns 
+            WHERE table_schema = 'public' 
+                AND table_name = current_table
+                AND column_name = 'metadata'
+        ) INTO column_exists;
+        
+        IF column_exists THEN
+            -- Rename the column
+            EXECUTE format('ALTER TABLE %I RENAME COLUMN metadata TO additional_metadata', current_table);
+            RAISE NOTICE 'Renamed metadata column in table: %', current_table;
+        ELSE
+            RAISE NOTICE 'Skipped table (no metadata column): %', current_table;
+        END IF;
+    END LOOP;
+END $$;
+
+-- Commit transaction
+COMMIT;
+
+-- ============================================
+-- Verification Query
+-- ============================================
+-- Run this to see which tables have metadata vs additional_metadata:
+SELECT 
+    table_name,
+    column_name,
+    data_type
+FROM information_schema.columns
+WHERE table_schema = 'public'
+    AND column_name IN ('metadata', 'additional_metadata')
+ORDER BY 
+    CASE WHEN column_name = 'metadata' THEN 0 ELSE 1 END,
+    table_name;
+
+-- Expected: 0 rows with 'metadata', N rows with 'additional_metadata' (where N = number of tables that had metadata)

migrations/002_fix_contractor_invoices_metadata.sql

@@ -0,0 +1,21 @@
+-- ============================================
+-- Migration: Fix contractor_invoices metadata column
+-- Date: 2025-11-15
+-- Reason: This table was missed in the first migration
+-- ============================================
+
+BEGIN;
+
+-- Rename metadata to additional_metadata in contractor_invoices
+ALTER TABLE contractor_invoices RENAME COLUMN metadata TO additional_metadata;
+
+COMMIT;
+
+-- Verification: Should return 0 rows with 'metadata'
+SELECT 
+    table_name,
+    column_name,
+    data_type
+FROM information_schema.columns
+WHERE table_schema = 'public'
+    AND column_name = 'metadata';

src/app/models/user.py

@@ -69,8 +69,8 @@ class User(BaseModel):
     current_longitude = Column(String(50), nullable=True)  # DOUBLE PRECISION in DB
     current_location_updated_at = Column(DateTime(timezone=True), nullable=True)
     
-    # Metadata (JSONB in schema) - renamed to avoid SQLAlchemy reserved word
-    user_metadata = Column('metadata', JSONB, default={})
+    # Additional Metadata (JSONB in schema)
+    additional_metadata = Column(JSONB, default={})
     
     def __repr__(self):
         return f"<User(email='{self.email}', name='{self.name}')>"