# ============================================================
# ADDITIVE: Time, Biometrics & Perimeter Security - Admin / HR API
# ------------------------------------------------------------
# Mounted at /api/attendance-hub/   (see People/att_urls.py)
# Auth: Company Admin token, or an employee whose role has the EXISTING attendance checkboxes
#       can_view_attendance / can_create_attendance / can_edit_attendance /
#       can_delete_attendance / can_manage_attendance.
#
# Screen tab                  -> endpoint(s)
# -----------------------------------------------------------------
# Attendance Dashboard        -> GET dashboard/  GET meta/  GET|PATCH policy/
# Daily Attendance            -> CRUD daily/ , GET daily/export/ (CSV)
# Geofenced Web/Mobile Check-in -> CRUD geofences/ , POST geofences/simulate/
# Biometric Hardware Hub      -> CRUD devices/ , POST devices/<id>/rotate-key|ping|sync , POST devices/sync-all/
#                                CRUD enrollments/ , CRUD punches/ (raw buffer) , POST punches/reprocess/
#                                GET|PATCH gateway/ , POST gateway/ping/
# Field Force Geo-Tracking    -> CRUD field/agents/ , CRUD field/points/ , GET field/summary/ ,
#                                GET field/route/ , GET field/travel-claim/
# Late / Early Leaving        -> GET late-early/
# Regularization              -> CRUD regularizations/ , POST <id>/approve|reject/
# Perimeter Exceptions        -> CRUD perimeter-events/ , POST <id>/resolve|override/
# Device-facing (API key)     -> POST device/ingest/ , POST device/heartbeat/   (People/views_att_device.py)
# ============================================================
import csv
import io
import re
from datetime import datetime, time, timedelta
from decimal import Decimal

from django.db import IntegrityError, transaction
from django.db.models import Q
from django.http import HttpResponse
from django.utils import timezone
from django.utils.dateparse import parse_datetime
from rest_framework.decorators import action
from rest_framework.permissions import BasePermission
from rest_framework.views import APIView
from rest_framework.viewsets import ViewSet

from Employee.employee_crud_permissions import _role_is_usable, resolve_actor_role, role_allows
from Employee.models import EMP_check_in_check_out, EmployeeDT

from . import att_engine as en
from .att_models import (AttendanceGeofence, AttendancePolicy, AttendancePunchMeta, AttendanceRegularization, BiometricDevice,
                         BiometricEnrollment, BiometricPunch, FieldForceAgent, FieldTrackPoint, PerimeterEvent)
from .common import CrudBase, PeopleAuthMixin, emp_by_code, employees_qs, err, iso, next_seq, ok, paginate, to_bool, to_date, to_decimal, to_int
from .models import Branch
from .reports_exports import safe_cell


# ------------------------------------------------------------
# permissions (existing attendance role checkboxes)
# ------------------------------------------------------------

def attendance_allows(user, action_name):
    actor = resolve_actor_role(user)
    if actor == "admin":
        return True
    if actor is None:
        return False
    role = _role_is_usable(user)
    if role is None:
        return False
    return role_allows(role, "attendance", "edit" if action_name == "approve" else action_name)


class IsAttendanceUser(BasePermission):
    message = "You do not have permission to use Attendance."
    METHOD_ACTION = {"GET": "view", "HEAD": "view", "OPTIONS": "view", "POST": "create", "PUT": "edit", "PATCH": "edit", "DELETE": "delete"}

    def has_permission(self, request, view):
        act = getattr(view, "permission_action", None)
        if act is None:
            va = getattr(view, "action", None)
            act = {"update_post": "edit", "delete_post": "delete"}.get(va) or (getattr(view, "permission_action_map", None) or {}).get(va)
        act = act or self.METHOD_ACTION.get(request.method)
        return bool(act) and attendance_allows(request.user, act)


class AttMixin(PeopleAuthMixin):
    permission_classes = [IsAttendanceUser]


class AttView(AttMixin, APIView):
    pass


class AttCrud(AttMixin, CrudBase):
    """CrudBase + 409 on unique clashes (inside a savepoint so the transaction stays usable)."""
    dup_message = "A record with the same details already exists."

    def filter(self, qs, p):
        return super().filter(qs, {k: v for k, v in p.items() if k != "employee"})

    def create(self, request):
        try:
            with transaction.atomic():
                return super().create(request)
        except IntegrityError:
            return err("EXISTS", self.dup_message, 409)

    def partial_update(self, request, pk=None):
        try:
            with transaction.atomic():
                return super().partial_update(request, pk)
        except IntegrityError:
            return err("EXISTS", self.dup_message, 409)

    update = partial_update


def date_range(p, default_days=7):
    """?from=&to= (default: last N days) -> (start, end)."""
    end = to_date(p.get("to")) or timezone.localdate()
    start = to_date(p.get("from")) or (end - timedelta(days=default_days - 1))
    if end < start:
        raise ValueError("'to' cannot be before 'from'.")
    return start, end


def parse_time(v, field):
    if v in (None, ""):
        return None
    m = re.match(r"^(\d{1,2}):(\d{2})(?::(\d{2}))?$", str(v).strip())
    if not m or int(m.group(1)) > 23 or int(m.group(2)) > 59:
        raise ValueError(f"{field} must be HH:MM or HH:MM:SS (24h).")
    return time(int(m.group(1)), int(m.group(2)), int(m.group(3) or 0))


def parse_dt(v, field):
    d = parse_datetime(str(v)) if v else None
    if d is None:
        raise ValueError(f"{field} must be an ISO date-time (e.g. 2026-09-11T09:28:14+05:30).")
    return timezone.make_aware(d) if timezone.is_naive(d) else d


def valid_ip(v):
    import ipaddress
    try:
        return str(ipaddress.ip_address(str(v).strip()))
    except ValueError:
        raise ValueError(f"Invalid IP address: {v}")


# ============================================================
# DASHBOARD / META / POLICY
# ============================================================

class AttMetaView(AttView):
    """GET /api/attendance-hub/meta/"""

    def get(self, request):
        return ok("ATT_META", "Attendance metadata.", {
            "tabs": [{"key": k, "endpoint": e} for k, e in (
                ("dashboard", "dashboard/"), ("daily", "daily/"), ("geofence", "geofences/"), ("biometric", "devices/"),
                ("field", "field/summary/"), ("late_early", "late-early/"), ("regularization", "regularizations/"),
                ("perimeter_exceptions", "perimeter-events/"))],
            "vendors": [c for c, _ in BiometricDevice.VENDORS], "sync_protocols": [c for c, _ in BiometricDevice.PROTOCOLS],
            "device_statuses": [c for c, _ in BiometricDevice.STATUS], "verification_modes": [c for c, _ in BiometricEnrollment.MODES],
            "punch_sources": [c for c, _ in AttendancePunchMeta.SOURCES], "perimeter_verdicts": [c for c, _ in AttendancePunchMeta.VERDICTS],
            "punch_sync_statuses": [c for c, _ in BiometricPunch.SYNC], "perimeter_event_statuses": [c for c, _ in PerimeterEvent.STATUS],
            "field_point_types": [c for c, _ in FieldTrackPoint.TYPES], "regularization_statuses": [c for c, _ in AttendanceRegularization.STATUS]})


class AttDashboardView(AttView):
    """GET /api/attendance-hub/dashboard/?date=YYYY-MM-DD"""

    def get(self, request):
        try:
            day = to_date(request.query_params.get("date")) or timezone.localdate()
        except ValueError as e:
            return err("VALIDATION", str(e))
        return ok("ATT_DASHBOARD", "Attendance dashboard.", en.dashboard(self.company(), day, request))


