# ============================================================
# ADDITIVE: Admin / HR API - Performance Management & OKRs
# ------------------------------------------------------------
# Mounted at  /api/performance/   (see Company/performance_api_urls.py)
#
# Screen tab               -> endpoint(s)
# -----------------------------------------------------------
# Performance Dashboard    -> GET  dashboard/
#                             CRUD pips/            (Performance PIPs card)
# Goals / KPIs             -> CRUD goals/
#                             GET  goals/overview/
#                             POST goals/set-objectives/   ("+ Set Objectives")
#                             POST goals/import-targets/   (old Employee.Target -> goals)
#                             POST goals/<id>/progress/
# Appraisals               -> CRUD appraisals/
#                             GET  appraisals/summary/
#                             POST appraisals/<id>/complete/
#                             POST appraisals/<id>/nominate-promotion/
# Review Cycles            -> CRUD review-cycles/
#                             POST review-cycles/<id>/launch/ | activate/ | close/
# Manager Feedback         -> CRUD manager-feedback/
# Employee Self Review     -> CRUD self-reviews/ , POST self-reviews/<id>/submit/
# Rating History           -> CRUD rating-history/
#                             GET  rating-history/distribution/   (bell curve)
#
# Permissions: the same dynamic EmployeeRole checkboxes used by the
# rest of the HR API (module "performance": can_view_performance,
# can_create_performance, can_edit_performance, can_delete_performance,
# can_manage_performance). Company Admin is always allowed, and an
# employee role with can_manage_employees is accepted as HR-level
# fallback. Every query is company-isolated.
# ============================================================

from decimal import Decimal

from django.db import IntegrityError, transaction
from django.db.models import Avg, Count, Q
from django.http import Http404
from django.utils import timezone

from rest_framework import serializers
from rest_framework import status as http_status
from rest_framework.decorators import action
from rest_framework.exceptions import NotFound, PermissionDenied
from rest_framework.views import APIView
from rest_framework.viewsets import ModelViewSet

from Employee.employee_crud_permissions import (
    AdminOrEmployeeJWTAuthentication,
    IsAdminOrHR,
    _role_is_usable,
    actor_label,
    resolve_company_for_user,
)
from Employee.models import EmployeeDT, Target
from Employee.performance_models import (
    PerfAppraisal,
    PerfGoal,
    PerfImprovementPlan,
    PerfManagerFeedback,
    PerfRatingHistory,
    PerfReviewCycle,
    PerfSelfReview,
)
from People.models import PromotionRequest

from . import performance_engine as eng
from .performance_engine import _err, _ok, _truthy, employee_mini, employee_title


SCORE = dict(max_digits=3, decimal_places=1, min_value=Decimal("0"),
             max_value=Decimal("5"), required=False, allow_null=True)


# ============================================================
# PERMISSION
# ============================================================

class IsPerformanceAdminOrHR(IsAdminOrHR):
    """
    IsAdminOrHR (module "performance") + HR-level fallback: an employee
    whose role has can_manage_employees may use the performance API even
    before the performance checkboxes are ticked on the role.
    """

    def has_permission(self, request, view):
        if super().has_permission(request, view):
            return True
        role = _role_is_usable(request.user)
        return bool(role is not None and getattr(role, "can_manage_employees", False))


# ============================================================
# SERIALIZER BASE
# ============================================================

class PerfSerializer(serializers.ModelSerializer):
    """
    employee is written with `employee_code` (company-checked) and
    read back as `employee_code` + an `employee` block.
    """

    employee_code = serializers.CharField(write_only=True, required=False)

    # field name -> model, limited to the caller's company
    company_scoped = {}

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        company = self.context.get("company")

        for f in self.fields.values():
            if isinstance(f, serializers.DecimalField):
                f.coerce_to_string = False

        if company is not None:
            for name, model in self.company_scoped.items():
                if name in self.fields:
                    self.fields[name].queryset = model.objects.filter(company=company)

    @property
    def company(self):
        return self.context["company"]

    def resolve_employee(self, attrs):
        code = attrs.pop("employee_code", None)
        if self.instance is None:
            if not code:
                raise serializers.ValidationError({"employee_code": "This field is required."})
        elif code is None or code == self.instance.employee.employee_code:
            return
        else:
            raise serializers.ValidationError({"employee_code": "employee_code cannot be changed."})

        emp = eng.get_employee(self.company, code)
        if emp is None:
            raise serializers.ValidationError(
                {"employee_code": "Employee not found in your company."})
        attrs["employee"] = emp

    def to_representation(self, obj):
        data = super().to_representation(obj)
        data["employee_code"] = obj.employee.employee_code
        data["employee"] = employee_mini(obj.employee)
        return data


# ============================================================
# 1. REVIEW CYCLES
# ============================================================

class ReviewCycleSerializer(serializers.ModelSerializer):

    appraisal_count = serializers.SerializerMethodField()

    class Meta:
        model = PerfReviewCycle
        fields = ["id", "name", "cycle_type", "period_label", "financial_year",
                  "start_date", "end_date", "submission_deadline",
                  "eligible_joined_before", "description", "status", "is_active",
                  "appraisal_count", "created_at", "updated_at"]
        read_only_fields = ["id", "created_at", "updated_at"]
        extra_kwargs = {"financial_year": {"required": False},
                        "period_label": {"required": False}}

    def get_appraisal_count(self, obj):
        v = getattr(obj, "appraisal_total", None)
        return v if v is not None else obj.appraisals.count()

    def validate(self, attrs):
        inst = self.instance
        start = attrs.get("start_date", inst.start_date if inst else None)
        end = attrs.get("end_date", inst.end_date if inst else None)
        if start and end and end < start:
            raise serializers.ValidationError({"end_date": "end_date cannot be before start_date."})

        fy = attrs.get("financial_year")
        if fy and not eng.valid_fy(fy):
            raise serializers.ValidationError({"financial_year": "Use the format 2026-27."})
        if not fy and (inst is None or not inst.financial_year):
            attrs["financial_year"] = eng.default_fy_for_cycle({
                "submission_deadline": attrs.get("submission_deadline"),
                "start_date": start,
            })
        return attrs

    def to_representation(self, obj):
        data = super().to_representation(obj)
        data["is_active_cycle"] = obj.status == "Active"
        data["submission_deadline_label"] = eng.fmt_date(obj.submission_deadline)
        data["eligibility_label"] = eng.eligibility_text(obj)
        data["summary_line"] = (
            f"Submission Deadline: {eng.fmt_date(obj.submission_deadline) or '-'} • "
            f"Eligible: {eng.eligibility_text(obj)}"
        )
        return data


