Add performing partner to clients and engagements

app/modules/services/client_services.py

@@ -70,6 +70,7 @@ def list_subscription_payload(
             selectinload(ClientServiceSubscription.client),
             selectinload(ClientServiceSubscription.catalogue),
             selectinload(ClientServiceSubscription.assigned_partner),
+            selectinload(ClientServiceSubscription.performing_partner),
             selectinload(ClientServiceSubscription.assigned_manager),
             selectinload(ClientServiceSubscription.assigned_staff),
             selectinload(ClientServiceSubscription.review_partner),
@@ -118,6 +119,7 @@ def get_subscription(db: Session, *, subscription_id: int, tenant_id: int) -> Cl
             selectinload(ClientServiceSubscription.client),
             selectinload(ClientServiceSubscription.catalogue),
             selectinload(ClientServiceSubscription.assigned_partner),
+            selectinload(ClientServiceSubscription.performing_partner),
             selectinload(ClientServiceSubscription.assigned_manager),
             selectinload(ClientServiceSubscription.assigned_staff),
             selectinload(ClientServiceSubscription.review_partner),

app/modules/services/engagements_ui.py

@@ -223,6 +223,7 @@ def subscription_create_page(request: Request, client_id: int | None = None):
         )
         enabled_services = list_enabled_services_for_assignment(db, tenant_id=tenant_id)
         assignable_users = list_assignable_users(db, tenant_id=tenant_id, branch_id=branch_id)