class PolicyView(AttView):
    """
    GET   /api/attendance-hub/policy/            saved policy or the defaults
    PATCH|PUT|POST /api/attendance-hub/policy/   {shift_start, shift_end, grace_minutes, early_leave_grace_minutes,
                                                  perimeter_enforced, allow_web_punch, allow_mobile_punch, wfh_redirect_enabled,
                                                  field_ping_interval_minutes, device_online_minutes, ingestion_mode,
                                                  reconcile_interval_seconds}
    The same shift / grace feed the Late-Early tab, the daily "Late" badge AND the punctuality
    numbers of the Reports module.
    """
    permission_action_map = {}

    def get(self, request):
        return ok("ATT_POLICY", "Attendance policy.", en.policy_row(en.get_policy(self.company())))

    def _save(self, request):
        co, d = self.company(), request.data
        p = AttendancePolicy.objects.filter(company=co).first() or AttendancePolicy(company=co, created_by=self.actor())
        try:
            for f in ("shift_start", "shift_end"):
                if f in d:
                    setattr(p, f, parse_time(d[f], f))
            for f, lo, hi in (("grace_minutes", 0, 180), ("early_leave_grace_minutes", 0, 180), ("field_ping_interval_minutes", 1, 240),
                              ("device_online_minutes", 1, 1440), ("reconcile_interval_seconds", 5, 86400)):
                if f in d:
                    v = to_int(d[f])
                    if v is None or not (lo <= v <= hi):
                        raise ValueError(f"{f} must be between {lo} and {hi}.")
                    setattr(p, f, v)
            for f in ("perimeter_enforced", "allow_web_punch", "allow_mobile_punch", "wfh_redirect_enabled"):
                if f in d:
                    setattr(p, f, to_bool(d[f]))
            if "ingestion_mode" in d:
                if not str(d["ingestion_mode"] or "").strip():
                    raise ValueError("ingestion_mode cannot be empty.")
                p.ingestion_mode = str(d["ingestion_mode"]).strip()[:80]
            if p.shift_end <= p.shift_start:
                raise ValueError("shift_end must be after shift_start.")
        except ValueError as e:
            return err("VALIDATION", str(e))
        p.is_active, p.updated_by = True, self.actor()
        p.save()
        return ok("ATT_POLICY_SAVED", "Attendance policy saved.", en.policy_row(p))

    def patch(self, request):
        return self._save(request)

    def put(self, request):
        return self._save(request)

    def post(self, request):
        return self._save(request)


# ============================================================
# GEOFENCES (Geofenced Web/Mobile Check-in)
# ============================================================

class GeofenceViewSet(AttCrud):
    """
    CRUD /api/attendance-hub/geofences/   {name, latitude, longitude, radius_m?, ip_ranges?[CIDR], branch_id?, is_primary?, notes?}
    POST /api/attendance-hub/geofences/simulate/   {latitude, longitude, ip?, employee_code?}
         = "Location & Geo-Controls Perimeter Simulator" (HR side).
    Until a geofence is saved the company-profile office location / allowed_radius is used.
    """
    model = AttendanceGeofence
    code = "GEOFENCE"
    soft_delete = False
    status_field = None
    search_fields = ("name", "notes")
    select = ("branch",)
    permission_action_map = {"simulate": "view"}
    dup_message = "A geofence with this name already exists."

    def build(self, g):
        return {**en.geofence_dict(g), "notes": g.notes, "created_at": iso(g.created_at), "updated_at": iso(g.updated_at)}

    def apply(self, g, d, creating):
        if creating or "name" in d:
            name = str(d.get("name") or "").strip()
            if not name:
                raise ValueError("name is required.")
            if AttendanceGeofence.objects.filter(company=g.company, name__iexact=name).exclude(pk=g.pk).exists():
                raise IntegrityError
            g.name = name
        for f, lo, hi in (("latitude", -90, 90), ("longitude", -180, 180)):
            if creating or f in d:
                try:
                    v = float(d.get(f))
                except (TypeError, ValueError):
                    raise ValueError(f"{f} is required and must be a number.")
                if not (lo <= v <= hi):
                    raise ValueError(f"{f} must be between {lo} and {hi}.")
                setattr(g, f, v)
        if "radius_m" in d or creating:
            r = to_int(d.get("radius_m"), 200)
            if not (10 <= r <= 50000):
                raise ValueError("radius_m must be between 10 and 50000.")
            g.radius_m = r
        if "ip_ranges" in d:
            import ipaddress
            ranges = d["ip_ranges"] or []
            if not isinstance(ranges, list):
                raise ValueError("ip_ranges must be a list of CIDR strings, e.g. [\"192.168.1.0/24\"].")
            for r in ranges:
                try:
                    ipaddress.ip_network(str(r), strict=False)
                except ValueError:
                    raise ValueError(f"Invalid CIDR range: {r}")
            g.ip_ranges = [str(r) for r in ranges]
        if "branch_id" in d:
            g.branch = Branch.objects.filter(company=g.company, pk=d["branch_id"]).first() if d["branch_id"] else None
            if d["branch_id"] and g.branch is None:
                raise ValueError("Branch not found.")
        if "is_primary" in d:
            g.is_primary = to_bool(d["is_primary"])
        if "notes" in d:
            g.notes = d["notes"]

    def after_save(self, g, creating):
        if g.is_primary:
            AttendanceGeofence.objects.filter(company=g.company).exclude(pk=g.pk).update(is_primary=False)

    @action(detail=False, methods=["post"])
    def simulate(self, request):
        d = request.data
        try:
            lat = float(d["latitude"]) if d.get("latitude") not in (None, "") else None
            lng = float(d["longitude"]) if d.get("longitude") not in (None, "") else None
            ip = valid_ip(d["ip"]) if d.get("ip") else None
            emp = emp_by_code(self.company(), d.get("employee_code"), required=False)
        except (TypeError, ValueError) as e:
            return err("VALIDATION", str(e))
        if emp is not None:
            dec = en.decide_punch(self.company(), emp, lat, lng, ip, timezone.localdate())
            return ok("GEOFENCE_SIMULATION", "Perimeter simulation.", {k: dec[k] for k in (
                "allowed", "perimeter_status", "event_status", "reason", "policy_action", "wfh_today", "wfh_remaining_this_week", "evaluation")})
        return ok("GEOFENCE_SIMULATION", "Perimeter simulation.", en.evaluate_perimeter(self.company(), lat, lng, ip))


# ============================================================
# DAILY ATTENDANCE
# ============================================================