# ============================================================
# 2. GOALS / KPIs
# ============================================================

class GoalSerializer(PerfSerializer):

    company_scoped = {"cycle": PerfReviewCycle, "parent": PerfGoal, "legacy_target": Target}

    progress_percent = serializers.DecimalField(
        max_digits=5, decimal_places=2, min_value=Decimal("0"), max_value=Decimal("100"),
        required=False)
    weight = serializers.DecimalField(
        max_digits=5, decimal_places=2, min_value=Decimal("0"), max_value=Decimal("100"),
        required=False)

    class Meta:
        model = PerfGoal
        fields = ["id", "employee_code", "cycle", "parent", "legacy_target", "title",
                  "description", "goal_type", "financial_year", "weight", "target_value",
                  "current_value", "unit", "progress_percent", "start_date", "due_date",
                  "status", "completed_at", "is_active", "created_at", "updated_at"]
        read_only_fields = ["id", "completed_at", "created_at", "updated_at"]

    def validate(self, attrs):
        self.resolve_employee(attrs)
        inst = self.instance

        start = attrs.get("start_date", inst.start_date if inst else None)
        due = attrs.get("due_date", inst.due_date if inst else None)
        if start and due and due < start:
            raise serializers.ValidationError({"due_date": "due_date cannot be before start_date."})

        parent = attrs.get("parent")
        if parent is not None and inst is not None and parent.pk == inst.pk:
            raise serializers.ValidationError({"parent": "A goal cannot be its own parent."})

        fy = attrs.get("financial_year")
        if fy and not eng.valid_fy(fy):
            raise serializers.ValidationError({"financial_year": "Use the format 2026-27."})
        if not fy and (inst is None or not inst.financial_year):
            cycle = attrs.get("cycle") or (inst.cycle if inst else None)
            attrs["financial_year"] = (
                cycle.financial_year if cycle and cycle.financial_year
                else eng.financial_year(due or timezone.localdate())
            )

        return eng.apply_goal_progress(attrs, inst)

    def to_representation(self, obj):
        data = super().to_representation(obj)
        data["cycle_name"] = obj.cycle.name if obj.cycle_id else None
        data["progress_label"] = f"{eng.num(obj.progress_percent, 0):g}%"
        return data


# ============================================================
# 3. APPRAISALS
# ============================================================

class AppraisalSerializer(PerfSerializer):

    company_scoped = {"cycle": PerfReviewCycle}

    self_score = serializers.DecimalField(**SCORE)
    manager_score = serializers.DecimalField(**SCORE)
    normalized_rating = serializers.DecimalField(**SCORE)

    class Meta:
        model = PerfAppraisal
        fields = ["id", "employee_code", "cycle", "financial_year", "self_score",
                  "manager_score", "normalized_rating", "is_calibrated",
                  "rating_label_override", "potential", "nine_box_position",
                  "promotion_proposed", "proposed_level", "promotion_request",
                  "reviewer_code", "manager_comments", "hr_comments", "status",
                  "completed_at", "is_active", "created_at", "updated_at"]
        read_only_fields = ["id", "is_calibrated", "promotion_request", "completed_at",
                            "created_at", "updated_at"]

    def validate(self, attrs):
        self.resolve_employee(attrs)
        inst = self.instance

        if "normalized_rating" in attrs:
            # explicit value = HR calibration; null = back to "follows manager score"
            attrs["is_calibrated"] = attrs["normalized_rating"] is not None

        proposed = attrs.get("promotion_proposed", inst.promotion_proposed if inst else False)
        level = attrs.get("proposed_level", inst.proposed_level if inst else "")
        if proposed and not level:
            raise serializers.ValidationError(
                {"proposed_level": "Required when promotion_proposed is true (e.g. L4)."})
        if not proposed:
            attrs["proposed_level"] = ""

        status = attrs.get("status", inst.status if inst else None)
        if status == "Completed":
            manager = attrs.get("manager_score", inst.manager_score if inst else None)
            normalized = attrs.get("normalized_rating", inst.normalized_rating if inst else None)
            if manager is None and normalized is None:
                raise serializers.ValidationError(
                    {"status": "An appraisal cannot be completed without a manager score."})
        return attrs

    def to_representation(self, obj):
        data = super().to_representation(obj)
        rating = obj.normalized_rating
        data["cycle_name"] = obj.cycle.name
        data["rating_label"] = eng.appraisal_label(obj) if rating is not None else None
        data["rating_bucket"] = eng.rating_bucket(rating)
        data["normalized_badge"] = (
            f"{rating} ({obj.rating_label_override or eng.rating_label(rating, short=True)})"
            if rating is not None else None
        )
        data["promotion_label"] = (
            f"Yes ({obj.proposed_level})" if obj.promotion_proposed else "No"
        )
        data["employee_label"] = f"{obj.employee.name} ({obj.employee.employee_code})"
        return data


