# ============================================================
# 1. EMPLOYEE DIRECTORY   /api/people/directory/
# 2. EMPLOYEE 360 PROFILE /api/people/profile360/<employee_code>/
# + Branch hubs           /api/people/branches/
# + Meta (dropdowns)      /api/people/meta/
# ============================================================
from calendar import monthrange

from django.db import transaction
from django.db.models import Count, Q, Sum
from django.utils import timezone
from rest_framework.decorators import action
from rest_framework.views import APIView
from rest_framework.viewsets import ViewSet

from Employee.models import (AttendanceEmp, BankAccount, Department, EmployeeAccount, EmployeeDocument,
                             EmployeeDT, EmployeeRole, LeaveRequest, Payroll)

from .common import (CrudBase, PeopleAuthMixin, dept_name, emp_brief, emp_by_code, employees_qs, ensure_extra,
                     err, get_extra, infer_lifecycle, iso, sync_extras, lifecycle_label, log_history, ok, paginate, to_bool, to_date, to_decimal)
from .models import (AssetAllocation, Branch, ConfirmationReview, EmployeeExtra, ExitClearance, HistoryEvent,
                     OnboardingRecord)
from .views_onboarding import start_onboarding

LEAVE_ENTITLEMENT_DEFAULT = {"Paid Leave": 12, "Sick Leave": 8, "Casual Leave": 8}


def _entitlement():
    from django.conf import settings
    return getattr(settings, "PEOPLE_LEAVE_ENTITLEMENT", LEAVE_ENTITLEMENT_DEFAULT)


def directory_row(e, request=None):
    x = get_extra(e)
    lifecycle = x.lifecycle_status if x else infer_lifecycle(e)
    label = dict(EmployeeExtra.LIFECYCLE).get(lifecycle, lifecycle)
    if not e.is_active:
        label = "Inactive"
    m = x.reporting_manager if x else None
    return {
        "id": e.id, "employee_code": e.employee_code, "name": e.name, "email": e.email,
        "phone_number": e.phone_number, "profile_image": emp_brief(e, request)["profile_image"],
        "designation": e.Designation, "department": dept_name(e), "department_id": e.department_id,
        "branch": {"id": x.branch_id, "name": x.branch.name} if x and x.branch_id else None,
        "work_location": e.Work_Location,
        "reporting_manager": ({"employee_code": m.employee_code, "name": m.name} if m else None),
        "joining_date": iso(e.Date_of_Joining), "status": label, "lifecycle_status": lifecycle,
        "employee_status": e.Employee_Status, "employee_type": e.Employee_Type, "is_active": e.is_active,
    }


# base EmployeeDT columns editable from Directory / 360 (payload key -> model field)
BASE_FIELDS = {
    "name": "name", "phone_number": "phone_number", "designation": "Designation", "job_title": "Job_Title",
    "work_location": "Work_Location", "employee_type": "Employee_Type", "employee_status": "Employee_Status",
    "probation_period": "Probation_Period", "pan_number": "pan_number", "aadhaar_number": "aadhaar_number",
    "pf_number": "pf_number", "esi_number": "esi_number", "current_address": "Current_Address",
    "permanent_address": "Permanent_Address", "personal_email": "Personal_Email",
    "alternate_phone_number": "Alternate_Phone_Number", "gender": "Gender", "blood_group": "Blood_Group",
    "marital_status": "Marital_Status", "work_shift": "Work_sift", "sub_department": "Sub_Department",
}
EXTRA_TEXT = ["grade_band", "uan_number", "emergency_contact_name", "emergency_contact_relation",
              "emergency_contact_phone"]


