# ============================================================
# ADDITIVE: Enterprise Document Vault & Letters  (Admin / HR side)
#
#   /api/people/vault/                     overview: tab counts + 9 template cards  (Document Vault tab)
#   /api/people/vault/recipients/          employee / candidate picker for "Generate New Letter"
#   /api/people/letter-templates/          9 standard templates, company overrides   (Templates tab)
#   /api/people/generated-letters/         generated letters log + generate/preview   (Generated Letters tab)
#   /api/people/hr-documents/              HR manuals & SOPs                          (HR Documents tab)
#   /api/people/policies/                  company policies                           (Company Policies tab)
#   /api/people/documents/                 Employee Documents tab -> EXISTING views_documents.py
#
# Re-uses (no duplicates): EmployeeLetter + letters.py engine, EmployeeDocument + DocumentCheck,
# People.common envelope / CrudBase / permissions (Company Admin always, HR via role checkboxes).
# ============================================================
import os
from string import Formatter

from django.db.models import Count, Q
from django.http import FileResponse, Http404
from rest_framework.decorators import action
from rest_framework.parsers import FormParser, JSONParser, MultiPartParser
from rest_framework.viewsets import ViewSet

from Employee.models import EmployeeDocument, EmployeeDT
from Recruitment.common import candidate_by_ref, candidates_qs

from .common import (CrudBase, PeopleAuthMixin, emp_brief, emp_by_code, employees_qs, err, iso, ok, to_bool,
                     to_date)
from .letters import (BASE_PLACEHOLDERS, EXTRA_PLACEHOLDERS, TEMPLATES, _Safe, build_variables, issue_letter,
                      resolve_template)
from .models import (CompanyPolicy, DocumentCheck, EmployeeLetter, HRDocument, LetterTemplate)
from .views_letters import LetterViewSet, letter_row

# ---------------------------------------------------------------
# the 9 standard enterprise letterhead templates (screen cards)
# ---------------------------------------------------------------
CARDS = [
    ("OFFER", "Official Offer Letter", "Pre-joining employment offer with detailed CTC annexure and terms"),
    ("APPOINTMENT", "Letter of Appointment", "Formal contract issued on Day 1 of joining with role description"),
    ("CONFIRMATION", "Probation Confirmation Letter", "Issued upon successful 6-month probation completion"),
    ("COMPENSATION_REVISION", "Annual Compensation Revision Letter",
     "Annual increment and performance bonus notification"),
    ("PROMOTION", "Promotion & Title Change Letter", "Grade advancement, new responsibilities, and revised compensation"),
    ("TRANSFER", "Internal Transfer Letter", "Relocation to new branch or strategic department handover"),
    ("DISCIPLINARY_WARNING", "Formal Disciplinary Warning Letter",
     "Official HR caution regarding attendance or policy breaches"),
    ("EXPERIENCE_CERTIFICATE", "Certificate of Experience", "Certified tenure, designation, and conduct letter on exit"),
    ("RELIEVING_EXPERIENCE", "Formal Relieving Letter",
     "Issued on last working day after 100% departmental clearance and F&F"),
]
CARD_MAP = {c[0]: c for c in CARDS}