# ============================================================
# 4. SELF REVIEW
# ============================================================

class SelfReviewSerializer(PerfSerializer):

    company_scoped = {"cycle": PerfReviewCycle}

    self_score = serializers.DecimalField(**SCORE)

    class Meta:
        model = PerfSelfReview
        fields = ["id", "employee_code", "cycle", "appraisal", "summary", "self_score",
                  "status", "submitted_at", "is_active", "created_at", "updated_at"]
        read_only_fields = ["id", "appraisal", "submitted_at", "created_at", "updated_at"]

    def validate(self, attrs):
        self.resolve_employee(attrs)
        inst = self.instance
        status = attrs.get("status", inst.status if inst else "Draft")
        summary = attrs.get("summary", inst.summary if inst else "")
        if status == "Submitted" and not str(summary).strip():
            raise serializers.ValidationError({"summary": "Write your self-appraisal before submitting."})
        return attrs

    def to_representation(self, obj):
        data = super().to_representation(obj)
        data["cycle_name"] = obj.cycle.name
        data["heading"] = f"{obj.employee.name} ({obj.employee.employee_code}) - Self-Appraisal:"
        return data


# ============================================================
# 5. MANAGER FEEDBACK
# ============================================================

class ManagerFeedbackSerializer(PerfSerializer):

    company_scoped = {"cycle": PerfReviewCycle}

    manager_code = serializers.CharField(write_only=True, required=False, allow_blank=True)
    rating = serializers.DecimalField(**SCORE)

    class Meta:
        model = PerfManagerFeedback
        fields = ["id", "employee_code", "manager_code", "cycle", "feedback_type",
                  "feedback", "rating", "meeting_date", "visible_to_employee",
                  "is_active", "created_at", "updated_at"]
        read_only_fields = ["id", "created_at", "updated_at"]

    def validate(self, attrs):
        self.resolve_employee(attrs)

        if "manager_code" in attrs:
            code = attrs.pop("manager_code")
            if code:
                mgr = eng.get_employee(self.company, code)
                if mgr is None:
                    raise serializers.ValidationError(
                        {"manager_code": "Manager not found in your company."})
                attrs["manager"] = mgr
            else:
                attrs["manager"] = None

        emp = attrs.get("employee") or (self.instance.employee if self.instance else None)
        mgr = attrs.get("manager")
        if emp is not None and mgr is not None and emp.pk == mgr.pk:
            raise serializers.ValidationError(
                {"manager_code": "A manager cannot write feedback about themselves."})
        return attrs

    def to_representation(self, obj):
        data = super().to_representation(obj)
        data["manager_code"] = obj.manager.employee_code if obj.manager_id else None
        data["manager"] = employee_mini(obj.manager)
        data["cycle_name"] = obj.cycle.name if obj.cycle_id else None
        mgr_name = obj.manager.name if obj.manager_id else "HR"
        data["heading"] = f"{mgr_name} (Manager) on {employee_title(obj.employee)}:"
        return data


# ============================================================
# 6. PERFORMANCE IMPROVEMENT PLAN
# ============================================================

class PIPSerializer(PerfSerializer):

    company_scoped = {"appraisal": PerfAppraisal}

    class Meta:
        model = PerfImprovementPlan
        fields = ["id", "employee_code", "appraisal", "reason", "coaching_plan",
                  "start_date", "end_date", "status", "outcome", "is_active",
                  "created_at", "updated_at"]
        read_only_fields = ["id", "created_at", "updated_at"]

    def validate(self, attrs):
        self.resolve_employee(attrs)
        inst = self.instance
        start = attrs.get("start_date", inst.start_date if inst else None)
        end = attrs.get("end_date", inst.end_date if inst else None)
        if start and end and end < start:
            raise serializers.ValidationError({"end_date": "end_date cannot be before start_date."})
        return attrs


# ============================================================
# 7. RATING HISTORY
# ============================================================

class RatingHistorySerializer(PerfSerializer):

    company_scoped = {"cycle": PerfReviewCycle}

    rating = serializers.DecimalField(
        max_digits=3, decimal_places=1, min_value=Decimal("0"), max_value=Decimal("5"))

    class Meta:
        model = PerfRatingHistory
        fields = ["id", "employee_code", "cycle", "appraisal", "period_label",
                  "financial_year", "rating", "rating_bucket", "rating_label", "source",
                  "remarks", "is_active", "created_at", "updated_at"]
        read_only_fields = ["id", "appraisal", "rating_bucket", "rating_label", "source",
                            "created_at", "updated_at"]
        extra_kwargs = {"rating": {"required": False}}

    def validate(self, attrs):
        self.resolve_employee(attrs)
        inst = self.instance

        if inst is None and attrs.get("rating") is None:
            raise serializers.ValidationError({"rating": "This field is required."})

        if "rating" in attrs:
            attrs["rating_bucket"] = eng.rating_bucket(attrs["rating"])
            attrs["rating_label"] = eng.rating_label(attrs["rating"])

        cycle = attrs.get("cycle") or (inst.cycle if inst else None)
        if cycle is not None:
            if not attrs.get("period_label") and not (inst and inst.period_label):
                attrs["period_label"] = eng.cycle_period(cycle)
            if not attrs.get("financial_year") and not (inst and inst.financial_year):
                attrs["financial_year"] = cycle.financial_year or ""

        fy = attrs.get("financial_year")
        if fy and not eng.valid_fy(fy):
            raise serializers.ValidationError({"financial_year": "Use the format 2026-27."})
        return attrs

    def to_representation(self, obj):
        data = super().to_representation(obj)
        data["cycle_name"] = obj.cycle.name if obj.cycle_id else None
        return data


# ============================================================
# BASE VIEWS
# ============================================================

