amsdal_crm 0.1.0__py3-none-any.whl

amsdal_crm/models/deal.py

@@ -0,0 +1,172 @@
+"""Deal Model."""
+
+import datetime as _dt
+from typing import Any
+from typing import ClassVar
+from typing import Optional
+
+from amsdal.contrib.auth.models.user import User
+from amsdal.models.mixins import TimestampMixin
+from amsdal_models.classes.data_models.indexes import IndexInfo
+from amsdal_models.classes.model import Model
+from amsdal_utils.models.data_models.reference import Reference
+from amsdal_utils.models.enums import ModuleType
+from pydantic.fields import Field
+
+
+class Deal(TimestampMixin, Model):
+    """Deal (Sales Opportunity) model.
+
+    Represents a sales opportunity linked to an account and contact,
+    progressing through pipeline stages.
+    """
+
+    __module_type__: ClassVar[ModuleType] = ModuleType.CONTRIB
+    __indexes__: ClassVar[list[IndexInfo]] = [
+        IndexInfo(name='idx_deal_owner_email', field='owner_email'),
+        IndexInfo(name='idx_deal_close_date', field='expected_close_date'),
+        IndexInfo(name='idx_deal_created_at', field='created_at'),
+    ]
+
+    # Core fields
+    name: str = Field(title='Deal Name')
+    amount: float | None = Field(default=None, title='Amount', ge=0)
+    currency: str = Field(default='USD', title='Currency')
+
+    # Relationships
+    account: Optional['Account'] = Field(default=None, title='Account')
+    contact: Optional['Contact'] = Field(default=None, title='Primary Contact')
+    stage: 'Stage' = Field(title='Stage')
+    owner_email: str = Field(title='Owner Email')
+
+    # Dates
+    expected_close_date: _dt.datetime | None = Field(default=None, title='Expected Close Date')
+    closed_date: _dt.datetime | None = Field(default=None, title='Closed Date')
+
+    # Status tracking
+    is_closed: bool = Field(default=False, title='Is Closed')
+    is_won: bool = Field(default=False, title='Is Won')
+
+    # Custom fields (JSON)
+    custom_fields: dict[str, Any] | None = Field(default=None, title='Custom Fields')
+
+    @property
+    def display_name(self) -> str:
+        """Return display name for the deal."""
+        return self.name
+
+    @property
+    def stage_name(self) -> str:
+        """Returns stage name for display."""
+        if hasattr(self.stage, 'name'):
+            return self.stage.name
+        return str(self.stage)
+
+    def has_object_permission(self, user: 'User', action: str) -> bool:
+        """Check if user has permission to perform action on this deal.
+
+        Args:
+            user: The user attempting the action
+            action: The action being attempted (read, create, update, delete)
+
+        Returns:
+            True if user has permission, False otherwise
+        """
+        # Owner has all permissions
+        if self.owner_email == user.email:
+            return True
+
+        # Check admin permissions
+        if user.permissions:
+            for permission in user.permissions:
+                if permission.model == '*' and permission.action in ('*', action):
+                    return True
+                if permission.model == 'Deal' and permission.action in ('*', action):
+                    return True
+
+        return False
+
+    def pre_create(self) -> None:
+        """Hook called before creating deal."""
+        if self.custom_fields:
+            from amsdal_crm.services.custom_field_service import CustomFieldService
+
+            self.custom_fields = CustomFieldService.validate_custom_fields('Deal', self.custom_fields)
+        super().pre_create()
+
+    async def apre_create(self) -> None:
+        """Async hook called before creating deal."""
+        if self.custom_fields:
+            from amsdal_crm.services.custom_field_service import CustomFieldService
+
+            self.custom_fields = CustomFieldService.validate_custom_fields('Deal', self.custom_fields)
+        await super().apre_create()
+
+    def pre_update(self) -> None:
+        """Hook called before updating deal.
+
+        Automatically syncs is_closed and is_won status with stage,
+        and sets closed_date when deal is closed.
+        """
+        # Validate custom fields first
+        if self.custom_fields:
+            from amsdal_crm.services.custom_field_service import CustomFieldService
+
+            self.custom_fields = CustomFieldService.validate_custom_fields('Deal', self.custom_fields)
+
+        # Load stage if it's a reference and sync closed status
+        from amsdal_models.classes.helpers.reference_loader import ReferenceLoader
+
+        stage = ReferenceLoader(self.stage).load_reference() if isinstance(self.stage, Reference) else self.stage
+        self.is_closed = stage.is_closed_won or stage.is_closed_lost
+        self.is_won = stage.is_closed_won
+
+        if self.is_closed and not self.closed_date:
+            self.closed_date = _dt.datetime.now(_dt.UTC)
+
+        # Call parent to handle timestamps
+        super().pre_update()
+
+    async def apre_update(self) -> None:
+        """Async hook called before updating deal.
+
+        Automatically syncs is_closed and is_won status with stage,
+        and sets closed_date when deal is closed.
+        """
+        # Validate custom fields first
+        if self.custom_fields:
+            from amsdal_crm.services.custom_field_service import CustomFieldService
+
+            self.custom_fields = CustomFieldService.validate_custom_fields('Deal', self.custom_fields)
+
+        # Load stage if it's a reference and sync closed status
+        from amsdal_models.classes.helpers.reference_loader import ReferenceLoader
+
+        stage = await ReferenceLoader(self.stage).aload_reference() if isinstance(self.stage, Reference) else self.stage
+        self.is_closed = stage.is_closed_won or stage.is_closed_lost
+        self.is_won = stage.is_closed_won
+
+        if self.is_closed and not self.closed_date:
+            self.closed_date = _dt.datetime.now(_dt.UTC)
+
+        # Call parent to handle timestamps
+        await super().apre_update()
+
+    def post_update(self) -> None:
+        """Hook called after updating deal."""
+        from amsdal_crm.services.workflow_service import WorkflowService
+
+        WorkflowService.execute_rules('Deal', 'update', self)
+
+    async def apost_update(self) -> None:
+        """Async hook called after updating deal."""
+        from amsdal_crm.services.workflow_service import WorkflowService
+
+        WorkflowService.execute_rules('Deal', 'update', self)
+
+
+from amsdal_crm.models.account import Account
+from amsdal_crm.models.contact import Contact
+from amsdal_crm.models.stage import Stage
+
+Deal.model_rebuild()