+        performing_partners = list_assignable_users(db, tenant_id=tenant_id, branch_id=branch_id, role_names=("Partner",))
         review_partners = list_review_partners(db, tenant_id=tenant_id, branch_id=branch_id)
 
         return _render(
@@ -236,6 +237,7 @@ def subscription_create_page(request: Request, client_id: int | None = None):
             clients=clients,
             enabled_services=enabled_services,
             assignable_users=assignable_users,
+            performing_partners=performing_partners,
             review_partners=review_partners,
             selected_client_id=client_id,
             financial_year=_active_financial_year(request),
@@ -252,6 +254,7 @@ def subscription_create_submit(
     assigned_partner_user_id: str = Form(""),
     assigned_manager_user_id: str = Form(""),
     assigned_staff_user_id: str = Form(""),
+    performing_partner_user_id: str = Form(""),
     review_partner_user_id: str = Form(""),
     financial_year: str = Form(""),
     start_date: str = Form(""),
@@ -317,6 +320,8 @@ def subscription_create_submit(
         row.branch_id = firm_selection.default_branch_id or getattr(user, "branch_id", None)
         row.firm_service_selection_id = firm_selection.id
         row.assigned_partner_user_id = int(assigned_partner_user_id) if assigned_partner_user_id.strip() else None
+        requested_performing_partner_id = int(performing_partner_user_id) if performing_partner_user_id.strip() else None
+        row.performing_partner_user_id = requested_performing_partner_id or getattr(client, "default_performing_partner_user_id", None) or row.assigned_partner_user_id
         row.assigned_manager_user_id = int(assigned_manager_user_id) if assigned_manager_user_id.strip() else None
         row.assigned_staff_user_id = int(assigned_staff_user_id) if assigned_staff_user_id.strip() else None
         if review_partner_required_for_engagement(db, tenant_id=tenant_id, engagement_type=row.engagement_type):
@@ -364,6 +369,7 @@ def subscription_bulk_create_page(request: Request, error: str = ""):
         )
         enabled_services = list_enabled_services_for_assignment(db, tenant_id=tenant_id)
         partners = list_assignable_users(db, tenant_id=tenant_id, role_names=("Partner",))
+        performing_partners = partners
         managers = list_assignable_users(db, tenant_id=tenant_id, role_names=("Branch Manager",))
         staff_users = list_assignable_users(db, tenant_id=tenant_id, role_names=("Staff",))
         review_partners = list_review_partners(db, tenant_id=tenant_id)
@@ -377,6 +383,7 @@ def subscription_bulk_create_page(request: Request, error: str = ""):
             clients=clients,
             enabled_services=enabled_services,
             partners=partners,
+            performing_partners=performing_partners,
             client_partner_names={row.id: (row.full_name or row.email) for row in partners},
             managers=managers,
             staff_users=staff_users,
@@ -385,6 +392,7 @@ def subscription_bulk_create_page(request: Request, error: str = ""):
             error_message={
                 "service": "Select a valid enabled firm service.",
                 "partner": "Select a valid active Partner.",
+                "performing_partner": "The selected Performing Partner is not available for this firm.",
                 "manager": "The selected Manager is not available for this firm.",
                 "staff": "The selected Staff member is not available for this firm.",
                 "review_partner": "The selected Review Partner is not available for this firm.",
@@ -404,6 +412,7 @@ def subscription_bulk_create_submit(
     assigned_partner_user_id: int = Form(...),
     assigned_manager_user_id: str = Form(""),
     assigned_staff_user_id: str = Form(""),
+    performing_partner_user_id: str = Form(""),
     review_partner_user_id: str = Form(""),
     financial_year: str = Form(""),
     remarks: str = Form(""),
@@ -448,6 +457,7 @@ def subscription_bulk_create_submit(
         review_partners = list_review_partners(db, tenant_id=tenant_id)
 
         partner_ids = {row.id for row in partners}
+        performing_partner_ids = partner_ids
         manager_ids = {row.id for row in managers}
         staff_ids = {row.id for row in staff_users}
         review_partner_ids = {row.id for row in review_partners}
@@ -455,9 +465,12 @@ def subscription_bulk_create_submit(
         if assigned_partner_user_id not in partner_ids:
             return RedirectResponse(url="/services/engagements/bulk-new?error=partner", status_code=303)
 
+        performing_partner_id = int(performing_partner_user_id) if performing_partner_user_id.strip() else assigned_partner_user_id
         manager_id = int(assigned_manager_user_id) if assigned_manager_user_id.strip() else None
         staff_id = int(assigned_staff_user_id) if assigned_staff_user_id.strip() else None
         review_partner_id = int(review_partner_user_id) if review_partner_user_id.strip() else None
+        if performing_partner_id not in performing_partner_ids:
+            return RedirectResponse(url="/services/engagements/bulk-new?error=performing_partner", status_code=303)
         if manager_id is not None and manager_id not in manager_ids:
             return RedirectResponse(url="/services/engagements/bulk-new?error=manager", status_code=303)
         if staff_id is not None and staff_id not in staff_ids:
@@ -531,6 +544,7 @@ def subscription_bulk_create_submit(
                 service_catalogue_id=service_catalogue_id,
                 firm_service_selection_id=firm_selection.id,
                 assigned_partner_user_id=assigned_partner_user_id,
+                performing_partner_user_id=performing_partner_id or getattr(client, "default_performing_partner_user_id", None) or assigned_partner_user_id,
                 assigned_manager_user_id=manager_id,
                 assigned_staff_user_id=staff_id,
                 review_partner_user_id=(
@@ -980,6 +994,7 @@ def subscription_edit_page(request: Request, subscription_id: int):
         )
         enabled_services = list_enabled_services_for_assignment(db, tenant_id=tenant_id)
         assignable_users = list_assignable_users(db, tenant_id=tenant_id, branch_id=branch_id)
+        performing_partners = list_assignable_users(db, tenant_id=tenant_id, branch_id=branch_id, role_names=("Partner",))
         review_partners = list_review_partners(db, tenant_id=tenant_id, branch_id=branch_id)
         return _render(
             request,
@@ -992,6 +1007,7 @@ def subscription_edit_page(request: Request, subscription_id: int):
             clients=clients,
             enabled_services=enabled_services,
             assignable_users=assignable_users,
+            performing_partners=performing_partners,
             review_partners=review_partners,
             selected_client_id=row.client_id,
             financial_year=row.financial_year,
@@ -1007,6 +1023,7 @@ def subscription_edit_submit(
     assigned_partner_user_id: str = Form(""),
     assigned_manager_user_id: str = Form(""),
     assigned_staff_user_id: str = Form(""),
+    performing_partner_user_id: str = Form(""),
     review_partner_user_id: str = Form(""),
     start_date: str = Form(""),
     end_date: str = Form(""),
@@ -1038,6 +1055,8 @@ def subscription_edit_submit(
             return RedirectResponse(url=f"/services/engagements/{row.id}?year_locked=1", status_code=303)
 
         row.assigned_partner_user_id = int(assigned_partner_user_id) if assigned_partner_user_id.strip() else None
+        requested_performing_partner_id = int(performing_partner_user_id) if performing_partner_user_id.strip() else None
+        row.performing_partner_user_id = requested_performing_partner_id or getattr(row.client, "default_performing_partner_user_id", None) or row.assigned_partner_user_id
         row.assigned_manager_user_id = int(assigned_manager_user_id) if assigned_manager_user_id.strip() else None
         row.assigned_staff_user_id = int(assigned_staff_user_id) if assigned_staff_user_id.strip() else None
         if review_partner_required_for_engagement(db, tenant_id=tenant_id, engagement_type=row.engagement_type):

app/modules/services/models.py

@@ -394,6 +394,7 @@ class ClientServiceSubscription(CommonBase):
     firm_service_selection_id: Mapped[int | None] = mapped_column(ForeignKey("firm_service_selections.id", ondelete="SET NULL"), nullable=True, index=True)
 
     assigned_partner_user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), nullable=True, index=True)
+    performing_partner_user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), nullable=True, index=True)
     assigned_manager_user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), nullable=True, index=True)
     assigned_staff_user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), nullable=True, index=True)
     review_partner_user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), nullable=True, index=True)
