# ============================================================
# ADDITIVE: Employee Engagement, Surveys & Culture  (Admin / HR side)
#
#   /api/people/engagement/                         overview (tabs + stats)       GET
#   /api/people/engagement/meta/                    dropdown values for every form GET
#   /api/people/engagement/announcements/           Announcements tab  (CRUD + publish/unpublish/archive/pin/metrics)
#   /api/people/engagement/announcement-comments/   moderate / reply to comments  (CRUD)
#   /api/people/engagement/surveys/                 Surveys tab (CRUD + launch/close/reopen/clone/results/responses)
#   /api/people/engagement/survey-questions/        survey questions (CRUD, draft only)
#   /api/people/engagement/feedback/                Feedback tab (suggestion box: CRUD + review)
#   /api/people/engagement/recognition/             Recognition tab (kudos CRUD + leaderboard)
#   /api/people/engagement/events/                  Events tab (CRUD + cancel/restore/attendees)
#
# Auth  : AdminOrEmployeeJWTAuthentication  (company admin token, or employee token of an HR user)
# Authz : Company Admin = full access; employee = EmployeeRole checkboxes can_<view|create|edit|delete>_employees
#         (or can_manage_employees).  Every query is company-scoped.
# ============================================================
from django.db import transaction
from django.db.models import Avg, Count, Q, Sum
from django.utils import timezone
from rest_framework.decorators import action
from rest_framework.parsers import FormParser, JSONParser, MultiPartParser
from rest_framework.viewsets import ViewSet

from Employee.models import EmployeeDT

from .common import (CrudBase, PeopleAuthMixin, emp_brief, emp_by_code, employees_qs, err, iso, ok, paginate,
                     to_bool, to_date, to_int)
from .engagement_common import (BADGES, announcement_metrics, announcement_row, audience_employees, check_image,
                                choices_of, clean_question, enps_for, event_phase, event_row, initials,
                                live_q, media_url, parse_audience, question_row, rsvp_counts, survey_row, to_dt)
from .engagement_models import (Announcement, AnnouncementComment, AnnouncementReaction, AnnouncementView,
                                CompanyEvent, EventRsvp, FeedbackSuggestion, Kudos, Survey, SurveyAnswer,
                                SurveyQuestion, SurveyResponse)

PARSERS = [JSONParser, MultiPartParser, FormParser]


def person(request):
    """(EmployeeDT or None, display name, title) of whoever is calling."""
    u = request.user
    if isinstance(u, EmployeeDT):
        return u, u.name, u.Designation
    return None, "Company Admin", None


def pick(value, allowed, label):
    v = str(value or "").upper()
    if v not in allowed:
        raise ValueError(f"Invalid {label}. Allowed: {', '.join(allowed)}")
    return v


def dup_check(model, company, exclude_pk=None, **lookup):
    qs = model.objects.filter(company=company, is_active=True, **lookup)
    if exclude_pk:
        qs = qs.exclude(pk=exclude_pk)
    return qs.exists()


# ===============================================================
# overview + meta
# ===============================================================
class EngagementViewSet(PeopleAuthMixin, ViewSet):
    def list(self, request):
        c, now = self.company(), timezone.now()
        ann = Announcement.objects.filter(company=c, is_active=True)
        sv = Survey.objects.filter(company=c, is_active=True)
        ev = [e for e in CompanyEvent.objects.filter(company=c, is_active=True)]
        n_fb = FeedbackSuggestion.objects.filter(company=c, is_active=True).count()
        n_k = Kudos.objects.filter(company=c, is_active=True).count()
        tabs = [{"key": "announcements", "label": "Announcements", "count": ann.filter(live_q(now)).count()},
                {"key": "surveys", "label": "Surveys", "count": sv.count()},
                {"key": "feedback", "label": "Feedback", "count": n_fb},
                {"key": "recognition", "label": "Recognition", "count": n_k},
                {"key": "events", "label": "Events", "count": len(ev)}]
        return ok("ENGAGEMENT_OVERVIEW", "Employee Engagement, Surveys & Culture.", {
            "title": "Employee Engagement, Surveys & Culture",
            "subtitle": "Corporate announcements, recognition kudos, pulse surveys, and company events",
            "tabs": tabs,
            "stats": {"active_announcements": tabs[0]["count"],
                      "draft_or_scheduled": ann.exclude(live_q(now)).exclude(status="ARCHIVED").count(),
                      "active_surveys": sv.filter(status="ACTIVE").count(),
                      "open_feedback": FeedbackSuggestion.objects.filter(
                          company=c, is_active=True, status__in=["SUBMITTED", "UNDER_REVIEW"]).count(),
                      "kudos_this_month": Kudos.objects.filter(company=c, is_active=True,
                                                               created_at__month=now.month,
                                                               created_at__year=now.year).count(),
                      "upcoming_events": sum(1 for e in ev if event_phase(e, now) == "Upcoming")}})

    @action(detail=False, methods=["get"])
    def meta(self, request):
        from Employee.models import Department
        from .models import Branch
        c = self.company()
        return ok("ENGAGEMENT_META", "Dropdown values.", {
            "announcement_categories": choices_of(Announcement.CATEGORY),
            "announcement_priorities": choices_of(Announcement.PRIORITY),
            "announcement_statuses": choices_of(Announcement.STATUS),
            "reactions": choices_of(AnnouncementReaction.REACTIONS),
            "audience_types": choices_of([("ALL", "All Organization"), ("DEPARTMENT", "Department"),
                                          ("BRANCH", "Branch")]),
            "departments": list(Department.objects.filter(company=c).values("id", "name")),
            "branches": list(Branch.objects.filter(company=c, is_active=True).values("id", "name")),
            "survey_types": choices_of(Survey.TYPES), "survey_statuses": choices_of(Survey.STATUS),
            "question_types": choices_of(SurveyQuestion.QTYPES),
            "feedback_categories": choices_of(FeedbackSuggestion.CATEGORY),
            "feedback_statuses": choices_of(FeedbackSuggestion.STATUS),
            "badges": BADGES, "event_types": choices_of(CompanyEvent.TYPES),
            "event_modes": choices_of(CompanyEvent.MODES), "event_phases": ["Upcoming", "Ongoing", "Completed",
                                                                             "Cancelled"],
            "rsvp_responses": choices_of(EventRsvp.RESPONSES)})


