Add employee engagement pause and dependency workflow phase 3

app/modules/employees/service.py

@@ -13,6 +13,7 @@ from sqlalchemy.orm import Session, selectinload
 
 from app.core.security.passwords import hash_password
 from app.modules.core.iam.models import User
+from app.modules.alerts.service import create_alert
 from app.modules.core.iam.scope import build_scope, list_visible_branches, list_visible_tenants, validate_branch_matches_tenant
 from app.modules.core.rbac.deps import get_user_roles
 from app.modules.core.rbac.models import Role, UserRole
@@ -57,6 +58,20 @@ TASK_COMMUNICATION_VISIBILITIES = [
 ]
 
 TASK_COMMUNICATION_TYPE_CODES = {code for code, _ in TASK_COMMUNICATION_TYPES}
+
+WORKFLOW_HOLD_REASONS = {
+    "documents_from_client": "Documents awaited from client",
+    "clarification_from_client": "Clarification awaited from client",
+    "client_requested_hold": "Client requested hold",
+    "manager_review": "Manager review pending",
+    "partner_review": "Partner review pending",
+    "review_partner_review": "Review Partner review pending",
+    "payment_pending": "Payment pending",
+    "portal_issue": "Portal or system issue",
+    "internal_dependency": "Internal dependency",
+    "other": "Other",
+}
+
 TASK_COMMUNICATION_VISIBILITY_CODES = {code for code, _ in TASK_COMMUNICATION_VISIBILITIES}
 
 
@@ -2701,6 +2716,85 @@ def _phase7i_task_card_enrich(task: ClientServiceTaskInstance, *, today: date) -
     task.engagement_label = _subscription_label(getattr(task, "subscription", None), task)
 
 