amsdal_crm/models/pipeline.py

@@ -0,0 +1,28 @@
+"""Pipeline Model."""
+
+from typing import ClassVar
+
+from amsdal_models.classes.data_models.constraints import UniqueConstraint
+from amsdal_models.classes.model import Model
+from amsdal_utils.models.enums import ModuleType
+from pydantic.fields import Field
+
+
+class Pipeline(Model):
+    """Sales pipeline model.
+
+    Represents a sales pipeline with multiple stages.
+    Pipelines are system-wide and not owned by individual users.
+    """
+
+    __module_type__: ClassVar[ModuleType] = ModuleType.CONTRIB
+    __constraints__: ClassVar[list[UniqueConstraint]] = [UniqueConstraint(name='unq_pipeline_name', fields=['name'])]
+
+    name: str = Field(title='Pipeline Name')
+    description: str | None = Field(default=None, title='Description')
+    is_active: bool = Field(default=True, title='Is Active')
+
+    @property
+    def display_name(self) -> str:
+        """Return display name for the pipeline."""
+        return self.name

amsdal_crm/models/stage.py

@@ -0,0 +1,47 @@
+"""Stage Model."""
+
+from typing import ClassVar
+
+from amsdal_models.classes.data_models.constraints import UniqueConstraint
+from amsdal_models.classes.data_models.indexes import IndexInfo
+from amsdal_models.classes.model import Model
+from amsdal_utils.models.enums import ModuleType
+from pydantic import ConfigDict
+from pydantic.fields import Field
+
+
+class Stage(Model):
+    """Pipeline stage model.
+
+    Represents a stage within a sales pipeline with win probability
+    and closed status indicators.
+    """
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(arbitrary_types_allowed=True)
+
+    __module_type__: ClassVar[ModuleType] = ModuleType.CONTRIB
+    __constraints__: ClassVar[list[UniqueConstraint]] = [
+        UniqueConstraint(name='unq_stage_pipeline_name', fields=['pipeline', 'name'])
+    ]
+    __indexes__: ClassVar[list[IndexInfo]] = [
+        IndexInfo(name='idx_stage_order', field='order'),
+    ]
+
+    pipeline: 'Pipeline' = Field(title='Pipeline')
+    name: str = Field(title='Stage Name')
+    order: int = Field(title='Order')
+    probability: float = Field(default=0.0, title='Win Probability (%)', ge=0, le=100)
+    is_closed_won: bool = Field(default=False, title='Is Closed Won')
+    is_closed_lost: bool = Field(default=False, title='Is Closed Lost')
+
+    @property
+    def display_name(self) -> str:
+        """Return display name for the stage."""
+        if isinstance(self.pipeline, str):
+            return f'{self.pipeline} - {self.name}'
+        return f'{self.pipeline.display_name} - {self.name}'
+
+
+from amsdal_crm.models.pipeline import Pipeline
+
+Stage.model_rebuild()