# ===============================================================
# 1. ANNOUNCEMENTS
# ===============================================================
class AnnouncementViewSet(CrudBase):
    """
    GET    /api/people/engagement/announcements/   ?tab=all_active|drafts|archived ?category= ?priority= ?status=
                                                    ?audience_type= ?search= ?page= ?page_size=
    POST   /api/people/engagement/announcements/   json or multipart(banner_image): title, body, category?, priority?,
                                                    status?(DRAFT|SCHEDULED|PUBLISHED), publish_at?, expires_at?,
                                                    is_pinned?, allow_comments?, audience_type?, audience_ids?,
                                                    author_name?, author_title?
    GET    .../<id>/            PUT|PATCH|POST .../<id>/(update/)            DELETE|POST .../<id>/(delete/)
    POST   .../<id>/publish/    .../unpublish/    .../archive/    .../pin/ {is_pinned}
    GET    .../<id>/metrics/    ("Engagement Metrics": reach, views, reactions, comments)
    """
    model, code, parser_classes = Announcement, "ANNOUNCEMENT", PARSERS
    select = ("author",)
    permission_action_map = {"publish": "edit", "unpublish": "edit", "archive": "edit", "pin": "edit",
                             "metrics": "view"}

    def filter(self, qs, p):
        now = timezone.now()
        tab = (p.get("tab") or "").lower()
        if tab in ("all_active", "active"):
            qs = qs.filter(live_q(now))
        elif tab in ("drafts", "drafts_scheduled"):
            qs = qs.filter(Q(status="DRAFT") | Q(status="SCHEDULED") & (Q(publish_at__gt=now)
                                                                       | Q(publish_at__isnull=True)))
        elif tab == "archived":
            qs = qs.filter(status="ARCHIVED")
        for f in ("category", "priority", "status", "audience_type"):
            if p.get(f):
                qs = qs.filter(**{f: p[f].upper()})
        q = (p.get("search") or "").strip()
        return qs.filter(Q(title__icontains=q) | Q(body__icontains=q)) if q else qs

    def build(self, a):
        return announcement_row(a, self.request, getattr(self, "_m", {}).get(a.id))

    def list(self, request):
        base = self.scope().filter(is_active=True)
        qs = self.filter(base, request.query_params)
        objs, meta = paginate(request, qs, lambda o: o)
        self._m = announcement_metrics([o.id for o in objs])
        now = timezone.now()
        live = base.filter(live_q(now))
        cats = dict(live.values_list("category").annotate(n=Count("id")))
        summary = {"all_active": live.count(),
                   "drafts_scheduled": base.filter(Q(status="DRAFT") | Q(status="SCHEDULED") & (
                       Q(publish_at__gt=now) | Q(publish_at__isnull=True))).count(),
                   "archived": base.filter(status="ARCHIVED").count(), "by_category": cats}
        return ok("ANNOUNCEMENT_LIST", "List fetched.", [self.build(o) for o in objs], meta=meta, summary=summary)

    def retrieve(self, request, pk=None):
        a = self.scope().filter(pk=pk, is_active=True).first()
        if a is None:
            return err("NOT_FOUND", "Announcement not found.", 404)
        self._m = announcement_metrics([a.id])
        return ok("ANNOUNCEMENT_DETAIL", "Detail fetched.", self.build(a))

    def apply(self, o, d, creating):
        now = timezone.now()
        if creating or "title" in d:
            if not str(d.get("title") or "").strip():
                raise ValueError("title is required.")
            o.title = str(d["title"]).strip()[:200]
        if creating or "body" in d:
            if not str(d.get("body") or "").strip():
                raise ValueError("body is required.")
            o.body = str(d["body"]).strip()
        if "category" in d:
            o.category = pick(d["category"], dict(Announcement.CATEGORY), "category")
        if "priority" in d:
            o.priority = pick(d["priority"], dict(Announcement.PRIORITY), "priority")
        if "publish_at" in d:
            o.publish_at = to_dt(d["publish_at"])
        if "expires_at" in d:
            o.expires_at = to_dt(d["expires_at"])
        if "status" in d:
            o.status = pick(d["status"], dict(Announcement.STATUS), "status")
        if o.status == "SCHEDULED":
            if not o.publish_at:
                raise ValueError("publish_at is required for a SCHEDULED announcement.")
            if ("status" in d or "publish_at" in d) and o.publish_at <= now:
                raise ValueError("publish_at must be in the future for a SCHEDULED announcement.")
        if o.status == "PUBLISHED" and not o.published_at:
            o.published_at = now
        if o.expires_at and o.expires_at <= (o.publish_at or o.published_at or now):
            raise ValueError("expires_at must be after the publish time.")
        if "is_pinned" in d:
            o.is_pinned = to_bool(d["is_pinned"])
        if "allow_comments" in d:
            o.allow_comments = to_bool(d["allow_comments"], True)
        parse_audience(self.company(), d, o)
        emp, name, title = person(self.request)
        if creating:
            o.author = emp
            o.author_name, o.author_title = name, title
        if "author_name" in d:
            o.author_name = d["author_name"] or o.author_name
        if "author_title" in d:
            o.author_title = d["author_title"]
        f = self.request.FILES.get("banner_image")
        if f is not None:
            check_image(f)
            o.banner_image = f
        elif to_bool(d.get("remove_banner")):
            o.banner_image = None
        if dup_check(Announcement, o.company, o.pk, title__iexact=o.title, category=o.category) and (
                creating or "title" in d or "category" in d):
            raise ValueError("An announcement with this title and category already exists.")

    def _set(self, request, pk, **fields):
        a = self.scope().filter(pk=pk, is_active=True).first()
        if a is None:
            return err("NOT_FOUND", "Announcement not found.", 404)
        for k, v in fields.items():
            setattr(a, k, v)
        a.updated_by = self.actor()
        a.save()
        return ok("ANNOUNCEMENT_UPDATED", "Updated.", self.build(a))

    @action(detail=True, methods=["post"])
    def publish(self, request, pk=None):
        a = self.scope().filter(pk=pk, is_active=True).first()
        if a is None:
            return err("NOT_FOUND", "Announcement not found.", 404)
        if a.status == "ARCHIVED":
            return err("VALIDATION", "Archived announcements cannot be published. Create a new one.")
        return self._set(request, pk, status="PUBLISHED", published_at=a.published_at or timezone.now(),
                         publish_at=None)

    @action(detail=True, methods=["post"])
    def unpublish(self, request, pk=None):
        return self._set(request, pk, status="DRAFT")

    @action(detail=True, methods=["post"])
    def archive(self, request, pk=None):
        return self._set(request, pk, status="ARCHIVED")

    @action(detail=True, methods=["post"])
    def pin(self, request, pk=None):
        return self._set(request, pk, is_pinned=to_bool(request.data.get("is_pinned"), True))

    @action(detail=True, methods=["get"])
    def metrics(self, request, pk=None):
        a = self.scope().filter(pk=pk, is_active=True).first()
        if a is None:
            return err("NOT_FOUND", "Announcement not found.", 404)
        m = announcement_metrics([a.id])[a.id]
        size = audience_employees(self.company(), a).count()
        viewers = AnnouncementView.objects.filter(announcement=a, is_active=True)
        recent = (AnnouncementReaction.objects.filter(announcement=a, is_active=True).select_related("employee")
                  .order_by("-id")[:20])
        return ok("ANNOUNCEMENT_METRICS", "Engagement metrics.", {
            "announcement_id": a.id, "title": a.title, "audience_size": size, "views": m["views"],
            "unique_viewers": m["viewers"], "not_viewed": max(size - m["viewers"], 0),
            "reach_percent": round(m["viewers"] * 100 / size) if size else None,
            "reactions": m["reactions"], "reactions_total": m["reactions_total"], "comments": m["comments"],
            "engagement_rate": round((m["reactions_total"] + m["comments"]) * 100 / size) if size else None,
            "recent_reactions": [{"employee": emp_brief(r.employee), "reaction": r.reaction,
                                  "at": iso(r.updated_at)} for r in recent],
            "top_viewers": [{"employee": emp_brief(v.employee), "view_count": v.view_count}
                            for v in viewers.select_related("employee").order_by("-view_count")[:10]]})


