Add state machine diagrams and code examples for ThrillWiki

- Created a comprehensive documentation file for state machine diagrams, detailing various states and transitions for models such as EditSubmission, ModerationReport, and Park Status. - Included transition matrices for each state machine to clarify role requirements and guards. - Developed a new document providing code examples for implementing state machines, including adding new state machines to models, defining custom guards, implementing callbacks, and testing state machines. - Added examples for document approval workflows, custom guards, email notifications, and cache invalidation callbacks. - Implemented a test suite for document workflows, covering various scenarios including approval, rejection, and transition logging.
2025-12-22 18:11:09 -05:00 · 2025-12-21 20:21:54 -05:00
parent 8f6acbdc23
commit b508434574
24 changed files with 9979 additions and 360 deletions
--- a/docs/state_machines/diagrams.md
+++ b/docs/state_machines/diagrams.md
@@ -0,0 +1,383 @@
+# State Machine Diagrams
+
+This document contains Mermaid state diagrams for all models with state machines in ThrillWiki.
+
+## EditSubmission / PhotoSubmission States
+
+User submissions for edits and photos follow the same state flow.
+
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING: User submits
+    
+    PENDING --> APPROVED: Moderator approves
+    PENDING --> REJECTED: Moderator rejects
+    PENDING --> ESCALATED: Moderator escalates
+    
+    ESCALATED --> APPROVED: Admin approves
+    ESCALATED --> REJECTED: Admin rejects
+    
+    APPROVED --> [*]
+    REJECTED --> [*]
+    
+    note right of PENDING
+        Guards: None (any authenticated user)
+        Callbacks: None
+    end note
+    
+    note right of APPROVED
+        Guards: PermissionGuard (moderator+)
+        Callbacks: 
+        - Apply changes to target object
+        - Send approval notification
+        - Invalidate cache
+    end note
+    
+    note right of REJECTED
+        Guards: PermissionGuard (moderator+)
+        Callbacks:
+        - Send rejection notification with reason
+    end note
+    
+    note right of ESCALATED
+        Guards: PermissionGuard (moderator+)
+        Callbacks:
+        - Notify admins of escalation
+        - Update escalation_level
+    end note
+```
+
+### Transition Matrix
+
+| From State | To State | Required Role | Guard |
+|------------|----------|---------------|-------|
+| PENDING | APPROVED | MODERATOR+ | PermissionGuard |
+| PENDING | REJECTED | MODERATOR+ | PermissionGuard |
+| PENDING | ESCALATED | MODERATOR+ | PermissionGuard |
+| ESCALATED | APPROVED | ADMIN+ | PermissionGuard |
+| ESCALATED | REJECTED | ADMIN+ | PermissionGuard |
+
+## ModerationReport States
+
+Content reports from users follow a review workflow.
+
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING: User reports content
+    
+    PENDING --> UNDER_REVIEW: Moderator claims report
+    
+    UNDER_REVIEW --> RESOLVED: Issue fixed
+    UNDER_REVIEW --> DISMISSED: Invalid report
+    
+    RESOLVED --> [*]
+    DISMISSED --> [*]
+    
+    note right of PENDING
+        Priority: LOW, MEDIUM, HIGH, CRITICAL
+        Auto-assigned based on report type
+    end note
+    
+    note right of UNDER_REVIEW
+        Guards: PermissionGuard (moderator+)
+        Sets: assigned_moderator
+        Callbacks: Update queue counts
+    end note
+    
+    note right of RESOLVED
+        Guards: AssignmentGuard (assigned moderator)
+        Sets: resolved_at, resolution_action
+        Callbacks: Notify reporter
+    end note
+    
+    note right of DISMISSED
+        Guards: AssignmentGuard (assigned moderator)
+        Sets: resolved_at, resolution_notes
+        Callbacks: Notify reporter
+    end note
+```
+
+### Transition Matrix
+
+| From State | To State | Required Role | Additional Guard |
+|------------|----------|---------------|------------------|
+| PENDING | UNDER_REVIEW | MODERATOR+ | None |
+| UNDER_REVIEW | RESOLVED | MODERATOR+ | AssignmentGuard |
+| UNDER_REVIEW | DISMISSED | MODERATOR+ | AssignmentGuard |
+
+## ModerationQueue States
+
+Queue items for moderator work.
+
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING: Item created
+    
+    PENDING --> IN_PROGRESS: Moderator claims
+    PENDING --> CANCELLED: Cancelled
+    
+    IN_PROGRESS --> COMPLETED: Work finished
+    IN_PROGRESS --> CANCELLED: Cancelled
+    
+    COMPLETED --> [*]
+    CANCELLED --> [*]
+    
+    note right of IN_PROGRESS
+        Guards: PermissionGuard (moderator+)
+        Sets: assigned_to, assigned_at
+    end note
+    
+    note right of COMPLETED
+        Guards: AssignmentGuard
+        Sets: completed_at
+    end note
+```
+
+## BulkOperation States
+
+Admin bulk operations with progress tracking.
+
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING: Operation created
+    
+    PENDING --> RUNNING: Operation starts
+    PENDING --> CANCELLED: Admin cancels
+    
+    RUNNING --> COMPLETED: All items processed
+    RUNNING --> FAILED: Fatal error
+    RUNNING --> CANCELLED: Admin cancels (if cancellable)
+    
+    COMPLETED --> [*]
+    FAILED --> [*]
+    CANCELLED --> [*]
+    
+    note right of PENDING
+        Guards: PermissionGuard (admin+)
+        Fields: total_items, parameters
+    end note
+    
+    note right of RUNNING
+        Guards: PermissionGuard (admin+)
+        Sets: started_at
+        Progress: processed_items / total_items
+    end note
+    
+    note right of COMPLETED
+        Sets: completed_at
+        Fields: processed_items, results
+    end note
+    
+    note right of FAILED
+        Sets: completed_at
+        Fields: failed_items, results (error)
+    end note
+```
+
+### Transition Matrix
+
+| From State | To State | Required Role | Condition |
+|------------|----------|---------------|-----------|
+| PENDING | RUNNING | ADMIN+ | None |
+| PENDING | CANCELLED | ADMIN+ | None |
+| RUNNING | COMPLETED | ADMIN+ | None |
+| RUNNING | FAILED | ADMIN+ | None |
+| RUNNING | CANCELLED | ADMIN+ | can_cancel=True |
+
+## Park Status States
+
+Park lifecycle management.
+
+```mermaid
+stateDiagram-v2
+    [*] --> UNDER_CONSTRUCTION: New park announced
+    [*] --> OPERATING: Existing park
+
+    UNDER_CONSTRUCTION --> OPERATING: Grand opening
+    
+    OPERATING --> CLOSED_TEMP: Seasonal/temporary closure
+    OPERATING --> CLOSED_PERM: Permanent closure
+    
+    CLOSED_TEMP --> OPERATING: Reopens
+    CLOSED_TEMP --> CLOSED_PERM: Becomes permanent
+    
+    CLOSED_PERM --> DEMOLISHED: Site cleared
+    CLOSED_PERM --> RELOCATED: Moved to new location
+    
+    DEMOLISHED --> [*]
+    RELOCATED --> [*]
+    
+    note right of OPERATING
+        Default state for active parks
+        Guards: Any authenticated user
+    end note
+    
+    note right of CLOSED_TEMP
+        Seasonal closures, maintenance
+        Guards: Any authenticated user
+    end note
+    
+    note right of CLOSED_PERM
+        Guards: PermissionGuard (moderator+)
+        Sets: closing_date
+        Callbacks: Update ride statuses
+    end note
+    
+    note right of DEMOLISHED
+        Guards: PermissionGuard (moderator+)
+        Final state - no transitions out
+    end note
+    
+    note right of RELOCATED
+        Guards: PermissionGuard (moderator+)
+        Final state - link to new location
+    end note
+```
+
+### Transition Matrix
+
+| From State | To State | Required Role | Sets |
+|------------|----------|---------------|------|
+| UNDER_CONSTRUCTION | OPERATING | USER+ | None |
+| OPERATING | CLOSED_TEMP | USER+ | None |
+| OPERATING | CLOSED_PERM | MODERATOR+ | closing_date |
+| CLOSED_TEMP | OPERATING | USER+ | None |
+| CLOSED_TEMP | CLOSED_PERM | MODERATOR+ | closing_date |
+| CLOSED_PERM | DEMOLISHED | MODERATOR+ | None |
+| CLOSED_PERM | RELOCATED | MODERATOR+ | None |
+
+## Ride Status States
+
+Ride lifecycle with scheduled closures.
+
+```mermaid
+stateDiagram-v2
+    [*] --> UNDER_CONSTRUCTION: New ride announced
+    [*] --> OPERATING: Existing ride
+
+    UNDER_CONSTRUCTION --> OPERATING: Grand opening
+    
+    OPERATING --> CLOSED_TEMP: Maintenance/refurb
+    OPERATING --> SBNO: Extended closure
+    OPERATING --> CLOSING: Scheduled closure
+    
+    CLOSED_TEMP --> OPERATING: Reopens
+    CLOSED_TEMP --> SBNO: Extended to SBNO
+    CLOSED_TEMP --> CLOSED_PERM: Permanent closure
+    
+    SBNO --> OPERATING: Revival
+    SBNO --> CLOSED_PERM: Confirmed closure
+    
+    CLOSING --> SBNO: Becomes SBNO
+    CLOSING --> CLOSED_PERM: Closure date reached
+    
+    CLOSED_PERM --> DEMOLISHED: Removed
+    CLOSED_PERM --> RELOCATED: Moved
+    
+    DEMOLISHED --> [*]
+    RELOCATED --> [*]
+    
+    note right of OPERATING
+        Active ride
+        Guards: Any authenticated user
+    end note
+    
+    note right of CLOSED_TEMP
+        Short-term closure
+        Guards: Any authenticated user
+    end note
+    
+    note right of SBNO
+        Standing But Not Operating
+        Guards: PermissionGuard (moderator+)
+        Long-term uncertainty
+    end note
+    
+    note right of CLOSING
+        Scheduled to close
+        Guards: PermissionGuard (moderator+)
+        Requires: closing_date, post_closing_status
+        Automated transition on date
+    end note
+    
+    note right of CLOSED_PERM
+        Guards: PermissionGuard (moderator+)
+        Sets: closing_date
+    end note
+    
+    note right of DEMOLISHED
+        Guards: PermissionGuard (moderator+)
+        Final state
+    end note
+    
+    note right of RELOCATED
+        Guards: PermissionGuard (moderator+)
+        Final state - link to new installation
+    end note
+```
+
+### CLOSING State Automation
+
+The CLOSING state is special - it represents a ride that has been announced to close on a specific date. When the `closing_date` is reached, the ride automatically transitions to the `post_closing_status` (SBNO, CLOSED_PERM, DEMOLISHED, or RELOCATED).
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Ride
+    participant Scheduler
+    
+    User->>Ride: mark_closing(closing_date, post_closing_status)
+    Ride->>Ride: transition_to_closing()
+    Ride->>Ride: Set closing_date, post_closing_status
+    Ride->>Ride: Save
+    
+    Note over Scheduler: Daily job runs
+    
+    Scheduler->>Ride: Check closing_date <= today
+    alt Date reached
+        Scheduler->>Ride: apply_post_closing_status()
+        Ride->>Ride: Transition to post_closing_status
+        Ride->>Ride: Save
+    end
+```
+
+### Transition Matrix
+
+| From State | To State | Required Role | Sets |
+|------------|----------|---------------|------|
+| UNDER_CONSTRUCTION | OPERATING | USER+ | None |
+| OPERATING | CLOSED_TEMP | USER+ | None |
+| OPERATING | SBNO | MODERATOR+ | None |
+| OPERATING | CLOSING | MODERATOR+ | closing_date, post_closing_status |
+| CLOSED_TEMP | OPERATING | USER+ | None |
+| CLOSED_TEMP | SBNO | MODERATOR+ | None |
+| CLOSED_TEMP | CLOSED_PERM | MODERATOR+ | closing_date |
+| SBNO | OPERATING | MODERATOR+ | None |
+| SBNO | CLOSED_PERM | MODERATOR+ | None |
+| CLOSING | SBNO | MODERATOR+ | None |
+| CLOSING | CLOSED_PERM | MODERATOR+ | None |
+| CLOSED_PERM | DEMOLISHED | MODERATOR+ | None |
+| CLOSED_PERM | RELOCATED | MODERATOR+ | None |
+
+## State Color Legend
+
+All state machines use consistent colors for states:
+
+| Color | Meaning | Example States |
+|-------|---------|----------------|
+| 🟡 Yellow | Pending/Waiting | PENDING, UNDER_REVIEW, CLOSING |
+| 🟢 Green | Active/Approved | OPERATING, APPROVED, COMPLETED |
+| 🔴 Red | Closed/Rejected | REJECTED, FAILED, CLOSED_PERM |
+| 🟠 Orange | Warning/SBNO | SBNO, ESCALATED, IN_PROGRESS |
+| ⚫ Gray | Final/Terminal | DEMOLISHED, RELOCATED, CANCELLED |
+| 🔵 Blue | Temporary | CLOSED_TEMP, UNDER_CONSTRUCTION |
+
+## Guard Icons
+
+| Icon | Guard Type | Description |
+|------|-----------|-------------|
+| 🔐 | PermissionGuard | Role-based access |
+| 👤 | OwnershipGuard | Owner verification |
+| 📋 | AssignmentGuard | Assigned user check |
+| 📊 | StateGuard | State validation |
+| 📝 | MetadataGuard | Required fields |