class DailyViewSet(AttMixin, ViewSet):
    """
    GET    /api/attendance-hub/daily/        ?date= | ?from=&to= (default today) ?employee_code= ?department= ?source= ?perimeter_status=
                                             ?status=Late|Present ?search= ?page= ?page_size=
    GET    /api/attendance-hub/daily/<id>/
    POST   /api/attendance-hub/daily/        manual punch by HR {employee_code, date, punch_in, punch_out?, reason}
    PATCH  /api/attendance-hub/daily/<id>/   {punch_in?, punch_out?, comment?, reason}
    DELETE /api/attendance-hub/daily/<id>/   soft delete
    GET    /api/attendance-hub/daily/export/ same filters -> CSV ("Export CSV")
    """
    permission_action_map = {"export": "view"}

    def _qs(self, p):
        co = self.company()
        if p.get("date"):
            start = end = to_date(p["date"])
        else:
            start, end = date_range(p, 1)
        qs = EMP_check_in_check_out.objects.filter(company=co, is_active=True, login_date__gte=start, login_date__lte=end)
        if p.get("employee_code"):
            qs = qs.filter(Employee_ID=p["employee_code"])
        if p.get("department"):
            codes = [e.employee_code for e in employees_qs(co).filter(Q(department__name__iexact=p["department"]) | Q(Department__iexact=p["department"]))]
            qs = qs.filter(Employee_ID__in=codes)
        if p.get("source"):
            s = p["source"]
            if s == "GPS Mobile Punch":
                qs = qs.filter(Q(punch_meta__source=s) | (Q(punch_meta__isnull=True) & Q(checkin_latitude__isnull=False)))
            elif s == "Web Portal Punch":
                qs = qs.filter(Q(punch_meta__source=s) | (Q(punch_meta__isnull=True) & Q(checkin_latitude__isnull=True)))
            else:
                qs = qs.filter(punch_meta__source=s)
        if p.get("perimeter_status"):
            qs = qs.filter(punch_meta__perimeter_status=p["perimeter_status"]) if p["perimeter_status"] != "Unverified" \
                else qs.filter(Q(punch_meta__isnull=True) | Q(punch_meta__perimeter_status="Unverified"))
        q = (p.get("search") or "").strip()
        if q:
            qs = qs.filter(Q(Name__icontains=q) | Q(Employee_ID__icontains=q))
        return qs.select_related("punch_meta", "punch_meta__device", "punch_meta__device__branch").order_by("-login_date", "-id")

    def _meta(self, r):
        try:
            return r.punch_meta
        except AttendancePunchMeta.DoesNotExist:
            return None

    def _row(self, r, request):
        pol = en.get_policy(self.company())
        return en.punch_row(r, self._meta(r), en.employee_map(self.company(), [r.Employee_ID]).get(r.Employee_ID), pol, request)

    def list(self, request):
        try:
            qs = self._qs(request.query_params)
        except ValueError as e:
            return err("VALIDATION", str(e))
        pol = en.get_policy(self.company())
        emap = en.employee_map(self.company())
        status = request.query_params.get("status")
        if status in ("Late", "Present"):
            items = [r for r in qs if en.punch_row(r, self._meta(r), emap.get(r.Employee_ID), pol)["status"] == status]
        else:
            items = qs
        rows, meta = paginate(request, items, lambda r: en.punch_row(r, self._meta(r), emap.get(r.Employee_ID), pol, request))
        return ok("DAILY_LIST", "Daily workforce attendance logs.", rows, meta=meta)

    def retrieve(self, request, pk=None):
        r = self._qs({"from": "2000-01-01", "to": "2100-01-01"}).filter(pk=pk).first() if str(pk).isdigit() else None
        if r is None:
            return err("NOT_FOUND", "Record not found.", 404)
        return ok("DAILY_DETAIL", "Attendance log.", self._row(r, request))

    @transaction.atomic
    def create(self, request):
        d, actor, co = request.data, self.actor(), self.company()
        try:
            emp = emp_by_code(co, d.get("employee_code"))
            day = to_date(d.get("date")) or timezone.localdate()
            if day > timezone.localdate():
                raise ValueError("date cannot be in the future.")
            tin, tout = parse_time(d.get("punch_in"), "punch_in"), parse_time(d.get("punch_out"), "punch_out")
            if tin is None:
                raise ValueError("punch_in is required.")
            if tout is not None and tout <= tin:
                raise ValueError("punch_out must be after punch_in.")
            if not str(d.get("reason") or "").strip():
                raise ValueError("reason is required for a manual entry.")
        except ValueError as e:
            return err("VALIDATION", str(e))
        rec = EMP_check_in_check_out.objects.create(Employee_ID=emp.employee_code, company=co, Name=emp.name, login_date=day,
                                                    login_time=en.fmt_time24(tin), comment=str(d["reason"])[:500], created_by=actor, updated_by=actor)
        if tout:
            rec.logout_date, rec.logout_time = day, en.fmt_time24(tout)
            rec.total_working_hours = en._hours(day, rec.login_time, day, rec.logout_time)
            rec.save()
        AttendancePunchMeta.objects.create(company=co, checkin=rec, source="Manual", perimeter_status="Manual Entry", created_by=actor, updated_by=actor)
        return ok("DAILY_CREATED", "Attendance entry created.", self._row(rec, request), 201)

    @transaction.atomic
    def partial_update(self, request, pk=None):
        r = self._qs({"from": "2000-01-01", "to": "2100-01-01"}).filter(pk=pk).first() if str(pk).isdigit() else None
        if r is None:
            return err("NOT_FOUND", "Record not found.", 404)
        d = request.data
        try:
            if not str(d.get("reason") or "").strip():
                raise ValueError("reason is required to change an attendance entry.")
            if "punch_in" in d:
                t = parse_time(d["punch_in"], "punch_in")
                if t is None:
                    raise ValueError("punch_in cannot be empty.")
                r.login_time = en.fmt_time24(t)
            if "punch_out" in d:
                t = parse_time(d["punch_out"], "punch_out")
                r.logout_date, r.logout_time = (r.login_date, en.fmt_time24(t)) if t else (None, None)
            if r.logout_time and en.parse_minutes(r.logout_time) <= en.parse_minutes(r.login_time) and r.logout_date == r.login_date:
                raise ValueError("punch_out must be after punch_in.")
        except ValueError as e:
            return err("VALIDATION", str(e))
        r.total_working_hours = en._hours(r.login_date, r.login_time, r.logout_date, r.logout_time) if r.logout_time else None
        r.comment = (f"{d['reason']} | {r.comment}" if r.comment else str(d["reason"]))[:500]
        r.updated_by, r.id_version = self.actor(), (r.id_version or 1) + 1
        r.save()
        return ok("DAILY_UPDATED", "Attendance entry updated.", self._row(r, request))

    update = partial_update

    def destroy(self, request, pk=None):
        r = self._qs({"from": "2000-01-01", "to": "2100-01-01"}).filter(pk=pk).first() if str(pk).isdigit() else None
        if r is None:
            return err("NOT_FOUND", "Record not found.", 404)
        r.is_active, r.updated_by = False, self.actor()
        r.save()
        return ok("DAILY_DELETED", "Attendance entry deleted.", {"id": int(pk)})

    @action(detail=False, methods=["get"])
    def export(self, request):
        try:
            qs = self._qs(request.query_params)
        except ValueError as e:
            return err("VALIDATION", str(e))
        buf = io.StringIO()
        w = csv.writer(buf)
        w.writerow(["Date", "Employee Code", "Employee", "Punch In", "Punch Out", "Hours", "Device Mode", "Perimeter / Verification",
                    "Latitude", "Longitude", "Status"])
        pol, emap = en.get_policy(self.company()), en.employee_map(self.company())
        for r in qs[:50000]:
            x = en.punch_row(r, self._meta(r), emap.get(r.Employee_ID), pol)
            w.writerow([safe_cell(c) for c in (x["date"], r.Employee_ID, r.Name, x["punch_in_label"], x["punch_out_label"], r.total_working_hours,
                                               x["device_mode"], x["perimeter_status"], r.checkin_latitude, r.checkin_longitude, x["status"])])
        resp = HttpResponse(buf.getvalue().encode("utf-8-sig"), content_type="text/csv")
        resp["Content-Disposition"] = f'attachment; filename="daily_attendance_{timezone.localdate():%Y%m%d}.csv"'
        return resp


# ============================================================
# BIOMETRIC HARDWARE HUB
# ============================================================