@@ -449,6 +450,7 @@ class ClientServiceSubscription(CommonBase):
     due_date_rule = relationship("ServiceDueDateRule", foreign_keys=[due_date_rule_id])
     firm_selection = relationship("FirmServiceSelection")
     assigned_partner = relationship("User", foreign_keys=[assigned_partner_user_id])
+    performing_partner = relationship("User", foreign_keys=[performing_partner_user_id])
     assigned_manager = relationship("User", foreign_keys=[assigned_manager_user_id])
     assigned_staff = relationship("User", foreign_keys=[assigned_staff_user_id])
     review_partner = relationship("User", foreign_keys=[review_partner_user_id])

app/modules/services/templates/services/engagements/bulk_form.html

@@ -44,6 +44,15 @@
         <p class="mt-1 text-xs text-slate-500">The engagement branch is derived automatically from the selected Partner’s branch.</p>
       </div>
 
+      <div>
+        <label class="mb-2 block text-sm font-medium text-slate-700">Performing Partner</label>
+        <select name="performing_partner_user_id" id="bulk-performing-partner" class="w-full rounded-xl border border-slate-300 px-4 py-2 text-sm">
+          <option value="">Same as Engagement Partner</option>
+          {% for u in performing_partners %}<option value="{{ u.id }}" data-branch="{{ u.branch_id }}">{{ u.full_name or u.email }}</option>{% endfor %}
+        </select>
+        <p class="mt-1 text-xs text-slate-500">Defaults to the Engagement Partner when left blank.</p>
+      </div>
+
       <div>
         <label class="mb-2 block text-sm font-medium text-slate-700">Default Manager</label>
         <select name="assigned_manager_user_id" id="bulk-manager" class="w-full rounded-xl border border-slate-300 px-4 py-2 text-sm">

app/modules/services/templates/services/engagements/detail.html

