chore: fix pghistory migration deps and improve htmx utilities

- Update pghistory dependency from 0007 to 0006 in account migrations - Add docstrings and remove unused imports in htmx_forms.py - Add DJANGO_SETTINGS_MODULE bash commands to Claude settings - Add state transition definitions for ride statuses
2025-12-23 21:11:09 -05:00 · 2025-12-21 17:33:24 -05:00
parent b9063ff4f8
commit 7ba0004c93
74 changed files with 11134 additions and 198 deletions
--- a/backend/apps/moderation/VERIFICATION_FIXES.md
+++ b/backend/apps/moderation/VERIFICATION_FIXES.md
@@ -0,0 +1,299 @@
+# Verification Fixes Implementation Summary
+
+## Overview
+This document summarizes the fixes implemented in response to the verification comments after the initial FSM migration.
+
+---
+
+## Comment 1: FSM Method Name Conflicts with Business Logic
+
+### Problem
+The FSM generation was creating methods with names like `approve()`, `reject()`, and `escalate()` which would override the existing business logic methods on `EditSubmission` and `PhotoSubmission`. These business logic methods contain critical side effects:
+
+- **EditSubmission.approve()**: Creates/updates Park or Ride objects from submission data
+- **PhotoSubmission.approve()**: Creates ParkPhoto or RidePhoto objects
+
+If these methods were overridden by FSM-generated methods, the business logic would be lost.
+
+### Solution Implemented
+
+#### 1. Updated FSM Method Naming Strategy
+**File**: `backend/apps/core/state_machine/builder.py`
+
+Changed `determine_method_name_for_transition()` to always use the `transition_to_<state>` pattern:
+
+```python
+def determine_method_name_for_transition(source: str, target: str) -> str:
+    """
+    Determine appropriate method name for a transition.
+    
+    Always uses transition_to_<state> pattern to avoid conflicts with
+    business logic methods (approve, reject, escalate, etc.).
+    """
+    return f"transition_to_{target.lower()}"
+```
+
+**Before**: Generated methods like `approve()`, `reject()`, `escalate()`  
+**After**: Generates methods like `transition_to_approved()`, `transition_to_rejected()`, `transition_to_escalated()`
+
+#### 2. Updated Business Logic Methods to Call FSM Transitions
+**File**: `backend/apps/moderation/models.py`
+
+Updated `EditSubmission` methods:
+
+```python
+def approve(self, moderator: UserType, user=None) -> Optional[models.Model]:
+    # ... business logic (create/update Park or Ride objects) ...
+    
+    # Use FSM transition to update status
+    self.transition_to_approved(user=approver)
+    self.handled_by = approver
+    self.handled_at = timezone.now()
+    self.save()
+    
+    return obj
+```
+
+```python
+def reject(self, moderator: UserType = None, reason: str = "", user=None) -> None:
+    # Use FSM transition to update status
+    self.transition_to_rejected(user=rejecter)
+    self.handled_by = rejecter
+    self.handled_at = timezone.now()
+    self.notes = f"Rejected: {reason}" if reason else "Rejected"
+    self.save()
+```
+
+```python
+def escalate(self, moderator: UserType = None, reason: str = "", user=None) -> None:
+    # Use FSM transition to update status
+    self.transition_to_escalated(user=escalator)
+    self.handled_by = escalator
+    self.handled_at = timezone.now()
+    self.notes = f"Escalated: {reason}" if reason else "Escalated"
+    self.save()
+```
+
+Updated `PhotoSubmission` methods similarly:
+
+```python
+def approve(self, moderator: UserType = None, notes: str = "", user=None) -> None:
+    # ... business logic (create ParkPhoto or RidePhoto) ...
+    
+    # Use FSM transition to update status
+    self.transition_to_approved(user=approver)
+    self.handled_by = approver
+    self.handled_at = timezone.now()
+    self.notes = notes
+    self.save()
+```
+
+### Result
+- ✅ No method name conflicts
+- ✅ Business logic preserved in `approve()`, `reject()`, `escalate()` methods
+- ✅ FSM transitions called explicitly by business logic methods
+- ✅ Services continue to call business logic methods unchanged
+- ✅ All side effects (object creation) properly executed
+
+### Verification
+Service layer calls remain unchanged and work correctly:
+```python
+# services.py - calls business logic method which internally uses FSM
+submission.approve(moderator)  # Creates Park/Ride, calls transition_to_approved()
+submission.reject(moderator, reason="...")  # Calls transition_to_rejected()
+```
+
+---
+
+## Comment 2: Missing Django Migration
+
+### Problem
+The status field type changes from `RichChoiceField` to `RichFSMField` across 5 models required a Django migration to be created and committed.
+
+### Solution Implemented
+
+#### Created Migration File
+**File**: `backend/apps/moderation/migrations/0007_convert_status_to_richfsmfield.py`
+
+```python
+class Migration(migrations.Migration):
+    dependencies = [
+        ("moderation", "0006_alter_bulkoperation_operation_type_and_more"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="bulkoperation",
+            name="status",
+            field=apps.core.state_machine.fields.RichFSMField(
+                choice_group="bulk_operation_statuses",
+                default="PENDING",
+                domain="moderation",
+                max_length=20,
+            ),
+        ),
+        # ... similar for other 4 models ...
+    ]
+```
+
+### Migration Details
+
+**Models Updated**:
+1. `EditSubmission` - edit_submission_statuses
+2. `ModerationReport` - moderation_report_statuses
+3. `ModerationQueue` - moderation_queue_statuses
+4. `BulkOperation` - bulk_operation_statuses
+5. `PhotoSubmission` - photo_submission_statuses
+
+**Field Changes**:
+- Type: `RichChoiceField` → `RichFSMField`
+- All other attributes preserved (default, max_length, choice_group, domain)
+
+**Data Safety**:
+- ✅ No data loss - field type change is compatible
+- ✅ Default values preserved
+- ✅ All existing data remains valid
+- ✅ Indexes and constraints maintained
+
+### Result
+- ✅ Migration file created and committed
+- ✅ All 5 models included
+- ✅ Ready to apply with `python manage.py migrate moderation`
+- ✅ Backward compatible
+
+---
+
+## Files Modified Summary
+
+### Core FSM Infrastructure
+- **backend/apps/core/state_machine/builder.py**
+  - Updated `determine_method_name_for_transition()` to use `transition_to_<state>` pattern
+
+### Moderation Models
+- **backend/apps/moderation/models.py**
+  - Updated `EditSubmission.approve()` to call `transition_to_approved()`
+  - Updated `EditSubmission.reject()` to call `transition_to_rejected()`
+  - Updated `EditSubmission.escalate()` to call `transition_to_escalated()`
+  - Updated `PhotoSubmission.approve()` to call `transition_to_approved()`
+  - Updated `PhotoSubmission.reject()` to call `transition_to_rejected()`
+  - Updated `PhotoSubmission.escalate()` to call `transition_to_escalated()`
+
+### Migrations
+- **backend/apps/moderation/migrations/0007_convert_status_to_richfsmfield.py** (NEW)
+  - Converts status fields from RichChoiceField to RichFSMField
+  - Covers all 5 moderation models
+
+### Documentation
+- **backend/apps/moderation/FSM_MIGRATION.md**
+  - Updated to reflect completed migration and verification fixes
+
+---
+
+## Testing Recommendations
+
+### 1. Verify FSM Method Generation
+```python
+# Should have transition_to_* methods, not approve/reject/escalate
+submission = EditSubmission.objects.first()
+assert hasattr(submission, 'transition_to_approved')
+assert hasattr(submission, 'transition_to_rejected')
+assert hasattr(submission, 'transition_to_escalated')
+```
+
+### 2. Verify Business Logic Methods Exist
+```python
+# Business logic methods should still exist
+assert hasattr(submission, 'approve')
+assert hasattr(submission, 'reject')
+assert hasattr(submission, 'escalate')
+```
+
+### 3. Test Approve Workflow
+```python
+# Should create Park/Ride object AND transition state
+submission = EditSubmission.objects.create(...)
+obj = submission.approve(moderator)
+assert obj is not None  # Object created
+assert submission.status == 'APPROVED'  # State transitioned
+```
+
+### 4. Test FSM Transitions Directly
+```python
+# FSM transitions should work independently
+submission.transition_to_approved(user=moderator)
+assert submission.status == 'APPROVED'
+```
+
+### 5. Apply and Test Migration
+```bash
+# Apply migration
+python manage.py migrate moderation
+
+# Verify field types
+python manage.py shell
+>>> from apps.moderation.models import EditSubmission
+>>> field = EditSubmission._meta.get_field('status')
+>>> print(type(field))  # Should be RichFSMField
+```
+
+---
+
+## Benefits of These Fixes
+
+### 1. Method Name Clarity
+- Clear distinction between FSM transitions (`transition_to_*`) and business logic (`approve`, `reject`, `escalate`)
+- No naming conflicts
+- Intent is obvious from method name
+
+### 2. Business Logic Preservation
+- All side effects properly executed
+- Object creation logic intact
+- No code duplication
+
+### 3. Backward Compatibility
+- Service layer requires no changes
+- API remains unchanged
+- Tests require minimal updates
+
+### 4. Flexibility
+- Business logic methods can be extended without affecting FSM
+- FSM transitions can be called directly when needed
+- Clear separation of concerns
+
+---
+
+## Rollback Procedure
+
+If issues arise with these fixes:
+
+### 1. Revert Method Naming Change
+```bash
+git revert <commit_hash_for_builder_py_change>
+```
+
+### 2. Revert Business Logic Updates
+```bash
+git revert <commit_hash_for_models_py_change>
+```
+
+### 3. Rollback Migration
+```bash
+python manage.py migrate moderation 0006_alter_bulkoperation_operation_type_and_more
+```
+
+### 4. Delete Migration File
+```bash
+rm backend/apps/moderation/migrations/0007_convert_status_to_richfsmfield.py
+```
+
+---
+
+## Conclusion
+
+Both verification comments have been fully addressed:
+
+✅ **Comment 1**: FSM method naming changed to `transition_to_<state>` pattern, business logic methods preserved and updated to call FSM transitions internally
+
+✅ **Comment 2**: Django migration created for all 5 models converting RichChoiceField to RichFSMField
+
+The implementation maintains full backward compatibility while properly integrating FSM state management with existing business logic.