Core Framework

class CremeEntity(CremeModel):
    """
    Base class for all business entities in Creme CRM.
    Provides common functionality like properties, relationships, permissions, and history.

    Fields:
    - created: CreationDateTimeField, creation timestamp (auto-set, non-clonable)
    - modified: ModificationDateTimeField, last modification timestamp (auto-set)
    - entity_type: CTypeForeignKey, content type (auto-set, non-editable)
    - header_filter_search_field: CharField(200), searchable field content (auto-generated)
    - is_deleted: BooleanField, soft deletion flag (default: False)
    - user: CremeUserForeignKey, owner user
    - description: TextField, entity description (optional)
    - uuid: UUIDField, unique identifier (auto-generated, non-editable)
    - sandbox: ForeignKey(Sandbox), isolation/security context (optional)
    - extra_data: JSONField, additional data storage (default: {})

    Manager: CremeEntityManager
    Meta: Ordered by header_filter_search_field

    Methods:
    - get_absolute_url(): Get entity detail URL
    - get_edit_absolute_url(): Get entity edit URL
    - get_delete_url(): Get entity deletion URL
    - get_lv_absolute_url(): Get list view URL
    - trash(): Soft delete the entity
    - restore(): Restore soft deleted entity
    - clone(): Create a copy of the entity
    """

class CremeModel(models.Model):
    """
    Base model class for Creme CRM models.
    Provides common functionality for all models.

    Attributes:
    - created: datetime, creation timestamp
    - modified: datetime, last modification timestamp
    """

class MinionModel(models.Model):
    """
    Base class for auxiliary models that support main entities.
    Used for configuration and supporting data structures.
    """

class CremeUser(AbstractUser):
    """
    Extended Django user model with CRM-specific fields and functionality.

    Attributes:
    - displayed_name: str, display name for UI
    - language: str, preferred language code
    - time_zone: str, user timezone
    - role: UserRole, assigned role for permissions
    - is_team: bool, indicates team user account
    - json_settings: JSONField, user preferences storage

    Methods:
    - get_teams(): Get teams this user belongs to
    - has_perm_to_access(app_label): Check app access permission
    - has_perm_to_view(entity): Check entity view permission
    - has_perm_to_change(entity): Check entity edit permission
    - has_perm_to_delete(entity): Check entity delete permission
    - has_perm_to_link(entity): Check entity link permission
    - has_perm_to_unlink(entity): Check entity unlink permission
    """

class UserRole(models.Model):
    """
    Role-based permission system for users.

    Attributes:
    - name: str, role name
    - allowed_apps: ManyToMany, accessible applications
    - admin_4_apps: ManyToMany, applications with admin rights
    - creatable_ctypes: ManyToMany, entities user can create
    - exportable_ctypes: ManyToMany, entities user can export

    Methods:
    - can_access(app_label): Check if role allows app access
    - can_admin(app_label): Check if role has admin rights for app
    - can_create(ctype): Check if role can create entity type
    - can_export(ctype): Check if role can export entity type
    """

class Relation(models.Model):
    """
    Relationship between two entities with a specific type.

    Attributes:
    - user: CremeUser, user who created the relationship
    - type: RelationType, type of relationship
    - subject_entity: CremeEntity, source entity
    - object_entity: CremeEntity, target entity
    - symmetric_relation: Relation, reverse relation for bidirectional types

    Methods:
    - delete(): Delete relationship and symmetric counterpart
    - get_symmetric_relation(): Get the reverse relationship
    """

class RelationType(models.Model):
    """
    Definition of relationship types between entities.

    Attributes:
    - id: str, unique identifier
    - predicate: str, relationship description (subject -> object)
    - symmetric_type: RelationType, reverse type for bidirectional relations
    - is_copiable: bool, whether relation should be copied when cloning entities
    - enabled: bool, whether this relation type is active
    - subject_ctypes: ManyToMany, allowed subject entity types
    - object_ctypes: ManyToMany, allowed object entity types
    - subject_properties: ManyToMany, required subject properties
    - object_properties: ManyToMany, required object properties

    Methods:
    - is_compatible(subject_ctype, object_ctype): Check type compatibility
    - get_compatible_subject_ctypes(): Get allowed subject types
    - get_compatible_object_ctypes(): Get allowed object types
    """

class SemiFixedRelationType(models.Model):
    """
    Predefined relationship types with specific configurations.
    Used for system-defined relationships like 'has' or 'owns'.

    Attributes:
    - relation_type: RelationType, the actual relation type
    - predicate: str, relationship description
    - object_entity: CremeEntity, fixed target entity (optional)
    """

class CremeProperty(models.Model):
    """
    Property assigned to an entity, providing flexible attributes.

    Attributes:
    - type: CremePropertyType, property type definition
    - creme_entity: CremeEntity, entity this property belongs to
    - value: str, optional property value

    Methods:
    - __str__(): String representation of property
    """