amsdal_crm/models/workflow_rule.py

@@ -0,0 +1,44 @@
+"""WorkflowRule Model."""
+
+from typing import Any
+from typing import ClassVar
+from typing import Literal
+
+from amsdal_models.classes.model import Model
+from amsdal_utils.models.enums import ModuleType
+from pydantic.fields import Field
+
+
+class WorkflowRule(Model):
+    """Configuration for workflow automation rules.
+
+    Defines rules that trigger actions when certain conditions are met
+    on CRM entities (create, update, delete events).
+    """
+
+    __module_type__: ClassVar[ModuleType] = ModuleType.CONTRIB
+
+    name: str = Field(title='Rule Name')
+    entity_type: Literal['Contact', 'Account', 'Deal', 'Activity'] = Field(title='Entity Type')
+
+    # Trigger
+    trigger_event: Literal['create', 'update', 'delete'] = Field(title='Trigger Event')
+
+    # Condition (simplified - single field condition)
+    condition_field: str | None = Field(None, title='Condition Field')
+    condition_operator: Literal['equals', 'not_equals', 'contains', 'greater_than', 'less_than'] | None = Field(
+        default=None, title='Condition Operator'
+    )
+    condition_value: Any | None = Field(None, title='Condition Value')
+
+    # Action
+    action_type: Literal['update_field', 'create_activity', 'send_notification'] = Field(title='Action Type')
+    action_config: dict[str, Any] = Field(title='Action Configuration')
+
+    # Status
+    is_active: bool = Field(default=True, title='Is Active')
+
+    @property
+    def display_name(self) -> str:
+        """Return display name for the workflow rule."""
+        return f'{self.entity_type}: {self.name}'

amsdal_crm/services/__init__.py

@@ -0,0 +1,15 @@
+"""CRM Services."""
+
+from amsdal_crm.services.activity_service import ActivityService
+from amsdal_crm.services.custom_field_service import CustomFieldService
+from amsdal_crm.services.deal_service import DealService
+from amsdal_crm.services.email_service import EmailService
+from amsdal_crm.services.workflow_service import WorkflowService
+
+__all__ = [
+    'ActivityService',
+    'CustomFieldService',
+    'DealService',
+    'EmailService',
+    'WorkflowService',
+]

amsdal_crm/services/activity_service.py

@@ -0,0 +1,56 @@
+"""ActivityService for managing activities and timelines."""
+
+from amsdal_utils.models.enums import Versions
+
+from amsdal_crm.models.activity import Activity
+from amsdal_crm.models.activity import ActivityRelatedTo
+
+
+class ActivityService:
+    """Service for querying and managing activities."""
+
+    @classmethod
+    def get_timeline(cls, related_to_type: ActivityRelatedTo, related_to_id: str, limit: int = 100) -> list[Activity]:
+        """Get chronological activity timeline for a record.
+
+        Args:
+            related_to_type: Type of record (Contact, Account, Deal)
+            related_to_id: ID of the record
+            limit: Maximum number of activities to return
+
+        Returns:
+            List of activities sorted by created_at desc (newest first)
+        """
+        activities = (
+            Activity.objects.filter(
+                related_to_type=related_to_type, related_to_id=related_to_id, _address__object_version=Versions.LATEST
+            )
+            .order_by('-created_at')
+            .execute()
+        )
+
+        return activities[:limit]
+
+    @classmethod
+    async def aget_timeline(
+        cls, related_to_type: ActivityRelatedTo, related_to_id: str, limit: int = 100
+    ) -> list[Activity]:
+        """Async version of get_timeline.
+
+        Args:
+            related_to_type: Type of record (Contact, Account, Deal)
+            related_to_id: ID of the record
+            limit: Maximum number of activities to return
+
+        Returns:
+            List of activities sorted by created_at desc (newest first)
+        """
+        activities = await (
+            Activity.objects.filter(
+                related_to_type=related_to_type, related_to_id=related_to_id, _address__object_version=Versions.LATEST
+            )
+            .order_by('-created_at')
+            .aexecute()
+        )
+
+        return activities[:limit]

amsdal_crm/services/custom_field_service.py