class PerfMixin:
    authentication_classes = [AdminOrEmployeeJWTAuthentication]
    permission_classes = [IsPerformanceAdminOrHR]
    permission_module = "performance"

    def get_company(self):
        company = resolve_company_for_user(self.request.user)
        if company is None:
            raise PermissionDenied("Unable to resolve your company. Access denied.")
        return company

    def _limit(self, default=500, cap=2000):
        try:
            return max(1, min(int(self.request.query_params.get("limit", default)), cap))
        except (TypeError, ValueError):
            return default

    def _offset(self):
        try:
            return max(0, int(self.request.query_params.get("offset", 0)))
        except (TypeError, ValueError):
            return 0

    def handle_exception(self, exc):
        if isinstance(exc, PermissionDenied):
            return _err("permission_denied", str(exc.detail), http_status.HTTP_403_FORBIDDEN)
        if isinstance(exc, (Http404, NotFound)):
            return _err("not_found", "Record not found.", http_status.HTTP_404_NOT_FOUND)
        return super().handle_exception(exc)


class PerfAPIView(PerfMixin, APIView):
    permission_write_action = None


class PerfCRUD(PerfMixin, ModelViewSet):
    """
    Generic company-isolated CRUD with the project's response envelope:
      GET    <base>/                list (filters, ?search=, ?limit=&offset=)
      POST   <base>/                create
      GET    <base>/<id>/           detail
      PUT    <base>/<id>/           full update
      PATCH  <base>/<id>/           partial update
      DELETE <base>/<id>/           delete
    """

    http_method_names = ["get", "post", "put", "patch", "delete", "head", "options"]

    model = None
    entity = "record"          # response codes: <entity>_list / _created ...
    label = "Record"
    select = ()
    filter_map = {}            # query param -> ORM lookup
    search_fields = ()
    conflict_message = "A record with the same details already exists."

    # ---- plumbing -------------------------------------------------

    def get_serializer_context(self):
        ctx = super().get_serializer_context()
        ctx["company"] = self.get_company()
        return ctx

    def get_queryset(self):
        qs = self.model.objects.filter(company=self.get_company())
        if self.select:
            qs = qs.select_related(*self.select)
        qs = self.extra_queryset(qs)

        p = self.request.query_params
        for param, lookup in self.filter_map.items():
            value = p.get(param)
            if value not in (None, ""):
                qs = qs.filter(**{lookup: value})

        if p.get("is_active") not in (None, ""):
            qs = qs.filter(is_active=_truthy(p.get("is_active")))

        term = (p.get("search") or "").strip()
        if term and self.search_fields:
            cond = Q()
            for f in self.search_fields:
                cond |= Q(**{f"{f}__icontains": term})
            qs = qs.filter(cond)
        return qs

    def extra_queryset(self, qs):
        return qs

    # ---- hooks ----------------------------------------------------

    def after_save(self, obj, actor, created):
        pass

    def before_delete(self, obj):
        return None

    # ---- CRUD -----------------------------------------------------

    def list(self, request, *args, **kwargs):
        qs = self.get_queryset()
        total = qs.count()
        limit, offset = self._limit(), self._offset()
        rows = self.get_serializer(qs[offset:offset + limit], many=True).data
        return _ok(f"{self.entity}_list", f"{self.label} list fetched successfully.", {
            "count": total, "limit": limit, "offset": offset, "results": rows,
        })

    def retrieve(self, request, *args, **kwargs):
        return _ok(f"{self.entity}_detail", f"{self.label} fetched successfully.",
                   self.get_serializer(self.get_object()).data)

    def create(self, request, *args, **kwargs):
        ser = self.get_serializer(data=request.data)
        if not ser.is_valid():
            return _err("invalid_input", "Please correct the highlighted fields.",
                        errors=ser.errors)
        actor = actor_label(request.user)
        try:
            with transaction.atomic():
                obj = ser.save(company=self.get_company(), created_by=actor, updated_by=actor)
                self.after_save(obj, actor, True)
        except IntegrityError:
            return _err(f"{self.entity}_exists", self.conflict_message,
                        http_status.HTTP_409_CONFLICT)
        obj = self.get_queryset().get(pk=obj.pk)
        return _ok(f"{self.entity}_created", f"{self.label} created.",
                   self.get_serializer(obj).data, http_status.HTTP_201_CREATED)

    def update(self, request, *args, **kwargs):
        partial = kwargs.pop("partial", False)
        obj = self.get_object()
        ser = self.get_serializer(obj, data=request.data, partial=partial)
        if not ser.is_valid():
            return _err("invalid_input", "Please correct the highlighted fields.",
                        errors=ser.errors)
        actor = actor_label(request.user)
        try:
            with transaction.atomic():
                obj = ser.save(updated_by=actor, id_version=(obj.id_version or 1) + 1)
                self.after_save(obj, actor, False)
        except IntegrityError:
            return _err(f"{self.entity}_exists", self.conflict_message,
                        http_status.HTTP_409_CONFLICT)
        obj = self.get_queryset().get(pk=obj.pk)
        return _ok(f"{self.entity}_updated", f"{self.label} updated.",
                   self.get_serializer(obj).data)

    def destroy(self, request, *args, **kwargs):
        obj = self.get_object()
        blocked = self.before_delete(obj)
        if blocked is not None:
            return blocked
        pk = obj.pk
        obj.delete()
        return _ok(f"{self.entity}_deleted", f"{self.label} deleted.", {"id": pk})

    # ---- shared helper for custom actions -------------------------

    def _row(self, obj):
        return self.get_serializer(self.get_queryset().get(pk=obj.pk)).data


# ============================================================
# 1. PERFORMANCE DASHBOARD
# ============================================================