class AnnouncementCommentViewSet(CrudBase):
    """GET ?announcement=<id> | POST {announcement_id, body} (HR reply) | PATCH {body} | DELETE (moderation)"""
    model, code, select = AnnouncementComment, "ANNOUNCEMENT_COMMENT", ("employee",)

    def filter(self, qs, p):
        if p.get("announcement"):
            qs = qs.filter(announcement_id=p["announcement"])
        q = (p.get("search") or "").strip()
        return qs.filter(body__icontains=q) if q else qs

    def build(self, c):
        return {"id": c.id, "announcement_id": c.announcement_id, "body": c.body,
                "author": {"name": c.author_name or (c.employee.name if c.employee_id else "Company Admin"),
                           "employee_code": c.employee.employee_code if c.employee_id else None},
                "created_at": iso(c.created_at), "updated_at": iso(c.updated_at)}

    def apply(self, o, d, creating):
        if creating:
            a = Announcement.objects.filter(company=o.company, is_active=True, pk=to_int(d.get("announcement_id"))
                                            ).first()
            if a is None:
                raise ValueError("announcement_id is invalid.")
            if not a.allow_comments:
                raise ValueError("Comments are turned off for this announcement.")
            o.announcement = a
            o.employee, o.author_name, _ = person(self.request)
        if creating or "body" in d:
            if not str(d.get("body") or "").strip():
                raise ValueError("body is required.")
            o.body = str(d["body"]).strip()[:2000]


