# ============================================================
# Payroll Inputs & Compensation Coordination - Admin / HR     /api/payroll-hub/...
#
#   dashboard/ meta/ settings/          Payroll Dashboard, dropdowns, company payroll rules
#   components/                         Salary Structure   (+ preview/, employee_breakup/, reorder/)
#   inputs/                             Payroll Inputs     (+ approve / reject / verify / bulk_approve)
#   variable-pay/                       Variable Pay       (+ approve / reject / schedule / mark_paid)
#   deductions/                         Deductions         (+ approve / waive / mark_fnf)
#   loans/                              Loans / Advances   (+ approve / reject / foreclose / schedule / skip_installment / outstanding)
#   cycles/<MM-YYYY>/                   Processing Status  (+ generate_payroll / freeze / unfreeze / validate / bank_file / release / revoke)
#   payslips/                           Payslip Management (+ <employee_code>/?month=&year= , pdf/)
#   Statutory Components tab            = existing /api/compliance/dashboard/ (not rebuilt)
#
# Auth  : AdminOrEmployeeJWTAuthentication (company admin token or HR employee token)
# Authz : Company Admin = everything; employee needs EmployeeRole can_<view|create|edit|delete|manage>_payroll.
# ============================================================
from decimal import Decimal

from django.db import transaction
from django.db.models import Q, Sum
from django.http import Http404, HttpResponse
from django.utils import timezone
from rest_framework.decorators import action
from rest_framework.parsers import FormParser, JSONParser, MultiPartParser
from rest_framework.views import APIView
from rest_framework.viewsets import ViewSet

from Employee.models import EmployeeDT, Payroll
from People.exit_models import ExitFnF
from Timesheet.models import OvertimeClaim

from . import engine as en
from .common import (MONTHS, PayAuthMixin, PayCrud, check_file, emp_brief, emp_by_code, employees_qs, err, f,
                     file_url, get_setting, iso, lakhs, money, month_label, month_year, ok, paginate, person,
                     pick, q2, to_bool, to_date, to_decimal, to_int)
from .models import (Loan, LoanRepayment, PayrollCycle, PayrollDeduction, PayrollInput, PayrollSetting, Payslip,
                     SalaryComponent, VariablePay)

PARSERS = [JSONParser, MultiPartParser, FormParser]


def locked(company, month, year):
    return PayrollCycle.objects.filter(company=company, month=month, year=year).exclude(status="OPEN").exists()


def ensure_open(company, month, year):
    if month and year and locked(company, month, year):
        raise ValueError(f"Payroll inputs for {month_label(month, year)} are frozen. Unfreeze the cycle first.")


def cur_period(p):
    t = timezone.localdate()
    m, y = to_int(p.get("month"), t.month), to_int(p.get("year"), t.year)
    if not 1 <= m <= 12:
        raise ValueError("month must be 1-12.")
    return m, y


# =============================================================== shared row builders
def input_row(i, request=None):
    return {"id": i.id, "source_type": "INPUT", "month": i.month, "year": i.year, "period": month_label(i.month, i.year),
            "employee": emp_brief(i.employee, request), "input_type": i.input_type,
            "adjustment_type": i.label or dict(PayrollInput.TYPES)[i.input_type],
            "direction": "INFO" if i.input_type == "LOP" else ("EARNING" if i.input_type in PayrollInput.EARNING_TYPES
                                                              else "DEDUCTION"),
            "amount": f(i.amount), "days": f(i.days), "remarks": i.remarks, "status": i.status,
            "status_label": ("Verified (%g Days)" % float(i.days)) if (i.status == "VERIFIED" and i.input_type == "LOP")
            else dict(PayrollInput.STATUS)[i.status], "source": i.source, "readonly": False,
            "attachment": file_url(request, i.attachment), "decided_by": i.decided_by, "decided_at": iso(i.decided_at),
            "decision_remarks": i.decision_remarks, "created_at": iso(i.created_at)}


def overtime_rows(company, month, year, request=None):
    out = []
    for c in OvertimeClaim.objects.filter(company=company, month=month, year=year, is_active=True,
                                          status__in=["Approved", "Passed to Payroll"]).select_related("employee"):
        out.append({"id": c.id, "source_type": "TIMESHEET_OVERTIME", "month": month, "year": year,
                    "period": month_label(month, year), "employee": emp_brief(c.employee, request),
                    "input_type": "OVERTIME_PAYOUT", "adjustment_type": "Overtime Payout", "direction": "EARNING",
                    "amount": f(c.calculated_pay), "days": 0, "remarks": c.remarks or f"{c.approved_hours} hours verified",
                    "status": "APPROVED" if c.status == "Passed to Payroll" else "PENDING_REVIEW",
                    "status_label": "Approved" if c.status == "Passed to Payroll" else "Approved by manager - not yet passed",
                    "source": "TIMESHEET", "readonly": True, "attachment": None, "decided_by": c.decided_by,
                    "decided_at": iso(c.decided_at), "decision_remarks": c.decision_remarks,
                    "created_at": iso(c.created_at)})
    return out


def variable_row(v, request=None):
    return {"id": v.id, "employee": emp_brief(v.employee, request), "period_type": v.period_type,
            "period": v.period_label, "target_variable": f(v.target_amount),
            "achievement_percent": f(v.achievement_percent), "payable_bonus": f(v.payable_amount),
            "status": v.status, "status_label": dict(VariablePay.STATUS)[v.status], "payout_month": v.payout_month,
            "payout_year": v.payout_year, "payout_period": month_label(v.payout_month, v.payout_year),
            "appraisal_id": v.appraisal_id, "remarks": v.remarks, "decided_by": v.decided_by,
            "decided_at": iso(v.decided_at), "created_at": iso(v.created_at), "updated_at": iso(v.updated_at)}


def deduction_row(d, request=None):
    fnf = ExitFnF.objects.filter(pk=d.exit_fnf_id).first() if d.exit_fnf_id else None
    return {"id": d.id, "employee": emp_brief(d.employee, request), "deduction_head": d.head, "amount": f(d.amount),
            "reason": d.reason, "month": d.month, "year": d.year, "period": month_label(d.month, d.year),
            "status": d.status, "status_label": dict(PayrollDeduction.STATUS)[d.status],
            "exit_fnf": {"id": fnf.id, "statement_no": fnf.statement_no, "status": fnf.status} if fnf else None,
            "decided_by": d.decided_by, "decided_at": iso(d.decided_at), "created_at": iso(d.created_at)}


def loan_row(l, request=None, schedule=False):
    bal = en.loan_balance(l)
    r = {"id": l.id, "loan_id": l.loan_no, "employee": emp_brief(l.employee, request), "loan_type": l.loan_type,
         "loan_type_label": dict(Loan.TYPES)[l.loan_type], "sanctioned_principal": f(l.principal),
         "interest_rate": f(l.interest_rate), "monthly_emi": f(l.emi_amount), "tenure_months": l.tenure_months,
         "tenure_label": f"{l.tenure_months} Months", **bal,
         "balance_label": f"₹{bal['balance_remaining']:,.0f} ({bal['emis_left']} EMIs left)",
         "start_period": month_label(l.start_month, l.start_year), "status": l.status,
         "status_label": dict(Loan.STATUS)[l.status], "purpose": l.purpose, "sanctioned_on": iso(l.sanctioned_on),
         "decided_by": l.decided_by, "decision_remarks": l.decision_remarks,
         "requested_by_employee": l.requested_by_employee, "created_at": iso(l.created_at)}
    if schedule:
        r["schedule"] = [{"installment_no": x.installment_no, "month": x.month, "year": x.year,
                          "period": month_label(x.month, x.year), "amount": f(x.amount),
                          "principal": f(x.principal_part), "interest": f(x.interest_part), "status": x.status,
                          "deducted_at": iso(x.deducted_at)} for x in l.repayments.filter(is_active=True)]
    return r