# ---------------------------------------------------------------
# file helpers (policies / HR documents)
# ---------------------------------------------------------------
ALLOWED_EXT = {".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".txt", ".png", ".jpg", ".jpeg"}
MAX_UPLOAD_MB = 10


def check_upload(f):
    ext = os.path.splitext(f.name)[1].lower()
    if ext not in ALLOWED_EXT:
        raise ValueError("Unsupported file type. Allowed: " + ", ".join(sorted(ALLOWED_EXT)))
    if f.size > MAX_UPLOAD_MB * 1024 * 1024:
        raise ValueError(f"File too large (max {MAX_UPLOAD_MB} MB).")


def file_url(request, f):
    if not f:
        return None
    try:
        return request.build_absolute_uri(f.url) if request else f.url
    except Exception:
        return None


def file_name(f):
    return os.path.basename(f.name) if f else None


def send_file(f, download_name=None, inline=False):
    if not f:
        raise Http404("File not found.")
    try:
        fh = f.open("rb")
    except (FileNotFoundError, ValueError, OSError):
        raise Http404("File not found.")
    return FileResponse(fh, as_attachment=not inline, filename=download_name or file_name(f))


def actor_name(company, label):
    """'admin:C8829CD0' -> 'Company Admin';  'employee:EMP-0001' -> employee name."""
    if not label:
        return None
    if label.startswith("employee:"):
        name = (EmployeeDT.objects.filter(company=company, employee_code=label.split(":", 1)[1])
                .values_list("name", flat=True).first())
        return name or label
    if label.startswith("admin:"):
        return "Company Admin"
    return label


def placeholders_for(code):
    return BASE_PLACEHOLDERS + [p for p in EXTRA_PLACEHOLDERS.get(code, []) if p not in BASE_PLACEHOLDERS]


def unknown_placeholders(code, text):
    allowed = set(placeholders_for(code))
    found = {f for _, f, _, _ in Formatter().parse(text or "") if f}
    return sorted(found - allowed)


def check_template_text(code, subject, body):
    """Reject broken { } syntax; return a list of unknown placeholders (non-blocking warning)."""
    sample = _Safe({p: "x" for p in placeholders_for(code)})
    for label, txt in (("subject", subject), ("body", body)):
        try:
            (txt or "").format_map(sample)
        except (ValueError, IndexError, KeyError, AttributeError) as ex:
            raise ValueError(f"Template {label} has invalid {{placeholder}} syntax: {ex}")
    return sorted(set(unknown_placeholders(code, subject)) | set(unknown_placeholders(code, body)))


# ---------------------------------------------------------------
# Document Vault overview + recipient picker
# ---------------------------------------------------------------
class VaultViewSet(PeopleAuthMixin, ViewSet):
    """
    GET /api/people/vault/                           tabs with counts + 9 template cards
    GET /api/people/vault/recipients/?search=&letter_type=&limit=   pick employee (or candidate for OFFER)
    """
    lookup_value_regex = r"[^/]+"

    def list(self, request):
        company = self.company()
        docs = EmployeeDocument.objects.filter(company=company, is_active=True)
        rejected = DocumentCheck.objects.filter(document__in=docs, status="Rejected").count()
        verified = docs.filter(is_verified=True).count()
        n_docs, n_hr = docs.count(), HRDocument.objects.filter(company=company, is_active=True).count()
        n_pol = CompanyPolicy.objects.filter(company=company, is_active=True).count()
        letters = EmployeeLetter.objects.filter(company=company, is_active=True)
        custom = set(LetterTemplate.objects.filter(company=company, is_active=True).values_list("code", flat=True))
        issued = dict(letters.values_list("letter_type").annotate(n=Count("id")))
        cards = [{"code": c, "title": t, "description": d, "customised": c in custom,
                  "issued_count": issued.get(c, 0)} for c, t, d in CARDS]
        tabs = [
            {"key": "vault", "label": "Document Vault", "count": len(CARDS)},
            {"key": "employee_documents", "label": "Employee Documents", "count": n_docs},
            {"key": "hr_documents", "label": "HR Documents", "count": n_hr},
            {"key": "company_policies", "label": "Company Policies", "count": n_pol},
            {"key": "templates", "label": "Templates", "count": len(CARDS)},
            {"key": "generated_letters", "label": "Generated Letters", "count": letters.count()},
        ]
        return ok("VAULT_OVERVIEW", "Enterprise Document Vault & Letters.", {
            "title": "Enterprise Document Vault & Letters",
            "subtitle": "Company policies, templates, generated letters, and employee compliance files",
            "tabs": tabs, "templates_heading": f"{len(CARDS)} Standard Enterprise Letterhead Templates",
            "templates": cards,
            "stats": {"employee_documents": n_docs, "verified_documents": verified,
                      "rejected_documents": rejected, "pending_documents": max(n_docs - verified - rejected, 0),
                      "hr_documents": n_hr, "policies": n_pol, "generated_letters": letters.count(),
                      "customised_templates": len(custom)}})

    @action(detail=False, methods=["get"])
    def recipients(self, request):
        company, p = self.company(), request.query_params
        q = (p.get("search") or "").strip()
        lt = (p.get("letter_type") or "").upper()
        try:
            limit = max(1, min(int(p.get("limit", 20)), 100))
        except ValueError:
            limit = 20
        emps = employees_qs(company).filter(is_active=True)
        if q:
            emps = emps.filter(Q(name__icontains=q) | Q(employee_code__icontains=q))
        rows = [{"kind": "employee", "ref": e.employee_code, "name": e.name, "email": e.email,
                 "designation": e.Designation} for e in emps.order_by("name")[:limit]]
        if lt == "OFFER":
            cands = candidates_qs(company)
            if q:
                cands = cands.filter(Q(name__icontains=q) | Q(candidate_id__icontains=q))
            rows += [{"kind": "candidate", "ref": c.candidate_id, "name": c.name, "email": c.email,
                      "designation": c.applied_position} for c in cands.order_by("name")[:limit]]
        return ok("VAULT_RECIPIENTS", "Recipients.", rows)


# ---------------------------------------------------------------
# Templates tab  /api/people/letter-templates/<CODE>/
# ---------------------------------------------------------------
class LetterTemplateViewSet(PeopleAuthMixin, ViewSet):
    """
    GET    /api/people/letter-templates/             the 9 cards (default or company-customised text)
    GET    /api/people/letter-templates/<CODE>/      full subject/body + default text + placeholders
    POST   /api/people/letter-templates/             {code, subject?, body}      create / customise (upsert)
    PUT|PATCH|POST .../<CODE>/(update/)              {subject?, body?}           edit
    DELETE|POST    .../<CODE>/(delete/)              reset to the built-in default
    """
    lookup_value_regex = r"[A-Za-z_]+"

    def _row(self, code, override=None, issued=0, detail=False):
        _, title, desc = CARD_MAP[code]
        d_subject, d_body = TEMPLATES[code]
        subject, body = (override.subject or d_subject, override.body) if override else (d_subject, d_body)
        row = {"code": code, "title": title, "description": desc, "customised": override is not None,
               "id": override.id if override else None, "issued_count": issued,
               "subject": subject, "updated_at": iso(override.updated_at) if override else None,
               "updated_by": override.updated_by if override else None}
        if detail:
            row.update(body=body, default_subject=d_subject, default_body=d_body,
                       placeholders=placeholders_for(code))
        return row

    def _code(self, pk):
        code = (pk or "").upper()
        return code if code in CARD_MAP else None

    def _override(self, code):
        return LetterTemplate.objects.filter(company=self.company(), code=code, is_active=True).first()

    def list(self, request):
        company = self.company()
        over = {t.code: t for t in LetterTemplate.objects.filter(company=company, is_active=True)}
        issued = dict(EmployeeLetter.objects.filter(company=company, is_active=True)
                      .values_list("letter_type").annotate(n=Count("id")))
        q = (request.query_params.get("search") or "").strip().lower()
        rows = [self._row(c, over.get(c), issued.get(c, 0)) for c, _, _ in CARDS]
        if q:
            rows = [r for r in rows if q in r["title"].lower() or q in r["description"].lower()]
        return ok("TEMPLATE_LIST", f"{len(rows)} standard enterprise letterhead templates.", rows)

    def retrieve(self, request, pk=None):
        code = self._code(pk)
        if code is None:
            return err("NOT_FOUND", "Unknown template code. Allowed: " + ", ".join(CARD_MAP), 404)
        n = EmployeeLetter.objects.filter(company=self.company(), letter_type=code, is_active=True).count()
        return ok("TEMPLATE_DETAIL", "Template.", self._row(code, self._override(code), n, detail=True))

    def _save(self, request, code, creating):
        d = request.data
        t = self._override(code)
        d_subject, d_body = TEMPLATES[code]
        if t is None:
            t = LetterTemplate.objects.filter(company=self.company(), code=code).first()   # soft-deleted row
            if t is None:
                t = LetterTemplate(company=self.company(), code=code, created_by=self.actor())
            t.is_active = True
            t.subject, t.body = d_subject, d_body
        subject = d["subject"] if "subject" in d else t.subject
        body = d["body"] if "body" in d else t.body
        if not str(body or "").strip():
            raise ValueError("body is required.")
        warnings = check_template_text(code, subject, body)
        t.subject, t.body, t.updated_by = subject, body, self.actor()
        t.save()
        return t, warnings

    def create(self, request):
        code = self._code(request.data.get("code"))
        if code is None:
            return err("VALIDATION", "code is required. Allowed: " + ", ".join(CARD_MAP))
        try:
            t, warnings = self._save(request, code, True)
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        return ok("TEMPLATE_SAVED", "Template saved.", self._row(code, t, detail=True), 201, warnings=warnings)

    def partial_update(self, request, pk=None):
        code = self._code(pk)
        if code is None:
            return err("NOT_FOUND", "Unknown template code.", 404)
        try:
            t, warnings = self._save(request, code, False)
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        return ok("TEMPLATE_UPDATED", "Template updated.", self._row(code, t, detail=True), warnings=warnings)

    update = partial_update

    def destroy(self, request, pk=None):
        code = self._code(pk)
        if code is None:
            return err("NOT_FOUND", "Unknown template code.", 404)
        t = self._override(code)
        if t is None:
            return err("NOT_FOUND", "Template is already the built-in default.", 404)
        t.is_active, t.updated_by = False, self.actor()
        t.save()
        return ok("TEMPLATE_RESET", "Template reset to the built-in default.", self._row(code, None, detail=True))


# ---------------------------------------------------------------
# Generated Letters tab  /api/people/generated-letters/
# (extends the EXISTING LetterViewSet: same CRUD / revoke / download, + candidates for OFFER, 9 types)
# ---------------------------------------------------------------
def offer_defaults(c):
    """Pre-fill an offer letter from the candidate row and the latest Recruitment.Offer."""
    v = {"employee_code": c.candidate_id or c.employee_code}
    if getattr(c, "applied_position", None):
        v["designation"] = c.applied_position
    if getattr(c, "expected_joining_date", None):
        v["joining_date"] = c.expected_joining_date
    try:
        offer = c.offers.order_by("-id").first()
    except Exception:
        offer = None
    if offer is not None:
        if offer.designation:
            v["designation"] = offer.designation
        if offer.target_joining_date:
            v["joining_date"] = offer.target_joining_date
        if offer.valid_until:
            v["offer_valid_until"] = offer.valid_until
        if offer.offered_ctc_lpa is not None:
            v["ctc_annual"] = f"{offer.offered_ctc_lpa * 100000:,.0f}"
    return v


class GeneratedLetterViewSet(LetterViewSet):
    """
    GET  /api/people/generated-letters/                 ?letter_type= ?status= ?search= ?from=YYYY-MM-DD ?to= ?page=
    GET  /api/people/generated-letters/types/           the 9 templates
    POST /api/people/generated-letters/generate/        {recipient_code (EMP code, or CAN code for OFFER), letter_type,
                                                         variables?{}, subject?, body?}
    POST /api/people/generated-letters/preview/         same payload, nothing saved
    GET  /api/people/generated-letters/<id>/            detail incl. body
    GET  /api/people/generated-letters/<id>/pdf/        inline PDF  ("View / Print")
    GET  /api/people/generated-letters/<id>/download/   PDF attachment
    PUT|PATCH|POST /<id>/(update/)                      {subject?, body?}  re-renders the PDF
    POST /api/people/generated-letters/<id>/revoke/
    DELETE|POST /<id>/(delete/)
    """
    code = "GENERATED_LETTER"
    search_fields = ("letter_no", "subject", "employee__name", "employee__employee_code", "employee__candidate_id")

    # ---- row ----
    def build(self, l):
        row = letter_row(l, self.request)
        e = l.employee
        is_offer = l.letter_type == "OFFER"
        ref = (e.candidate_id if is_offer and e.candidate_id else e.employee_code)
        names = getattr(self, "_names", None)
        if names is None:
            names = self._names = {}
        if l.issued_by not in names:
            names[l.issued_by] = actor_name(l.company, l.issued_by)
        row.update(letter_ref=l.letter_no, generated_date=iso(l.issued_on), dispatched_by=l.issued_by,
                   dispatched_by_name=names[l.issued_by],
                   recipient={"name": e.name, "ref": ref, "label": f"{e.name} ({ref})",
                              "kind": "candidate" if is_offer else "employee"},
                   view_url=f"/api/people/generated-letters/{l.id}/pdf/",
                   download_url=f"/api/people/generated-letters/{l.id}/download/")
        return row

    # ---- list ----
    def filter(self, qs, p):
        qs = super().filter(qs, p)
        try:
            if p.get("from"):
                qs = qs.filter(issued_on__gte=to_date(p["from"]))
            if p.get("to"):
                qs = qs.filter(issued_on__lte=to_date(p["to"]))
        except ValueError:
            pass
        return qs

    def list(self, request):
        resp = super().list(request)
        base = self.scope().filter(is_active=True)
        resp.data["summary"] = {
            "total": base.count(),
            "by_type": {c: n for c, n in base.values_list("letter_type").annotate(n=Count("id"))},
            "by_status": {s: n for s, n in base.values_list("status").annotate(n=Count("id"))}}
        return resp

    def retrieve(self, request, pk=None):          # hide soft-deleted letters
        l = self.scope().filter(pk=pk, is_active=True).first()
        if l is None:
            return err("NOT_FOUND", "Letter not found.", 404)
        return ok("LETTER_DETAIL", "Letter.", self.build(l) | {"body": l.body, "variables": l.variables})

    @action(detail=False, methods=["get"])
    def types(self, request):
        company = self.company()
        custom = set(LetterTemplate.objects.filter(company=company, is_active=True).values_list("code", flat=True))
        issued = dict(self.scope().filter(is_active=True).values_list("letter_type").annotate(n=Count("id")))
        return ok("LETTER_TYPES", "Letter types.", [
            {"code": c, "title": t, "description": d, "default_subject": resolve_template(company, c)[0],
             "customised": c in custom, "issued_count": issued.get(c, 0), "placeholders": placeholders_for(c)}
            for c, t, d in CARDS])

    # ---- generate / preview ----
    def _prepare(self, d):
        company = self.company()
        lt = (d.get("letter_type") or "").upper()
        if lt not in TEMPLATES:
            raise ValueError(f"Invalid letter_type. Allowed: {', '.join(CARD_MAP)}")
        ref = d.get("recipient_code") or d.get("employee_code") or d.get("candidate_id")
        try:
            emp = emp_by_code(company, ref)
        except ValueError:
            emp = candidate_by_ref(company, ref) if lt == "OFFER" else None
            if emp is None:
                raise
        extra = offer_defaults(emp) if lt == "OFFER" else {}
        if isinstance(d.get("variables"), dict):
            extra.update(d["variables"])
        return emp, lt, extra

    @action(detail=False, methods=["post"])
    def generate(self, request):
        d = request.data
        try:
            emp, lt, extra = self._prepare(d)
            l = issue_letter(self.company(), emp, lt, self.actor(), extra, d.get("subject"), d.get("body"))
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        return ok("LETTER_ISSUED", "Letter generated.", self.build(l) | {"body": l.body, "variables": l.variables},
                  201)

    @action(detail=False, methods=["post"])
    def preview(self, request):
        d = request.data
        try:
            emp, lt, extra = self._prepare(d)
        except ValueError as ex:
            return err("VALIDATION", str(ex))
        v = build_variables(emp, extra)
        s, b = resolve_template(self.company(), lt)
        return ok("LETTER_PREVIEW", "Letter preview (not saved).", {
            "subject": (d.get("subject") or s).format_map(_Safe(v)),
            "body": (d.get("body") or b).format_map(_Safe(v)), "variables": {k: str(x) for k, x in v.items()}})

    @action(detail=True, methods=["get"])
    def pdf(self, request, pk=None):
        l = self.scope().filter(pk=pk, is_active=True).first()
        if l is None or not l.pdf_file:
            raise Http404("Letter PDF not found.")
        return send_file(l.pdf_file, f"{l.letter_no}.pdf", inline=True)


# ---------------------------------------------------------------
# shared base for file-backed master records (policies / HR documents)
# ---------------------------------------------------------------
class FileRecordBase(CrudBase):
    parser_classes = [JSONParser, MultiPartParser, FormParser]
    status_field = None
    dup_label = "record"

    def file_fields(self, obj):
        return {"file_url": file_url(self.request, obj.file), "file_name": file_name(obj.file),
                "download_url": f"{self.download_prefix}{obj.id}/download/" if obj.file else None}

    def filter(self, qs, p):
        q = (p.get("search") or "").strip()
        return qs.filter(Q(title__icontains=q) | Q(description__icontains=q)) if q else qs

    def attach_file(self, obj, d):
        f = self.request.FILES.get("file")
        if f is not None:
            check_upload(f)
            obj.file = f
        elif to_bool(d.get("remove_file")):
            obj.file = None

    def check_duplicate(self, obj):
        dup = (self.model.objects.filter(company=obj.company, is_active=True, title__iexact=obj.title.strip(),
                                         version=obj.version).exclude(pk=obj.pk))
        if dup.exists():
            raise ValueError(f"A {self.dup_label} titled '{obj.title}' with version {obj.version} already exists. "
                             "Change the version or update the existing record.")

    @action(detail=True, methods=["get"])
    def download(self, request, pk=None):
        o = self.scope().filter(pk=pk, is_active=True).first()
        if o is None or not o.file:
            raise Http404("File not found.")
        return send_file(o.file)


class PolicyViewSet(FileRecordBase):
    """
    GET  /api/people/policies/                 ?search= ?mandatory=true
    POST /api/people/policies/                 multipart/json: title, version?, effective_date?, is_mandatory?,
                                               compliance_note?, description?, file?
    GET  /api/people/policies/<id>/
    GET  /api/people/policies/<id>/download/
    PUT|PATCH|POST /<id>/(update/)             same fields (+ remove_file=true)
    DELETE|POST    /<id>/(delete/)
    """
    model = CompanyPolicy
    code = "POLICY"
    dup_label = "policy"
    download_prefix = "/api/people/policies/"

    def build(self, o):
        ver = f"Version {o.version}"
        sub = ver + (f" • Effective: {o.effective_date.strftime('%d %b %Y')}" if o.effective_date else "")
        if o.is_mandatory:
            sub += f" • {o.compliance_note or 'Mandatory Compliance'}"
        return {"id": o.id, "title": o.title, "version": o.version, "effective_date": iso(o.effective_date),
                "is_mandatory": o.is_mandatory, "compliance_note": o.compliance_note,
                "description": o.description, "subtitle": sub, "created_at": iso(o.created_at),
                "updated_at": iso(o.updated_at), **self.file_fields(o)}

    def filter(self, qs, p):
        qs = super().filter(qs, p)
        return qs.filter(is_mandatory=to_bool(p["mandatory"])) if p.get("mandatory") else qs

    def apply(self, o, d, creating):
        if "title" in d or creating:
            if not str(d.get("title") or "").strip():
                raise ValueError("title is required.")
            o.title = str(d["title"]).strip()
        if "version" in d:
            o.version = str(d["version"]).strip() or "1.0"
        if "effective_date" in d:
            o.effective_date = to_date(d["effective_date"])
        if "is_mandatory" in d:
            o.is_mandatory = to_bool(d["is_mandatory"])
        if "compliance_note" in d:
            o.compliance_note = d["compliance_note"] or None
        if "description" in d:
            o.description = d["description"]
        self.attach_file(o, d)
        self.check_duplicate(o)


class HRDocumentViewSet(FileRecordBase):
    """
    GET  /api/people/hr-documents/             ?category=SOP|MANUAL|FORM|OTHER ?search=
    POST /api/people/hr-documents/             multipart/json: title, category?, version?, description?, file?
    GET  /api/people/hr-documents/<id>/
    GET  /api/people/hr-documents/<id>/download/
    PUT|PATCH|POST /<id>/(update/)             same fields (+ remove_file=true)
    DELETE|POST    /<id>/(delete/)
    """
    model = HRDocument
    code = "HR_DOCUMENT"
    dup_label = "HR document"
    download_prefix = "/api/people/hr-documents/"
    status_field = "category"

    def build(self, o):
        return {"id": o.id, "title": o.title, "category": o.category,
                "category_label": dict(HRDocument.CATEGORY).get(o.category), "version": o.version,
                "description": o.description, "uploaded_by": o.uploaded_by,
                "uploaded_by_name": actor_name(o.company, o.uploaded_by), "created_at": iso(o.created_at),
                "updated_at": iso(o.updated_at), **self.file_fields(o)}

    def filter(self, qs, p):
        qs = super().filter(qs, p)
        cat = (p.get("category") or "").upper()
        return qs.filter(category=cat) if cat else qs

    def apply(self, o, d, creating):
        if "title" in d or creating:
            if not str(d.get("title") or "").strip():
                raise ValueError("title is required.")
            o.title = str(d["title"]).strip()
        if "category" in d:
            cat = str(d["category"]).upper()
            if cat not in dict(HRDocument.CATEGORY):
                raise ValueError("Invalid category. Allowed: " + ", ".join(dict(HRDocument.CATEGORY)))
            o.category = cat
        if "version" in d:
            o.version = str(d["version"]).strip() or "1.0"
        if "description" in d:
            o.description = d["description"]
        if creating:
            o.uploaded_by = self.actor()
        self.attach_file(o, d)
        self.check_duplicate(o)
 
 

# ---- ADDITIVE: letters now carry layout markup; resolve [[if ...]] lines and offer a plain-text version
def _letter_body(template, v):
    from .letter_data import format_body
    return format_body(template, v)


def _letter_plain(template, v):
    from .letter_format import plain_text
    return plain_text(_letter_body(template, v))
    
 
 