class PerformanceDashboardView(PerfAPIView):
    """
    GET /api/performance/dashboard/?cycle_id=&financial_year=2026-27&limit=50

    Company Average Rating / Appraisal Completion / High Potential Talent /
    Performance PIPs cards + the employee cards (rating badge, cycle, goal bars).
    Default scope = newest Active review cycle, else the current financial year.
    """

    def get(self, request):
        company = self.get_company()
        cycle, fy, error = eng.resolve_scope(company, request.query_params)
        if error:
            return _err("invalid_input", error)

        limit = self._limit(50, 500)
        return _ok("performance_dashboard", "Performance dashboard fetched successfully.", {
            "title": "Performance Management & OKRs",
            "subtitle": "Goal setting, self-reviews, manager reviews, and rating distribution",
            "scope": {
                "cycle_id": cycle.pk if cycle else None,
                "cycle_name": cycle.name if cycle else None,
                "period_label": eng.cycle_period(cycle) if cycle else None,
                "financial_year": fy,
            },
            "cards": eng.dashboard_cards(company, cycle, fy),
            "employees": eng.employee_cards(company, cycle, fy, limit=limit, request=request),
        })


class PIPViewSet(PerfCRUD):
    """
    /api/performance/pips/        CRUD  (dashboard "Performance PIPs" card)
    POST /api/performance/pips/<id>/complete/   {"outcome": "..."}
    """

    model = PerfImprovementPlan
    serializer_class = PIPSerializer
    entity, label = "pip", "Performance improvement plan"
    select = ("employee", "employee__department")
    filter_map = {"employee_code": "employee__employee_code", "status": "status",
                  "appraisal_id": "appraisal_id"}
    search_fields = ("employee__name", "employee__employee_code", "reason")
    permission_action_map = {"complete": "edit"}

    @action(detail=True, methods=["post"], url_path="complete")
    def complete(self, request, pk=None):
        obj = self.get_object()
        if obj.status in ("Completed", "Cancelled"):
            return _err("already_closed", f"This PIP is already {obj.status}.",
                        http_status.HTTP_409_CONFLICT)
        obj.status = "Completed"
        obj.outcome = request.data.get("outcome", obj.outcome) or ""
        obj.end_date = obj.end_date or timezone.localdate()
        obj.updated_by = actor_label(request.user)
        obj.id_version = (obj.id_version or 1) + 1
        obj.save()
        return _ok("pip_completed", "PIP marked as completed.", self._row(obj))


# ============================================================
# 2. GOALS / KPIs
# ============================================================

class GoalViewSet(PerfCRUD):
    """
    CRUD  /api/performance/goals/
      filters: employee_code, cycle_id, status, goal_type, financial_year, parent_id,
               search, is_active
    """

    model = PerfGoal
    serializer_class = GoalSerializer
    entity, label = "goal", "Goal"
    select = ("employee", "employee__department", "cycle")
    filter_map = {"employee_code": "employee__employee_code", "cycle_id": "cycle_id",
                  "status": "status", "goal_type": "goal_type",
                  "financial_year": "financial_year", "parent_id": "parent_id"}
    search_fields = ("title", "description", "employee__name", "employee__employee_code")
    permission_action_map = {
        "overview": "view", "progress": "edit",
        "set_objectives": "create", "import_targets": "create",
    }

    @action(detail=False, methods=["get"], url_path="overview")
    def overview(self, request):
        """GET goals/overview/ - the Goals / KPIs tab: one card per employee."""
        company = self.get_company()
        cycle, fy, error = eng.resolve_scope(company, request.query_params)
        if error:
            return _err("invalid_input", error)
        codes = None
        if request.query_params.get("employee_code"):
            codes = [request.query_params["employee_code"]]
        return _ok("goal_overview", "Goals overview fetched successfully.", {
            "scope": {"cycle_id": cycle.pk if cycle else None, "financial_year": fy},
            "employees": eng.employee_cards(company, cycle, fy, limit=self._limit(200, 1000),
                                            employee_codes=codes, request=request),
        })

    @action(detail=True, methods=["post"], url_path="progress")
    def progress(self, request, pk=None):
        """POST goals/<id>/progress/  {"current_value": 85} or {"progress_percent": 85}"""
        obj = self.get_object()
        allowed = {k: v for k, v in request.data.items()
                   if k in ("current_value", "progress_percent", "status")}
        if not allowed:
            return _err("invalid_input",
                        "Send current_value, progress_percent or status.")
        ser = self.get_serializer(obj, data=allowed, partial=True)
        if not ser.is_valid():
            return _err("invalid_input", "Please correct the highlighted fields.",
                        errors=ser.errors)
        ser.save(updated_by=actor_label(request.user), id_version=(obj.id_version or 1) + 1)
        return _ok("goal_progress_updated", "Goal progress updated.", self._row(obj))

    @action(detail=False, methods=["post"], url_path="set-objectives")
    def set_objectives(self, request):
        """
        POST goals/set-objectives/      ("+ Set Objectives" button)
        {
          "employee_codes": ["EMP-0248", "EMP-0312"],
          "cycle": 1,
          "objectives": [
            {"title": "...", "goal_type": "Objective", "weight": 40,
             "target_value": 100, "unit": "%", "due_date": "2026-12-31"}
          ]
        }
        Every employee gets every objective. Exact duplicates (same employee,
        cycle and title) are skipped. All-or-nothing: one invalid row = nothing saved.
        """
        company = self.get_company()
        codes = request.data.get("employee_codes") or []
        objectives = request.data.get("objectives") or []
        if not isinstance(codes, list) or not codes:
            return _err("invalid_input", "employee_codes must be a non-empty list.")
        if not isinstance(objectives, list) or not objectives:
            return _err("invalid_input", "objectives must be a non-empty list.")
        if len(codes) * len(objectives) > 500:
            return _err("too_many", "Maximum 500 goals per request.")

        actor = actor_label(request.user)
        ctx = {**self.get_serializer_context(), "request": request}
        base = {k: request.data[k] for k in ("cycle", "financial_year") if k in request.data}

        errors, valid, skipped = [], [], 0
        for code in codes:
            for idx, obj in enumerate(objectives):
                payload = {**base, **obj, "employee_code": code}
                ser = GoalSerializer(data=payload, context=ctx)
                if not ser.is_valid():
                    errors.append({"employee_code": code, "objective_index": idx,
                                   "errors": ser.errors})
                    continue
                emp = ser.validated_data["employee"]
                if PerfGoal.objects.filter(
                    company=company, employee=emp, title=ser.validated_data["title"],
                    cycle=ser.validated_data.get("cycle"),
                ).exists():
                    skipped += 1
                    continue
                valid.append(ser)

        if errors:
            return _err("invalid_input", "Some objectives are invalid. Nothing was saved.",
                        errors=errors)

        with transaction.atomic():
            created = [s.save(company=company, created_by=actor, updated_by=actor) for s in valid]

        return _ok("objectives_set", "Objectives set successfully.", {
            "created": len(created), "skipped_duplicates": skipped,
            "goal_ids": [g.pk for g in created],
        }, http_status.HTTP_201_CREATED)

    @action(detail=False, methods=["post"], url_path="import-targets")
    def import_targets(self, request):
        """
        POST goals/import-targets/   {"employee_code": "optional", "cycle": optional id}
        Copies the OLD Employee.Target rows into goals (once each - re-running
        is safe). The old Target rows are not changed.
        """
        company = self.get_company()
        actor = actor_label(request.user)

        cycle = None
        if request.data.get("cycle"):
            cycle = PerfReviewCycle.objects.filter(company=company, pk=request.data["cycle"]).first()
            if cycle is None:
                return _err("invalid_input", "Review cycle not found.")

        targets = Target.objects.filter(company=company).select_related("employee")
        if request.data.get("employee_code"):
            targets = targets.filter(employee__employee_code=request.data["employee_code"])
        already = set(PerfGoal.objects.filter(
            company=company, legacy_target__isnull=False).values_list("legacy_target_id", flat=True))

        created = skipped = 0
        with transaction.atomic():
            for t in targets:
                if t.pk in already:
                    skipped += 1
                    continue
                PerfGoal.objects.create(
                    company=company, employee=t.employee, cycle=cycle, legacy_target=t,
                    title=t.titel, description=t.description or "", goal_type="Objective",
                    financial_year=(cycle.financial_year if cycle and cycle.financial_year
                                    else eng.financial_year(t.target_date or t.create_date)),
                    start_date=t.create_date, due_date=t.target_date,
                    status="Completed" if t.completed else "Not Started",
                    progress_percent=Decimal("100") if t.completed else Decimal("0"),
                    completed_at=timezone.now() if t.completed else None,
                    created_by=actor, updated_by=actor,
                )
                created += 1

        return _ok("targets_imported", "Targets imported as goals.",
                   {"created": created, "skipped_already_imported": skipped})