def slip_row(company, emp, slip, snap, request=None):
    return {"employee": emp_brief(emp, request), "employee_id": emp.employee_code, "employee_name": emp.name,
            "designation": emp.Designation, "month": slip["month"], "year": slip["year"],
            "gross_salary": slip["gross_salary"], "deductions": slip["total_deductions"],
            "net_payable": slip["net_payable"], "released": bool(snap and snap.status == "RELEASED"),
            "payslip_no": snap.payslip_no if snap else None, "payroll_status": slip["payroll_status"],
            "view_url": f"/api/payroll-hub/payslips/{emp.employee_code}/?month={slip['month']}&year={slip['year']}",
            "pdf_url": f"/api/payroll-hub/payslips/{emp.employee_code}/pdf/?month={slip['month']}&year={slip['year']}"}


def cycle_row(c, st):
    card = en.STATUS_CARD[c.status]
    return {"id": c.id, "month": c.month, "year": c.year, "period": month_label(c.month, c.year), "status": c.status,
            "status_label": card[0], "status_sub": card[1], "steps": en.cycle_steps(c, st),
            "release_on": iso(c.release_on or en.default_release_date(st, c.month, c.year)),
            "inputs_frozen_at": iso(c.inputs_frozen_at), "verified_at": iso(c.verified_at),
            "verification_result": c.verification_result or None, "bank_file_at": iso(c.bank_file_at),
            "bank_file_total": f(c.bank_file_total), "bank_file_count": c.bank_file_count,
            "bank_file_url": f"/api/payroll-hub/cycles/{c.month:02d}-{c.year}/bank_file_download/" if c.bank_file else None,
            "released_at": iso(c.released_at), "remarks": c.remarks}


# =============================================================== dashboard / meta / settings
class DashboardViewSet(PayAuthMixin, ViewSet):
    """GET /api/payroll-hub/dashboard/?month=9&year=2026 (defaults to the current month)"""

    def list(self, request):
        c = self.company()
        try:
            m, y = cur_period(request.query_params)
        except ValueError as e:
            return err("VALIDATION", str(e))
        st = get_setting(c)
        cyc = en.get_cycle(c, m, y, self.actor())
        emps, _ = en.employees_in_cycle(c, m, y)
        slips = [en.compute_payslip(c, e, m, y, st) for e in emps.values()]
        net = sum(Decimal(str(s["net_payable"])) for s in slips)
        stat = {"PF": 0, "ESI": 0, "TDS": 0, "PT": 0}
        for s in slips:
            for d in s["deductions"]:
                if d["code"] in stat:
                    stat[d["code"]] += d["amount"]
        stat_total = sum(stat.values())
        parts = [{"PF": "EPF", "ESI": "ESIC", "PT": "PT", "TDS": "TDS"}[k] for k in ("PF", "ESI", "PT", "TDS") if stat[k]]
        ctc = Decimal("0")
        for e in employees_qs(c).filter(is_active=True):
            try:
                pk = e.compensation_package
                annual = pk.offered_annual_ctc or pk.current_annual_ctc
            except Exception:
                annual = None
            ctc += (annual / 12) if annual else Decimal("0")
        if not ctc:
            ctc = sum((Decimal(str(s["gross_salary"])) for s in slips), Decimal("0"))
        card = en.STATUS_CARD[cyc.status]
        rows = [input_row(i, request) for i in PayrollInput.objects.filter(company=c, month=m, year=y, is_active=True)
                .select_related("employee")] + overtime_rows(c, m, y, request)
        rows.sort(key=lambda r: r["created_at"] or "", reverse=True)
        return ok("PAYROLL_DASHBOARD", "Payroll Inputs & Compensation Coordination.", {
            "title": "Payroll Inputs & Compensation Coordination",
            "subtitle": "Variances, overtime payouts, LOP, statutory deductions, and payslips",
            "period": month_label(m, y), "month": m, "year": y,
            "kpis": {"total_monthly_ctc": {"value": f(ctc), "display": lakhs(ctc), "subtitle": f"{month_label(m, y)} cycle"},
                     "net_disbursable_salary": {"value": f(net), "display": lakhs(net), "subtitle": "Post PF, PT & TDS"
                                                if stat["PT"] else "Post PF, ESIC & TDS", "employees": len(slips)},
                     "statutory_liabilities": {"value": round(stat_total, 2), "display": lakhs(stat_total),
                                               "subtitle": " + ".join(parts) or "No statutory deductions",
                                               "breakup": {k: round(v, 2) for k, v in stat.items()}},
                     "payroll_status": {"value": card[0], "subtitle": card[1], "status": cyc.status}},
            "inputs": rows[:25], "inputs_total": len(rows),
            "cycle": cycle_row(cyc, st)})


class MetaViewSet(PayAuthMixin, ViewSet):
    def list(self, request):
        c = self.company()
        t = timezone.localdate()
        return ok("PAYROLL_HUB_META", "Dropdown values.", {
            "input_types": [{"code": k, "label": v, "direction": "INFO" if k == "LOP" else (
                "EARNING" if k in PayrollInput.EARNING_TYPES else "DEDUCTION")} for k, v in PayrollInput.TYPES],
            "input_statuses": [{"code": k, "label": v} for k, v in PayrollInput.STATUS],
            "variable_periods": [{"code": k, "label": v} for k, v in VariablePay.PERIODS],
            "variable_statuses": [{"code": k, "label": v} for k, v in VariablePay.STATUS],
            "deduction_statuses": [{"code": k, "label": v} for k, v in PayrollDeduction.STATUS],
            "loan_types": [{"code": k, "label": v} for k, v in Loan.TYPES],
            "loan_statuses": [{"code": k, "label": v} for k, v in Loan.STATUS],
            "component_types": [{"code": k, "label": v} for k, v in SalaryComponent.TYPES],
            "calc_methods": [{"code": k, "label": v} for k, v in SalaryComponent.METHODS],
            "cycle_statuses": [{"code": k, "label": v} for k, v in PayrollCycle.STATUS],
            "months": MONTHS[1:], "current": {"month": t.month, "year": t.year},
            "components": [{"id": x.id, "code": x.code, "name": x.name} for x in
                           SalaryComponent.objects.filter(company=c, is_active=True)],
            "settings": SettingsView().row(get_setting(c))})


class SettingsView(PayAuthMixin, APIView):
    """GET /api/payroll-hub/settings/ | PUT|PATCH (company payroll rules)"""
    BOOLS = ("include_timesheet_overtime", "allow_employee_claims", "allow_employee_loan_requests",
             "require_verification_before_bank_file")
    INTS = {"loan_max_emi_percent": (1, 100), "loan_max_tenure_months": (1, 360), "payslip_release_day": (0, 31)}

    def row(self, s):
        r = {k: getattr(s, k) for k in self.BOOLS + tuple(self.INTS)}
        r.update(loan_max_principal=f(s.loan_max_principal), bank_portal_name=s.bank_portal_name,
                 updated_at=iso(s.updated_at), updated_by=s.updated_by)
        return r

    def get(self, request):
        return ok("PAYROLL_SETTINGS", "Settings.", self.row(get_setting(self.company())))

    def put(self, request):
        s, d = get_setting(self.company()), request.data
        try:
            for k in self.BOOLS:
                if k in d:
                    setattr(s, k, to_bool(d[k]))
            for k, (lo, hi) in self.INTS.items():
                if k in d:
                    v = to_int(d[k])
                    if v is None or not lo <= v <= hi:
                        raise ValueError(f"{k} must be between {lo} and {hi}.")
                    setattr(s, k, v)
            if "loan_max_principal" in d:
                s.loan_max_principal = money(d, "loan_max_principal", Decimal("0"))
            if "bank_portal_name" in d:
                s.bank_portal_name = (d["bank_portal_name"] or None) and str(d["bank_portal_name"])[:60]
        except ValueError as e:
            return err("VALIDATION", str(e))
        s.updated_by = self.actor()
        s.save()
        return ok("PAYROLL_SETTINGS_SAVED", "Settings saved.", self.row(s))

    patch = put