class DeviceViewSet(AttCrud):
    """
    CRUD /api/attendance-hub/devices/   {device_code?, name, vendor, location_label?, branch_id?, ip_address?, port?,
                                         sync_protocol?, firmware?, status?}      ?status= ?vendor= ?search=
    The device API key is returned ONCE on create / rotate-key (only its hash is stored).
    POST devices/<id>/rotate-key/   POST devices/<id>/ping/   POST devices/<id>/sync/   POST devices/sync-all/
    """
    model = BiometricDevice
    code = "BIO_DEVICE"
    soft_delete = False
    search_fields = ("device_code", "name", "location_label", "ip_address")
    select = ("branch",)
    permission_action_map = {"rotate_key": "edit", "ping": "edit", "sync": "edit", "sync_all": "edit"}
    dup_message = "A device with this device_code already exists."

    def _stats(self):
        if not hasattr(self, "_st"):
            self._st = en.device_stats(self.company(), timezone.localdate())
        return self._st

    def build(self, d):
        row = en.device_row(d, en.get_policy(self.company()), self._stats())
        if getattr(d, "_plain_key", None):
            row["api_key"] = d._plain_key
            row["api_key_notice"] = "Store this key now - it is shown only once. Send it as the X-Device-Key header."
        return row

    def filter(self, qs, p):
        qs = super().filter(qs, p)
        return qs.filter(vendor=p["vendor"]) if p.get("vendor") else qs

    def apply(self, d, data, creating):
        if creating:
            code = str(data.get("device_code") or "").strip() or next_seq(BiometricDevice, d.company, "device_code", "BIO-DEV-", 2)
            if BiometricDevice.objects.filter(company=d.company, device_code__iexact=code).exists():
                raise IntegrityError
            d.device_code = code
            d._plain_key = en.new_device_key(code)
            d.api_key_hash, d.api_key_hint = en.hash_key(d._plain_key), "****" + d._plain_key[-4:]
        elif "device_code" in data and data["device_code"] != d.device_code:
            raise ValueError("device_code cannot be changed.")
        if creating or "name" in data:
            if not str(data.get("name") or "").strip():
                raise ValueError("name is required.")
            d.name = str(data["name"]).strip()
        for f, choices in (("vendor", BiometricDevice.VENDORS), ("sync_protocol", BiometricDevice.PROTOCOLS), ("status", BiometricDevice.STATUS)):
            if f in data:
                if data[f] not in dict(choices):
                    raise ValueError(f"Invalid {f}. Allowed: " + ", ".join(dict(choices)))
                setattr(d, f, data[f])
        for f in ("location_label", "firmware"):
            if f in data:
                setattr(d, f, data[f])
        if "ip_address" in data:
            d.ip_address = valid_ip(data["ip_address"]) if data["ip_address"] else None
        if "port" in data:
            p = to_int(data["port"])
            if p is not None and not (1 <= p <= 65535):
                raise ValueError("port must be between 1 and 65535.")
            d.port = p
        if "branch_id" in data:
            d.branch = Branch.objects.filter(company=d.company, pk=data["branch_id"]).first() if data["branch_id"] else None
            if data["branch_id"] and d.branch is None:
                raise ValueError("Branch not found.")

    def _dev(self, pk):
        return self.scope().filter(pk=pk, is_active=True).first() if str(pk).isdigit() else None

    @action(detail=True, methods=["post"], url_path="rotate-key")
    def rotate_key(self, request, pk=None):
        d = self._dev(pk)
        if d is None:
            return err("NOT_FOUND", "Device not found.", 404)
        d._plain_key = en.new_device_key(d.device_code)
        d.api_key_hash, d.api_key_hint, d.updated_by = en.hash_key(d._plain_key), "****" + d._plain_key[-4:], self.actor()
        d.save()
        return ok("BIO_DEVICE_KEY_ROTATED", "New device key generated. The old key stopped working.", self.build(d))

    @action(detail=True, methods=["post"])
    def ping(self, request, pk=None):
        d = self._dev(pk)
        if d is None:
            return err("NOT_FOUND", "Device not found.", 404)
        try:
            good, ms, msg = en.ping_device(d)
        except ValueError as e:
            return err("VALIDATION", str(e))
        return ok("BIO_DEVICE_PING", msg, {"reachable": good, "latency_ms": ms, "message": msg, "device": self.build(d)})

    def _sync(self, devices):
        now, done = timezone.now(), 0
        pending = BiometricPunch.objects.filter(company=self.company(), sync_status__in=["Pending", "Unmatched"], device__in=devices)
        results = {}
        for p in pending.order_by("punch_time"):
            en.reconcile(p, self.actor())
            results[p.sync_status] = results.get(p.sync_status, 0) + 1
            done += 1
        for d in devices:
            d.last_sync_at = now
            d.save(update_fields=["last_sync_at", "updated_at"])
        return {"devices_synced": len(devices), "punches_reprocessed": done, "results": results, "synced_at": iso(now)}

    @action(detail=True, methods=["post"])
    def sync(self, request, pk=None):
        d = self._dev(pk)
        if d is None:
            return err("NOT_FOUND", "Device not found.", 404)
        if d.status != "Enabled":
            return err("CONFLICT", f"The device is {d.status}.", 409)
        return ok("BIO_DEVICE_SYNCED", "Device synced.", self._sync([d]))

    @action(detail=False, methods=["post"], url_path="sync-all")
    def sync_all(self, request):
        devs = list(self.scope().filter(is_active=True, status="Enabled"))
        return ok("BIO_DEVICES_SYNCED", "All enabled devices synced.", self._sync(devs))


class GatewayView(AttView):
    """
    GET   /api/attendance-hub/gateway/        central hardware gateway + ingestion settings
    PATCH /api/attendance-hub/gateway/        {central_gateway_url?, ingestion_mode?, reconcile_interval_seconds?}
    POST  /api/attendance-hub/gateway/ping/   "Test Ping" (SSRF-guarded: private addresses are blocked unless
                                              settings.ADMIN_CENTER_ALLOW_PRIVATE_PING = True)
    The gateway URL is stored in the existing Admin Center connector (type "Biometric").
    """
    permission_action_map = {}

    def get(self, request):
        return ok("BIO_GATEWAY", "Hardware gateway configuration.", en.gateway_row(self.company()))

    def patch(self, request):
        co, d = self.company(), request.data
        try:
            if "ingestion_mode" in d or "reconcile_interval_seconds" in d:
                p = AttendancePolicy.objects.filter(company=co).first() or AttendancePolicy(company=co, created_by=self.actor())
                if "ingestion_mode" in d:
                    if not str(d["ingestion_mode"] or "").strip():
                        raise ValueError("ingestion_mode cannot be empty.")
                    p.ingestion_mode = str(d["ingestion_mode"]).strip()[:80]
                if "reconcile_interval_seconds" in d:
                    v = to_int(d["reconcile_interval_seconds"])
                    if v is None or not (5 <= v <= 86400):
                        raise ValueError("reconcile_interval_seconds must be between 5 and 86400.")
                    p.reconcile_interval_seconds = v
                p.updated_by = self.actor()
                p.save()
            if "central_gateway_url" in d:
                url = str(d["central_gateway_url"] or "").strip()
                if not re.match(r"^(https?|tcp)://[^\s/]+", url):
                    raise ValueError("central_gateway_url must start with http://, https:// or tcp://.")
                c = en.gateway(co)
                if c is None:
                    from AdminCenter.models import IntegrationConnector
                    c = IntegrationConnector(company=co, name=en.GATEWAY_NAME, connector_type="Biometric", created_by=self.actor())
                c.endpoint, c.status, c.updated_by = url[:300], "Not Tested", self.actor()
                c.save()
        except ValueError as e:
            return err("VALIDATION", str(e))
        return ok("BIO_GATEWAY_SAVED", "Gateway configuration saved.", en.gateway_row(co))

    put = patch



class GatewayPingView(AttView):
    """POST /api/attendance-hub/gateway/ping/  - "Test Ping" (needs edit permission)."""
    permission_action = "edit"

    def post(self, request):
        try:
            good, ms, msg = en.ping_gateway(self.company())
        except ValueError as e:
            return err("VALIDATION", str(e))
        return ok("BIO_GATEWAY_PING", msg, {"reachable": good, "latency_ms": ms, "message": msg, "gateway": en.gateway_row(self.company())})