# ===============================================================
# 2. SURVEYS
# ===============================================================
class SurveyViewSet(CrudBase):
    """
    GET  /api/people/engagement/surveys/      ?status=DRAFT|ACTIVE|CLOSED ?survey_type= ?search=
    POST /api/people/engagement/surveys/      {title, description?, survey_type?, is_anonymous?, start_date?, end_date?,
                                              audience_type?, audience_ids?, questions?:[{text,qtype,options?,is_required?}]}
    GET .../<id>/   PATCH|PUT|POST .../<id>/(update/)   DELETE|POST .../<id>/(delete/)
      after launch only title, description, end_date can change
    POST .../<id>/launch/  .../close/  .../reopen/  .../clone/
    GET  .../<id>/questions/   .../<id>/results/   .../<id>/responses/
    """
    model, code = Survey, "SURVEY"
    permission_action_map = {"launch": "edit", "close": "edit", "reopen": "edit", "clone": "create",
                             "results": "view", "responses": "view", "questions": "view"}

    def scope(self):
        return (super().scope().annotate(_rc=Count("responses", filter=Q(responses__is_active=True), distinct=True),
                                         _qc=Count("questions", filter=Q(questions__is_active=True), distinct=True)))

    def filter(self, qs, p):
        for f in ("status", "survey_type"):
            if p.get(f):
                qs = qs.filter(**{f: p[f].upper()})
        q = (p.get("search") or "").strip()
        return qs.filter(Q(title__icontains=q) | Q(description__icontains=q)) if q else qs

    def build(self, s):
        return survey_row(s, self.request, getattr(s, "_rc", None), getattr(s, "_qc", None))

    def apply(self, o, d, creating):
        self._qs = None
        locked = not creating and o.status != "DRAFT"
        if creating or "title" in d:
            if not str(d.get("title") or "").strip():
                raise ValueError("title is required.")
            o.title = str(d["title"]).strip()[:200]
        if "description" in d:
            o.description = d["description"]
        if locked:
            frozen = {"survey_type", "is_anonymous", "start_date", "audience_type", "audience_ids", "questions"}
            if frozen & set(d.keys()):
                raise ValueError("After launch only title, description and end_date can be changed.")
        else:
            if "survey_type" in d:
                o.survey_type = pick(d["survey_type"], dict(Survey.TYPES), "survey_type")
            if "is_anonymous" in d:
                o.is_anonymous = to_bool(d["is_anonymous"], True)
            if "start_date" in d:
                o.start_date = to_date(d["start_date"])
            parse_audience(self.company(), d, o)
            if "questions" in d:
                qs = d["questions"]
                if not isinstance(qs, list):
                    raise ValueError("questions must be a list.")
                self._qs = [clean_question(q) for q in qs]
        if "end_date" in d:
            o.end_date = to_date(d["end_date"])
        if o.start_date and o.end_date and o.end_date < o.start_date:
            raise ValueError("end_date cannot be before start_date.")
        if (creating or "title" in d) and dup_check(Survey, o.company, o.pk, title__iexact=o.title
                                                    ) and not Survey.objects.filter(
                company=o.company, is_active=True, title__iexact=o.title, status="CLOSED").exists():
            raise ValueError("A survey with this title already exists.")

    def after_save(self, o, creating):
        if getattr(self, "_qs", None) is not None:
            o.questions.all().delete()
            for i, q in enumerate(self._qs, 1):
                SurveyQuestion.objects.create(company=o.company, survey=o, order=i, created_by=self.actor(),
                                              updated_by=self.actor(), **q)

    def _get(self, pk):
        return self.scope().filter(pk=pk, is_active=True).first()

    @action(detail=True, methods=["post"])
    def launch(self, request, pk=None):
        s = self._get(pk)
        if s is None:
            return err("NOT_FOUND", "Survey not found.", 404)
        if s.status != "DRAFT":
            return err("VALIDATION", "Only a Draft survey can be launched.")
        if not s.questions.filter(is_active=True).exists():
            return err("VALIDATION", "Add at least one question before launching.")
        today = timezone.localdate()
        if s.end_date and s.end_date < today:
            return err("VALIDATION", "end_date is in the past.")
        size = audience_employees(self.company(), s).count()
        if size == 0:
            return err("VALIDATION", "The selected audience has no active employees.")
        s.status, s.launched_at, s.target_count = "ACTIVE", timezone.now(), size
        s.start_date = s.start_date or today
        s.updated_by = self.actor()
        s.save()
        return ok("SURVEY_LAUNCHED", "Survey launched.", self.build(self._get(pk)))

    @action(detail=True, methods=["post"])
    def close(self, request, pk=None):
        s = self._get(pk)
        if s is None:
            return err("NOT_FOUND", "Survey not found.", 404)
        if s.status != "ACTIVE":
            return err("VALIDATION", "Only an Active survey can be closed.")
        s.status, s.closed_at, s.updated_by = "CLOSED", timezone.now(), self.actor()
        s.save()
        return ok("SURVEY_CLOSED", "Survey closed.", self.build(self._get(pk)))

    @action(detail=True, methods=["post"])
    def reopen(self, request, pk=None):
        s = self._get(pk)
        if s is None:
            return err("NOT_FOUND", "Survey not found.", 404)
        if s.status != "CLOSED":
            return err("VALIDATION", "Only a Closed survey can be reopened.")
        if s.end_date and s.end_date < timezone.localdate():
            return err("VALIDATION", "Extend end_date first (PATCH end_date), then reopen.")
        s.status, s.closed_at, s.updated_by = "ACTIVE", None, self.actor()
        s.save()
        return ok("SURVEY_REOPENED", "Survey reopened.", self.build(self._get(pk)))

    @action(detail=True, methods=["post"])
    @transaction.atomic
    def clone(self, request, pk=None):
        s = self._get(pk)
        if s is None:
            return err("NOT_FOUND", "Survey not found.", 404)
        title, n = f"Copy of {s.title}"[:190], 1
        while Survey.objects.filter(company=s.company, is_active=True, title__iexact=title).exists():
            n += 1
            title = f"Copy of {s.title} ({n})"[:196]
        c = Survey.objects.create(company=s.company, title=title, description=s.description,
                                  survey_type=s.survey_type, is_anonymous=s.is_anonymous,
                                  audience_type=s.audience_type, audience_ids=s.audience_ids,
                                  created_by=self.actor(), updated_by=self.actor())
        for q in s.questions.filter(is_active=True):
            SurveyQuestion.objects.create(company=s.company, survey=c, order=q.order, text=q.text, qtype=q.qtype,
                                          options=q.options, is_required=q.is_required, created_by=self.actor(),
                                          updated_by=self.actor())
        return ok("SURVEY_CLONED", "Survey cloned as Draft.", self.build(self._get(c.pk)), 201)

    @action(detail=True, methods=["get"])
    def questions(self, request, pk=None):
        s = self._get(pk)
        if s is None:
            return err("NOT_FOUND", "Survey not found.", 404)
        return ok("SURVEY_QUESTIONS", "Questions.", [question_row(q) for q in s.questions.filter(is_active=True)])

    @action(detail=True, methods=["get"])
    def results(self, request, pk=None):
        s = self._get(pk)
        if s is None:
            return err("NOT_FOUND", "Survey not found.", 404)
        out = []
        for q in s.questions.filter(is_active=True):
            ans = SurveyAnswer.objects.filter(question=q, response__is_active=True)
            row = question_row(q) | {"answered": ans.count()}
            if q.qtype == "RATING":
                row["average"] = round(ans.aggregate(a=Avg("rating"))["a"] or 0, 2)
                dist = dict(ans.values_list("rating").annotate(n=Count("id")))
                row["distribution"] = {str(i): dist.get(i, 0) for i in range(1, 6)}
            elif q.qtype == "NPS":
                dist = dict(ans.values_list("rating").annotate(n=Count("id")))
                row["distribution"] = {str(i): dist.get(i, 0) for i in range(0, 11)}
                row["enps"] = enps_for(s)
            elif q.qtype in ("SINGLE", "MULTI", "YES_NO"):
                counts = {o: 0 for o in q.options}
                for ch in ans.values_list("choices", flat=True):
                    for c in ch or []:
                        counts[c] = counts.get(c, 0) + 1
                row["counts"] = counts
            else:
                row["answers"] = [{"text": a.text,
                                   **({} if s.is_anonymous else {"employee": emp_brief(a.response.employee)})}
                                  for a in ans.exclude(text__isnull=True).exclude(text="").select_related(
                        "response__employee").order_by("-id")[:200]]
            out.append(row)
        return ok("SURVEY_RESULTS", "Survey results.", {"survey": self.build(s), "enps": enps_for(s),
                                                        "questions": out})

    @action(detail=True, methods=["get"])
    def responses(self, request, pk=None):
        s = self._get(pk)
        if s is None:
            return err("NOT_FOUND", "Survey not found.", 404)
        qs = s.responses.filter(is_active=True).select_related("employee").prefetch_related("answers__question")
        qs = qs.order_by("-id")

        def row(r):
            base = {"id": r.id, "submitted_on": r.created_at.date().isoformat(),
                    "answers": [{"question_id": a.question_id, "question": a.question.text, "rating": a.rating,
                                 "text": a.text, "choices": a.choices} for a in r.answers.all()]}
            if not s.is_anonymous:
                base["employee"] = emp_brief(r.employee)
                base["submitted_at"] = iso(r.created_at)
            return base
        rows, meta = paginate(request, qs, row)
        return ok("SURVEY_RESPONSES", "Responses.", rows, meta=meta, anonymous=s.is_anonymous)