# =============================================================== salary structure
class ComponentViewSet(PayCrud):
    """
    GET  /api/payroll-hub/components/        ?component_type=EARNING|DEDUCTION ?search=
    POST /api/payroll-hub/components/        {code, name, component_type, calc_method, calc_value?, base_component?,
                                              cap_amount?, is_taxable?, tax_treatment?, description?, sort_order?}
    GET|PATCH|PUT|DELETE .../<id>/ ; POST .../<id>/update|delete/
    GET  .../preview/?gross=150000           salary breakup of a monthly gross using the company architecture
    GET  .../employee_breakup/?employee=<code>[&gross=]   same for an employee (gross defaults to the latest payroll gross)
    POST .../reorder/ {ids:[...]}
    """
    model, code, select, status_field = SalaryComponent, "SALARY_COMPONENT", ("base_component",), "component_type"
    search_fields = ("code", "name")
    permission_action_map = {"preview": "view", "employee_breakup": "view", "reorder": "edit"}

    def build(self, c):
        return en.component_row(c)

    def apply(self, o, d, creating):
        if creating or "code" in d:
            code = str(d.get("code") or "").strip().upper()
            if not code:
                raise ValueError("code is required.")
            o.code = code[:20]
        if creating or "name" in d:
            if not str(d.get("name") or "").strip():
                raise ValueError("name is required.")
            o.name = str(d["name"]).strip()[:100]
        if "component_type" in d:
            o.component_type = pick(d["component_type"], dict(SalaryComponent.TYPES), "component_type")
        if "calc_method" in d:
            o.calc_method = pick(d["calc_method"], dict(SalaryComponent.METHODS), "calc_method")
        if "calc_value" in d:
            o.calc_value = money(d, "calc_value", Decimal("0"))
        if o.calc_method.startswith("PERCENT") and o.calc_value > 100:
            raise ValueError("A percentage cannot exceed 100.")
        if o.calc_method == "BALANCING" and o.component_type != "EARNING":
            raise ValueError("Only an earning can be the balancing component.")
        if "base_component" in d:
            if d["base_component"] in (None, ""):
                o.base_component = None
            else:
                b = SalaryComponent.objects.filter(company=o.company, pk=to_int(d["base_component"]), is_active=True).first()
                if b is None or (o.pk and b.pk == o.pk):
                    raise ValueError("base_component is invalid.")
                o.base_component = b
        if o.calc_method == "PERCENT_OF_COMPONENT" and not o.base_component_id:
            raise ValueError("base_component is required for % of component.")
        if "cap_amount" in d:
            o.cap_amount = money(d, "cap_amount")
        for k in ("tax_treatment", "description"):
            if k in d:
                setattr(o, k, d[k] or None)
        if "is_taxable" in d:
            o.is_taxable = to_bool(d["is_taxable"], True)
        if "sort_order" in d:
            o.sort_order = max(to_int(d["sort_order"], 1), 1)
        elif creating:
            o.sort_order = SalaryComponent.objects.filter(company=o.company, is_active=True).count() + 1
        if SalaryComponent.objects.filter(company=o.company, code=o.code).exclude(pk=o.pk).exists():
            raise ValueError("A component with this code already exists.")
        if o.calc_method == "BALANCING" and SalaryComponent.objects.filter(
                company=o.company, calc_method="BALANCING", is_active=True).exclude(pk=o.pk).exists():
            raise ValueError("Only one balancing component is allowed.")

    @action(detail=False, methods=["get"])
    def preview(self, request):
        try:
            g = to_decimal(request.query_params.get("gross"))
            if g is None or g <= 0:
                raise ValueError("gross (monthly) is required.")
        except ValueError as e:
            return err("VALIDATION", str(e))
        return ok("SALARY_BREAKUP", "Salary breakup.", en.breakup(self.company(), g))

    @action(detail=False, methods=["get"])
    def employee_breakup(self, request):
        c, p = self.company(), request.query_params
        try:
            e = emp_by_code(c, p.get("employee"))
            g = to_decimal(p.get("gross"))
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        if g is None:
            last = Payroll.objects.filter(company=c, Employee_ID=e.employee_code).order_by("-year", "-month").first()
            g = last.gross_salary if last else None
        if not g:
            return err("VALIDATION", "No payroll gross found for this employee - pass ?gross=.")
        return ok("SALARY_BREAKUP", "Salary breakup.", en.breakup(c, g) | {"employee": emp_brief(e, request)})

    @action(detail=False, methods=["post"])
    def reorder(self, request):
        ids = request.data.get("ids")
        if not isinstance(ids, list) or not ids:
            return err("VALIDATION", "ids must be a list of component ids.")
        comps = {x.id: x for x in self.scope().filter(is_active=True, id__in=ids)}
        for i, cid in enumerate(ids, 1):
            if to_int(cid) in comps:
                comps[to_int(cid)].sort_order = i
                comps[to_int(cid)].save()
        return ok("SALARY_COMPONENTS_REORDERED", "Order saved.", [en.component_row(x) for x in self.scope().filter(
            is_active=True)])