@@ -11,7 +11,7 @@
   {% if row.is_locked %}<div class="rounded-2xl border border-amber-200 bg-amber-50 p-4 text-sm text-amber-800">This engagement is locked as historical record. It cannot be edited.</div>{% endif %}
   <div class="grid gap-6 lg:grid-cols-2">
     <section class="rounded-2xl bg-white p-5 shadow-soft"><h3 class="text-sm font-semibold text-slate-900">Client & Service</h3><dl class="mt-4 space-y-3 text-sm"><div><dt class="text-slate-500">Client</dt><dd class="font-medium text-slate-900">{{ row.client.client_name if row.client else '-' }}</dd></div><div><dt class="text-slate-500">Service</dt><dd class="font-medium text-slate-900">{{ row.catalogue.service_name if row.catalogue else '-' }}</dd></div><div><dt class="text-slate-500">Financial Year</dt><dd>{{ row.financial_year or '-' }}</dd></div><div><dt class="text-slate-500">Assessment Year</dt><dd>{{ row.assessment_year or '-' }}</dd></div><div><dt class="text-slate-500">Engagement Type</dt><dd>{{ 'Assurance' if row.engagement_type == 'assurance' else 'Non-Assurance' }}</dd></div><div><dt class="text-slate-500">Original Due Date</dt><dd>{{ row.original_due_date or '-' }}</dd></div><div><dt class="text-slate-500">Expiry Date</dt><dd>{{ row.expiry_date or '-' }}</dd></div><div><dt class="text-slate-500">Current Due Date</dt><dd class="font-medium text-slate-900">{{ row.current_due_date or '-' }}{% if row.due_date_source %}<span class="ml-2 rounded-full bg-slate-100 px-2 py-1 text-xs font-medium text-slate-600">{{ row.due_date_source|replace('_',' ')|title }}</span>{% endif %}</dd></div><div><dt class="text-slate-500">Status</dt><dd>{{ 'Locked' if row.is_locked else row.status|replace('_',' ')|title }}{% if not row.is_active %} / Inactive{% endif %}</dd></div><div><dt class="text-slate-500">Period</dt><dd>{{ row.start_date or '-' }} to {{ row.end_date or '-' }}</dd></div></dl></section>
-    <section class="rounded-2xl bg-white p-5 shadow-soft"><h3 class="text-sm font-semibold text-slate-900">Assignment</h3><dl class="mt-4 space-y-3 text-sm"><div><dt class="text-slate-500">Partner</dt><dd>{{ row.assigned_partner.full_name if row.assigned_partner and row.assigned_partner.full_name else (row.assigned_partner.email if row.assigned_partner else '-') }}</dd></div><div><dt class="text-slate-500">Manager</dt><dd>{{ row.assigned_manager.full_name if row.assigned_manager and row.assigned_manager.full_name else (row.assigned_manager.email if row.assigned_manager else '-') }}</dd></div><div><dt class="text-slate-500">Staff</dt><dd>{{ row.assigned_staff.full_name if row.assigned_staff and row.assigned_staff.full_name else (row.assigned_staff.email if row.assigned_staff else '-') }}</dd></div><div><dt class="text-slate-500">Review Partner</dt><dd>{{ row.review_partner.full_name if row.review_partner and row.review_partner.full_name else (row.review_partner.email if row.review_partner else '-') }}</dd></div></dl></section>
+    <section class="rounded-2xl bg-white p-5 shadow-soft"><h3 class="text-sm font-semibold text-slate-900">Assignment</h3><dl class="mt-4 space-y-3 text-sm"><div><dt class="text-slate-500">Partner</dt><dd>{{ row.assigned_partner.full_name if row.assigned_partner and row.assigned_partner.full_name else (row.assigned_partner.email if row.assigned_partner else '-') }}</dd></div><div><dt class="text-slate-500">Performing Partner</dt><dd>{{ row.performing_partner.full_name if row.performing_partner and row.performing_partner.full_name else (row.performing_partner.email if row.performing_partner else (row.assigned_partner.full_name if row.assigned_partner and row.assigned_partner.full_name else (row.assigned_partner.email if row.assigned_partner else '-'))) }}</dd></div><div><dt class="text-slate-500">Manager</dt><dd>{{ row.assigned_manager.full_name if row.assigned_manager and row.assigned_manager.full_name else (row.assigned_manager.email if row.assigned_manager else '-') }}</dd></div><div><dt class="text-slate-500">Staff</dt><dd>{{ row.assigned_staff.full_name if row.assigned_staff and row.assigned_staff.full_name else (row.assigned_staff.email if row.assigned_staff else '-') }}</dd></div><div><dt class="text-slate-500">Review Partner</dt><dd>{{ row.review_partner.full_name if row.review_partner and row.review_partner.full_name else (row.review_partner.email if row.review_partner else '-') }}</dd></div></dl></section>
   </div>
 
   {% if row.quality_workflow_required %}