@@ -0,0 +1,143 @@
+"""CustomFieldService for validating custom field values."""
+
+from datetime import datetime
+from decimal import Decimal
+from decimal import InvalidOperation
+from typing import Any
+
+from amsdal_utils.models.enums import Versions
+
+from amsdal_crm.errors import CustomFieldValidationError
+from amsdal_crm.models.custom_field_definition import CustomFieldDefinition
+
+
+class CustomFieldService:
+    """Service for validating custom field values against their definitions."""
+
+    @classmethod
+    def validate_custom_fields(cls, entity_type: str, custom_fields: dict[str, Any] | None) -> dict[str, Any]:
+        """Validate custom field values against their definitions.
+
+        Args:
+            entity_type: The entity type (Contact, Account, Deal)
+            custom_fields: Dictionary of custom field values
+
+        Returns:
+            Validated custom_fields dict
+
+        Raises:
+            CustomFieldValidationError: If validation fails
+        """
+        if not custom_fields:
+            return {}
+
+        # Load field definitions for this entity type
+        definitions = CustomFieldDefinition.objects.filter(
+            entity_type=entity_type, _address__object_version=Versions.LATEST
+        ).execute()
+
+        definitions_by_name = {d.field_name: d for d in definitions}
+        validated = {}
+
+        for field_name, value in custom_fields.items():
+            if field_name not in definitions_by_name:
+                msg = f'Unknown custom field: {field_name} for {entity_type}'
+                raise CustomFieldValidationError(msg)
+
+            definition = definitions_by_name[field_name]
+
+            # Required check
+            if definition.is_required and value is None:
+                msg = f'Required custom field {field_name} is missing'
+                raise CustomFieldValidationError(msg)
+
+            # Type validation
+            if value is not None:
+                validated[field_name] = cls._validate_field_value(definition, value)
+
+        return validated
+
+    @classmethod
+    async def avalidate_custom_fields(cls, entity_type: str, custom_fields: dict[str, Any] | None) -> dict[str, Any]:
+        """Validate custom field values against their definitions.
+
+        Args:
+            entity_type: The entity type (Contact, Account, Deal)
+            custom_fields: Dictionary of custom field values
+
+        Returns:
+            Validated custom_fields dict
+
+        Raises:
+            CustomFieldValidationError: If validation fails
+        """
+        if not custom_fields:
+            return {}
+
+        # Load field definitions for this entity type
+        definitions = await CustomFieldDefinition.objects.filter(
+            entity_type=entity_type, _address__object_version=Versions.LATEST
+        ).aexecute()
+
+        definitions_by_name = {d.field_name: d for d in definitions}
+        validated = {}
+
+        for field_name, value in custom_fields.items():
+            if field_name not in definitions_by_name:
+                msg = f'Unknown custom field: {field_name} for {entity_type}'
+                raise CustomFieldValidationError(msg)
+
+            definition = definitions_by_name[field_name]
+
+            # Required check
+            if definition.is_required and value is None:
+                msg = f'Required custom field {field_name} is missing'
+                raise CustomFieldValidationError(msg)
+
+            # Type validation
+            if value is not None:
+                validated[field_name] = cls._validate_field_value(definition, value)
+
+        return validated
+
+    @classmethod
+    def _validate_field_value(cls, definition: CustomFieldDefinition, value: Any) -> Any:
+        """Validate a single field value against its definition.
+
+        Args:
+            definition: The field definition
+            value: The value to validate
+
+        Returns:
+            The validated (and potentially converted) value
+
+        Raises:
+            CustomFieldValidationError: If validation fails
+        """
+        if definition.field_type == 'text':
+            return str(value)
+
+        elif definition.field_type == 'number':
+            try:
+                return Decimal(str(value))
+            except (InvalidOperation, ValueError) as exc:
+                msg = f'Invalid number for field {definition.field_name}: {value}'
+                raise CustomFieldValidationError(msg) from exc
+
+        elif definition.field_type == 'date':
+            if isinstance(value, datetime):
+                return value
+            # Try parsing ISO format
+            try:
+                return datetime.fromisoformat(value)
+            except (ValueError, AttributeError) as exc:
+                msg = f'Invalid date for field {definition.field_name}: {value}'
+                raise CustomFieldValidationError(msg) from exc
+
+        elif definition.field_type == 'choice':
+            if definition.choices and value not in definition.choices:
+                msg = f'Invalid choice for field {definition.field_name}: {value}. Must be one of {definition.choices}'
+                raise CustomFieldValidationError(msg)
+            return value
+
+        return value

amsdal_crm/services/deal_service.py