# =============================================================== payroll inputs
class InputViewSet(PayCrud):
    """
    GET  /api/payroll-hub/inputs/    ?month= ?year= ?employee=<code> ?input_type= ?status= ?search= ?include_timesheet=true(default)
                                     (Overtime Payout rows come read-only from Timesheet overtime claims)
    POST /api/payroll-hub/inputs/    multipart/json: employee_code, month, year, input_type, amount, label?, days?, remarks?, status?, attachment?
    GET|PATCH|PUT|DELETE .../<id>/   POST .../<id>/update|delete|approve|reject|verify/    POST .../bulk_approve/ {ids:[]}
    LOP rows are attendance verifications (days) - salary for absent days is already handled by the payroll engine.
    """
    model, code, select, status_field = PayrollInput, "PAYROLL_INPUT", ("employee",), "status"
    parser_classes = PARSERS
    search_fields = ("label", "remarks", "employee__name", "employee__employee_code")
    permission_action_map = {"approve": "edit", "reject": "edit", "verify": "edit", "bulk_approve": "edit"}

    def filter(self, qs, p):
        qs = super().filter(qs, p)
        for k, col in (("month", "month"), ("year", "year"), ("input_type", "input_type")):
            if p.get(k):
                qs = qs.filter(**{col: p[k]})
        if p.get("employee"):
            qs = qs.filter(employee__employee_code=p["employee"])
        return qs

    def build(self, i):
        return input_row(i, self.request)

    def list(self, request):
        p, c = request.query_params, self.company()
        qs = self.filter(self.scope().filter(is_active=True), p).select_related("employee")
        rows = [input_row(i, request) for i in qs]
        if to_bool(p.get("include_timesheet"), True) and p.get("month") and p.get("year"):
            ot = overtime_rows(c, to_int(p["month"]), to_int(p["year"]), request)
            if p.get("employee"):
                ot = [r for r in ot if r["employee"]["employee_code"] == p["employee"]]
            if p.get("status"):
                ot = [r for r in ot if r["status"] == p["status"].upper()]
            if p.get("input_type"):
                ot = [r for r in ot if r["input_type"] == p["input_type"].upper()]
            q = (p.get("search") or "").lower()
            if q:
                ot = [r for r in ot if q in (r["remarks"] or "").lower() or q in r["employee"]["name"].lower()]
            rows += ot
        rows.sort(key=lambda r: (r["year"], r["month"], r["created_at"] or ""), reverse=True)
        page, meta = paginate(request, rows, lambda r: r)
        summary = {s: sum(1 for r in rows if r["status"] == s) for s in dict(PayrollInput.STATUS)}
        return ok("PAYROLL_INPUT_LIST", "Monthly Payroll Variances & Inputs.", page, meta=meta, summary=summary)

    def apply(self, o, d, creating):
        if creating:
            o.employee = emp_by_code(o.company, d.get("employee_code"))
            o.month, o.year = month_year(d)
            o.source = "MANUAL"
        ensure_open(o.company, o.month, o.year)
        if o.status == "PROCESSED":
            raise ValueError("A processed input cannot be changed.")
        if creating or "input_type" in d:
            o.input_type = pick(d.get("input_type"), dict(PayrollInput.TYPES), "input_type")
        for k in ("label", "remarks"):
            if k in d:
                setattr(o, k, d[k] or None)
        if o.input_type == "LOP":
            o.days = money(d, "days", o.days)
            if o.days is None or o.days < 0 or o.days > 31:
                raise ValueError("days must be 0-31 for an LOP verification.")
            o.amount = Decimal("0")
            if creating and "status" not in d:
                o.status = "VERIFIED"
        else:
            o.amount = money(d, "amount", o.amount, allow_zero=False)
            if creating and "status" not in d:
                o.status = "APPROVED"
        if "status" in d:
            o.status = pick(d["status"], ["PENDING_REVIEW", "APPROVED", "VERIFIED", "REJECTED"], "status")
            o.decided_by, o.decided_at = self.actor(), timezone.now()
        f_ = self.request.FILES.get("attachment")
        if f_ is not None:
            check_file(f_)
            o.attachment = f_
        if PayrollInput.objects.filter(company=o.company, employee=o.employee, month=o.month, year=o.year,
                                       input_type=o.input_type, amount=o.amount, is_active=True,
                                       label__iexact=o.label or "").exclude(pk=o.pk).exists():
            raise ValueError("An identical input already exists for this employee and month.")

    def destroy(self, request, pk=None):
        i = self.scope().filter(pk=pk, is_active=True).first()
        if i is not None:
            if i.status == "PROCESSED":
                return err("LOCKED", "A processed input cannot be deleted.", 403)
            try:
                ensure_open(i.company, i.month, i.year)
            except ValueError as e:
                return err("LOCKED", str(e), 409)
        return super().destroy(request, pk)

    def _decide(self, pk, status, remarks=None):
        i = self.scope().filter(pk=pk, is_active=True).first()
        if i is None:
            return None, err("NOT_FOUND", "Input not found.", 404)
        if i.status == "PROCESSED":
            return None, err("LOCKED", "A processed input cannot be changed.", 403)
        try:
            ensure_open(i.company, i.month, i.year)
        except ValueError as e:
            return None, err("LOCKED", str(e), 409)
        i.status, i.decided_by, i.decided_at, i.updated_by = status, self.actor(), timezone.now(), self.actor()
        if remarks is not None:
            i.decision_remarks = remarks
        i.save()
        return i, None

    @action(detail=True, methods=["post"])
    def approve(self, request, pk=None):
        i, e = self._decide(pk, "APPROVED", request.data.get("remarks"))
        return e or ok("PAYROLL_INPUT_APPROVED", "Input approved.", self.build(i))

    @action(detail=True, methods=["post"])
    def reject(self, request, pk=None):
        if not str(request.data.get("remarks") or "").strip():
            return err("VALIDATION", "remarks are required to reject.")
        i, e = self._decide(pk, "REJECTED", str(request.data["remarks"]))
        return e or ok("PAYROLL_INPUT_REJECTED", "Input rejected.", self.build(i))

    @action(detail=True, methods=["post"])
    def verify(self, request, pk=None):
        i, e = self._decide(pk, "VERIFIED", request.data.get("remarks"))
        return e or ok("PAYROLL_INPUT_VERIFIED", "Input verified.", self.build(i))

    @action(detail=False, methods=["post"])
    def bulk_approve(self, request):
        ids = request.data.get("ids")
        if not isinstance(ids, list) or not ids:
            return err("VALIDATION", "ids must be a non-empty list.")
        done, skipped = [], []
        for pk in ids:
            i, e = self._decide(pk, "APPROVED")
            (skipped if e else done).append(pk)
        return ok("PAYROLL_INPUT_BULK_APPROVED", f"{len(done)} approved, {len(skipped)} skipped.",
                  {"approved": done, "skipped": skipped})


# =============================================================== variable pay
class VariablePayViewSet(PayCrud):
    """
    GET  /api/payroll-hub/variable-pay/   ?employee=<code> ?status= ?period= ?search=
    POST /api/payroll-hub/variable-pay/   {employee_code, period_label, target_amount, achievement_percent?, payable_amount?,
                                           period_type?, payout_month?, payout_year?, appraisal_id?, remarks?, status?}
    GET|PATCH|PUT|DELETE .../<id>/ ; POST .../<id>/update|delete/
    POST .../<id>/approve/ {payout_month?, payout_year?}  .../reject/ {remarks}  .../schedule/ {payout_month, payout_year}  .../mark_paid/
    payable_amount = target x achievement% unless you send it explicitly.
    """
    model, code, select, status_field = VariablePay, "VARIABLE_PAY", ("employee",), "status"
    search_fields = ("period_label", "remarks", "employee__name", "employee__employee_code")
    permission_action_map = {"approve": "edit", "reject": "edit", "schedule": "edit", "mark_paid": "edit"}

    def filter(self, qs, p):
        qs = super().filter(qs, p)
        if p.get("employee"):
            qs = qs.filter(employee__employee_code=p["employee"])
        if p.get("period"):
            qs = qs.filter(period_label__iexact=p["period"])
        return qs

    def build(self, v):
        return variable_row(v, self.request)

    def apply(self, o, d, creating):
        if o.status == "PAID":
            raise ValueError("Paid variable pay cannot be changed.")
        if creating:
            o.employee = emp_by_code(o.company, d.get("employee_code"))
        if creating or "period_label" in d:
            if not str(d.get("period_label") or "").strip():
                raise ValueError("period_label is required (e.g. Q2 2026).")
            o.period_label = str(d["period_label"]).strip()[:40]
        if "period_type" in d:
            o.period_type = pick(d["period_type"], dict(VariablePay.PERIODS), "period_type")
        if creating or "target_amount" in d:
            o.target_amount = money(d, "target_amount", o.target_amount, allow_zero=False)
        if "achievement_percent" in d:
            a = to_decimal(d["achievement_percent"])
            if a is None or a < 0 or a > 500:
                raise ValueError("achievement_percent must be 0-500.")
            o.achievement_percent = a
        if "payable_amount" in d and d["payable_amount"] not in (None, ""):
            o.payable_amount = money(d, "payable_amount")
        elif creating or "target_amount" in d or "achievement_percent" in d:
            o.payable_amount = q2(o.target_amount * o.achievement_percent / 100)
        if "payout_month" in d or "payout_year" in d:
            o.payout_month, o.payout_year = month_year({"month": d.get("payout_month"), "year": d.get("payout_year")},
                                                       None, required=False)
        if "appraisal_id" in d:
            o.appraisal_id = to_int(d["appraisal_id"])
        if "remarks" in d:
            o.remarks = d["remarks"] or None
        if "status" in d:
            o.status = pick(d["status"], ["DRAFT", "PENDING_APPROVAL"], "status")
        if o.payout_month:
            ensure_open(o.company, o.payout_month, o.payout_year)
        if VariablePay.objects.filter(company=o.company, employee=o.employee, period_label__iexact=o.period_label
                                      ).exclude(pk=o.pk).exists():
            raise ValueError("Variable pay for this employee and period already exists.")

    def _get(self, pk):
        return self.scope().filter(pk=pk, is_active=True).first()

    @action(detail=True, methods=["post"])
    def approve(self, request, pk=None):
        v = self._get(pk)
        if v is None:
            return err("NOT_FOUND", "Variable pay not found.", 404)
        if v.status in ("PAID", "APPROVED"):
            return err("VALIDATION", f"Variable pay is already {v.status.lower()}.")
        try:
            if request.data.get("payout_month") or request.data.get("payout_year"):
                v.payout_month, v.payout_year = month_year({"month": request.data.get("payout_month"),
                                                            "year": request.data.get("payout_year")})
            if not v.payout_month:
                raise ValueError("payout_month and payout_year are required to approve.")
            ensure_open(v.company, v.payout_month, v.payout_year)
        except ValueError as e:
            return err("VALIDATION", str(e))
        v.status, v.decided_by, v.decided_at, v.updated_by = "APPROVED", self.actor(), timezone.now(), self.actor()
        v.save()
        return ok("VARIABLE_PAY_APPROVED", "Variable pay approved.", self.build(v))

    @action(detail=True, methods=["post"])
    def reject(self, request, pk=None):
        v = self._get(pk)
        if v is None:
            return err("NOT_FOUND", "Variable pay not found.", 404)
        if v.status == "PAID":
            return err("VALIDATION", "Paid variable pay cannot be rejected.")
        v.status, v.decided_by, v.decided_at, v.remarks = "REJECTED", self.actor(), timezone.now(), (
            request.data.get("remarks") or v.remarks)
        v.save()
        return ok("VARIABLE_PAY_REJECTED", "Variable pay rejected.", self.build(v))

    @action(detail=True, methods=["post"])
    def schedule(self, request, pk=None):
        v = self._get(pk)
        if v is None:
            return err("NOT_FOUND", "Variable pay not found.", 404)
        try:
            m, y = month_year({"month": request.data.get("payout_month"), "year": request.data.get("payout_year")})
            ensure_open(v.company, m, y)
        except ValueError as e:
            return err("VALIDATION", str(e))
        if v.status == "PAID":
            return err("VALIDATION", "Paid variable pay cannot be rescheduled.")
        v.payout_month, v.payout_year, v.updated_by = m, y, self.actor()
        v.save()
        return ok("VARIABLE_PAY_SCHEDULED", "Payout month set.", self.build(v))

    @action(detail=True, methods=["post"])
    def mark_paid(self, request, pk=None):
        v = self._get(pk)
        if v is None:
            return err("NOT_FOUND", "Variable pay not found.", 404)
        if v.status != "APPROVED":
            return err("VALIDATION", "Only approved variable pay can be marked paid.")
        v.status, v.updated_by = "PAID", self.actor()
        v.save()
        return ok("VARIABLE_PAY_PAID", "Marked as paid.", self.build(v))

    def destroy(self, request, pk=None):
        v = self._get(pk)
        if v is not None and v.status in ("PAID", "APPROVED"):
            return err("LOCKED", "Approved or paid variable pay cannot be deleted. Reject it first.", 403)
        return super().destroy(request, pk)