class SurveyQuestionViewSet(CrudBase):
    """GET ?survey=<id> | POST {survey_id, text, qtype, options?, is_required?, order?} | PATCH | DELETE (Draft surveys only)"""
    model, code, select, soft_delete = SurveyQuestion, "SURVEY_QUESTION", ("survey",), False

    def filter(self, qs, p):
        return qs.filter(survey_id=p["survey"]) if p.get("survey") else qs

    def build(self, q):
        return question_row(q)

    def apply(self, o, d, creating):
        if creating:
            s = Survey.objects.filter(company=o.company, is_active=True, pk=to_int(d.get("survey_id"))).first()
            if s is None:
                raise ValueError("survey_id is invalid.")
            o.survey = s
        if o.survey.status != "DRAFT":
            raise ValueError("Questions can only be changed while the survey is a Draft.")
        merged = {"text": o.text, "qtype": o.qtype, "options": o.options, "is_required": o.is_required} if (
            not creating) else {}
        merged.update({k: d[k] for k in ("text", "qtype", "options", "is_required") if k in d})
        for k, v in clean_question(merged).items():
            setattr(o, k, v)
        if "order" in d:
            o.order = max(to_int(d["order"], 1), 1)
        elif creating:
            o.order = (o.survey.questions.aggregate(m=Count("id"))["m"] or 0) + 1

    def destroy(self, request, pk=None):
        q = self.scope().filter(pk=pk).first()
        if q is not None and q.survey.status != "DRAFT":
            return err("VALIDATION", "Questions can only be changed while the survey is a Draft.")
        return super().destroy(request, pk)