@@ -0,0 +1,131 @@
+"""DealService for deal management and pipeline operations."""
+
+from amsdal_data.transactions.decorators import async_transaction
+from amsdal_data.transactions.decorators import transaction
+from amsdal_utils.lifecycle.producer import LifecycleProducer
+from amsdal_utils.models.enums import Versions
+
+from amsdal_crm.constants import CRMLifecycleEvent
+from amsdal_crm.models.activity import ActivityRelatedTo
+from amsdal_crm.models.activity import ActivityType
+from amsdal_crm.models.activity import Note
+from amsdal_crm.models.deal import Deal
+from amsdal_crm.models.stage import Stage
+
+
+class DealService:
+    """Business logic for deal management."""
+
+    @classmethod
+    @transaction
+    def move_deal_to_stage(cls, deal: Deal, new_stage_id: str, note: str | None, user_email: str) -> Deal:
+        """Move a deal to a new stage with optional note.
+
+        Creates an activity log entry for stage change and emits lifecycle events.
+
+        Args:
+            deal: The deal to move
+            new_stage_id: ID of the new stage
+            note: Optional note about the stage change
+            user_email: Email of user performing the action
+
+        Returns:
+            The updated deal
+        """
+        # Load new stage
+        new_stage = (
+            Stage.objects.filter(_object_id=new_stage_id, _address__object_version=Versions.LATEST).get().execute()
+        )
+
+        old_stage_name = deal.stage_name
+
+        # Update deal stage (lifecycle hook will handle closed status)
+        deal.stage = new_stage
+        deal.save()
+
+        # Create activity log
+        activity_note = Note(
+            activity_type=ActivityType.NOTE,
+            subject=f'Deal moved: {old_stage_name} → {new_stage.name}',
+            description=note or f'Deal stage changed from {old_stage_name} to {new_stage.name}',
+            related_to_type=ActivityRelatedTo.DEAL,
+            related_to_id=deal._object_id,
+            owner_email=user_email,
+            due_date=None,
+            completed_at=None,
+            is_completed=False,
+        )
+        activity_note.save(force_insert=True)
+
+        # Emit lifecycle events
+        LifecycleProducer.publish(
+            CRMLifecycleEvent.ON_DEAL_STAGE_CHANGE,  # type: ignore[arg-type]
+            deal=deal,
+            old_stage=old_stage_name,
+            new_stage=new_stage.name,
+            user_email=user_email,
+        )
+
+        if new_stage.is_closed_won:
+            LifecycleProducer.publish(CRMLifecycleEvent.ON_DEAL_WON, deal=deal, user_email=user_email)  # type: ignore[arg-type]
+        elif new_stage.is_closed_lost:
+            LifecycleProducer.publish(CRMLifecycleEvent.ON_DEAL_LOST, deal=deal, user_email=user_email)  # type: ignore[arg-type]
+
+        return deal
+
+    @classmethod
+    @async_transaction
+    async def amove_deal_to_stage(cls, deal: Deal, new_stage_id: str, note: str | None, user_email: str) -> Deal:
+        """Async version of move_deal_to_stage.
+
+        Args:
+            deal: The deal to move
+            new_stage_id: ID of the new stage
+            note: Optional note about the stage change
+            user_email: Email of user performing the action
+
+        Returns:
+            The updated deal
+        """
+        # Load new stage
+        new_stage = (
+            await Stage.objects.filter(_object_id=new_stage_id, _address__object_version=Versions.LATEST)
+            .get()
+            .aexecute()
+        )
+
+        old_stage_name = deal.stage_name
+
+        # Update deal stage (lifecycle hook will handle closed status)
+        deal.stage = new_stage
+        await deal.asave()
+
+        # Create activity log
+        activity_note = Note(
+            activity_type=ActivityType.NOTE,
+            subject=f'Deal moved: {old_stage_name} → {new_stage.name}',
+            description=note or f'Deal stage changed from {old_stage_name} to {new_stage.name}',
+            related_to_type=ActivityRelatedTo.DEAL,
+            related_to_id=deal._object_id,
+            owner_email=user_email,
+            due_date=None,
+            completed_at=None,
+            is_completed=False,
+        )
+        await activity_note.asave(force_insert=True)
+
+        # Emit lifecycle events
+        await LifecycleProducer.publish_async(
+            CRMLifecycleEvent.ON_DEAL_STAGE_CHANGE,  # type: ignore[arg-type]
+            deal=deal,
+            old_stage=old_stage_name,
+            new_stage=new_stage.name,
+            user_email=user_email,
+        )
+
+        if new_stage.is_closed_won:
+            await LifecycleProducer.publish_async(CRMLifecycleEvent.ON_DEAL_WON, deal=deal, user_email=user_email)  # type: ignore[arg-type]
+        elif new_stage.is_closed_lost:
+            await LifecycleProducer.publish_async(CRMLifecycleEvent.ON_DEAL_LOST, deal=deal, user_email=user_email)  # type: ignore[arg-type]
+
+        return deal