# ============================================================
# 3. APPRAISALS
# ============================================================

class AppraisalViewSet(PerfCRUD):
    """
    CRUD  /api/performance/appraisals/
      filters: employee_code, cycle_id, status, financial_year, potential,
               promotion_proposed=true|false, search, is_active
    """

    model = PerfAppraisal
    serializer_class = AppraisalSerializer
    entity, label = "appraisal", "Appraisal"
    select = ("employee", "employee__department", "cycle")
    filter_map = {"employee_code": "employee__employee_code", "cycle_id": "cycle_id",
                  "status": "status", "financial_year": "financial_year",
                  "potential": "potential"}
    search_fields = ("employee__name", "employee__employee_code", "manager_comments")
    conflict_message = "An appraisal already exists for this employee in this review cycle."
    permission_action_map = {"summary": "view", "complete": "edit",
                             "nominate_promotion": "edit"}

    def extra_queryset(self, qs):
        pp = self.request.query_params.get("promotion_proposed")
        if pp not in (None, ""):
            qs = qs.filter(promotion_proposed=_truthy(pp))
        return qs

    def after_save(self, obj, actor, created):
        eng.after_appraisal_save(obj, actor)

    @action(detail=False, methods=["get"], url_path="summary")
    def summary(self, request):
        """GET appraisals/summary/?cycle_id=&financial_year=  - counts for the tab header."""
        company = self.get_company()
        cycle, fy, error = eng.resolve_scope(company, request.query_params)
        if error:
            return _err("invalid_input", error)
        qs = eng.appraisal_scope_qs(company, cycle, fy)
        agg = qs.aggregate(
            total=Count("id"),
            avg_self=Avg("self_score"),
            avg_manager=Avg("manager_score"),
            avg_normalized=Avg("normalized_rating"),
            promotions=Count("id", filter=Q(promotion_proposed=True)),
        )
        by_status = {s: qs.filter(status=s).count() for s, _ in
                     PerfAppraisal._meta.get_field("status").choices}
        return _ok("appraisal_summary", "Appraisal summary fetched successfully.", {
            "scope": {"cycle_id": cycle.pk if cycle else None, "financial_year": fy},
            "total": agg["total"] or 0,
            "by_status": by_status,
            "average_self_score": eng.num(agg["avg_self"]),
            "average_manager_score": eng.num(agg["avg_manager"]),
            "average_normalized_rating": eng.num(agg["avg_normalized"]),
            "promotions_proposed": agg["promotions"] or 0,
        })

    @action(detail=True, methods=["post"], url_path="complete")
    def complete(self, request, pk=None):
        """
        POST appraisals/<id>/complete/
        {"normalized_rating": 4.8, "rating_label_override": "Exceeds Expectations",
         "hr_comments": "Calibrated"}     (all optional)
        Needs a manager score. Writes the Rating History row.
        """
        obj = self.get_object()
        if obj.status == "Completed":
            return _err("already_completed", "This appraisal is already completed.",
                        http_status.HTTP_409_CONFLICT)

        data = {k: request.data[k] for k in
                ("normalized_rating", "rating_label_override", "hr_comments")
                if k in request.data}
        data["status"] = "Completed"
        ser = self.get_serializer(obj, data=data, partial=True)
        if not ser.is_valid():
            return _err("invalid_input", "Please correct the highlighted fields.",
                        errors=ser.errors)
        actor = actor_label(request.user)
        with transaction.atomic():
            obj = ser.save(updated_by=actor, id_version=(obj.id_version or 1) + 1)
            eng.after_appraisal_save(obj, actor)
        return _ok("appraisal_completed", "Appraisal completed.", self._row(obj))

    @action(detail=True, methods=["post"], url_path="nominate-promotion")
    def nominate_promotion(self, request, pk=None):
        """
        POST appraisals/<id>/nominate-promotion/
        {"proposed_designation": "Lead Architect", "hike_percent": 12, "remarks": "..."}
        Creates a nomination in the EXISTING People promotions list
        (People.PromotionRequest) - no duplicate promotion model.
        """
        obj = self.get_object()
        if not obj.promotion_proposed:
            return _err("not_proposed",
                        "Set promotion_proposed=true (with proposed_level) on the appraisal first.")
        if obj.promotion_request_id:
            return _err("already_nominated", "A promotion was already nominated for this appraisal.",
                        http_status.HTTP_409_CONFLICT)

        designation = (request.data.get("proposed_designation") or "").strip()
        if not designation:
            return _err("invalid_input", "proposed_designation is required.",
                        errors={"proposed_designation": ["This field is required."]})

        try:
            hike = Decimal(str(request.data.get("hike_percent", 0) or 0))
        except Exception:
            return _err("invalid_input", "hike_percent must be a number.")

        actor = actor_label(request.user)
        with transaction.atomic():
            promo = PromotionRequest.objects.create(
                company=obj.company, employee=obj.employee,
                current_designation=obj.employee.Designation,
                proposed_designation=designation,
                proposed_grade=obj.proposed_level or None,
                hike_percent=hike,
                manager_rating=obj.manager_score,
                remarks=request.data.get("remarks") or f"From appraisal #{obj.pk} ({obj.cycle.name})",
                status="Nominated", nominated_by=actor,
                created_by=actor, updated_by=actor,
            )
            obj.promotion_request = promo
            obj.updated_by = actor
            obj.save()

        return _ok("promotion_nominated", "Promotion nominated.", {
            "promotion_request_id": promo.pk,
            "appraisal": self._row(obj),
        }, http_status.HTTP_201_CREATED)