# ===============================================================
# 3. FEEDBACK (suggestion box)
# ===============================================================
class FeedbackViewSet(CrudBase):
    """
    GET  /api/people/engagement/feedback/   ?status= ?category= ?search=
    POST /api/people/engagement/feedback/   {category, message, subject?}   (HR logs a suggestion on behalf of staff)
    GET .../<id>/   PATCH|POST .../<id>/(update/)   DELETE|POST .../<id>/(delete/)
    POST .../<id>/review/ {status, response_note?, assigned_team?}
    Submitter identity is NEVER returned for anonymous suggestions.
    """
    model, code, select = FeedbackSuggestion, "FEEDBACK", ("submitted_by",)
    permission_action_map = {"review": "edit"}

    def filter(self, qs, p):
        for f in ("status", "category"):
            if p.get(f):
                qs = qs.filter(**{f: p[f].upper()})
        q = (p.get("search") or "").strip()
        return qs.filter(Q(subject__icontains=q) | Q(message__icontains=q)) if q else qs

    def build(self, f):
        line = dict(FeedbackSuggestion.STATUS).get(f.status)
        if f.status != "SUBMITTED" and f.assigned_team:
            line = f"{line} by {f.assigned_team}"
        return {"id": f.id, "category": f.category, "category_label": dict(FeedbackSuggestion.CATEGORY).get(f.category),
                "subject": f.subject, "message": f.message, "is_anonymous": f.is_anonymous, "status": f.status,
                "status_label": dict(FeedbackSuggestion.STATUS).get(f.status), "status_line": line,
                "response_note": f.response_note, "assigned_team": f.assigned_team, "reviewed_by": f.reviewed_by,
                "reviewed_at": iso(f.reviewed_at),
                "submitted_by": None if (f.is_anonymous or not f.submitted_by_id) else emp_brief(f.submitted_by),
                "created_at": iso(f.created_at), "updated_at": iso(f.updated_at)}

    def list(self, request):
        resp = super().list(request)
        resp.data["summary"] = {"total": self.scope().filter(is_active=True).count(),
                                **{s: n for s, n in self.scope().filter(is_active=True).values_list("status")
                                   .annotate(n=Count("id"))}}
        return resp

    def apply(self, o, d, creating):
        if "category" in d or creating:
            o.category = pick(d.get("category", "OTHER"), dict(FeedbackSuggestion.CATEGORY), "category")
        if creating or (o.submitted_by_id is None and "message" in d):
            if not str(d.get("message") or "").strip():
                raise ValueError("message is required.")
            o.message = str(d["message"]).strip()
        if "subject" in d and (creating or o.submitted_by_id is None):
            o.subject = d["subject"]
        if creating:
            o.is_anonymous = to_bool(d.get("is_anonymous"), True)
        if "status" in d:
            o.status = pick(d["status"], dict(FeedbackSuggestion.STATUS), "status")
            if o.status != "SUBMITTED":
                o.reviewed_by, o.reviewed_at = person(self.request)[1], timezone.now()
        for f in ("response_note", "assigned_team"):
            if f in d:
                setattr(o, f, d[f] or None)

    @action(detail=True, methods=["post"])
    def review(self, request, pk=None):
        if not request.data.get("status"):
            return err("VALIDATION", "status is required.")
        return self.partial_update(request, pk)