class CremePropertyType(models.Model):
    """
    Definition of property types that can be assigned to entities.

    Attributes:
    - uuid: str, unique identifier
    - text: str, human-readable description
    - is_custom: bool, whether this is a user-defined property type
    - is_copiable: bool, whether property should be copied when cloning entities
    - subject_ctypes: ManyToMany, allowed entity types for this property

    Methods:
    - can_be_assigned_to(entity_type): Check if property can be assigned to entity type
    - generate_uuid(): Generate unique UUID for new property types
    """

class EntityCredentials(models.Model):
    """
    Entity-level permissions for users and roles.

    Attributes:
    - role: UserRole, role these credentials apply to
    - value: int, permission bitmask (VIEW, CHANGE, DELETE, LINK, UNLINK)
    - set_type: int, whether permissions are granted or forbidden
    - ctype: ContentType, entity type these permissions apply to
    - efilter: EntityFilter, filter to limit which entities permissions apply to

    Constants:
    - VIEW: Permission to view entities
    - CHANGE: Permission to modify entities
    - DELETE: Permission to delete entities
    - LINK: Permission to create relationships with entities
    - UNLINK: Permission to remove relationships from entities

    Methods:
    - get_permissions(): Get list of permission names
    - has_perm(perm): Check if specific permission is included
    """

class SetCredentials(models.Model):
    """
    Permission sets that can be assigned to users for specific entity types.

    Attributes:
    - role: UserRole, role these credentials belong to
    - value: int, permission bitmask
    - set_type: int, grant or forbid permissions
    - ctype: ContentType, entity type
    - efilter: EntityFilter, entity filter for conditional permissions

    Methods:
    - can_view(): Check if view permission is granted
    - can_change(): Check if change permission is granted
    - can_delete(): Check if delete permission is granted
    - can_link(): Check if link permission is granted
    - can_unlink(): Check if unlink permission is granted
    """

class Sandbox(models.Model):
    """
    User sandboxing system for isolating user data.

    Attributes:
    - uuid: str, unique sandbox identifier
    - user: CremeUser, sandbox owner
    - type: ContentType, entity type this sandbox applies to
    - role: UserRole, role for sandbox permissions

    Methods:
    - check_perm(user, perm): Check if user has permission in this sandbox
    - get_related_entities(): Get entities associated with this sandbox
    """

def get_concrete_model(model_setting: str) -> type[models.Model]:
    """
    Get the concrete model class that is active in this project.

    Parameters:
    - model_setting: str, settings key containing model path

    Returns:
    type[models.Model]: The actual model class

    Raises:
    - ImproperlyConfigured: If setting is malformed or model doesn't exist

    Example:
    ContactModel = get_concrete_model('PERSONS_CONTACT_MODEL')
    """

def get_world_settings_model():
    """
    Get the WorldSettings model that is active in this project.

    Returns:
    type[WorldSettings]: The WorldSettings model class
    """

class FieldsConfig(models.Model):
    """
    Configuration for field visibility and behavior per entity type.

    Attributes:
    - content_type: ContentType, entity type this config applies to
    - descriptions: JSONField, field configuration data

    Methods:
    - is_field_hidden(field_name): Check if field should be hidden
    - is_field_required(field_name): Check if field is required
    - get_4_model(model): Get field configuration for model
    - create_4_model(model, **kwargs): Create configuration for model
    """

class EntityFilter(models.Model):
    """
    Saved filters for entity queries with conditions.

    Attributes:
    - id: str, unique filter identifier
    - name: str, human-readable filter name
    - entity_type: ContentType, entity type this filter applies to
    - filter_type: int, filter type (regular, private, etc.)
    - user: CremeUser, filter owner (for private filters)
    - is_custom: bool, whether this is a user-defined filter
    - use_or: bool, whether conditions use OR logic (default: AND)

    Methods:
    - can_view(user): Check if user can view this filter
    - can_edit(user): Check if user can edit this filter
    - can_delete(user): Check if user can delete this filter
    - get_conditions(): Get filter conditions
    - filter_queryset(queryset): Apply filter to queryset
    """

class EntityFilterCondition(models.Model):
    """
    Individual condition within an entity filter.

    Attributes:
    - filter: EntityFilter, parent filter
    - type: int, condition type (field, relation, property, etc.)
    - name: str, field/condition name
    - value: JSONField, condition value and parameters

    Methods:
    - decode_value(): Parse condition value
    - apply_to_queryset(queryset): Apply condition to queryset
    """

# Permission constants
VIEW = 1
CHANGE = 2
DELETE = 4
LINK = 8
UNLINK = 16

# Deletion behavior
CREME_REPLACE = 1      # Replace deleted entity with another
CREME_REPLACE_NULL = 2 # Set foreign keys to null on deletion

# Root user credentials
ROOT_USERNAME = "root"
ROOT_PASSWORD = "root"

# Core relation types
REL_SUB_HAS = "creme_core-subject_has"
REL_OBJ_HAS = "creme_core-object_has"