@transaction.atomic
def apply_employee_update(company, emp, d, actor):
    """Shared by Directory update + 360 overview update. Writes history for key changes."""
    x = ensure_extra(emp)
    before = {"designation": emp.Designation, "department": dept_name(emp), "manager": x.reporting_manager_id,
              "grade": x.grade_band}
    if "email" in d and d["email"] and d["email"].lower() != (emp.email or "").lower():
        if EmployeeDT.objects.filter(company=company, email__iexact=d["email"]).exclude(pk=emp.pk).exists():
            raise ValueError("Email already exists in your company.")
        emp.email = d["email"]
    for key, field in BASE_FIELDS.items():
        if key in d:
            setattr(emp, field, d[key])
    if "date_of_joining" in d:
        emp.Date_of_Joining = to_date(d["date_of_joining"])
    if "date_of_birth" in d:
        emp.Date_of_Birth = to_date(d["date_of_birth"])
    if "department" in d or "department_id" in d:
        ref = d.get("department_id", d.get("department"))
        dep = None
        if ref not in (None, ""):
            dep = Department.objects.filter(company=company).filter(
                Q(pk=int(ref)) if str(ref).isdigit() else Q(name__iexact=str(ref))).first()
            if dep is None:
                raise ValueError(f"Department '{ref}' not found.")
        emp.department, emp.Department = dep, (dep.name if dep else None)
    emp.updated_by = actor
    emp.save()
    for k in EXTRA_TEXT:
        if k in d:
            setattr(x, k, d[k] or None)
    for k in ("probation_due_date", "confirmation_date"):
        if k in d:
            setattr(x, k, to_date(d[k]))
    if "lifecycle_status" in d:
        if d["lifecycle_status"] not in dict(EmployeeExtra.LIFECYCLE):
            raise ValueError(f"Invalid lifecycle_status. Allowed: {', '.join(dict(EmployeeExtra.LIFECYCLE))}")
        x.lifecycle_status = d["lifecycle_status"]
    if "branch" in d or "branch_id" in d:
        ref = d.get("branch_id", d.get("branch"))
        br = None
        if ref not in (None, ""):
            br = Branch.objects.filter(company=company, is_active=True).filter(
                Q(pk=int(ref)) if str(ref).isdigit() else Q(name__iexact=str(ref))).first()
            if br is None:
                raise ValueError(f"Branch '{ref}' not found.")
        x.branch = br
    if "reporting_manager" in d:
        mgr = emp_by_code(company, d.get("reporting_manager"), required=False)
        if mgr and mgr.pk == emp.pk:
            raise ValueError("An employee cannot report to themselves.")
        if mgr:                                   # ADDITIVE: no reporting loops (A -> B -> A) from the directory edit either
            from .org_chart_engine import assert_no_cycle
            assert_no_cycle(company, emp, mgr)
        x.reporting_manager = mgr
    x.updated_by = actor
    x.save()
    if emp.Designation != before["designation"] or x.grade_band != before["grade"]:
        log_history(company, emp, "DESIGNATION_CHANGE", f"Designation updated to {emp.Designation}",
                    f"Grade {before['grade'] or '-'} -> {x.grade_band or '-'}", actor=actor,
                    meta={"from": before["designation"], "to": emp.Designation})
    if x.reporting_manager_id != before["manager"]:
        log_history(company, emp, "MANAGER_CHANGE",
                    f"Reporting manager changed to {x.reporting_manager.name if x.reporting_manager else 'none'}",
                    actor=actor)
    return emp