# ===============================================================
# 4. RECOGNITION (kudos)
# ===============================================================
class KudosViewSet(CrudBase):
    """
    GET  /api/people/engagement/recognition/   ?recipient=<emp_code> ?giver=<emp_code> ?badge= ?from= ?to= ?search=
    POST /api/people/engagement/recognition/   {recipient_code, badge, message, points?, is_public?}
    GET .../<id>/   PATCH|POST .../<id>/(update/)   DELETE|POST .../<id>/(delete/)
    GET .../leaderboard/ ?from= ?to= ?limit=10     GET .../badges/
    """
    model, code, select = Kudos, "KUDOS", ("recipient", "giver")
    permission_action_map = {"leaderboard": "view", "badges": "view"}

    def filter(self, qs, p):
        if p.get("recipient"):
            qs = qs.filter(recipient__employee_code=p["recipient"])
        if p.get("giver"):
            qs = qs.filter(giver__employee_code=p["giver"])
        if p.get("badge"):
            qs = qs.filter(badge__iexact=p["badge"])
        try:
            if p.get("from"):
                qs = qs.filter(created_at__date__gte=to_date(p["from"]))
            if p.get("to"):
                qs = qs.filter(created_at__date__lte=to_date(p["to"]))
        except ValueError:
            pass
        q = (p.get("search") or "").strip()
        return qs.filter(Q(message__icontains=q) | Q(recipient__name__icontains=q)) if q else qs

    def build(self, k):
        return {"id": k.id, "badge": k.badge, "message": k.message, "points": k.points, "is_public": k.is_public,
                "recipient": emp_brief(k.recipient, self.request),
                "giver": {"name": k.giver_name or (k.giver.name if k.giver_id else "Company Admin"),
                          "employee_code": k.giver.employee_code if k.giver_id else None},
                "created_at": iso(k.created_at), "updated_at": iso(k.updated_at)}

    def apply(self, o, d, creating):
        if creating:
            o.recipient = emp_by_code(o.company, d.get("recipient_code"))
            o.giver, o.giver_name, _ = person(self.request)
            if o.giver and o.giver.pk == o.recipient.pk:
                raise ValueError("You cannot recognise yourself.")
        if creating or "badge" in d:
            if not str(d.get("badge") or "").strip():
                raise ValueError("badge is required.")
            o.badge = str(d["badge"]).strip()[:60]
        if creating or "message" in d:
            if not str(d.get("message") or "").strip():
                raise ValueError("message is required.")
            o.message = str(d["message"]).strip()[:1000]
        if "points" in d:
            pts = to_int(d["points"], 10)
            if pts < 0 or pts > 1000:
                raise ValueError("points must be between 0 and 1000.")
            o.points = pts
        if "is_public" in d:
            o.is_public = to_bool(d["is_public"], True)

    @action(detail=False, methods=["get"])
    def leaderboard(self, request):
        p = request.query_params
        qs = self.filter(self.scope().filter(is_active=True), {"from": p.get("from"), "to": p.get("to")})
        limit = max(1, min(to_int(p.get("limit"), 10), 100))
        rows = (qs.values("recipient_id").annotate(kudos=Count("id"), points=Sum("points"))
                .order_by("-points", "-kudos")[:limit])
        emps = {e.id: e for e in EmployeeDT.objects.filter(id__in=[r["recipient_id"] for r in rows])}
        return ok("KUDOS_LEADERBOARD", "Leaderboard.", [
            {"rank": i, "employee": emp_brief(emps.get(r["recipient_id"]), request), "kudos": r["kudos"],
             "points": r["points"]} for i, r in enumerate(rows, 1)])

    @action(detail=False, methods=["get"])
    def badges(self, request):
        return ok("KUDOS_BADGES", "Badges.", BADGES)