# =============================================================== non-statutory deductions
class DeductionViewSet(PayCrud):
    """
    GET  /api/payroll-hub/deductions/   ?month= ?year= ?employee=<code> ?status= ?search=
    POST /api/payroll-hub/deductions/   {employee_code, head, amount, reason?, month?, year?, exit_fnf_id?, status?}
    GET|PATCH|PUT|DELETE .../<id>/ ; POST .../<id>/update|delete/
    POST .../<id>/approve/ {month, year}   .../waive/ {remarks}   .../mark_fnf/ {exit_fnf_id?}   (recover in Full & Final)
    """
    model, code, select, status_field = PayrollDeduction, "PAYROLL_DEDUCTION", ("employee",), "status"
    search_fields = ("head", "reason", "employee__name", "employee__employee_code")
    permission_action_map = {"approve": "edit", "waive": "edit", "mark_fnf": "edit"}

    def filter(self, qs, p):
        qs = super().filter(qs, p)
        for k in ("month", "year"):
            if p.get(k):
                qs = qs.filter(**{k: p[k]})
        if p.get("employee"):
            qs = qs.filter(employee__employee_code=p["employee"])
        return qs

    def build(self, d):
        return deduction_row(d, self.request)

    def _fnf(self, company, emp, v):
        fnf = ExitFnF.objects.filter(company=company, pk=to_int(v)).select_related("exit").first()
        if fnf is None:
            raise ValueError("exit_fnf_id is invalid.")
        return fnf.id

    def apply(self, o, d, creating):
        if o.status in ("RECOVERED",):
            raise ValueError("A recovered deduction cannot be changed.")
        if creating:
            o.employee = emp_by_code(o.company, d.get("employee_code"))
        if creating or "head" in d:
            if not str(d.get("head") or "").strip():
                raise ValueError("head is required (e.g. Notice Period Shortfall).")
            o.head = str(d["head"]).strip()[:100]
        if creating or "amount" in d:
            o.amount = money(d, "amount", o.amount, allow_zero=False)
        if "reason" in d:
            o.reason = d["reason"] or None
        if "month" in d or "year" in d:
            o.month, o.year = month_year(d, o, required=False)
        if d.get("exit_fnf_id"):
            o.exit_fnf_id = self._fnf(o.company, o.employee, d["exit_fnf_id"])
            o.status = "PENDING_FNF" if "status" not in d else o.status
        if "status" in d:
            o.status = pick(d["status"], ["PENDING_APPROVAL", "PENDING_FNF"], "status")
        if o.month:
            ensure_open(o.company, o.month, o.year)
        if PayrollDeduction.objects.filter(company=o.company, employee=o.employee, head__iexact=o.head,
                                           amount=o.amount, month=o.month, year=o.year, is_active=True
                                           ).exclude(pk=o.pk).exists():
            raise ValueError("An identical deduction already exists for this employee.")

    def _get(self, pk):
        return self.scope().filter(pk=pk, is_active=True).first()

    @action(detail=True, methods=["post"])
    def approve(self, request, pk=None):
        d = self._get(pk)
        if d is None:
            return err("NOT_FOUND", "Deduction not found.", 404)
        if d.status in ("RECOVERED", "WAIVED"):
            return err("VALIDATION", f"This deduction is already {d.status.lower()}.")
        try:
            if request.data.get("month") or request.data.get("year"):
                d.month, d.year = month_year(request.data)
            if not d.month:
                raise ValueError("month and year are required to approve a deduction.")
            ensure_open(d.company, d.month, d.year)
        except ValueError as e:
            return err("VALIDATION", str(e))
        d.status, d.decided_by, d.decided_at, d.updated_by = "APPROVED", self.actor(), timezone.now(), self.actor()
        d.save()
        return ok("PAYROLL_DEDUCTION_APPROVED", "Deduction approved.", self.build(d))

    @action(detail=True, methods=["post"])
    def waive(self, request, pk=None):
        d = self._get(pk)
        if d is None:
            return err("NOT_FOUND", "Deduction not found.", 404)
        if d.status == "RECOVERED":
            return err("VALIDATION", "A recovered deduction cannot be waived.")
        d.status, d.decided_by, d.decided_at = "WAIVED", self.actor(), timezone.now()
        d.reason = request.data.get("remarks") or d.reason
        d.save()
        return ok("PAYROLL_DEDUCTION_WAIVED", "Deduction waived.", self.build(d))

    @action(detail=True, methods=["post"])
    def mark_fnf(self, request, pk=None):
        d = self._get(pk)
        if d is None:
            return err("NOT_FOUND", "Deduction not found.", 404)
        if d.status in ("RECOVERED", "WAIVED"):
            return err("VALIDATION", f"This deduction is already {d.status.lower()}.")
        try:
            if request.data.get("exit_fnf_id"):
                d.exit_fnf_id = self._fnf(d.company, d.employee, request.data["exit_fnf_id"])
        except ValueError as e:
            return err("VALIDATION", str(e))
        d.status, d.month, d.year, d.updated_by = "PENDING_FNF", None, None, self.actor()
        d.save()
        return ok("PAYROLL_DEDUCTION_FNF", "Marked to be recovered in Full & Final.", self.build(d))

    def destroy(self, request, pk=None):
        d = self._get(pk)
        if d is not None and d.status == "RECOVERED":
            return err("LOCKED", "A recovered deduction cannot be deleted.", 403)
        return super().destroy(request, pk)


# =============================================================== loans / advances
def loan_terms_check(o, gross=None):
    st = get_setting(o.company)
    if o.tenure_months < 1 or o.tenure_months > st.loan_max_tenure_months:
        raise ValueError(f"tenure_months must be between 1 and {st.loan_max_tenure_months}.")
    if st.loan_max_principal and o.principal > st.loan_max_principal:
        raise ValueError(f"principal cannot exceed {st.loan_max_principal}.")
    o.emi_amount = en.emi_for(o.principal, o.interest_rate, o.tenure_months)
    last = Payroll.objects.filter(company=o.company, Employee_ID=o.employee.employee_code).order_by("-year", "-month").first()
    g = gross or (last.gross_salary if last else None)
    if g and o.emi_amount > g * st.loan_max_emi_percent / 100:
        raise ValueError(f"EMI {o.emi_amount} exceeds {st.loan_max_emi_percent}% of the employee's monthly gross ({g}).")


