thrillwiki_django_no_react/.clinerules/rich-choice-objects.md

description, author, version, globs, tags

description	author	version	globs	tags
Mandatory Rich Choice Objects system enforcement for ThrillWiki project replacing Django tuple-based choices with rich metadata-driven choice fields	ThrillWiki Development Team	1.0	apps/**/choices.py apps/**/models.py apps/**/serializers.py apps/**/__init__.py	django choices rich-choice-objects data-modeling mandatory

Rich Choice Objects System (MANDATORY)

Objective

This rule enforces the mandatory use of the Rich Choice Objects system instead of Django's traditional tuple-based choices for ALL choice fields in the ThrillWiki project. It ensures consistent, metadata-rich choice handling with enhanced UI capabilities and maintainable code patterns.

Brief Overview

Mandatory use of Rich Choice Objects system instead of Django tuple-based choices for all choice fields in ThrillWiki project.

Rich Choice Objects Enforcement

Absolute Requirements

🚨 NEVER use Django tuple-based choices (e.g., choices=[('VALUE', 'Label')]) - ALWAYS use RichChoiceField

Implementation Standards

• Field Usage: All choice fields MUST use RichChoiceField(choice_group="group_name", domain="domain_name") pattern
• Choice Definitions: MUST be created in domain-specific choices.py files using RichChoice dataclass
• Rich Metadata: All choices MUST include rich metadata (color, icon, description, css_class at minimum)
• Registration: Choice groups MUST be registered with global registry using register_choices() function
• Auto-Registration: Import choices in domain __init__.py to trigger auto-registration on Django startup

Required Patterns

• Categorization: Use ChoiceCategory enum for proper categorization (STATUS, CLASSIFICATION, TECHNICAL, SECURITY)
• Business Logic: Leverage rich metadata for UI styling, permissions, and business logic instead of hardcoded values
• Serialization: Update serializers to use RichChoiceSerializer for choice fields

Migration Requirements

• NO Backwards Compatibility: DO NOT maintain backwards compatibility with tuple-based choices - migrate fully to Rich Choice Objects
• Model Refactoring: Ensure all existing models using tuple-based choices are refactored to use RichChoiceField
• Validation: Validate choice groups are correctly loaded in registry during application startup

Domain Consistency

• Follow Established Patterns: Follow established patterns from rides, parks, and accounts domains for consistency
• Domain-Specific Organization: Maintain domain-specific choice organization in separate choices.py files

Implementation Checklist

Before implementing choice fields, verify:

• RichChoiceField is used instead of Django tuple choices
• Choice group and domain are properly specified
• Rich metadata includes color, icon, description, css_class
• Choices are defined in domain-specific choices.py file
• Choice group is registered with register_choices() function
• Domain __init__.py imports choices for auto-registration
• Appropriate ChoiceCategory enum is used
• Serializers use RichChoiceSerializer for choice fields
• No tuple-based choices remain in the codebase

Examples

✅ CORRECT Implementation

# In apps/rides/choices.py
from core.choices import RichChoice, ChoiceCategory, register_choices

RIDE_STATUS_CHOICES = [
    RichChoice(
        value="operating",
        label="Operating",
        color="#10b981",
        icon="check-circle",
        description="Ride is currently operating normally",
        css_class="status-operating",
        category=ChoiceCategory.STATUS
    ),
    # ... more choices
]

register_choices("ride_status", RIDE_STATUS_CHOICES, domain="rides")

# In models.py
status = RichChoiceField(choice_group="ride_status", domain="rides")

❌ FORBIDDEN Implementation

# NEVER DO THIS - Tuple-based choices are forbidden
STATUS_CHOICES = [
    ('operating', 'Operating'),
    ('closed', 'Closed'),
]

status = models.CharField(max_length=20, choices=STATUS_CHOICES)

Verification Steps

To ensure compliance:

1. Search codebase for any remaining tuple-based choice patterns
2. Verify all choice fields use RichChoiceField
3. Confirm all choices have complete rich metadata
4. Test choice group registration during application startup
5. Validate serializers use RichChoiceSerializer where appropriate