Permission System

Two permission systems exist—use the right one for the context.

Quick Reference

PermissionManager (Object-Level)

For checking permissions on specific objects:

# In views - use permission mixins
class CharacterDetailView(ViewPermissionMixin, DetailView):
    pass  # Automatically checks VIEW_FULL permission

class CharacterUpdateView(EditPermissionMixin, MessageMixin, UpdateView):
    pass  # Automatically checks EDIT_FULL permission

# Explicit permission checks
from core.permissions import PermissionManager
pm = PermissionManager()
if pm.check_permission(user, character, 'edit_full'):
    # Allow editing

is_st() (Role-Based)

For general storyteller checks not tied to specific objects:

# In forms - determine available options
if user.profile.is_st():
    # Show ST-only form fields

# In templates
{% if user.profile.is_st %}
    <!-- ST-only controls -->
{% endif %}

View Mixins

All mixins in core/mixins.py:

from core.mixins import (
    ViewPermissionMixin,      # VIEW_FULL permission
    EditPermissionMixin,      # EDIT_FULL permission
    SpendXPPermissionMixin,   # XP spending permission
    SpendFreebiesPermissionMixin,  # Freebie spending permission
    VisibilityFilterMixin,    # Filter queryset by visibility
    OwnerRequiredMixin,       # Must be object owner
    STRequiredMixin,          # Must be storyteller
    MessageMixin,             # Success and error messages
)

Mixin Stacking Order (left to right)

class MyView(EditPermissionMixin, MessageMixin, UpdateView): pass
class MyListView(VisibilityFilterMixin, ListView): pass
class MyCreateView(LoginRequiredMixin, MessageMixin, CreateView): pass
class MySTView(STRequiredMixin, MessageMixin, CreateView): pass

Limited Forms for Owners

Owners can only edit descriptive fields:

def get_form_class(self):
    if self.request.user.profile.is_st() or self.request.user.is_staff:
        return CharacterForm  # Full form
    return LimitedCharacterEditForm  # Restricted fields only

Limited Form Pattern

class LimitedCharacterEditForm(forms.ModelForm):
    class Meta:
        model = Character
        fields = ["notes", "description", "public_info", "image", "history", "goals"]

Only allow: notes, description, public_info, image, history, goals. Never allow owners to edit: stats, XP, status, mechanical fields.

Detailed Documentation

For comprehensive implementation details, see:

• references/implementation-guide.md - Full PermissionManager implementation, query optimization, view patterns
• references/user-profile-pattern.md - User + Profile architecture, performance tips

Guidelines

• Use PermissionManager/mixins for detail/update/delete views
• Use is_st() for forms, templates, general role checks
• Use Limited forms to restrict owner editing
• Permission mixins handle view-level checks automatically
• See docs/design/permissions_system.md for full design documentation