+def _workflow_manual_blocker(subscription: ClientServiceSubscription | None) -> dict[str, Any] | None:
+    if not subscription or not getattr(subscription, "workflow_pause_reason", None):
+        return None
+    code = str(subscription.workflow_pause_reason).strip()
+    return {
+        "type": "manual",
+        "code": code,
+        "label": WORKFLOW_HOLD_REASONS.get(code, code.replace("_", " ").title()),
+        "notes": (getattr(subscription, "workflow_pause_notes", None) or "").strip() or None,
+        "follow_up_date": getattr(subscription, "workflow_follow_up_date", None),
+    }
+
+
+def _workflow_automatic_blocker(subscription: ClientServiceSubscription | None, tasks: list[ClientServiceTaskInstance]) -> dict[str, Any] | None:
+    if subscription and getattr(subscription, "quality_workflow_required", False):
+        qstatus = (getattr(subscription, "quality_acceptance_status", None) or "").strip().lower()
+        if qstatus not in {"approved", "not_required"}:
+            return {"type": "automatic", "code": "quality_acceptance", "label": "AQMM acceptance pending", "notes": getattr(subscription, "quality_block_reason", None), "follow_up_date": None}
+    checks = [
+        ("rework", "rework_status", {"open"}, "Rework response pending"),
+        ("manager_review", "manager_review_status", {"pending", "rework_required"}, "Manager review pending"),
+        ("partner_review", "partner_review_status", {"pending", "rework_required"}, "Partner review pending"),
+        ("review_partner_review", "review_partner_review_status", {"pending", "rework_required"}, "Review Partner review pending"),
+    ]
+    for code, field, values, label in checks:
+        for task in tasks:
+            if (getattr(task, field, None) or "").strip().lower() in values:
+                return {"type": "automatic", "code": code, "label": label, "notes": task.task_name, "follow_up_date": None}
+    return None
+
+
+def pause_employee_engagement_workflow(db: Session, scope: EmployeeScope, engagement_id: int, *, reason: str, notes: str, follow_up_date: str, actor_user_id: int, financial_year: str | None = None) -> ClientServiceSubscription:
+    code = (reason or "").strip().lower()
+    if code not in WORKFLOW_HOLD_REASONS:
+        raise ValueError("Select a valid hold reason.")
+    clean_notes = (notes or "").strip()
+    if code == "other" and not clean_notes:
+        raise ValueError("Remarks are required for Other hold reason.")
+    tasks = db.execute(_employee_work_task_query(db, scope, assigned_only=True, financial_year=financial_year).where(ClientServiceTaskInstance.subscription_id == engagement_id)).scalars().all()
+    if not tasks:
+        raise HTTPException(status_code=404, detail="Engagement work not found or not assigned to you")
+    subscription = tasks[0].subscription
+    if subscription.is_locked:
+        raise ValueError("Locked engagement cannot be paused.")
+    parsed_follow_up = parse_date(follow_up_date) if (follow_up_date or "").strip() else None
+    subscription.workflow_pause_reason = code
+    subscription.workflow_pause_notes = clean_notes or None
+    subscription.workflow_follow_up_date = parsed_follow_up
+    subscription.workflow_paused_at_utc = datetime.now(timezone.utc)
+    subscription.workflow_paused_by_user_id = actor_user_id
+    subscription.workflow_resumed_at_utc = None
+    subscription.workflow_resumed_by_user_id = None
+    subscription.updated_by_user_id = actor_user_id
+    manager_id = getattr(subscription, "assigned_manager_user_id", None)
+    if manager_id and manager_id != actor_user_id:
+        create_alert(db, user_id=manager_id, title=f"Engagement paused: {_subscription_label(subscription, tasks[0])}", message=f"{WORKFLOW_HOLD_REASONS[code]}" + (f". {clean_notes}" if clean_notes else "") + (f" Follow-up: {parsed_follow_up}." if parsed_follow_up else ""), tenant_id=subscription.tenant_id, branch_id=subscription.branch_id, role_context="manager", alert_type="clarification", priority="high", target_url=f"/employees/work/engagements/{engagement_id}", created_by_user_id=actor_user_id, commit=False)
+    db.commit(); db.refresh(subscription); return subscription
+
+
+def resume_employee_engagement_workflow(db: Session, scope: EmployeeScope, engagement_id: int, *, actor_user_id: int, financial_year: str | None = None) -> ClientServiceSubscription:
+    tasks = db.execute(_employee_work_task_query(db, scope, assigned_only=True, financial_year=financial_year).where(ClientServiceTaskInstance.subscription_id == engagement_id)).scalars().all()
+    if not tasks:
+        raise HTTPException(status_code=404, detail="Engagement work not found or not assigned to you")
+    subscription = tasks[0].subscription
+    if subscription.is_locked:
+        raise ValueError("Locked engagement cannot be resumed.")
+    old_reason = WORKFLOW_HOLD_REASONS.get(getattr(subscription, "workflow_pause_reason", None), "Paused")
+    subscription.workflow_pause_reason = None
+    subscription.workflow_pause_notes = None
+    subscription.workflow_follow_up_date = None
+    subscription.workflow_resumed_at_utc = datetime.now(timezone.utc)
+    subscription.workflow_resumed_by_user_id = actor_user_id
+    subscription.updated_by_user_id = actor_user_id
+    manager_id = getattr(subscription, "assigned_manager_user_id", None)
+    if manager_id and manager_id != actor_user_id:
+        create_alert(db, user_id=manager_id, title=f"Engagement resumed: {_subscription_label(subscription, tasks[0])}", message=f"The employee resumed work previously held for: {old_reason}.", tenant_id=subscription.tenant_id, branch_id=subscription.branch_id, role_context="manager", alert_type="general", priority="normal", target_url=f"/employees/work/engagements/{engagement_id}", created_by_user_id=actor_user_id, commit=False)
+    db.commit(); db.refresh(subscription); return subscription
+
+
 def list_employee_work_kanban(
     db: Session,
     scope: EmployeeScope,
@@ -2864,10 +2958,20 @@ def list_employee_work_kanban(
         card["progress_percent"] = int(round((completed * 100) / total)) if total else 0
         card["open_count"] = max(total - completed, 0)
 
+        manual_blocker = _workflow_manual_blocker(card.get("subscription"))
+        automatic_blocker = _workflow_automatic_blocker(card.get("subscription"), card.get("tasks", []))
+        card["manual_blocker"] = manual_blocker
+        card["automatic_blocker"] = automatic_blocker
+        card["workflow_blocker"] = manual_blocker or automatic_blocker
+        if card["workflow_blocker"]:
+            card["blocked_reason"] = card["workflow_blocker"]["label"]
+            card["blocked_notes"] = card["workflow_blocker"].get("notes")
+            card["follow_up_date"] = card["workflow_blocker"].get("follow_up_date")
+
         if total and completed == total:
             card_status = "completed"
             card["action_label"] = "View"
-        elif card["blocked_count"]:
+        elif card["workflow_blocker"] or card["blocked_count"]:
             card_status = "blocked"
             card["action_label"] = "Open / Follow Up"
         elif card["in_progress_count"] or completed:
@@ -3122,10 +3226,17 @@ def get_employee_engagement_work_board(
     selected_category = _employee_task_category(selected_task)
     next_task = _employee_workflow_next_task(tasks, selected_task.id)
     overall_progress = round((summary["completed"] / summary["total"]) * 100) if summary["total"] else 0
+    subscription = getattr(tasks[0], "subscription", None)
+    manual_blocker = _workflow_manual_blocker(subscription)
+    automatic_blocker = _workflow_automatic_blocker(subscription, tasks)
 
     return {
         "engagement_id": engagement_id,
-        "subscription": getattr(tasks[0], "subscription", None),
+        "subscription": subscription,
+        "manual_blocker": manual_blocker,
+        "automatic_blocker": automatic_blocker,
+        "workflow_blocker": manual_blocker or automatic_blocker,
+        "hold_reasons": WORKFLOW_HOLD_REASONS,
         "client": getattr(tasks[0], "client", None),
         "label": _subscription_label(getattr(tasks[0], "subscription", None), tasks[0]),
         "summary": summary,

app/modules/employees/templates/employees/self_work.html

@@ -90,6 +90,8 @@
           <div class="mt-4 rounded-xl border border-rose-200 bg-rose-50 p-3">
             <div class="text-xs font-semibold uppercase text-rose-700">Pending reason</div>
             <div class="mt-1 text-sm font-medium text-rose-900">{{ card.blocked_reason }}</div>
+            {% if card.blocked_notes %}<div class="mt-1 text-xs text-rose-700">{{ card.blocked_notes }}</div>{% endif %}
+            {% if card.follow_up_date %}<div class="mt-2 text-xs font-semibold text-rose-800">Follow-up: {{ card.follow_up_date }}</div>{% endif %}
             {% if card.blocked_task_name %}<div class="mt-1 text-xs text-rose-700">Task: {{ card.blocked_task_name }}</div>{% endif %}
           </div>
           {% elif card.next_task_name and column.code != 'completed' %}
@@ -107,6 +109,7 @@
           <a href="/employee/work/engagements/{{ card.engagement_id }}" class="mt-4 inline-flex w-full justify-center rounded-xl bg-brand-600 px-4 py-2 text-sm font-semibold text-white hover:bg-brand-700">Continue</a>
           {% elif column.code == 'blocked' %}
           <a href="/employee/work/engagements/{{ card.engagement_id }}" class="mt-4 inline-flex w-full justify-center rounded-xl bg-rose-600 px-4 py-2 text-sm font-semibold text-white hover:bg-rose-700">Open / Follow Up</a>
+          {% if card.manual_blocker %}<form method="post" action="/employee/work/engagements/{{ card.engagement_id }}/resume" class="mt-2"><input type="hidden" name="csrf_token" value="{{ csrf_token }}"><button type="submit" class="inline-flex w-full justify-center rounded-xl border border-emerald-300 bg-emerald-50 px-4 py-2 text-sm font-semibold text-emerald-700 hover:bg-emerald-100">Resume Workflow</button></form>{% endif %}
           {% else %}
           <a href="/employee/work/engagements/{{ card.engagement_id }}" class="mt-4 inline-flex w-full justify-center rounded-xl border border-slate-300 bg-white px-4 py-2 text-sm font-semibold text-slate-700 hover:bg-slate-50">View</a>
           {% endif %}

app/modules/employees/templates/employees/work_engagement_board.html

@@ -12,11 +12,44 @@
       </p>
     </div>
     <div class="flex flex-wrap gap-2">
+      {% if board.manual_blocker %}
+      <form method="post" action="/employee/work/engagements/{{ board.engagement_id }}/resume">
+        <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+        <button type="submit" class="rounded-xl bg-emerald-600 px-4 py-2 text-sm font-semibold text-white hover:bg-emerald-700">Resume Workflow</button>
+      </form>
+      {% elif not (board.subscription and board.subscription.is_locked) %}
+      <button type="button" onclick="document.getElementById('pause-workflow-panel').classList.toggle('hidden')" class="rounded-xl border border-amber-300 bg-amber-50 px-4 py-2 text-sm font-semibold text-amber-800 hover:bg-amber-100">Pause / Hold</button>
+      {% endif %}
       <a href="/employee/work" class="rounded-xl border border-slate-300 px-4 py-2 text-sm font-semibold text-slate-700 hover:bg-slate-50">Close Workspace</a>
       <a href="/documents/engagements/{{ board.engagement_id }}" class="rounded-xl border border-slate-300 px-4 py-2 text-sm font-semibold text-slate-700 hover:bg-slate-50">Engagement Documents</a>
     </div>
   </div>
 
+
+  {% if request.query_params.get('paused') %}<div class="rounded-xl border border-amber-200 bg-amber-50 px-4 py-3 text-sm text-amber-800">Engagement workflow paused and the assigned Manager was notified.</div>{% endif %}
+  {% if request.query_params.get('resumed') %}<div class="rounded-xl border border-emerald-200 bg-emerald-50 px-4 py-3 text-sm text-emerald-800">Engagement workflow resumed.</div>{% endif %}
+  {% if request.query_params.get('pause_error') or request.query_params.get('resume_error') %}<div class="rounded-xl border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-800">The workflow status could not be changed. Confirm the reason and that the engagement is not locked.</div>{% endif %}
+
+  {% if board.workflow_blocker %}
+  <div class="rounded-2xl border {% if board.workflow_blocker.type == 'manual' %}border-amber-300 bg-amber-50{% else %}border-violet-300 bg-violet-50{% endif %} p-4">
+    <div class="font-semibold text-slate-900">{{ board.workflow_blocker.label }}</div>
+    {% if board.workflow_blocker.notes %}<div class="mt-1 text-sm text-slate-700">{{ board.workflow_blocker.notes }}</div>{% endif %}
+    {% if board.workflow_blocker.follow_up_date %}<div class="mt-2 text-sm font-medium text-amber-900">Follow-up date: {{ board.workflow_blocker.follow_up_date }}</div>{% endif %}
+    {% if board.workflow_blocker.type == 'automatic' %}<div class="mt-2 text-xs text-violet-700">This blocker is derived automatically from the existing AQMM/review workflow.</div>{% endif %}
+  </div>
+  {% endif %}
+
+  <div id="pause-workflow-panel" class="hidden rounded-2xl border border-amber-300 bg-white p-5 shadow-soft">
+    <h3 class="font-semibold text-slate-900">Pause / Hold Engagement</h3>
+    <form method="post" action="/employee/work/engagements/{{ board.engagement_id }}/pause" class="mt-4 grid gap-4 md:grid-cols-3">
+      <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+      <div><label class="mb-2 block text-sm font-medium text-slate-700">Reason</label><select name="reason" required class="w-full rounded-xl border border-slate-300 px-4 py-2 text-sm"><option value="">Select reason</option>{% for code, label in board.hold_reasons.items() %}<option value="{{ code }}">{{ label }}</option>{% endfor %}</select></div>
+      <div><label class="mb-2 block text-sm font-medium text-slate-700">Follow-up Date</label><input type="date" name="follow_up_date" class="w-full rounded-xl border border-slate-300 px-4 py-2 text-sm"></div>
+      <div class="md:col-span-3"><label class="mb-2 block text-sm font-medium text-slate-700">Remarks / Dependency Details</label><textarea name="notes" rows="3" class="w-full rounded-xl border border-slate-300 px-4 py-2 text-sm" placeholder="Documents pending, query details, reviewer dependency or other follow-up information"></textarea></div>
+      <div class="md:col-span-3 flex justify-end"><button type="submit" class="rounded-xl bg-amber-600 px-4 py-2 text-sm font-semibold text-white hover:bg-amber-700">Pause and Notify Manager</button></div>
+    </form>
+  </div>
+
   {% if request.query_params.get('saved') %}
   <div class="rounded-xl border border-emerald-200 bg-emerald-50 px-4 py-3 text-sm text-emerald-800">Task response saved successfully.</div>
   {% endif %}

app/modules/employees/ui.py

@@ -49,6 +49,8 @@ from app.modules.employees.service import (
     get_employee_engagement_work_board,
     start_employee_engagement_workflow,
     save_employee_workflow_task,
+    pause_employee_engagement_workflow,
+    resume_employee_engagement_workflow,
     list_employee_work_assignable_users,
     list_visible_work_assignment_dashboard,
     list_engagement_progress_dashboard,
@@ -2129,6 +2131,44 @@ def employee_my_work_engagement_board(request: Request, engagement_id: int, task
         db.close()
 
 
+@portal_router.post("/work/engagements/{engagement_id}/pause")
+def employee_workflow_pause(request: Request, engagement_id: int, reason: str = Form(...), notes: str = Form(""), follow_up_date: str = Form(""), csrf_token: str = Form(...)):
+    db = CommonSessionLocal()
+    try:
+        current_user = get_current_user(request, db=db)
+        if not current_user: return _redirect_login()
+        try: require_permission(db, current_user, "employees.work.view_self")
+        except Exception: return _redirect_denied()
+        try: validate_csrf(request, csrf_token)
+        except PermissionError: return _csrf_rejected(request)
+        scope = build_employee_scope(db, current_user, tenant_id=request.session.get("active_tenant_id") or current_user.tenant_id, branch_id=request.session.get("active_branch_id"))
+        try:
+            pause_employee_engagement_workflow(db, scope, engagement_id, reason=reason, notes=notes, follow_up_date=follow_up_date, actor_user_id=current_user.id, financial_year=_active_financial_year(request))
+        except ValueError:
+            db.rollback(); return RedirectResponse(url=f"/employee/work/engagements/{engagement_id}?pause_error=1", status_code=303)
+        return RedirectResponse(url=f"/employee/work/engagements/{engagement_id}?paused=1", status_code=303)
+    finally: db.close()
+
+
+@portal_router.post("/work/engagements/{engagement_id}/resume")
+def employee_workflow_resume(request: Request, engagement_id: int, csrf_token: str = Form(...)):
+    db = CommonSessionLocal()
+    try:
+        current_user = get_current_user(request, db=db)
+        if not current_user: return _redirect_login()
+        try: require_permission(db, current_user, "employees.work.view_self")
+        except Exception: return _redirect_denied()
+        try: validate_csrf(request, csrf_token)
+        except PermissionError: return _csrf_rejected(request)
+        scope = build_employee_scope(db, current_user, tenant_id=request.session.get("active_tenant_id") or current_user.tenant_id, branch_id=request.session.get("active_branch_id"))
+        try:
+            resume_employee_engagement_workflow(db, scope, engagement_id, actor_user_id=current_user.id, financial_year=_active_financial_year(request))
+        except ValueError:
+            db.rollback(); return RedirectResponse(url=f"/employee/work/engagements/{engagement_id}?resume_error=1", status_code=303)
+        return RedirectResponse(url=f"/employee/work/engagements/{engagement_id}?resumed=1", status_code=303)
+    finally: db.close()
+
+
 @portal_router.post("/work/engagements/{engagement_id}/tasks/{task_id}/save")
 def employee_workflow_task_save(
     request: Request,