# ------------------------------------------------------------
# 1. DIRECTORY
# ------------------------------------------------------------
class DirectoryViewSet(PeopleAuthMixin, ViewSet):
    lookup_value_regex = r"[^/]+"

    def _emp(self, code):
        return employees_qs(self.company()).filter(employee_code=code).select_related("department").first()

    def list(self, request):
        p, company = request.query_params, self.company()
        sync_extras(company)
        qs = employees_qs(company).select_related("department", "people_profile__branch",
                                                  "people_profile__reporting_manager")
        if not to_bool(p.get("include_inactive")):
            qs = qs.filter(is_active=True)
        q = (p.get("search") or "").strip()
        if q:
            qs = qs.filter(Q(name__icontains=q) | Q(email__icontains=q) | Q(employee_code__icontains=q)
                           | Q(Designation__icontains=q) | Q(Department__icontains=q))
        if p.get("department"):
            qs = qs.filter(Q(department_id=int(p["department"])) if p["department"].isdigit()
                           else Q(Department__iexact=p["department"]))
        if p.get("branch"):
            qs = qs.filter(people_profile__branch_id=int(p["branch"])) if p["branch"].isdigit() \
                else qs.filter(people_profile__branch__name__iexact=p["branch"])
        if p.get("status"):
            qs = qs.filter(people_profile__lifecycle_status=p["status"])
        if p.get("manager"):
            qs = qs.filter(people_profile__reporting_manager__employee_code=p["manager"])
        order = {"name": "name", "-name": "-name", "joining": "Date_of_Joining",
                 "-joining": "-Date_of_Joining"}.get(p.get("ordering"), "-id")
        counts = {r["people_profile__lifecycle_status"]: r["n"] for r in
                  employees_qs(company).filter(is_active=True).values("people_profile__lifecycle_status")
                  .annotate(n=Count("id"))}
        rows, meta = paginate(request, qs.order_by(order), lambda e: directory_row(e, request))
        return ok("DIRECTORY_LIST", "Employee directory.", rows, meta=meta,
                  summary={"total": sum(counts.values()), "by_lifecycle": counts})

    def retrieve(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return err("NOT_FOUND", "Employee not found.", 404)
        return ok("DIRECTORY_DETAIL", "Employee detail.", directory_row(e, request))

    @transaction.atomic
    def create(self, request):
        """'Add Employee' button. (The full 8-step form still lives at /company/employees/add/.)"""
        d, company, actor = request.data, self.company(), self.actor()
        name, email = (d.get("name") or "").strip(), (d.get("email") or "").strip()
        if not name or not email:
            return err("VALIDATION", "name and email are required.")
        if EmployeeDT.objects.filter(company=company, email__iexact=email).exists():
            return err("VALIDATION", "Email already exists in your company.")
        password = d.get("password")
        if password and len(str(password)) > 50:
            return err("VALIDATION", "Password must be 50 characters or fewer.")
        try:
            emp = EmployeeDT(company=company, name=name, email=email, password=password,
                             Employee_Status=d.get("employee_status") or "Activate", is_active=True,
                             Date_of_Joining=to_date(d.get("date_of_joining")) or timezone.localdate(),
                             created_by=actor, updated_by=actor)
            emp.save()
            apply_employee_update(company, emp, {k: v for k, v in d.items()
                                                 if k not in ("name", "email", "password", "employee_status",
                                                              "date_of_joining")}, actor)
            log_history(company, emp, "JOINED", f"Joined as {emp.Designation or 'Employee'}",
                        f"Joined {dept_name(emp) or 'the company'}", emp.Date_of_Joining, actor=actor)
            if to_bool(d.get("create_login")):
                if not password:
                    raise ValueError("password is required to create the login.")
                role, _ = EmployeeRole.objects.get_or_create(
                    company=company, role_code=(d.get("role_code") or "employee").strip(),
                    defaults={"role_name": (d.get("role_code") or "employee").replace("_", " ").title()})
                EmployeeAccount.objects.get_or_create(
                    employee=emp, defaults={"role": role, "is_login_enabled": True, "is_verified": True})
            if to_bool(d.get("start_onboarding"), True):
                start_onboarding(company, emp, emp_by_code(company, d.get("buddy"), required=False), actor)
        except ValueError as e:
            transaction.set_rollback(True)
            return err("VALIDATION", str(e))
        return ok("EMPLOYEE_CREATED", "Employee added.", directory_row(emp, request), 201)

    def partial_update(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return err("NOT_FOUND", "Employee not found.", 404)
        try:
            apply_employee_update(self.company(), e, request.data, self.actor())
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        e.refresh_from_db()
        return ok("EMPLOYEE_UPDATED", "Employee updated.", directory_row(e, request))

    update = partial_update

    @action(detail=True, methods=["post"], url_path="update")
    def update_post(self, request, pk=None):
        return self.partial_update(request, pk)

    @action(detail=True, methods=["post"], url_path="deactivate")
    def deactivate(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return err("NOT_FOUND", "Employee not found.", 404)
        e.is_active, e.updated_by = False, self.actor()
        e.save()
        EmployeeAccount.objects.filter(employee=e).update(is_login_enabled=False)
        return ok("EMPLOYEE_DEACTIVATED", "Employee deactivated and login disabled.", directory_row(e, request))

    @action(detail=True, methods=["post"], url_path="reactivate")
    def reactivate(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return err("NOT_FOUND", "Employee not found.", 404)
        e.is_active, e.updated_by = True, self.actor()
        e.save()
        EmployeeAccount.objects.filter(employee=e).update(is_login_enabled=True)
        return ok("EMPLOYEE_REACTIVATED", "Employee reactivated.", directory_row(e, request))

    # delete convention: POST <code>/delete/ == deactivate (hard delete stays on /company/employees/delete/)
    @action(detail=True, methods=["post"], url_path="delete")
    def delete_post(self, request, pk=None):
        return self.deactivate(request, pk)

    def destroy(self, request, pk=None):
        return self.deactivate(request, pk)


# ------------------------------------------------------------
# Branch hubs
# ------------------------------------------------------------
class BranchViewSet(CrudBase):
    model = Branch
    code = "BRANCH"
    status_field = None
    search_fields = ("name", "code", "city")

    def build(self, b):
        return {"id": b.id, "name": b.name, "code": b.code, "city": b.city, "address": b.address,
                "employee_count": b.employees.filter(employee__is_active=True).count()}

    def apply(self, b, d, creating):
        name = (d.get("name") or b.name or "").strip()
        if not name:
            raise ValueError("name is required.")
        if Branch.objects.filter(company=self.company(), name__iexact=name).exclude(pk=b.pk).exists():
            raise ValueError("Branch with this name already exists.")
        b.name = name
        for k in ("code", "city", "address"):
            if k in d:
                setattr(b, k, d[k])


# ------------------------------------------------------------
# META  GET /api/people/meta/
# ------------------------------------------------------------
class PeopleMetaView(PeopleAuthMixin, APIView):
    def get(self, request):
        from .letters import TEMPLATES
        from .models import (AssetMaster, EmployeeLetter, OnboardingRecord, PromotionRequest, TransferRequest)
        c = self.company()
        return ok("PEOPLE_META", "Dropdown data for the Employees workspace.", {
            "tabs": ["directory", "profile360", "onboarding", "documents", "assets", "history", "transfers",
                     "promotions", "confirmation", "letters"],
            "departments": list(Department.objects.filter(company=c, is_active=True).values("id", "name")),
            "branches": list(Branch.objects.filter(company=c, is_active=True).values("id", "name", "city")),
            "managers": [{"employee_code": e.employee_code, "name": e.name, "designation": e.Designation}
                         for e in employees_qs(c).filter(is_active=True).order_by("name")],
            "lifecycle_statuses": [{"code": k, "label": v} for k, v in EmployeeExtra.LIFECYCLE],
            "onboarding_statuses": [k for k, _ in OnboardingRecord.STATUS],
            "asset_categories": [k for k, _ in AssetMaster.CATEGORY],
            "asset_statuses": [k for k, _ in AssetMaster.STATUS],
            "transfer_statuses": [k for k, _ in TransferRequest.STATUS],
            "promotion_statuses": [k for k, _ in PromotionRequest.STATUS],
            "confirmation_recommendations": [k for k, _ in ConfirmationReview.RECO],
            "letter_types": [{"code": k, "label": l, "default_subject": TEMPLATES[k][0]}
                             for k, l in EmployeeLetter.TYPES],
            "document_types": [{"code": k, "label": l} for k, l in EmployeeDocument.DOCUMENT_TYPE_CHOICES],
            "employee_types": ["Full-Time Permanent", "Full-Time Contract", "Part-Time", "Intern", "Consultant"],
        })


# ------------------------------------------------------------
# 2. 360 PROFILE
# ------------------------------------------------------------
def _bank_label(emp):
    b = BankAccount.objects.filter(employee=emp, active=True).order_by("-id").first()
    return (f"{b.bank_name} ({b.account_number})" if b else None), b


class Profile360ViewSet(PeopleAuthMixin, ViewSet):
    """
    GET  /api/people/profile360/<code>/                    header + Overview vitals
    POST /api/people/profile360/<code>/update/             edit vitals (same fields as directory update)
    GET  .../<code>/recruitment-history/ | salary/ | attendance/?month=&year= | leave/?year= |
         assets/ | performance/ | documents/ | exit/
    POST .../<code>/exit/initiate/  | exit/clear-item/ | exit/complete/ | exit/withdraw/
    """
    lookup_value_regex = r"[^/]+"

    def _emp(self, code):
        return employees_qs(self.company()).filter(employee_code=code).select_related("department").first()

    def _nf(self):
        return err("NOT_FOUND", "Employee not found.", 404)

    def retrieve(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        x = ensure_extra(e)
        bank, _ = _bank_label(e)
        row = directory_row(e, request)
        mgr = x.reporting_manager
        data = {
            "header": {**row, "reports_to": ({"employee_code": mgr.employee_code, "name": mgr.name} if mgr else None),
                       "company_name": e.company.Registered_Company_Name or e.company.Brand_Name},
            "overview": {
                "grade_band": x.grade_band, "employment_type": e.Employee_Type, "pan_number": e.pan_number,
                "uan_pf": x.uan_number or e.pf_number, "bank_account": bank,
                "confirmation_date": iso(x.confirmation_date), "probation_due_date": iso(x.probation_due_date),
                "current_address": e.Current_Address, "permanent_address": e.Permanent_Address,
                "emergency_contact": {"name": x.emergency_contact_name, "relation": x.emergency_contact_relation,
                                      "phone": x.emergency_contact_phone},
                "date_of_birth": iso(e.Date_of_Birth), "gender": e.Gender, "blood_group": e.Blood_Group,
                "personal_email": e.Personal_Email, "alternate_phone": e.Alternate_Phone_Number,
                "aadhaar_number": e.aadhaar_number, "esi_number": e.esi_number,
            },
            "quick_actions": ["salary_payslip", "appointment_letter"],
        }
        return ok("PROFILE360", "Employee 360 profile.", data)

    def partial_update(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        try:
            apply_employee_update(self.company(), e, request.data, self.actor())
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        return self.retrieve(request, pk)

    update = partial_update

    @action(detail=True, methods=["post"], url_path="update")
    def update_post(self, request, pk=None):
        return self.partial_update(request, pk)

    @action(detail=True, methods=["get"], url_path="recruitment-history")
    def recruitment_history(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        out = {"candidate_id": e.candidate_id, "applied_position": e.applied_position,
               "source": e.candidate_source, "recruiter": e.recruiter_name, "stages": [], "offers": []}
        try:
            from Recruitment.models import Offer, StageHistory
            out["stages"] = [{"from": s.from_stage, "to": s.to_stage, "note": s.note, "changed_by": s.changed_by,
                              "at": iso(s.created_at) if hasattr(s, "created_at") else None}
                             for s in StageHistory.objects.filter(candidate=e).order_by("id")]
            out["offers"] = [{"offer_id": o.offer_id, "status": o.status, "offered_ctc_lpa": float(o.offered_ctc_lpa),
                              "designation": o.designation} for o in Offer.objects.filter(candidate=e)]
        except Exception:
            pass
        return ok("PROFILE_RECRUITMENT", "Recruitment history.", out)

    @action(detail=True, methods=["get"])
    def salary(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        try:
            c = e.compensation_package
            comp = {k: (float(getattr(c, k)) if getattr(c, k) is not None else None) for k in
                    ("current_annual_ctc", "expected_annual_ctc", "offered_annual_ctc", "basic_salary", "hra",
                     "special_allowance", "provident_fund", "esic", "professional_tax", "gross_salary",
                     "net_in_hand_salary")}
        except Exception:
            comp = None
        slips = [{"month": p.month, "year": p.year, "gross_salary": float(p.gross_salary or 0),
                  "total_deductions": float(p.total_deductions or 0), "net_salary": float(p.net_salary or 0)}
                 for p in Payroll.objects.filter(company=e.company, Employee_ID=e.employee_code)
                 .order_by("-year", "-month")[:12]]
        return ok("PROFILE_SALARY", "Salary & CTC.", {
            "basic_salary": float(e.Basic_Salary) if e.Basic_Salary is not None else None,
            "pf_percentage": float(e.PF_Percentage) if e.PF_Percentage is not None else None,
            "esi_percentage": float(e.ESI_Percentage) if e.ESI_Percentage is not None else None,
            "tds_percentage": float(e.TDS_Percentage) if e.TDS_Percentage is not None else None,
            "compensation": comp, "recent_payslips": slips})

    @action(detail=True, methods=["get"])
    def attendance(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        today = timezone.localdate()
        try:
            month, year = int(request.query_params.get("month", today.month)), int(request.query_params.get("year", today.year))
            monthrange(year, month)
        except (ValueError, Exception):
            return err("VALIDATION", "Invalid month/year.")
        recs = AttendanceEmp.objects.filter(company=e.company, Employee_ID=e.employee_code,
                                            date__year=year, date__month=month).order_by("date")
        summary = {r["status"]: r["n"] for r in recs.values("status").annotate(n=Count("id"))}
        return ok("PROFILE_ATTENDANCE", "Attendance.", {
            "month": month, "year": year, "summary": summary,
            "days": [{"date": iso(r.date), "status": r.status, "hours": r.total_working_hours} for r in recs]})

    @action(detail=True, methods=["get"])
    def leave(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        year = int(request.query_params.get("year", timezone.localdate().year))
        reqs = LeaveRequest.objects.filter(company=e.company, Employee_ID=e.employee_code, from_date__year=year,
                                           is_active=True)
        bal = []
        for lt, total in _entitlement().items():
            used = reqs.filter(leave_type=lt, status="Approved").aggregate(s=Sum("total_days"))["s"] or 0
            pend = reqs.filter(leave_type=lt, status="Pending").aggregate(s=Sum("total_days"))["s"] or 0
            bal.append({"leave_type": lt, "entitlement": total, "used": float(used), "pending": float(pend),
                        "balance": float(total) - float(used)})
        return ok("PROFILE_LEAVE", "Leave balances.", {
            "year": year, "balances": bal,
            "requests": [{"id": r.id, "leave_type": r.leave_type, "from_date": iso(r.from_date),
                          "to_date": iso(r.to_date), "total_days": float(r.total_days), "status": r.status}
                         for r in reqs.order_by("-from_date")[:50]]})

    @action(detail=True, methods=["get"])
    def assets(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        rows = AssetAllocation.objects.filter(employee=e, is_active=True).select_related("asset")
        return ok("PROFILE_ASSETS", "Assigned assets.", [
            {"allocation_id": a.id, "asset_tag": a.asset.asset_tag, "device_name": a.asset.device_name,
             "category": a.asset.category, "status": a.status, "allocated_on": iso(a.allocated_on),
             "returned_on": iso(a.returned_on)} for a in rows])

    @action(detail=True, methods=["get"])
    def performance(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        from .models import PromotionRequest
        proms = PromotionRequest.objects.filter(employee=e, is_active=True, manager_rating__isnull=False)
        return ok("PROFILE_PERFORMANCE", "Performance snapshots (from promotion & probation reviews).", {
            "reviews": [{"source": "Promotion", "rating": float(p.manager_rating), "date": iso(p.created_at)}
                        for p in proms] +
                       [{"source": "Probation", "rating": float(c.manager_rating), "date": iso(c.decided_on or c.probation_due_date)}
                        for c in ConfirmationReview.objects.filter(employee=e, is_active=True, manager_rating__isnull=False)]})

    @action(detail=True, methods=["get"])
    def documents(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        docs = EmployeeDocument.objects.filter(employee=e, is_active=True).order_by("-uploaded_at")
        return ok("PROFILE_DOCUMENTS", "Documents.", [
            {"id": d.id, "document_type": d.document_type, "document_name": d.document_name,
             "is_verified": d.is_verified, "verified_by": d.verified_by, "uploaded_at": iso(d.uploaded_at),
             "file": request.build_absolute_uri(d.file.url) if d.file else None} for d in docs])

    # ---- Exit & Clearance ----
    DEFAULT_CLEARANCE = [("IT", "Return laptop & revoke access"), ("Finance", "Expense & advance settlement"),
                         ("HR", "Exit interview & documents"), ("Admin", "ID card & locker keys"),
                         ("Reporting Manager", "Knowledge transfer sign-off")]

    @staticmethod
    def _exit_row(x):
        items = x.items or []
        return {"id": x.id, "status": x.status, "resignation_date": iso(x.resignation_date),
                "last_working_day": iso(x.last_working_day), "reason": x.reason, "items": items,
                "cleared_count": sum(1 for i in items if i.get("cleared")), "total_items": len(items)}

    @action(detail=True, methods=["get"])
    def exit(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        x = ExitClearance.objects.filter(employee=e, is_active=True).exclude(status="Withdrawn").first()
        return ok("PROFILE_EXIT", "Exit & clearance.", self._exit_row(x) if x else None)

    @action(detail=True, methods=["post"], url_path="exit/initiate")
    @transaction.atomic
    def exit_initiate(self, request, pk=None):
        e = self._emp(pk)
        if e is None:
            return self._nf()
        if ExitClearance.objects.filter(employee=e, is_active=True, status__in=["Initiated", "In Progress", "Cleared"]).exists():
            return err("EXISTS", "Exit is already in progress.", 409)
        d = request.data
        try:
            res, lwd = to_date(d.get("resignation_date")) or timezone.localdate(), to_date(d.get("last_working_day"))
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        items = [{"department": dp, "title": t, "cleared": False, "cleared_by": None, "cleared_at": None}
                 for dp, t in self.DEFAULT_CLEARANCE]
        x = ExitClearance.objects.create(company=e.company, employee=e, resignation_date=res, last_working_day=lwd,
                                         reason=d.get("reason"), items=items, created_by=self.actor(),
                                         updated_by=self.actor())
        e.Resignation_Date, e.Resignation_Status = str(res), "Resigned"
        e.Last_Working_Day = str(lwd) if lwd else e.Last_Working_Day
        e.save()
        ex = ensure_extra(e)
        ex.lifecycle_status = "Notice"
        ex.save()
        log_history(e.company, e, "EXIT", "Resignation recorded", d.get("reason"), res, actor=self.actor())
        return ok("EXIT_INITIATED", "Exit process started.", self._exit_row(x), 201)

    @action(detail=True, methods=["post"], url_path="exit/clear-item")
    def exit_clear_item(self, request, pk=None):
        e = self._emp(pk)
        x = ExitClearance.objects.filter(employee=e, is_active=True, status__in=["Initiated", "In Progress", "Cleared"]).first() if e else None
        if x is None:
            return err("NOT_FOUND", "No active exit process.", 404)
        dept = request.data.get("department")
        done = to_bool(request.data.get("cleared"), True)
        hit = False
        for i in x.items:
            if i["department"] == dept:
                i.update(cleared=done, cleared_by=self.actor() if done else None,
                         cleared_at=timezone.now().isoformat() if done else None)
                hit = True
        if not hit:
            return err("VALIDATION", "Unknown clearance department.")
        x.status = "Cleared" if all(i["cleared"] for i in x.items) else "In Progress"
        x.updated_by = self.actor()
        x.save()
        return ok("EXIT_ITEM", "Clearance item updated.", self._exit_row(x))

    @action(detail=True, methods=["post"], url_path="exit/complete")
    @transaction.atomic
    def exit_complete(self, request, pk=None):
        e = self._emp(pk)
        x = ExitClearance.objects.filter(employee=e, is_active=True, status__in=["Initiated", "In Progress", "Cleared"]).first() if e else None
        if x is None:
            return err("NOT_FOUND", "No active exit process.", 404)
        if not all(i["cleared"] for i in x.items) and not to_bool(request.data.get("force")):
            return err("NOT_CLEARED", "All clearance items must be cleared (or pass force=true).")
        x.status, x.updated_by = "Completed", self.actor()
        x.save()
        e.is_active, e.Employee_Status = False, "Exited"
        e.save()
        EmployeeAccount.objects.filter(employee=e).update(is_login_enabled=False)
        ex = ensure_extra(e)
        ex.lifecycle_status = "Exited"
        ex.save()
        log_history(e.company, e, "EXIT", "Exit completed", "Login disabled; employee marked as exited.",
                    x.last_working_day, actor=self.actor())
        return ok("EXIT_COMPLETED", "Exit completed; login disabled.", self._exit_row(x))

    @action(detail=True, methods=["post"], url_path="exit/withdraw")
    @transaction.atomic
    def exit_withdraw(self, request, pk=None):
        e = self._emp(pk)
        x = ExitClearance.objects.filter(employee=e, is_active=True, status__in=["Initiated", "In Progress", "Cleared"]).first() if e else None
        if x is None:
            return err("NOT_FOUND", "No active exit process.", 404)
        x.status, x.updated_by = "Withdrawn", self.actor()
        x.save()
        e.Resignation_Status, e.Resignation_Date = None, None
        e.save()
        ex = ensure_extra(e)
        ex.lifecycle_status = "Confirmed" if ex.confirmation_date else "Probation"
        ex.save()
        log_history(e.company, e, "NOTE", "Resignation withdrawn", actor=self.actor())
        return ok("EXIT_WITHDRAWN", "Resignation withdrawn.", self._exit_row(x))