# ===============================================================
# 5. EVENTS
# ===============================================================
class EventViewSet(CrudBase):
    """
    GET  /api/people/engagement/events/   ?phase=Upcoming|Ongoing|Completed|Cancelled ?event_type= ?from= ?to= ?search=
    POST /api/people/engagement/events/   json or multipart(banner_image): title, start_at, end_at?, event_type?, mode?,
                                          location?, meeting_link?, description?, capacity?, rsvp_required?,
                                          audience_type?, audience_ids?
    GET .../<id>/   PATCH|PUT|POST .../<id>/(update/)   DELETE|POST .../<id>/(delete/)
    POST .../<id>/cancel/ {reason?}   POST .../<id>/restore/   GET .../<id>/attendees/ ?response=GOING|MAYBE|DECLINED
    """
    model, code, parser_classes = CompanyEvent, "EVENT", PARSERS
    permission_action_map = {"cancel": "edit", "restore": "edit", "attendees": "view"}

    def filter(self, qs, p):
        if p.get("event_type"):
            qs = qs.filter(event_type=p["event_type"].upper())
        try:
            if p.get("from"):
                qs = qs.filter(start_at__date__gte=to_date(p["from"]))
            if p.get("to"):
                qs = qs.filter(start_at__date__lte=to_date(p["to"]))
        except ValueError:
            pass
        q = (p.get("search") or "").strip()
        return qs.filter(Q(title__icontains=q) | Q(location__icontains=q)) if q else qs

    def build(self, e):
        return event_row(e, self.request, getattr(self, "_c", {}).get(e.id))

    def list(self, request):
        p = request.query_params
        events = list(self.filter(self.scope().filter(is_active=True), p))
        now = timezone.now()
        want = (p.get("phase") or "").capitalize()
        allv = events
        if want:
            events = [e for e in events if event_phase(e, now) == want]
        events.sort(key=lambda e: e.start_at, reverse=(want in ("Completed", "")))
        rows, meta = paginate(request, events, lambda e: e)
        self._c = rsvp_counts([e.id for e in rows])
        summary = {}
        for e in allv:
            ph = event_phase(e, now)
            summary[ph] = summary.get(ph, 0) + 1
        return ok("EVENT_LIST", "List fetched.", [self.build(e) for e in rows], meta=meta, summary=summary)

    def retrieve(self, request, pk=None):
        e = self.scope().filter(pk=pk, is_active=True).first()
        if e is None:
            return err("NOT_FOUND", "Event not found.", 404)
        self._c = rsvp_counts([e.id])
        return ok("EVENT_DETAIL", "Detail fetched.", self.build(e))

    def apply(self, o, d, creating):
        if creating or "title" in d:
            if not str(d.get("title") or "").strip():
                raise ValueError("title is required.")
            o.title = str(d["title"]).strip()[:200]
        if creating or "start_at" in d:
            o.start_at = to_dt(d.get("start_at"))
            if o.start_at is None:
                raise ValueError("start_at is required (ISO datetime or YYYY-MM-DD).")
        if "end_at" in d:
            o.end_at = to_dt(d["end_at"])
        if o.end_at and o.end_at < o.start_at:
            raise ValueError("end_at cannot be before start_at.")
        if "event_type" in d:
            o.event_type = pick(d["event_type"], dict(CompanyEvent.TYPES), "event_type")
        if "mode" in d:
            o.mode = pick(d["mode"], dict(CompanyEvent.MODES), "mode")
        for f in ("description", "location", "meeting_link"):
            if f in d:
                setattr(o, f, d[f] or None)
        if o.mode in ("VIRTUAL",) and not o.meeting_link and ("mode" in d or creating):
            raise ValueError("meeting_link is required for a virtual event.")
        if "capacity" in d:
            cap = to_int(d["capacity"])
            if cap is not None and cap < 1:
                raise ValueError("capacity must be at least 1.")
            if cap is not None and o.pk:
                going = o.rsvps.filter(response="GOING", is_active=True).count()
                if cap < going:
                    raise ValueError(f"capacity cannot be lower than the {going} people already going.")
            o.capacity = cap
        if "rsvp_required" in d:
            o.rsvp_required = to_bool(d["rsvp_required"])
        parse_audience(self.company(), d, o)
        f = self.request.FILES.get("banner_image")
        if f is not None:
            check_image(f)
            o.banner_image = f
        elif to_bool(d.get("remove_banner")):
            o.banner_image = None
        if dup_check(CompanyEvent, o.company, o.pk, title__iexact=o.title, start_at=o.start_at):
            raise ValueError("An event with this title and start time already exists.")

    @action(detail=True, methods=["post"])
    def cancel(self, request, pk=None):
        e = self.scope().filter(pk=pk, is_active=True).first()
        if e is None:
            return err("NOT_FOUND", "Event not found.", 404)
        e.is_cancelled, e.cancel_reason, e.updated_by = True, request.data.get("reason") or None, self.actor()
        e.save()
        return ok("EVENT_CANCELLED", "Event cancelled.", self.build(e))

    @action(detail=True, methods=["post"])
    def restore(self, request, pk=None):
        e = self.scope().filter(pk=pk, is_active=True).first()
        if e is None:
            return err("NOT_FOUND", "Event not found.", 404)
        e.is_cancelled, e.cancel_reason, e.updated_by = False, None, self.actor()
        e.save()
        return ok("EVENT_RESTORED", "Event restored.", self.build(e))

    @action(detail=True, methods=["get"])
    def attendees(self, request, pk=None):
        e = self.scope().filter(pk=pk, is_active=True).first()
        if e is None:
            return err("NOT_FOUND", "Event not found.", 404)
        qs = e.rsvps.filter(is_active=True).select_related("employee").order_by("employee__name")
        if request.query_params.get("response"):
            qs = qs.filter(response=request.query_params["response"].upper())
        rows, meta = paginate(request, qs, lambda r: {"employee": emp_brief(r.employee), "response": r.response,
                                                      "responded_at": iso(r.updated_at)})
        return ok("EVENT_ATTENDEES", "Attendees.", rows, meta=meta, summary=rsvp_counts([e.id])[e.id])