class EnrollmentViewSet(AttCrud):
    """
    CRUD /api/attendance-hub/enrollments/   {employee_code, biometric_id, verification_mode?, notes?}   ?employee= ?search=
    Saving an enrollment re-processes earlier 'Unmatched' punches of that biometric id.
    """
    model = BiometricEnrollment
    code = "BIO_ENROLLMENT"
    soft_delete = False
    status_field = None
    search_fields = ("biometric_id", "employee__name", "employee__employee_code")
    select = ("employee",)
    permission_action_map = {"bulk": "create"}
    dup_message = "This biometric id is already enrolled."

    def build(self, e):
        return {"id": e.id, "employee": {"employee_code": e.employee.employee_code, "name": e.employee.name},
                "biometric_id": e.biometric_id, "verification_mode": e.verification_mode, "notes": e.notes,
                "created_at": iso(e.created_at), "updated_at": iso(e.updated_at)}

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

    def apply(self, e, d, creating):
        if creating or "employee_code" in d:
            e.employee = emp_by_code(e.company, d.get("employee_code"))
        if creating or "biometric_id" in d:
            bid = str(d.get("biometric_id") or "").strip()
            if not bid:
                raise ValueError("biometric_id is required.")
            if BiometricEnrollment.objects.filter(company=e.company, biometric_id=bid).exclude(pk=e.pk).exists():
                raise IntegrityError
            e.biometric_id = bid
        if "verification_mode" in d:
            if d["verification_mode"] not in dict(BiometricEnrollment.MODES):
                raise ValueError("Invalid verification_mode. Allowed: " + ", ".join(dict(BiometricEnrollment.MODES)))
            e.verification_mode = d["verification_mode"]
        if "notes" in d:
            e.notes = d["notes"]

    def after_save(self, e, creating):
        for p in BiometricPunch.objects.filter(company=e.company, biometric_id=e.biometric_id, sync_status="Unmatched").order_by("punch_time"):
            p.employee = None
            en.reconcile(p, self.actor())

    @action(detail=False, methods=["post"])
    def bulk(self, request):
        """
        POST enrollments/bulk/  {"items": [{"biometric_id" | "essl_code": "4", "employee_code": "EMP0504", "verification_mode"?}, ...]}
        Existing ids are skipped; earlier 'Unmatched' punches of every enrolled id are re-processed in time order.
        """
        items = request.data.get("items")
        if not isinstance(items, list) or not items:
            return err("VALIDATION", "items must be a non-empty list.")
        if len(items) > 1000:
            return err("VALIDATION", "At most 1000 items per request.")
        co, actor = self.company(), self.actor()
        created, skipped, errors, ids = [], [], [], []
        for i, it in enumerate(items):
            try:
                bid = str((it or {}).get("biometric_id") or (it or {}).get("essl_code") or "").strip()
                if not bid:
                    raise ValueError("biometric_id (or essl_code) is required.")
                emp = emp_by_code(co, (it or {}).get("employee_code"))
                mode = (it or {}).get("verification_mode") or "Fingerprint"
                if mode not in dict(BiometricEnrollment.MODES):
                    raise ValueError("Invalid verification_mode.")
                cur = BiometricEnrollment.objects.filter(company=co, biometric_id=bid).select_related("employee").first()
                if cur:
                    skipped.append({"index": i, "biometric_id": bid, "reason": f"already enrolled for {cur.employee.employee_code}"})
                    continue
                BiometricEnrollment.objects.create(company=co, employee=emp, biometric_id=bid, verification_mode=mode,
                                                   created_by=actor, updated_by=actor)
                created.append({"biometric_id": bid, "employee_code": emp.employee_code})
                ids.append(bid)
            except (ValueError, TypeError) as e:
                errors.append({"index": i, "error": str(e)})
        results = {}
        for p in BiometricPunch.objects.filter(company=co, biometric_id__in=ids, sync_status="Unmatched").order_by("punch_time"):
            p.employee = None
            en.reconcile(p, actor)
            results[p.sync_status] = results.get(p.sync_status, 0) + 1
        return ok("BIO_ENROLLMENT_BULK", "Bulk enrollment processed.", {
            "created": len(created), "skipped": len(skipped), "errors": len(errors), "enrollments": created, "skipped_items": skipped,
            "error_items": errors, "unmatched_punches_reprocessed": results}, 201 if created else 200)


class PunchViewSet(AttCrud):
    """
    Raw biometric ingestion buffer ("Live Biometric Raw Ingestion Buffer").
    GET    /api/attendance-hub/punches/       ?sync_status= ?device_code= ?employee_code= ?direction= ?from= ?to= ?search=
    POST   /api/attendance-hub/punches/       manual import {biometric_id | employee_code, punch_time, direction?, device_code?,
                                              verification_mode?, match_score?}
    PATCH  /api/attendance-hub/punches/<id>/  re-map {employee_code?, direction?} (not once Reconciled)
    DELETE /api/attendance-hub/punches/<id>/  (not once Reconciled)
    POST   /api/attendance-hub/punches/<id>/reprocess/    POST /api/attendance-hub/punches/reprocess/  (all Pending / Unmatched / Failed)
    """
    model = BiometricPunch
    code = "BIO_PUNCH"
    soft_delete = False
    status_field = "sync_status"
    search_fields = ("biometric_id", "device_code", "employee__name", "employee__employee_code")
    select = ("employee", "device", "device__branch")
    permission_action_map = {"reprocess": "edit", "reprocess_all": "edit", "unmatched": "view"}
    dup_message = "This punch was already received."

    def build(self, p):
        e = p.employee
        return {"id": p.id, "timestamp": iso(p.punch_time),
                "timestamp_label": timezone.localtime(p.punch_time).strftime("%Y-%m-%d %H:%M:%S"),
                "device_id": p.device.device_code if p.device_id else p.device_code,
                "device_label": f"{p.device_code} ({p.device.vendor})" if p.device_id else p.device_code,
                "card_biometric_id": p.biometric_id, "employee": {"employee_code": e.employee_code, "name": e.name} if e else None,
                "employee_name": e.name if e else None, "direction": p.direction, "verification_mode": p.verification_mode,
                "match_score": fnum(p.match_score), "match_label": f"{p.match_score:g}% Match" if p.match_score is not None else None,
                "sync_status": p.sync_status, "sync_status_label": "Reconciled Instantly" if p.sync_status == "Reconciled" else p.sync_status,
                "sync_message": p.sync_message, "checkin_id": p.checkin_id, "source": p.source, "received_at": iso(p.created_at)}

    def filter(self, qs, p):
        qs = super().filter(qs, p)
        if p.get("device_code"):
            qs = qs.filter(device_code=p["device_code"])
        if p.get("employee_code"):
            qs = qs.filter(employee__employee_code=p["employee_code"])
        if p.get("direction"):
            qs = qs.filter(direction=p["direction"])
        if p.get("from"):
            qs = qs.filter(punch_time__gte=en.day_range(to_date(p["from"]))[0])
        if p.get("to"):
            qs = qs.filter(punch_time__lt=en.day_range(to_date(p["to"]))[1])
        return qs

    @transaction.atomic
    def create(self, request):
        d, co = request.data, self.company()
        try:
            emp = emp_by_code(co, d.get("employee_code"), required=False)
            bid = str(d.get("biometric_id") or (f"MANUAL-{emp.employee_code}" if emp else "")).strip()
            if not bid:
                raise ValueError("biometric_id or employee_code is required.")
            when = parse_dt(d.get("punch_time"), "punch_time")
            if when > timezone.now() + timedelta(minutes=5):
                raise ValueError("punch_time cannot be in the future.")
            direction = str(d.get("direction") or "IN").upper()
            if direction not in ("IN", "OUT"):
                raise ValueError("direction must be IN or OUT.")
            dev = BiometricDevice.objects.filter(company=co, device_code=d["device_code"]).first() if d.get("device_code") else None
            if d.get("device_code") and dev is None:
                raise ValueError("Device not found.")
            score = to_decimal(d.get("match_score"))
            if score is not None and not (0 <= score <= 100):
                raise ValueError("match_score must be between 0 and 100.")
        except ValueError as e:
            return err("VALIDATION", str(e))
        if BiometricPunch.objects.filter(company=co, device_code=dev.device_code if dev else None, biometric_id=bid,
                                         punch_time=when, direction=direction).exists():
            return err("EXISTS", self.dup_message, 409)
        p = BiometricPunch.objects.create(company=co, device=dev, device_code=dev.device_code if dev else None, biometric_id=bid,
                                          employee=emp, punch_time=when, direction=direction, verification_mode=d.get("verification_mode"),
                                          match_score=score, raw_payload=dict(d) if isinstance(d, dict) else {}, source="manual",
                                          created_by=self.actor(), updated_by=self.actor())
        en.reconcile(p, self.actor())
        return ok("BIO_PUNCH_CREATED", "Punch recorded.", self.build(self.scope().get(pk=p.pk)), 201)

    @transaction.atomic
    def partial_update(self, request, pk=None):
        p = self.scope().filter(pk=pk).first()
        if p is None:
            return err("NOT_FOUND", "Record not found.", 404)
        if p.sync_status == "Reconciled":
            return err("CONFLICT", "A reconciled punch is already part of attendance and cannot be edited.", 409)
        d = request.data
        try:
            if "employee_code" in d:
                p.employee = emp_by_code(p.company, d["employee_code"])
            if "direction" in d:
                if str(d["direction"]).upper() not in ("IN", "OUT"):
                    raise ValueError("direction must be IN or OUT.")
                p.direction = str(d["direction"]).upper()
        except ValueError as e:
            return err("VALIDATION", str(e))
        p.updated_by = self.actor()
        p.sync_status = "Pending"
        p.save()
        en.reconcile(p, self.actor())
        return ok("BIO_PUNCH_UPDATED", "Punch updated and re-processed.", self.build(self.scope().get(pk=p.pk)))

    update = partial_update

    def destroy(self, request, pk=None):
        p = self.scope().filter(pk=pk).first()
        if p is None:
            return err("NOT_FOUND", "Record not found.", 404)
        if p.sync_status == "Reconciled":
            return err("CONFLICT", "A reconciled punch cannot be deleted.", 409)
        p.delete()
        return ok("BIO_PUNCH_DELETED", "Deleted.", {"id": int(pk)})

    @action(detail=True, methods=["post"])
    def reprocess(self, request, pk=None):
        p = self.scope().filter(pk=pk).first()
        if p is None:
            return err("NOT_FOUND", "Record not found.", 404)
        if p.sync_status == "Reconciled":
            return err("CONFLICT", "Already reconciled.", 409)
        en.reconcile(p, self.actor())
        return ok("BIO_PUNCH_REPROCESSED", "Punch re-processed.", self.build(self.scope().get(pk=p.pk)))

    @action(detail=False, methods=["get"])
    def unmatched(self, request):
        """GET punches/unmatched/ - biometric ids that have punches but no enrollment yet (what HR must map)."""
        from django.db.models import Count, Max, Min
        rows = (self.scope().filter(sync_status="Unmatched").values("biometric_id")
                .annotate(punches=Count("id"), first=Min("punch_time"), last=Max("punch_time")).order_by("-punches", "biometric_id"))
        data = [{"biometric_id": r["biometric_id"], "punches": r["punches"], "first_punch": iso(r["first"]), "last_punch": iso(r["last"])} for r in rows]
        return ok("BIO_UNMATCHED_IDS", "Biometric ids without an enrolled employee.", {"count": len(data), "results": data})

    @action(detail=False, methods=["post"], url_path="reprocess")
    def reprocess_all(self, request):
        res = {}
        for p in self.scope().filter(sync_status__in=["Pending", "Unmatched", "Failed"]).order_by("punch_time")[:1000]:
            en.reconcile(p, self.actor())
            res[p.sync_status] = res.get(p.sync_status, 0) + 1
        return ok("BIO_PUNCHES_REPROCESSED", "Punches re-processed.", {"results": res, "total": sum(res.values())})