class LoanViewSet(PayCrud):
    """
    GET  /api/payroll-hub/loans/    ?status= ?employee=<code> ?loan_type= ?search=
    POST /api/payroll-hub/loans/    {employee_code, principal, tenure_months, loan_type?, interest_rate?, start_month, start_year,
                                     purpose?, sanction?=true}      sanction=true -> ACTIVE with EMI schedule, false -> PENDING
    GET|PATCH|PUT|DELETE .../<id>/  (edit / delete only while PENDING)   POST .../<id>/update|delete/
    POST .../<id>/approve/ {start_month, start_year, remarks?}  .../reject/ {remarks}  .../foreclose/ {remarks}
    GET  .../<id>/schedule/          POST .../<id>/skip_installment/ {installment_no}
    GET  .../outstanding/?employee=<code>     (for Full & Final recovery)
    """
    model, code, select, status_field = Loan, "LOAN", ("employee",), "status"
    search_fields = ("loan_no", "purpose", "employee__name", "employee__employee_code")
    permission_action_map = {"approve": "edit", "reject": "edit", "foreclose": "edit", "schedule": "view",
                             "skip_installment": "edit", "outstanding": "view"}

    def filter(self, qs, p):
        qs = super().filter(qs, p)
        if p.get("employee"):
            qs = qs.filter(employee__employee_code=p["employee"])
        if p.get("loan_type"):
            qs = qs.filter(loan_type=p["loan_type"].upper())
        return qs

    def build(self, l):
        return loan_row(l, self.request)

    def retrieve(self, request, pk=None):
        l = self.scope().filter(pk=pk, is_active=True).first()
        return ok("LOAN_DETAIL", "Detail.", loan_row(l, request, True)) if l else err("NOT_FOUND", "Loan not found.", 404)

    def list(self, request):
        resp = super().list(request)
        base = self.scope().filter(is_active=True, status="ACTIVE")
        active = list(base)
        resp.data["summary"] = {"active_loans": len(active), "sanctioned_principal": f(sum((l.principal for l in active),
                                Decimal("0"))), "monthly_emi_total": f(sum((l.emi_amount for l in active), Decimal("0"))),
                                "balance_remaining": round(sum(en.loan_balance(l)["balance_remaining"] for l in active), 2),
                                "pending_requests": self.scope().filter(is_active=True, status="PENDING").count()}
        return resp

    def _validate_terms(self, o, gross=None):
        return loan_terms_check(o, gross)

    def apply(self, o, d, creating):
        if not creating and o.status != "PENDING":
            raise ValueError("Only a pending loan can be edited.")
        if creating:
            o.employee = emp_by_code(o.company, d.get("employee_code"))
        if creating or "loan_type" in d:
            o.loan_type = pick(d.get("loan_type") or "LOAN", dict(Loan.TYPES), "loan_type")
        if creating or "principal" in d:
            o.principal = money(d, "principal", o.principal, allow_zero=False)
        if "interest_rate" in d:
            r = to_decimal(d["interest_rate"], Decimal("0"))
            if r < 0 or r > 60:
                raise ValueError("interest_rate must be 0-60.")
            o.interest_rate = r
        if creating or "tenure_months" in d:
            o.tenure_months = to_int(d.get("tenure_months"), o.tenure_months or 0)
        if "purpose" in d:
            o.purpose = d["purpose"] or None
        if "start_month" in d or "start_year" in d:
            o.start_month, o.start_year = month_year({"month": d.get("start_month"), "year": d.get("start_year")}, None,
                                                     required=False)
        self._validate_terms(o)
        self._sanction = creating and to_bool(d.get("sanction"), True)
        if self._sanction:
            if not o.start_month:
                raise ValueError("start_month and start_year are required to sanction a loan.")
            o.status, o.sanctioned_on, o.decided_by = "ACTIVE", timezone.localdate(), self.actor()
        if creating:
            o.loan_no = en.next_loan_no(o.company, timezone.localdate().year)
        if Loan.objects.filter(company=o.company, employee=o.employee, principal=o.principal,
                               tenure_months=o.tenure_months, status__in=["PENDING", "ACTIVE"]).exclude(pk=o.pk).exists():
            raise ValueError("A pending / active loan with the same amount and tenure already exists for this employee.")

    def after_save(self, o, creating):
        if creating and getattr(self, "_sanction", False):
            self._make_schedule(o)
        elif not creating and o.status == "PENDING":
            pass

    def _make_schedule(self, l):
        l.repayments.all().delete()
        for r in en.loan_schedule(l.principal, l.interest_rate, l.tenure_months, l.start_month, l.start_year):
            LoanRepayment.objects.create(company=l.company, loan=l, created_by=self.actor(), updated_by=self.actor(), **r)

    def _get(self, pk):
        return self.scope().filter(pk=pk, is_active=True).first()

    @action(detail=True, methods=["post"])
    @transaction.atomic
    def approve(self, request, pk=None):
        l = self._get(pk)
        if l is None:
            return err("NOT_FOUND", "Loan not found.", 404)
        if l.status != "PENDING":
            return err("VALIDATION", "Only a pending loan can be approved.")
        try:
            m, y = month_year({"month": request.data.get("start_month") or l.start_month,
                               "year": request.data.get("start_year") or l.start_year})
            l.start_month, l.start_year = m, y
            self._validate_terms(l)
        except ValueError as e:
            return err("VALIDATION", str(e))
        l.status, l.sanctioned_on, l.decided_by = "ACTIVE", timezone.localdate(), self.actor()
        l.decision_remarks, l.updated_by = request.data.get("remarks"), self.actor()
        l.save()
        self._make_schedule(l)
        return ok("LOAN_APPROVED", "Loan sanctioned and EMI schedule created.", loan_row(l, request, True))

    @action(detail=True, methods=["post"])
    def reject(self, request, pk=None):
        l = self._get(pk)
        if l is None:
            return err("NOT_FOUND", "Loan not found.", 404)
        if l.status != "PENDING":
            return err("VALIDATION", "Only a pending loan can be rejected.")
        if not str(request.data.get("remarks") or "").strip():
            return err("VALIDATION", "remarks are required to reject.")
        l.status, l.decided_by, l.decision_remarks = "REJECTED", self.actor(), request.data["remarks"]
        l.save()
        return ok("LOAN_REJECTED", "Loan rejected.", self.build(l))

    @action(detail=True, methods=["post"])
    @transaction.atomic
    def foreclose(self, request, pk=None):
        l = self._get(pk)
        if l is None:
            return err("NOT_FOUND", "Loan not found.", 404)
        if l.status != "ACTIVE":
            return err("VALIDATION", "Only an active loan can be foreclosed.")
        out = en.loan_balance(l)["balance_remaining"]
        l.repayments.filter(status="SCHEDULED").update(status="WAIVED")
        l.status, l.decision_remarks, l.updated_by = "FORECLOSED", request.data.get("remarks"), self.actor()
        l.save()
        return ok("LOAN_FORECLOSED", "Loan foreclosed (remaining EMIs closed).", loan_row(l, request, True),
                  settled_amount=out)

    @action(detail=True, methods=["get"])
    def schedule(self, request, pk=None):
        l = self._get(pk)
        return ok("LOAN_SCHEDULE", "EMI schedule.", loan_row(l, request, True)) if l else err("NOT_FOUND", "Loan not found.", 404)

    @action(detail=True, methods=["post"])
    @transaction.atomic
    def skip_installment(self, request, pk=None):
        l = self._get(pk)
        if l is None:
            return err("NOT_FOUND", "Loan not found.", 404)
        r = l.repayments.filter(status="SCHEDULED", installment_no=to_int(request.data.get("installment_no"))).first()
        if r is None or l.status != "ACTIVE":
            return err("VALIDATION", "installment_no must be a scheduled installment of an active loan.")
        if locked(l.company, r.month, r.year):
            return err("LOCKED", f"{month_label(r.month, r.year)} payroll is frozen.", 409)
        last = l.repayments.order_by("-installment_no").first()
        m, y = (1, last.year + 1) if last.month == 12 else (last.month + 1, last.year)
        r.status = "SKIPPED"
        r.save()
        LoanRepayment.objects.create(company=l.company, loan=l, installment_no=last.installment_no + 1, month=m, year=y,
                                     amount=r.amount, principal_part=r.principal_part, interest_part=r.interest_part,
                                     created_by=self.actor(), updated_by=self.actor())
        return ok("LOAN_INSTALLMENT_SKIPPED", "Installment skipped and added at the end.", loan_row(l, request, True))

    @action(detail=False, methods=["get"])
    def outstanding(self, request):
        try:
            e = emp_by_code(self.company(), request.query_params.get("employee"))
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        loans = self.scope().filter(is_active=True, employee=e, status="ACTIVE")
        rows = [loan_row(l, request) for l in loans]
        return ok("LOAN_OUTSTANDING", "Outstanding loans.", rows,
                  summary={"total_outstanding": round(sum(r["balance_remaining"] for r in rows), 2), "loans": len(rows)})

    def destroy(self, request, pk=None):
        l = self._get(pk)
        if l is not None and l.status not in ("PENDING", "REJECTED", "CANCELLED"):
            return err("LOCKED", "Only pending, rejected or cancelled loans can be deleted.", 403)
        return super().destroy(request, pk)


