Add phase 1 client consultant referral and linkage

app/modules/clients/schemas.py

@@ -22,6 +22,12 @@ class ClientBase(BaseModel):
     branch_id: int
     partner_id: Optional[int] = None
     default_review_partner_user_id: Optional[int] = None
+    referred_by_consultant_id: Optional[int] = None
+    primary_consultant_id: Optional[int] = None
+    referral_date: Optional[date] = None
+    referral_reference: Optional[str] = None
+    referral_status: str = "active"
+    communication_routing_mode: str = "client_and_consultant"
     engagement_mode: str = "internal_managed"
     client_code: str
     client_name: str
@@ -82,7 +88,7 @@ class ClientBase(BaseModel):
 
     @field_validator(
         "trade_name", "cin_llpin", "msme_no", "iec_code", "contact_person_name", "contact_person_designation",
-        "address_line_1", "address_line_2", "city", "state", "country", "client_category", "risk_category", "acceptance_review_notes", "acceptance_rejection_reason", "notes",
+        "address_line_1", "address_line_2", "city", "state", "country", "client_category", "risk_category", "referral_reference", "acceptance_review_notes", "acceptance_rejection_reason", "notes",
         mode="before",
     )
     @classmethod
@@ -94,6 +100,25 @@ class ClientBase(BaseModel):
     def uppercase_codes(cls, value):
         return normalize_upper(value)
 
+    @field_validator("referral_status", "communication_routing_mode", mode="before")
+    @classmethod
+    def clean_referral_fields(cls, value):
+        return (normalize_text(value) or "").lower()
+
+    @field_validator("referral_status")
+    @classmethod
+    def validate_referral_status(cls, value):
+        if value not in {"active", "inactive", "ended"}:
+            raise ValueError("Invalid referral status.")
+        return value
+
+    @field_validator("communication_routing_mode")
+    @classmethod
+    def validate_communication_routing_mode(cls, value):
+        if value not in {"client_direct", "consultant_primary", "client_and_consultant", "firm_only"}:
+            raise ValueError("Invalid communication routing mode.")
+        return value
+
     @field_validator("engagement_mode", mode="before")
     @classmethod
     def clean_engagement_mode(cls, value):
@@ -189,6 +214,12 @@ class ClientUpdate(BaseModel):
     branch_id: Optional[int] = None
     partner_id: Optional[int] = None
     default_review_partner_user_id: Optional[int] = None
+    referred_by_consultant_id: Optional[int] = None
+    primary_consultant_id: Optional[int] = None
+    referral_date: Optional[date] = None
+    referral_reference: Optional[str] = None
+    referral_status: Optional[str] = None
+    communication_routing_mode: Optional[str] = None
     engagement_mode: Optional[str] = None
     client_name: Optional[str] = None
     trade_name: Optional[str] = None
@@ -241,7 +272,7 @@ class ClientUpdate(BaseModel):
 
     @field_validator(
         "client_name", "trade_name", "cin_llpin", "msme_no", "iec_code", "contact_person_name", "contact_person_designation",
-        "address_line_1", "address_line_2", "city", "state", "country", "client_category", "risk_category", "acceptance_review_notes", "acceptance_rejection_reason", "notes",
+        "address_line_1", "address_line_2", "city", "state", "country", "client_category", "risk_category", "referral_reference", "acceptance_review_notes", "acceptance_rejection_reason", "notes",
         mode="before",
     )
     @classmethod
@@ -253,6 +284,26 @@ class ClientUpdate(BaseModel):
     def uppercase_codes(cls, value):
         return normalize_upper(value)
 
+    @field_validator("referral_status", "communication_routing_mode", mode="before")
+    @classmethod
+    def clean_optional_referral_fields(cls, value):
+        value = normalize_text(value)
+        return value.lower() if value else None
+
+    @field_validator("referral_status")
+    @classmethod
+    def validate_optional_referral_status(cls, value):
+        if value is not None and value not in {"active", "inactive", "ended"}:
+            raise ValueError("Invalid referral status.")
+        return value
+
+    @field_validator("communication_routing_mode")
+    @classmethod
+    def validate_optional_communication_routing_mode(cls, value):
+        if value is not None and value not in {"client_direct", "consultant_primary", "client_and_consultant", "firm_only"}:
+            raise ValueError("Invalid communication routing mode.")
+        return value
+
     @field_validator("engagement_mode", mode="before")
     @classmethod
     def clean_engagement_mode(cls, value):