def fnum(v):
    return None if v is None else float(v)


# ============================================================
# FIELD FORCE
# ============================================================

class FieldAgentViewSet(AttCrud):
    """CRUD /api/attendance-hub/field/agents/   {employee_code, territory?, ping_interval_minutes?, per_km_rate?}   ?search="""
    model = FieldForceAgent
    code = "FIELD_AGENT"
    soft_delete = False
    status_field = None
    search_fields = ("employee__name", "employee__employee_code", "territory")
    select = ("employee",)
    dup_message = "This employee is already a field force agent."

    def build(self, a):
        return en.agent_row(a)

    def apply(self, a, d, creating):
        if creating:
            a.employee = emp_by_code(a.company, d.get("employee_code"))
            if FieldForceAgent.objects.filter(company=a.company, employee=a.employee).exists():
                raise IntegrityError
        elif "employee_code" in d and d["employee_code"] != a.employee.employee_code:
            raise ValueError("employee_code cannot be changed.")
        if "territory" in d:
            a.territory = d["territory"]
        if "ping_interval_minutes" in d:
            v = to_int(d["ping_interval_minutes"])
            if v is None or not (1 <= v <= 240):
                raise ValueError("ping_interval_minutes must be between 1 and 240.")
            a.ping_interval_minutes = v
        if "per_km_rate" in d:
            v = to_decimal(d["per_km_rate"], Decimal("0"))
            if v < 0:
                raise ValueError("per_km_rate cannot be negative.")
            a.per_km_rate = v


class FieldPointViewSet(AttCrud):
    """
    CRUD /api/attendance-hub/field/points/  {agent_id | employee_code, recorded_at, point_type?, latitude, longitude,
                                             location_label?, client_name?, speed_kmh?, battery_percent?, notes?, site_verified?}
    filters: ?agent_id= ?employee_code= ?date= ?point_type=
    """
    model = FieldTrackPoint
    code = "FIELD_POINT"
    soft_delete = False
    status_field = "point_type"
    search_fields = ("location_label", "client_name", "notes")
    select = ("agent", "agent__employee")

    def build(self, p):
        return {**en.point_row(p), "employee": {"employee_code": p.agent.employee.employee_code, "name": p.agent.employee.name}}

    def filter(self, qs, p):
        qs = super().filter(qs, p)
        if p.get("agent_id"):
            qs = qs.filter(agent_id=p["agent_id"])
        if p.get("employee_code"):
            qs = qs.filter(agent__employee__employee_code=p["employee_code"])
        if p.get("date"):
            a, b = en.day_range(to_date(p["date"]))
            qs = qs.filter(recorded_at__gte=a, recorded_at__lt=b)
        return qs

    def apply(self, p, d, creating):
        if creating:
            q = FieldForceAgent.objects.filter(company=p.company)
            ag = q.filter(pk=d["agent_id"]).first() if d.get("agent_id") else q.filter(employee__employee_code=d.get("employee_code")).first()
            if ag is None:
                raise ValueError("Field agent not found (send agent_id or employee_code).")
            p.agent = ag
        if creating or "recorded_at" in d:
            p.recorded_at = parse_dt(d.get("recorded_at"), "recorded_at")
        for f, lo, hi in (("latitude", -90, 90), ("longitude", -180, 180)):
            if creating or f in d:
                try:
                    v = float(d.get(f))
                except (TypeError, ValueError):
                    raise ValueError(f"{f} is required and must be a number.")
                if not (lo <= v <= hi):
                    raise ValueError(f"{f} must be between {lo} and {hi}.")
                setattr(p, f, v)
        if "point_type" in d:
            if d["point_type"] not in dict(FieldTrackPoint.TYPES):
                raise ValueError("Invalid point_type. Allowed: " + ", ".join(dict(FieldTrackPoint.TYPES)))
            p.point_type = d["point_type"]
        for f in ("location_label", "client_name", "notes"):
            if f in d:
                setattr(p, f, d[f])
        if "speed_kmh" in d:
            v = to_decimal(d["speed_kmh"])
            if v is not None and not (0 <= v <= 400):
                raise ValueError("speed_kmh must be between 0 and 400.")
            p.speed_kmh = v
        if "battery_percent" in d:
            v = to_int(d["battery_percent"])
            if v is not None and not (0 <= v <= 100):
                raise ValueError("battery_percent must be between 0 and 100.")
            p.battery_percent = v
        if "site_verified" in d:
            p.site_verified = to_bool(d["site_verified"])