# =============================================================== processing cycle
class CycleViewSet(PayAuthMixin, ViewSet):
    """
    GET  /api/payroll-hub/cycles/                       all cycles
    GET  /api/payroll-hub/cycles/<MM-YYYY>/             Monthly Payroll Processing Lifecycle (4 steps) - created on first read
    POST .../<MM-YYYY>/generate_payroll/                run the EXISTING payroll generator for the month
    POST .../<MM-YYYY>/freeze/ {release_on?}            1. Inputs Freeze          POST .../unfreeze/ (back to OPEN)
    POST .../<MM-YYYY>/validate/                        2. Verification Run ("Run Payroll Validation")
    POST .../<MM-YYYY>/bank_file/                       3. Bank Transfer File     GET .../bank_file_download/
    POST .../<MM-YYYY>/release/ {force?, skip_bank_file?}   4. Release Payslips   POST .../revoke/
    """
    lookup_value_regex = r"\d{1,2}-\d{4}"
    permission_action_map = {"generate_payroll": "create", "freeze": "edit", "unfreeze": "edit", "validate": "edit",
                             "bank_file": "edit", "bank_file_download": "view", "release": "edit", "revoke": "edit"}

    def _cycle(self, pk, create=True):
        m, y = (int(x) for x in pk.split("-"))
        if not 1 <= m <= 12:
            raise ValueError("Invalid month.")
        c = self.company()
        return (en.get_cycle(c, m, y, self.actor()) if create else PayrollCycle.objects.filter(
            company=c, month=m, year=y).first())

    def list(self, request):
        st = get_setting(self.company())
        return ok("PAYROLL_CYCLES", "Payroll cycles.", [cycle_row(c, st) for c in PayrollCycle.objects.filter(
            company=self.company(), is_active=True)])

    def retrieve(self, request, pk=None):
        try:
            c = self._cycle(pk)
        except ValueError as e:
            return err("VALIDATION", str(e))
        st = get_setting(c.company)
        emps, _ = en.employees_in_cycle(c.company, c.month, c.year)
        return ok("PAYROLL_CYCLE", f"Monthly Payroll Processing Lifecycle ({c.month and month_label(c.month, c.year)}).",
                  cycle_row(c, st) | {"employees_with_payroll": len(emps)})

    def _do(self, pk, fn):
        try:
            c = self._cycle(pk)
            return fn(c, get_setting(c.company))
        except ValueError as e:
            return err("VALIDATION", str(e))

    @action(detail=True, methods=["post"])
    def generate_payroll(self, request, pk=None):
        def run(c, st):
            if c.status != "OPEN":
                raise ValueError("Unfreeze the cycle before regenerating payroll.")
            from Company.payroll_engine import generate_monthly_payroll
            res = generate_monthly_payroll(c.month, c.year, c.company)
            return ok("PAYROLL_GENERATED", f"Payroll generated for {len(res['payrolls'])} employee(s).", {
                "generated": len(res["payrolls"]), "skipped_paid": res["skipped_paid"], "errors": res["errors"]})
        return self._do(pk, run)

    @action(detail=True, methods=["post"])
    def freeze(self, request, pk=None):
        def run(c, st):
            if c.status != "OPEN":
                raise ValueError("Inputs are already frozen.")
            if not Payroll.objects.filter(company=c.company, month=c.month, year=c.year).exists():
                raise ValueError("Generate payroll for this month first (POST generate_payroll/).")
            if request.data.get("release_on"):
                c.release_on = to_date(request.data["release_on"])
            c.status, c.inputs_frozen_at, c.inputs_frozen_by, c.updated_by = ("INPUTS_FROZEN", timezone.now(),
                                                                              self.actor(), self.actor())
            c.save()
            return ok("PAYROLL_FROZEN", "Inputs frozen.", cycle_row(c, st))
        return self._do(pk, run)

    @action(detail=True, methods=["post"])
    def unfreeze(self, request, pk=None):
        def run(c, st):
            if c.status == "RELEASED":
                raise ValueError("Revoke the released payslips first.")
            if c.status == "OPEN":
                raise ValueError("Inputs are not frozen.")
            c.status, c.verified_at, c.bank_file_at, c.verification_result = "OPEN", None, None, {}
            c.inputs_frozen_at = None
            c.updated_by = self.actor()
            c.save()
            return ok("PAYROLL_UNFROZEN", "Cycle reopened for changes.", cycle_row(c, st))
        return self._do(pk, run)

    @action(detail=True, methods=["post"])
    def validate(self, request, pk=None):
        def run(c, st):
            res = en.validate_cycle(c.company, c.month, c.year)
            advanced = False
            if c.status == "INPUTS_FROZEN" and res["passed"]:
                c.status, c.verified_at, c.verified_by = "VERIFIED", timezone.now(), self.actor()
                advanced = True
            c.verification_result = {"passed": res["passed"], "errors": res["errors"], "warnings": res["warnings"],
                                     "ran_at": iso(timezone.now())}
            c.updated_by = self.actor()
            c.save()
            return ok("PAYROLL_VALIDATED", "Payroll validation passed." if res["passed"] else
                      "Payroll validation found issues.", res | {"cycle": cycle_row(c, st), "advanced": advanced})
        return self._do(pk, run)

    @action(detail=True, methods=["post"])
    def bank_file(self, request, pk=None):
        def run(c, st):
            ok_status = ("VERIFIED", "BANK_FILE_READY") if st.require_verification_before_bank_file else (
                "INPUTS_FROZEN", "VERIFIED", "BANK_FILE_READY")
            if c.status not in ok_status:
                raise ValueError("Run the verification successfully before generating the bank file.")
            rows, skipped = en.bank_file_rows(c.company, c.month, c.year)
            if not rows:
                raise ValueError("No payable bank transfers found.")
            from django.core.files.base import ContentFile
            c.bank_file.save(f"salary_{c.year}_{c.month:02d}.csv", ContentFile(en.bank_csv(rows).encode()), save=False)
            c.bank_file_total = Decimal(str(round(sum(r["amount"] for r in rows), 2)))
            c.bank_file_count = len(rows)
            c.status, c.bank_file_at, c.bank_file_by, c.updated_by = "BANK_FILE_READY", timezone.now(), self.actor(), self.actor()
            c.save()
            return ok("PAYROLL_BANK_FILE", f"Bank file generated for {len(rows)} employee(s).", cycle_row(c, st), 201,
                      skipped=skipped)
        return self._do(pk, run)

    @action(detail=True, methods=["get"])
    def bank_file_download(self, request, pk=None):
        c = self._cycle(pk, create=False)
        if c is None or not c.bank_file:
            raise Http404("Bank file not generated.")
        resp = HttpResponse(c.bank_file.read(), content_type="text/csv")
        resp["Content-Disposition"] = f'attachment; filename="salary_{c.year}_{c.month:02d}.csv"'
        return resp

    @action(detail=True, methods=["post"])
    @transaction.atomic
    def release(self, request, pk=None):
        def run(c, st):
            allowed = ["BANK_FILE_READY"] + (["VERIFIED"] if to_bool(request.data.get("skip_bank_file")) else [])
            if c.status not in allowed:
                raise ValueError("Generate the bank transfer file before releasing payslips.")
            due = c.release_on or en.default_release_date(st, c.month, c.year)
            if due > timezone.localdate() and not to_bool(request.data.get("force")):
                raise ValueError(f"Release is scheduled for {due:%d %b %Y}. Pass force=true to release now.")
            emps, _ = en.employees_in_cycle(c.company, c.month, c.year)
            n = 0
            for code, e in emps.items():
                s = en.compute_payslip(c.company, e, c.month, c.year, st)
                Payslip.objects.update_or_create(
                    company=c.company, employee=e, month=c.month, year=c.year,
                    defaults={"cycle": c, "payslip_no": f"PSL-{c.year}-{c.month:02d}-{code}",
                              "gross_salary": s["gross_salary"], "total_deductions": s["total_deductions"],
                              "net_payable": s["net_payable"], "breakup": {"earnings": s["earnings"],
                                                                           "deductions": s["deductions"]},
                              "status": "RELEASED", "released_at": timezone.now(), "released_by": self.actor(),
                              "is_active": True, "updated_by": self.actor()})
                n += 1
            now = timezone.now()
            PayrollInput.objects.filter(company=c.company, month=c.month, year=c.year, is_active=True,
                                        status__in=["APPROVED", "VERIFIED"]).exclude(input_type="LOP").update(status="PROCESSED")
            PayrollDeduction.objects.filter(company=c.company, month=c.month, year=c.year, is_active=True,
                                            status="APPROVED").update(status="RECOVERED")
            VariablePay.objects.filter(company=c.company, payout_month=c.month, payout_year=c.year, is_active=True,
                                       status="APPROVED").update(status="PAID")
            reps = LoanRepayment.objects.filter(company=c.company, month=c.month, year=c.year, is_active=True,
                                                status="SCHEDULED", loan__status="ACTIVE")
            loan_ids = set(reps.values_list("loan_id", flat=True))
            reps.update(status="DEDUCTED", deducted_at=now)
            for l in Loan.objects.filter(pk__in=loan_ids):
                if not l.repayments.filter(status="SCHEDULED", is_active=True).exists():
                    l.status = "CLOSED"
                    l.save()
            c.status, c.released_at, c.released_by, c.updated_by = "RELEASED", now, self.actor(), self.actor()
            c.save()
            return ok("PAYROLL_RELEASED", f"{n} payslip(s) released.", cycle_row(c, st), released=n)
        return self._do(pk, run)

    @action(detail=True, methods=["post"])
    @transaction.atomic
    def revoke(self, request, pk=None):
        def run(c, st):
            if c.status != "RELEASED":
                raise ValueError("Only a released cycle can be revoked.")
            Payslip.objects.filter(company=c.company, month=c.month, year=c.year).update(status="REVOKED")
            PayrollInput.objects.filter(company=c.company, month=c.month, year=c.year, status="PROCESSED").update(status="APPROVED")
            PayrollDeduction.objects.filter(company=c.company, month=c.month, year=c.year, status="RECOVERED").update(status="APPROVED")
            VariablePay.objects.filter(company=c.company, payout_month=c.month, payout_year=c.year, status="PAID").update(status="APPROVED")
            reps = LoanRepayment.objects.filter(company=c.company, month=c.month, year=c.year, status="DEDUCTED")
            loan_ids = set(reps.values_list("loan_id", flat=True))
            reps.update(status="SCHEDULED", deducted_at=None)
            Loan.objects.filter(pk__in=loan_ids, status="CLOSED").update(status="ACTIVE")
            c.status, c.released_at, c.updated_by = "BANK_FILE_READY", None, self.actor()
            c.save()
            return ok("PAYROLL_RELEASE_REVOKED", "Release revoked; payslips are hidden from employees.", cycle_row(c, st))
        return self._do(pk, run)