# ============================================================
# 4. REVIEW CYCLES
# ============================================================

class ReviewCycleViewSet(PerfCRUD):
    """
    CRUD  /api/performance/review-cycles/
      filters: status, cycle_type, financial_year, search, is_active
    POST review-cycles/<id>/launch/    create appraisal rows for eligible employees + Active
    POST review-cycles/<id>/activate/
    POST review-cycles/<id>/close/
    DELETE review-cycles/<id>/?force=true   (without force: blocked if appraisals exist)
    """

    model = PerfReviewCycle
    serializer_class = ReviewCycleSerializer
    entity, label = "review_cycle", "Review cycle"
    filter_map = {"status": "status", "cycle_type": "cycle_type",
                  "financial_year": "financial_year"}
    search_fields = ("name", "period_label", "description")
    conflict_message = "A review cycle with this name already exists."
    permission_action_map = {"launch": "edit", "activate": "edit", "close": "edit"}

    def extra_queryset(self, qs):
        return qs.annotate(appraisal_total=Count("appraisals", distinct=True))

    def before_delete(self, obj):
        if obj.appraisals.exists() and not _truthy(self.request.query_params.get("force")):
            return _err(
                "cycle_in_use",
                "This cycle already has appraisals. Close it instead, or pass ?force=true "
                "to delete the cycle together with its appraisals.",
                http_status.HTTP_409_CONFLICT)
        return None

    def _set_status(self, request, new_status, code, message):
        obj = self.get_object()
        obj.status = new_status
        obj.updated_by = actor_label(request.user)
        obj.id_version = (obj.id_version or 1) + 1
        obj.save()
        return _ok(code, message, self._row(obj))

    @action(detail=True, methods=["post"], url_path="activate")
    def activate(self, request, pk=None):
        return self._set_status(request, "Active", "review_cycle_activated",
                                "Review cycle activated.")

    @action(detail=True, methods=["post"], url_path="close")
    def close(self, request, pk=None):
        return self._set_status(request, "Closed", "review_cycle_closed",
                                "Review cycle closed.")

    @action(detail=True, methods=["post"], url_path="launch")
    def launch(self, request, pk=None):
        """
        POST review-cycles/<id>/launch/   {"employee_codes": ["..."]  (optional)}
        Creates a 'Pending Self Review' appraisal for every eligible employee
        (active, joined before eligible_joined_before) that has none yet, links
        the reporting manager, and activates the cycle.
        """
        cycle = self.get_object()
        if cycle.status == "Closed":
            return _err("cycle_closed", "A closed cycle cannot be launched.",
                        http_status.HTTP_409_CONFLICT)

        company = self.get_company()
        actor = actor_label(request.user)
        emps = eng.eligible_employees(company, cycle)
        codes = request.data.get("employee_codes")
        if codes:
            if not isinstance(codes, list):
                return _err("invalid_input", "employee_codes must be a list.")
            emps = emps.filter(employee_code__in=codes)

        created = skipped = unknown_joining = 0
        with transaction.atomic():
            for emp in emps:
                if emp.Date_of_Joining is None and cycle.eligible_joined_before:
                    unknown_joining += 1
                _, was_created = PerfAppraisal.objects.get_or_create(
                    company=company, employee=emp, cycle=cycle,
                    defaults={
                        "financial_year": cycle.financial_year or "",
                        "reviewer_code": eng.manager_code_of(company, emp.employee_code) or "",
                        "status": "Pending Self Review",
                        "created_by": actor, "updated_by": actor,
                    },
                )
                created += 1 if was_created else 0
                skipped += 0 if was_created else 1

            cycle.status = "Active"
            cycle.updated_by = actor
            cycle.id_version = (cycle.id_version or 1) + 1
            cycle.save()

        return _ok("review_cycle_launched", "Review cycle launched.", {
            "appraisals_created": created,
            "already_had_appraisal": skipped,
            "joining_date_missing": unknown_joining,
            "cycle": self._row(cycle),
        })