app/modules/services/templates/services/engagements/form.html

@@ -4,7 +4,7 @@
   <div class="flex items-center justify-between">
     <div>
       <h2 class="text-xl font-semibold text-slate-900">{% if mode == 'edit' %}Edit Engagement{% else %}Assign Service to Client{% endif %}</h2>
-      <p class="text-sm text-slate-500">Engagements are maintained financial-year wise. Review partner is used only for assurance engagements of partnership audit firms.</p>
+      <p class="text-sm text-slate-500">Engagement Partner owns the assignment, Performing Partner executes or supervises it, and Review Partner independently reviews applicable assurance engagements.</p>
     </div>
     <a href="/services/engagements" class="rounded-xl border border-slate-300 px-4 py-2 text-sm font-medium text-slate-700 hover:bg-slate-50">Back</a>
   </div>
@@ -50,6 +50,7 @@
     </div>
 
     <div><label class="mb-2 block text-sm font-medium text-slate-700">Assigned Partner</label><select name="assigned_partner_user_id" class="w-full rounded-xl border border-slate-300 px-4 py-2 text-sm"><option value="">Not assigned</option>{% for u in assignable_users %}<option value="{{ u.id }}" {% if subscription and subscription.assigned_partner_user_id == u.id %}selected{% endif %}>{{ u.full_name or u.email }}</option>{% endfor %}</select></div>
+    <div><label class="mb-2 block text-sm font-medium text-slate-700">Performing Partner</label><select name="performing_partner_user_id" class="w-full rounded-xl border border-slate-300 px-4 py-2 text-sm"><option value="">Use client default / Engagement Partner</option>{% for u in performing_partners or [] %}<option value="{{ u.id }}" {% if subscription and subscription.performing_partner_user_id == u.id %}selected{% endif %}>{{ u.full_name or u.email }}</option>{% endfor %}</select><p class="mt-1 text-xs text-slate-500">The Partner who directly performs or supervises this engagement.</p></div>
     <div><label class="mb-2 block text-sm font-medium text-slate-700">Assigned Manager</label><select name="assigned_manager_user_id" class="w-full rounded-xl border border-slate-300 px-4 py-2 text-sm"><option value="">Not assigned</option>{% for u in assignable_users %}<option value="{{ u.id }}" {% if subscription and subscription.assigned_manager_user_id == u.id %}selected{% endif %}>{{ u.full_name or u.email }}</option>{% endfor %}</select></div>
     <div><label class="mb-2 block text-sm font-medium text-slate-700">Assigned Staff</label><select name="assigned_staff_user_id" class="w-full rounded-xl border border-slate-300 px-4 py-2 text-sm"><option value="">Not assigned</option>{% for u in assignable_users %}<option value="{{ u.id }}" {% if subscription and subscription.assigned_staff_user_id == u.id %}selected{% endif %}>{{ u.full_name or u.email }}</option>{% endfor %}</select></div>
     <div><label class="mb-2 block text-sm font-medium text-slate-700">Review Partner</label><select name="review_partner_user_id" class="w-full rounded-xl border border-slate-300 px-4 py-2 text-sm"><option value="">Use client default / Not required</option>{% for u in review_partners or [] %}<option value="{{ u.id }}" {% if subscription and subscription.review_partner_user_id == u.id %}selected{% endif %}>{{ u.full_name or u.email }}</option>{% endfor %}</select><p class="mt-1 text-xs text-slate-500">Saved only for assurance engagements of partnership audit firms.</p></div>

