"""
Generate the FCC CPNI Annual Certification Letter — CLEC (Facilities) variant.

Tailors the generic CPNI certification under 47 CFR § 64.2009(e) for a
Competitive Local Exchange Carrier operating its own TDM / SS7 switching
plant.  Customer authorization for CPNI is obtained through traditional
written / oral opt-in methods; the CPNI Protection Officer's scope of
oversight explicitly includes SS7 / SIGTRAN intercept provisioning and
PIC / LIDB record handling.

2026 amendments included:
    * Maximum forfeiture $251,322 per violation (capped $2,513,215).
    * 47 CFR § 1.17 truthfulness representation.
    * Title 18 penalty acknowledgment.
    * Explicit "has / has not" language for customer complaints + data
      broker inquiries (Report & Order FCC-25-XXX).
    * Officer statement of personal knowledge.
    * Narrative "how procedures ensure compliance" section.

Usage:
    from scripts.document_gen.templates.cpni_clec_generator import (
        generate_cpni_clec,
    )
    path = generate_cpni_clec(
        output_path="/tmp/cpni_clec.docx",
        entity_name="Acme Telco LLC",
        frn="0027160886",
        filer_id_499="812345",
        officer_name="Jane Doe",
        officer_title="CEO",
        reporting_year=2025,
    )
"""
from __future__ import annotations

import logging
from datetime import datetime
from pathlib import Path
from typing import Optional

LOG = logging.getLogger("document_gen.cpni_clec")

try:
    from docx import Document
    from docx.shared import Pt, Inches, RGBColor
    from docx.enum.text import WD_ALIGN_PARAGRAPH
    from docx.oxml.ns import qn
except ImportError:
    LOG.warning("python-docx not installed — CPNI CLEC generation unavailable")
    Document = None  # type: ignore[assignment,misc]

_NAVY = RGBColor(0x1A, 0x27, 0x44) if Document else None

VARIANT_ID = "clec"
VARIANT_LABEL = "Competitive Local Exchange Carrier (CLEC)"

MAX_FORFEITURE_PER_VIOLATION = "$251,322"
MAX_FORFEITURE_CAP = "$2,513,215"


def _set_spacing(paragraph, after_pt=6, before_pt=0):
    pf = paragraph.paragraph_format
    pf.space_after = Pt(after_pt)
    if before_pt:
        pf.space_before = Pt(before_pt)


def _heading(doc, text: str) -> None:
    p = doc.add_paragraph()
    run = p.add_run(text)
    run.font.size = Pt(12)
    run.bold = True
    run.font.color.rgb = _NAVY
    _set_spacing(p, after_pt=4, before_pt=8)


def _body(doc, text: str, bold: bool = False, size: int = 10) -> None:
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.LEFT
    run = p.add_run(text)
    run.font.size = Pt(size)
    run.bold = bold
    _set_spacing(p, after_pt=6)


def _checkbox(doc, label: str, checked: bool = True) -> None:
    mark = "\u2611" if checked else "\u2610"
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.LEFT
    run = p.add_run(f"  {mark}  {label}")
    run.font.size = Pt(10)
    _set_spacing(p, after_pt=3)


def _spacer(doc) -> None:
    p = doc.add_paragraph()
    _set_spacing(p, after_pt=0)