# ============================================================
# 5. MANAGER FEEDBACK
# ============================================================

class ManagerFeedbackViewSet(PerfCRUD):
    """
    CRUD  /api/performance/manager-feedback/
      filters: employee_code, manager_code, cycle_id, feedback_type,
               visible_to_employee=true|false, search, is_active
    """

    model = PerfManagerFeedback
    serializer_class = ManagerFeedbackSerializer
    entity, label = "manager_feedback", "Manager feedback"
    select = ("employee", "employee__department", "manager", "manager__department", "cycle")
    filter_map = {"employee_code": "employee__employee_code",
                  "manager_code": "manager__employee_code", "cycle_id": "cycle_id",
                  "feedback_type": "feedback_type"}
    search_fields = ("feedback", "employee__name", "manager__name")

    def extra_queryset(self, qs):
        v = self.request.query_params.get("visible_to_employee")
        if v not in (None, ""):
            qs = qs.filter(visible_to_employee=_truthy(v))
        return qs


# ============================================================
# 6. EMPLOYEE SELF REVIEW
# ============================================================

class SelfReviewViewSet(PerfCRUD):
    """
    CRUD  /api/performance/self-reviews/
      filters: employee_code, cycle_id, status, search, is_active
    POST self-reviews/<id>/submit/
    """

    model = PerfSelfReview
    serializer_class = SelfReviewSerializer
    entity, label = "self_review", "Self review"
    select = ("employee", "employee__department", "cycle")
    filter_map = {"employee_code": "employee__employee_code", "cycle_id": "cycle_id",
                  "status": "status"}
    search_fields = ("summary", "employee__name", "employee__employee_code")
    conflict_message = "A self review already exists for this employee in this review cycle."
    permission_action_map = {"submit": "edit"}

    def after_save(self, obj, actor, created):
        eng.after_self_review_save(obj, actor)

    @action(detail=True, methods=["post"], url_path="submit")
    def submit(self, request, pk=None):
        obj = self.get_object()
        if obj.status == "Submitted":
            return _err("already_submitted", "This self review is already submitted.",
                        http_status.HTTP_409_CONFLICT)
        ser = self.get_serializer(obj, data={"status": "Submitted"}, partial=True)
        if not ser.is_valid():
            return _err("invalid_input", "Please correct the highlighted fields.",
                        errors=ser.errors)
        actor = actor_label(request.user)
        with transaction.atomic():
            obj = ser.save(updated_by=actor, id_version=(obj.id_version or 1) + 1)
            eng.after_self_review_save(obj, actor)
        return _ok("self_review_submitted", "Self review submitted.", self._row(obj))


# ============================================================
# 7. RATING HISTORY
# ============================================================

class RatingHistoryViewSet(PerfCRUD):
    """
    CRUD  /api/performance/rating-history/
      filters: employee_code, cycle_id, financial_year, source, rating_bucket, search
    GET  rating-history/distribution/?cycle_id=&financial_year=   (bell curve)
    """

    model = PerfRatingHistory
    serializer_class = RatingHistorySerializer
    entity, label = "rating_history", "Rating history"
    select = ("employee", "employee__department", "cycle")
    filter_map = {"employee_code": "employee__employee_code", "cycle_id": "cycle_id",
                  "financial_year": "financial_year", "source": "source",
                  "rating_bucket": "rating_bucket"}
    search_fields = ("employee__name", "employee__employee_code", "period_label", "remarks")
    conflict_message = "A rating already exists for this employee in this review cycle."
    permission_action_map = {"distribution": "view"}

    @action(detail=False, methods=["get"], url_path="distribution")
    def distribution(self, request):
        """
        GET rating-history/distribution/?cycle_id=&financial_year=2026-27
        "Bell Curve Distribution & Historical Ratings": Rating 5 / 4 / 3 / 2
        shares (latest rating per employee) + the reference curve.
        """
        company = self.get_company()
        params = request.query_params
        if params.get("cycle_id") or params.get("financial_year"):
            cycle, fy, error = eng.resolve_scope(company, params)
            if error:
                return _err("invalid_input", error)
        else:
            cycle, fy = None, None   # no filter = latest rating per employee overall

        data = eng.rating_distribution(company, cycle, fy)
        recent = self.get_serializer(
            self.get_queryset()[:self._limit(50, 500)], many=True).data

        return _ok("rating_distribution", "Rating distribution fetched successfully.", {
            "title": "Bell Curve Distribution & Historical Ratings",
            "scope": {"cycle_id": cycle.pk if cycle else None, "financial_year": fy},
            **data,
            "history": recent,
        })