app/modules/services/templates/services/engagements/list.html

@@ -87,7 +87,7 @@
           <td class="px-4 py-3 text-xs text-slate-600"><div>FY: {{ row.financial_year or '-' }}</div><div>AY: {{ row.assessment_year or '-' }}</div></td>
           <td class="px-4 py-3 text-xs text-slate-600"><div>Current: <span class="font-medium text-slate-900">{{ row.current_due_date or '-' }}</span></div><div>Original: {{ row.original_due_date or '-' }}</div>{% if row.expiry_date %}<div>Expiry: {{ row.expiry_date }}</div>{% endif %}{% if row.due_date_source %}<div class="text-slate-500">{{ row.due_date_source|replace('_',' ')|title }}</div>{% endif %}</td>
           <td class="px-4 py-3 text-sm text-slate-700">{{ 'Assurance' if row.engagement_type == 'assurance' else 'Non-Assurance' }}</td>
-          <td class="px-4 py-3 text-xs text-slate-600"><div>Partner: {{ row.assigned_partner.full_name if row.assigned_partner and row.assigned_partner.full_name else (row.assigned_partner.email if row.assigned_partner else '-') }}</div><div>Manager: {{ row.assigned_manager.full_name if row.assigned_manager and row.assigned_manager.full_name else (row.assigned_manager.email if row.assigned_manager else '-') }}</div><div>Staff: {{ row.assigned_staff.full_name if row.assigned_staff and row.assigned_staff.full_name else (row.assigned_staff.email if row.assigned_staff else '-') }}</div><div>Review: {{ row.review_partner.full_name if row.review_partner and row.review_partner.full_name else (row.review_partner.email if row.review_partner else '-') }}</div></td>
+          <td class="px-4 py-3 text-xs text-slate-600"><div>Partner: {{ row.assigned_partner.full_name if row.assigned_partner and row.assigned_partner.full_name else (row.assigned_partner.email if row.assigned_partner else '-') }}</div><div>Performing: {{ row.performing_partner.full_name if row.performing_partner and row.performing_partner.full_name else (row.performing_partner.email if row.performing_partner else (row.assigned_partner.full_name if row.assigned_partner and row.assigned_partner.full_name else (row.assigned_partner.email if row.assigned_partner else '-'))) }}</div><div>Manager: {{ row.assigned_manager.full_name if row.assigned_manager and row.assigned_manager.full_name else (row.assigned_manager.email if row.assigned_manager else '-') }}</div><div>Staff: {{ row.assigned_staff.full_name if row.assigned_staff and row.assigned_staff.full_name else (row.assigned_staff.email if row.assigned_staff else '-') }}</div><div>Review: {{ row.review_partner.full_name if row.review_partner and row.review_partner.full_name else (row.review_partner.email if row.review_partner else '-') }}</div></td>
           <td class="px-4 py-3 text-sm"><span class="rounded-full px-2 py-1 text-xs font-medium {% if row.is_locked %}bg-amber-100 text-amber-700{% elif row.is_active and row.status == 'active' %}bg-emerald-100 text-emerald-700{% else %}bg-slate-200 text-slate-700{% endif %}">{{ 'Locked' if row.is_locked else row.status|replace('_',' ')|title }}{% if not row.is_active %} / Inactive{% endif %}</span></td>
           <td class="px-4 py-3 text-right text-sm"><a href="/services/engagements/{{ row.id }}" class="font-medium text-brand-700 hover:underline">View</a>{% if can_manage and not row.is_locked %}<a href="/services/engagements/{{ row.id }}/edit" class="ml-3 font-medium text-brand-700 hover:underline">Edit</a>{% endif %}</td>
         </tr>