class FieldBase(AttView):
    def agent_and_day(self, request):
        co, p = self.company(), request.query_params
        q = FieldForceAgent.objects.filter(company=co, is_active=True).select_related("employee")
        ag = q.filter(pk=p["agent_id"]).first() if str(p.get("agent_id", "")).isdigit() else q.filter(employee__employee_code=p.get("employee_code")).first()
        if ag is None:
            return None, None, err("NOT_FOUND", "Field agent not found (send agent_id or employee_code).", 404)
        try:
            day = to_date(p.get("date")) or timezone.localdate()
        except ValueError as e:
            return None, None, err("VALIDATION", str(e))
        return ag, day, None


class FieldSummaryView(FieldBase):
    """GET /api/attendance-hub/field/summary/?agent_id=|employee_code=&date=  cards + chronological trail"""

    def get(self, request):
        ag, day, bad = self.agent_and_day(request)
        return bad or ok("FIELD_SUMMARY", "Field force summary.", en.agent_day(ag, day))


class FieldRouteView(FieldBase):
    """GET /api/attendance-hub/field/route/   ordered coordinates for route playback"""

    def get(self, request):
        ag, day, bad = self.agent_and_day(request)
        if bad:
            return bad
        d = en.agent_day(ag, day)
        return ok("FIELD_ROUTE", "Route.", {"agent": d["agent"], "date": d["date"], "total_distance_km": d["total_distance_km"],
                                            "route": [{"time": t["time"], "latitude": t["latitude"], "longitude": t["longitude"], "type": t["type"],
                                                       "cumulative_km": t["cumulative_km"]} for t in d["trail"]]})


class FieldTravelClaimView(FieldBase):
    """GET /api/attendance-hub/field/travel-claim/?agent_id=&date=[&download=csv]   distance x per_km_rate"""

    def get(self, request):
        ag, day, bad = self.agent_and_day(request)
        if bad:
            return bad
        d = en.agent_day(ag, day)
        claim = {"agent": d["agent"], "date": d["date"], "distance_km": d["total_distance_km"], "per_km_rate": d["agent"]["per_km_rate"],
                 "amount": d["travel_claim_amount"], "client_visits": d["client_visits"], "verified_client_visits": d["verified_client_visits"]}
        if request.query_params.get("download") == "csv":
            buf = io.StringIO()
            w = csv.writer(buf)
            w.writerow(["Date", "Employee Code", "Employee", "Distance (km)", "Rate / km", "Amount", "Client Visits"])
            w.writerow([claim["date"], ag.employee.employee_code, safe_cell(ag.employee.name), claim["distance_km"], claim["per_km_rate"], claim["amount"], claim["client_visits"]])
            resp = HttpResponse(buf.getvalue().encode("utf-8-sig"), content_type="text/csv")
            resp["Content-Disposition"] = f'attachment; filename="travel_claim_{ag.employee.employee_code}_{day}.csv"'
            return resp
        return ok("FIELD_TRAVEL_CLAIM", "Travel claim.", claim)


# ============================================================
# LATE / EARLY
# ============================================================

class LateEarlyView(AttView):
    """GET /api/attendance-hub/late-early/?from=&to=&kind=late|early&employee_code=  (default last 7 days)"""

    def get(self, request):
        p = request.query_params
        try:
            start, end = date_range(p, 7)
        except ValueError as e:
            return err("VALIDATION", str(e))
        kind = p.get("kind")
        if kind not in (None, "", "late", "early"):
            return err("VALIDATION", "kind must be late or early.")
        codes = [p["employee_code"]] if p.get("employee_code") else None
        pol = en.get_policy(self.company())
        rows = en.late_early_rows(self.company(), start, end, codes, kind or None, pol)
        page, meta = paginate(request, rows, lambda r: r)
        return ok("LATE_EARLY", "Late arrival & early departure exceptions.", {
            "period": {"from": str(start), "to": str(end)}, "shift": {"start": en.fmt12(pol.shift_start), "end": en.fmt12(pol.shift_end),
                                                                      "grace_minutes": pol.grace_minutes}, "rows": page}, meta=meta)


# ============================================================
# REGULARIZATION
# ============================================================

MAX_BACKDATE_DAYS = 60


def validate_reg(d, emp_required, existing=None):
    out = {}
    day = to_date(d.get("date")) if "date" in d or existing is None else existing.attendance_date
    if day is None:
        raise ValueError("date is required.")
    if day > timezone.localdate():
        raise ValueError("date cannot be in the future.")
    if (timezone.localdate() - day).days > MAX_BACKDATE_DAYS:
        raise ValueError(f"Requests older than {MAX_BACKDATE_DAYS} days cannot be regularized.")
    tin = parse_time(d.get("punch_in_time", d.get("punch_time")), "punch_in_time") if ("punch_in_time" in d or "punch_time" in d) else (existing.punch_in_time if existing else None)
    if tin is None:
        raise ValueError("punch_in_time is required.")
    tout = parse_time(d.get("punch_out_time"), "punch_out_time") if "punch_out_time" in d else (existing.punch_out_time if existing else None)
    if tout is not None and tout <= tin:
        raise ValueError("punch_out_time must be after punch_in_time.")
    reason = str(d.get("reason", existing.reason if existing else "") or "").strip()
    if not reason:
        raise ValueError("reason is required.")
    return day, tin, tout, reason