# =============================================================== payslips
class PayslipViewSet(PayAuthMixin, ViewSet):
    """
    GET /api/payroll-hub/payslips/?month=&year= ?search= ?department=<id> ?released=true|false ?page=   Payslip Distribution Center
    GET /api/payroll-hub/payslips/<employee_code>/?month=&year=        detail (released snapshot, else live preview)
    GET /api/payroll-hub/payslips/<employee_code>/pdf/?month=&year=    View / Print Payslip (PDF)
    """
    lookup_value_regex = r"[^/]+"
    permission_action_map = {"pdf": "view"}

    def _slip(self, company, emp, m, y):
        snap = Payslip.objects.filter(company=company, employee=emp, month=m, year=y, status="RELEASED").first()
        live = en.compute_payslip(company, emp, m, y)
        if live is None:
            return None, None
        if snap:
            live = live | {"gross_salary": f(snap.gross_salary), "total_deductions": f(snap.total_deductions),
                           "net_payable": f(snap.net_payable), "earnings": snap.breakup.get("earnings", []),
                           "deductions": snap.breakup.get("deductions", [])}
        return live, snap

    def list(self, request):
        c, p = self.company(), request.query_params
        try:
            m, y = cur_period(p)
        except ValueError as e:
            return err("VALIDATION", str(e))
        emps, _ = en.employees_in_cycle(c, m, y)
        q = (p.get("search") or "").lower()
        items = sorted(emps.values(), key=lambda e: e.employee_code)
        if q:
            items = [e for e in items if q in e.name.lower() or q in e.employee_code.lower()]
        if p.get("department"):
            items = [e for e in items if str(e.department_id) == p["department"]]
        snaps = {s.employee_id: s for s in Payslip.objects.filter(company=c, month=m, year=y, status="RELEASED")}
        if p.get("released"):
            want = to_bool(p["released"])
            items = [e for e in items if (e.id in snaps) == want]
        st = get_setting(c)
        page, meta = paginate(request, items, lambda e: e)
        rows = []
        for e in page:
            slip = en.compute_payslip(c, e, m, y, st)
            sn = snaps.get(e.id)
            if sn:
                slip = slip | {"gross_salary": f(sn.gross_salary), "total_deductions": f(sn.total_deductions),
                               "net_payable": f(sn.net_payable)}
            rows.append(slip_row(c, e, slip, sn, request))
        return ok("PAYSLIP_LIST", f"Payslip Distribution Center ({month_label(m, y)}).", rows, meta=meta,
                  summary={"employees": len(items), "released": sum(1 for e in items if e.id in snaps),
                           "period": month_label(m, y)})

    def retrieve(self, request, pk=None):
        c = self.company()
        try:
            m, y = cur_period(request.query_params)
            e = emp_by_code(c, pk)
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        slip, snap = self._slip(c, e, m, y)
        if slip is None:
            return err("NOT_FOUND", f"No payroll for {e.name} in {month_label(m, y)}.", 404)
        return ok("PAYSLIP_DETAIL", "Payslip.", slip | {"employee": emp_brief(e, request),
                                                       "released": bool(snap), "payslip_no": snap.payslip_no if snap else None,
                                                       "released_at": iso(snap.released_at) if snap else None})

    @action(detail=True, methods=["get"])
    def pdf(self, request, pk=None):
        c = self.company()
        try:
            m, y = cur_period(request.query_params)
            e = emp_by_code(c, pk)
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        slip, _ = self._slip(c, e, m, y)
        if slip is None:
            raise Http404("Payroll not found.")
        resp = HttpResponse(en.payslip_pdf(c, e, slip), content_type="application/pdf")
        resp["Content-Disposition"] = f'inline; filename="payslip_{e.employee_code}_{y}_{m:02d}.pdf"'
        return resp