def generate_cpni_clec(
    output_path: str,
    entity_name: str,
    frn: str = "",
    filer_id_499: str = "",
    officer_name: str = "",
    officer_title: str = "Chief Executive Officer",
    complaints_count: int = 0,
    complaints_description: str = "",
    has_data_broker_inquiries: bool = False,
    data_broker_description: str = "",
    reporting_year: int = 0,
    address_street: str = "",
    address_city: str = "",
    address_state: str = "",
    address_zip: str = "",
    contact_email: str = "",
    contact_phone: str = "",
    breaches: list[dict] | None = None,
    **_: dict,
) -> Optional[str]:
    """Generate the CLEC (facilities) CPNI Annual Certification Letter."""
    if Document is None:
        LOG.error("python-docx not installed")
        return None

    if reporting_year == 0:
        reporting_year = datetime.now().year - 1
    breaches = breaches or []

    doc = Document()
    for section in doc.sections:
        section.top_margin = Inches(1)
        section.bottom_margin = Inches(1)
        section.left_margin = Inches(1.25)
        section.right_margin = Inches(1.25)

    today = datetime.now().strftime("%B %d, %Y")
    signer = officer_name or "Authorized Officer"
    title = officer_title or "Officer"

    # ── Title ────────────────────────────────────────────────────────
    title_p = doc.add_paragraph()
    title_p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    tr = title_p.add_run("CPNI Annual Certification Letter")
    tr.font.size = Pt(14)
    tr.bold = True
    tr.font.color.rgb = _NAVY
    _set_spacing(title_p, after_pt=2)

    sub_p = doc.add_paragraph()
    sub_p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    sub = sub_p.add_run(
        f"Competitive Local Exchange Carrier  \u2014  "
        f"47 CFR \u00a7 64.2009  \u2014  Calendar Year {reporting_year}"
    )
    sub.font.size = Pt(10)
    sub.font.color.rgb = RGBColor(0x55, 0x55, 0x55)
    _set_spacing(sub_p, after_pt=8)

    # ── 1. Provider Information ──────────────────────────────────────
    _heading(doc, "1. Provider Information")
    lines = [f"Company Name: {entity_name}", f"Variant: {VARIANT_LABEL}"]
    if frn:
        lines.append(f"FCC Registration Number (FRN): {frn}")
    if filer_id_499:
        lines.append(f"FCC Form 499 Filer ID: {filer_id_499}")
    addr = ", ".join(filter(None, [address_street, address_city]))
    if address_state or address_zip:
        addr += f", {address_state} {address_zip}".strip()
    if addr.strip(", "):
        lines.append(f"Address: {addr.strip(', ')}")
    if contact_phone:
        lines.append(f"Telephone: {contact_phone}")
    if contact_email:
        lines.append(f"Email: {contact_email}")
    lines.append(f"Certifying Officer: {signer}, {title}")
    lines.append(f"Date of Filing: {today}")
    lines.append(f"Filing Deadline: March 2, {reporting_year + 1}")
    _body(doc, "\n".join(lines))

    # ── 2. Officer Statement of Personal Knowledge ───────────────────
    _heading(doc, "2. Officer Statement of Personal Knowledge")
    _body(doc, (
        f"I, {signer}, {title} of {entity_name}, state that I have personal "
        f"knowledge of the matters certified herein. I have reviewed "
        f"{entity_name}'s CPNI operating procedures, interviewed personnel "
        f"responsible for CPNI handling, and examined supervisory logs and "
        f"records covering the reporting period. The representations set "
        f"forth in this certification are based on my personal review and "
        f"are true and correct to the best of my knowledge, information, "
        f"and belief."
    ))

    # ── 3. Certification of Compliance ───────────────────────────────
    _heading(doc, "3. Certification of Compliance")
    _body(doc, (
        f"Pursuant to 47 CFR \u00a7 64.2009(e), {entity_name} hereby submits "
        f"its annual certification of compliance with the Customer Proprietary "
        f"Network Information (CPNI) rules at 47 CFR \u00a7\u00a7 64.2001 "
        f"through 64.2011 for the period January 1, {reporting_year} through "
        f"December 31, {reporting_year}. {entity_name} has established, "
        f"maintained, and adhered to operating procedures that ensure "
        f"compliance with these rules."
    ))

    # ── 4. How Procedures Ensure Compliance (narrative) ──────────────
    _heading(doc, "4. How Our Procedures Ensure Compliance")
    _body(doc, (
        f"As a competitive local exchange carrier operating on circuit-switched "
        f"(TDM) switching platforms with SS7 / SIGTRAN signaling, {entity_name} "
        f"protects CPNI throughout the complete life-cycle of a customer "
        f"relationship.  Specific procedures include:"
    ))
    _checkbox(doc, (
        "Customer authentication is required before any CPNI disclosure in "
        "response to a customer-initiated contact. Authentication is by "
        "pre-established password or, for in-store visits, a photo ID plus "
        "verification of two account attributes that are not CPNI "
        "(47 CFR \u00a7 64.2010)."
    ))
    _checkbox(doc, (
        "Customer approval for use of CPNI beyond the scope of the "
        "subscribed service is obtained through traditional written or oral "
        "opt-in consent, documented in the customer record per 47 CFR "
        "\u00a7 64.2007 and \u00a7 64.2008. Oral approvals are date-stamped "
        "and time-stamped with the agent's identity."
    ))
    _checkbox(doc, (
        "The CPNI Protection Officer's oversight scope expressly includes "
        "SS7 / SIGTRAN intercept provisioning, LIDB access, PIC-change "
        "verification, and wholesale handoff logs, ensuring that network-"
        "element CPNI (e.g., originating-number records, call-path signaling) "
        "is governed by the same safeguards as customer-facing systems."
    ))
    _checkbox(doc, (
        "PIC and account changes trigger customer notification to the "
        "address of record before taking effect, per 47 CFR \u00a7 64.2010(f)."
    ))
    _checkbox(doc, (
        "All access to CPNI-bearing systems is logged, with supervisory "
        "review at least quarterly. Retention of access logs meets or "
        "exceeds two years (CPNI) and five years (certification records) "
        "per 47 CFR \u00a7 64.2009."
    ))
    _checkbox(doc, (
        "Annual CPNI training is required for all personnel with CPNI "
        "access. Completion is tracked and attested to by the CPNI Protection "
        "Officer. Disciplinary procedures are documented and applied to any "
        "violation."
    ))
    _checkbox(doc, (
        "Breach notification under 47 CFR \u00a7 64.2011 is implemented as "
        "amended by FCC 23-111 \u2014 notice to the Commission within 7 "
        "business days and to customers / law enforcement as soon as "
        "practicable, not later than 30 days after reasonable determination."
    ))

    # ── 5. Customer Complaints (has / has not) ───────────────────────
    _heading(doc, "5. Customer Complaints")
    if complaints_count == 0:
        _body(doc, (
            f"{entity_name} has NOT received any customer complaints during "
            f"the reporting period concerning the unauthorized release or "
            f"use of CPNI. Zero (0) complaints were logged."
        ))
    else:
        desc = complaints_description or (
            "Each complaint was investigated and resolved in accordance with "
            "the company's CPNI compliance procedures."
        )
        _body(doc, (
            f"{entity_name} HAS received {complaints_count} customer "
            f"complaint{'s' if complaints_count != 1 else ''} during the "
            f"reporting period concerning the unauthorized release or use "
            f"of CPNI. {desc}"
        ))

    # ── 6. Data Broker Inquiries (has / has not) ─────────────────────
    _heading(doc, "6. Data Broker Inquiries and Pretexting")
    if not has_data_broker_inquiries:
        _body(doc, (
            f"{entity_name} has NOT received any inquiries, communications, "
            f"or attempts by data brokers or other unauthorized parties "
            f"seeking the unauthorized release of CPNI during the reporting "
            f"period."
        ))
    else:
        desc = data_broker_description or (
            "Each such inquiry was refused, documented, and escalated to "
            "the CPNI Protection Officer."
        )
        _body(doc, (
            f"{entity_name} HAS received data broker or pretexting-style "
            f"inquiries during the reporting period. {desc}"
        ))

    # ── 7. Breach Log Summary ────────────────────────────────────────
    _heading(doc, "7. Breach Log Summary")
    if not breaches:
        _body(doc, (
            f"{entity_name} experienced no CPNI breaches during the "
            f"reporting period. No 47 CFR \u00a7 64.2011 notifications were "
            f"required."
        ))
    else:
        _body(doc, (
            f"{entity_name} experienced {len(breaches)} CPNI breach"
            f"{'es' if len(breaches) != 1 else ''} during the reporting "
            f"period.  Each was reported to the Commission via the CPNI "
            f"Breach Reporting Portal within 7 business days."
        ))

    # ── 8. Penalties and Truthfulness ────────────────────────────────
    _heading(doc, "8. Penalties, Truthfulness, and Perjury Acknowledgment")
    _body(doc, (
        f"{entity_name} and the undersigned officer acknowledge that "
        f"violations of the CPNI rules may subject the carrier to monetary "
        f"forfeitures of up to {MAX_FORFEITURE_PER_VIOLATION} per violation "
        f"and up to {MAX_FORFEITURE_CAP} for any single act or failure to "
        f"act (adjusted for inflation per 47 CFR \u00a7 1.80)."
    ))
    _body(doc, (
        f"Pursuant to 47 CFR \u00a7 1.17, the undersigned represents that "
        f"no material factual information has been withheld from the "
        f"Commission and that all statements herein are truthful, accurate, "
        f"and complete to the best of the undersigned's knowledge and "
        f"belief, and are not intended to mislead the Commission."
    ))
    _body(doc, (
        f"The undersigned further acknowledges that willful false statements "
        f"made in this certification are punishable by fine and/or "
        f"imprisonment under Title 18, U.S.C. \u00a7 1001, and/or by "
        f"forfeiture under 47 U.S.C. \u00a7 503."
    ))

    # ── 9. Signature ─────────────────────────────────────────────────
    _heading(doc, "9. Signature of Certifying Officer")
    _body(doc, (
        f"I declare under penalty of perjury under the laws of the "
        f"United States of America that the foregoing is true and correct."
    ))
    _spacer(doc)

    sig = doc.add_paragraph()
    sig.add_run("_" * 45).font.size = Pt(10)
    _set_spacing(sig, after_pt=2)

    nm = doc.add_paragraph()
    nr = nm.add_run(signer)
    nr.bold = True
    nr.font.size = Pt(10)
    _set_spacing(nm, after_pt=2)

    tp = doc.add_paragraph()
    tp.add_run(f"{title}, {entity_name}").font.size = Pt(10)
    _set_spacing(tp, after_pt=2)

    dp = doc.add_paragraph()
    dp.add_run(f"Date: {today}").font.size = Pt(10)
    _set_spacing(dp, after_pt=2)

    out = Path(output_path)
    out.parent.mkdir(parents=True, exist_ok=True)
    doc.save(str(out))
    LOG.info("CPNI CLEC certification letter generated: %s", out)
    return str(out)