class RegularizationViewSet(AttMixin, ViewSet):
    """
    GET    /api/attendance-hub/regularizations/      ?status= ?employee_code= ?from= ?to= ?search= ?page=
    POST   /api/attendance-hub/regularizations/      "Apply Regularization" {employee_code, date, punch_in_time, punch_out_time?, reason,
                                                     auto_approve?}
    GET    /api/attendance-hub/regularizations/<id>/
    PATCH|PUT|POST(update/) /<id>/                   only while 'Pending Approval'
    DELETE|POST(delete/)    /<id>/                   only Pending / Rejected / Cancelled
    POST   /<id>/approve/ {comment?}   POST /<id>/reject/ {comment}     -> approving writes the punch (+ day status for past days)
    """
    permission_action_map = {"approve": "edit", "reject": "edit"}

    def _qs(self):
        return AttendanceRegularization.objects.filter(company=self.company(), is_active=True).select_related("employee")

    def _get(self, pk):
        return self._qs().filter(pk=pk).first() if str(pk).isdigit() else None

    def list(self, request):
        p, qs = request.query_params, self._qs()
        try:
            if p.get("status"):
                qs = qs.filter(status=p["status"])
            if p.get("employee_code"):
                qs = qs.filter(employee__employee_code=p["employee_code"])
            if p.get("from"):
                qs = qs.filter(attendance_date__gte=to_date(p["from"]))
            if p.get("to"):
                qs = qs.filter(attendance_date__lte=to_date(p["to"]))
        except ValueError as e:
            return err("VALIDATION", str(e))
        q = (p.get("search") or "").strip()
        if q:
            qs = qs.filter(Q(request_id__icontains=q) | Q(employee__name__icontains=q) | Q(reason__icontains=q))
        rows, meta = paginate(request, qs, en.reg_row)
        return ok("REGULARIZATION_LIST", "Attendance regularization approvals.", rows, meta=meta)

    def retrieve(self, request, pk=None):
        r = self._get(pk)
        return ok("REGULARIZATION_DETAIL", "Regularization.", en.reg_row(r)) if r else err("NOT_FOUND", "Record not found.", 404)

    @transaction.atomic
    def create(self, request):
        d, co, actor = request.data, self.company(), self.actor()
        try:
            emp = emp_by_code(co, d.get("employee_code"))
            day, tin, tout, reason = validate_reg(d, True)
        except ValueError as e:
            return err("VALIDATION", str(e))
        if AttendanceRegularization.objects.filter(company=co, employee=emp, attendance_date=day, status__in=["Pending Approval", "Approved"]).exists():
            return err("EXISTS", "A regularization request already exists for this employee and date.", 409)
        r = AttendanceRegularization.objects.create(
            company=co, request_id=next_seq(AttendanceRegularization, co, "request_id", "REG-", 3), employee=emp, attendance_date=day,
            punch_in_time=tin, punch_out_time=tout, reason=reason, requested_by="HR", created_by=actor, updated_by=actor)
        if to_bool(d.get("auto_approve")):
            self._decide(r, "Approved", d.get("comment") or "Auto-approved by HR", actor)
        return ok("REGULARIZATION_CREATED", "Regularization request created.", en.reg_row(self._get(r.pk)), 201)

    def _decide(self, r, status, comment, actor):
        return en.decide_regularization(r, status, comment, actor)

    @transaction.atomic
    def partial_update(self, request, pk=None):
        r = self._get(pk)
        if r is None:
            return err("NOT_FOUND", "Record not found.", 404)
        if r.status != "Pending Approval":
            return err("CONFLICT", f"A {r.status.lower()} request cannot be edited.", 409)
        try:
            day, tin, tout, reason = validate_reg(request.data, False, r)
        except ValueError as e:
            return err("VALIDATION", str(e))
        if day != r.attendance_date and AttendanceRegularization.objects.filter(
                company=r.company, employee=r.employee, attendance_date=day, status__in=["Pending Approval", "Approved"]).exists():
            return err("EXISTS", "A regularization request already exists for that date.", 409)
        r.attendance_date, r.punch_in_time, r.punch_out_time, r.reason, r.updated_by = day, tin, tout, reason, self.actor()
        r.save()
        return ok("REGULARIZATION_UPDATED", "Updated.", en.reg_row(r))

    update = partial_update

    def destroy(self, request, pk=None):
        r = self._get(pk)
        if r is None:
            return err("NOT_FOUND", "Record not found.", 404)
        if r.status == "Approved":
            return err("CONFLICT", "An approved regularization is part of attendance and cannot be deleted.", 409)
        r.is_active, r.updated_by = False, self.actor()
        r.status = "Cancelled" if r.status == "Pending Approval" else r.status
        r.save()
        return ok("REGULARIZATION_DELETED", "Deleted.", {"id": int(pk)})

    @action(detail=True, methods=["post"])
    @transaction.atomic
    def approve(self, request, pk=None):
        r = self._get(pk)
        if r is None:
            return err("NOT_FOUND", "Record not found.", 404)
        if r.status != "Pending Approval":
            return err("CONFLICT", f"This request is already {r.status}.", 409)
        self._decide(r, "Approved", request.data.get("comment"), self.actor())
        return ok("REGULARIZATION_APPROVED", "Regularization approved; attendance updated.", en.reg_row(self._get(pk)))

    @action(detail=True, methods=["post"])
    def reject(self, request, pk=None):
        r = self._get(pk)
        if r is None:
            return err("NOT_FOUND", "Record not found.", 404)
        if r.status != "Pending Approval":
            return err("CONFLICT", f"This request is already {r.status}.", 409)
        c = str(request.data.get("comment") or "").strip()
        if not c:
            return err("VALIDATION", "comment is required when rejecting.", errors={"comment": ["This field is required."]})
        self._decide(r, "Rejected", c, self.actor())
        return ok("REGULARIZATION_REJECTED", "Regularization rejected.", en.reg_row(self._get(pk)))


# ============================================================
# PERIMETER EXCEPTIONS
# ============================================================

class PerimeterEventViewSet(AttCrud):
    """
    GET    /api/attendance-hub/perimeter-events/   ?status= ?employee_code= ?from= ?to= ?search=
    POST   /api/attendance-hub/perimeter-events/   manual log {employee_code?, attempted_action, breach_reason, event_time?, status?, detected_ip?, latitude?, longitude?}
    GET    /<id>/    PATCH|PUT|POST(update/) /<id>/ {resolution_note?}    DELETE|POST(delete/) /<id>/   (soft delete)
    POST   /<id>/resolve/ {note?}    POST /<id>/override/ {note}   (HR lets the employee through -> 'Overridden by HR')
    Events are written automatically when a web / mobile punch is blocked or redirected.
    """
    model = PerimeterEvent
    code = "PERIMETER_EVENT"
    search_fields = ("employee_code", "employee__name", "breach_reason", "attempted_action", "detected_ip")
    select = ("employee",)
    permission_action_map = {"resolve": "edit", "override": "edit"}

    def build(self, e):
        name = e.employee.name if e.employee_id else None
        return {"id": e.id, "event_time": iso(e.event_time), "event_time_label": timezone.localtime(e.event_time).strftime("%Y-%m-%d %I:%M %p"),
                "employee": {"employee_code": e.employee_code, "name": name}, "employee_label": f"{name} ({e.employee_code})" if name else e.employee_code,
                "attempted_action": e.attempted_action, "detected_ip": e.detected_ip, "latitude": e.latitude, "longitude": e.longitude,
                "distance_m": float(e.distance_m) if e.distance_m is not None else None,
                "detected_location_ip": e.detected_ip or en.gps_label(e.latitude, e.longitude), "breach_reason": e.breach_reason,
                "status": e.status, "resolved_by": e.resolved_by, "resolved_at": iso(e.resolved_at), "resolution_note": e.resolution_note,
                "created_at": iso(e.created_at)}

    def filter(self, qs, p):
        qs = super().filter(qs, p)
        if p.get("employee_code"):
            qs = qs.filter(employee_code=p["employee_code"])
        if p.get("from"):
            qs = qs.filter(event_time__gte=en.day_range(to_date(p["from"]))[0])
        if p.get("to"):
            qs = qs.filter(event_time__lt=en.day_range(to_date(p["to"]))[1])
        return qs

    def apply(self, e, d, creating):
        if creating:
            emp = emp_by_code(e.company, d.get("employee_code"), required=False)
            e.employee, e.employee_code = emp, emp.employee_code if emp else None
            if not str(d.get("attempted_action") or "").strip() or not str(d.get("breach_reason") or "").strip():
                raise ValueError("attempted_action and breach_reason are required.")
            e.attempted_action, e.breach_reason = str(d["attempted_action"]).strip()[:60], d["breach_reason"]
            e.event_time = parse_dt(d["event_time"], "event_time") if d.get("event_time") else timezone.now()
            st = d.get("status") or "Blocked by Perimeter Lock"
            if st not in dict(PerimeterEvent.STATUS):
                raise ValueError("Invalid status. Allowed: " + ", ".join(dict(PerimeterEvent.STATUS)))
            e.status = st
            e.detected_ip = valid_ip(d["detected_ip"]) if d.get("detected_ip") else None
            for f in ("latitude", "longitude"):
                if d.get(f) not in (None, ""):
                    setattr(e, f, float(d[f]))
        else:
            forbidden = [k for k in d if k not in ("resolution_note", "breach_reason")]
            if forbidden:
                raise ValueError("Only resolution_note and breach_reason can be edited. Use resolve / override to change the status.")
            for f in ("resolution_note", "breach_reason"):
                if f in d:
                    setattr(e, f, d[f])

    def _close(self, request, pk, status, need_note):
        e = self.scope().filter(pk=pk, is_active=True).first()
        if e is None:
            return err("NOT_FOUND", "Record not found.", 404)
        if e.status in ("Resolved", "Overridden by HR"):
            return err("CONFLICT", f"This event is already {e.status}.", 409)
        note = str(request.data.get("note") or "").strip()
        if need_note and not note:
            return err("VALIDATION", "note is required.", errors={"note": ["This field is required."]})
        e.status, e.resolved_by, e.resolved_at, e.resolution_note, e.updated_by = status, self.actor(), timezone.now(), note or None, self.actor()
        e.save()
        return ok("PERIMETER_EVENT_" + ("RESOLVED" if status == "Resolved" else "OVERRIDDEN"), f"Event marked {status}.", self.build(e))

    @action(detail=True, methods=["post"])
    def resolve(self, request, pk=None):
        return self._close(request, pk, "Resolved", False)

    @action(detail=True, methods=["post"])
    def override(self, request, pk=None):
        return self._close(request, pk, "Overridden by HR", True)
