feat(phase-8): billing engine + invoice PDF + mark-paid + overdue escalation

Backend:
- app/services/invoice_pdf.py: Jinja2+WeasyPrint PDF generation, saves to
  /app/data/invoices/{id}.pdf, updates Invoice.pdf_path
- app/templates/invoice.html: professional branded A4 invoice template with
  school details, line items table, totals, payment instructions, paid receipt
- routers/billing.py: GET /invoices/{id}/pdf (auto-generate on demand, FileResponse),
  POST /invoices/{id}/mark-paid (payment_method + reference → status=paid),
  POST /trigger-generate-invoices (manual trigger), school_name in invoice list
- tasks/billing.py: fix missing func import in generate_monthly_invoices,
  new billing.generate_invoice_pdf Celery task, auto-send email after
  invoice creation, check_overdue upgraded with 7-day warning emails and
  30-day school suspension + suspension email

Frontend:
- BillingPage.vue: full rewrite — status filter tabs, school names (not UUIDs),
  PDF download button, mail icon, Mark Paid modal with method/reference fields,
  overdue rows highlighted, pagination, Generate Invoices trigger button
- api.ts: markInvoicePaid, downloadInvoicePdf, triggerGenerateInvoices

backend/app/routers/billing.py

@@ -1,7 +1,10 @@
 """Billing and invoice endpoints."""
+import os
 from datetime import date, datetime, timezone
+from pathlib import Path
 from typing import Optional
 from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi.responses import FileResponse
 from pydantic import BaseModel
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, func, desc
@@ -10,9 +13,15 @@ from app.auth.dependencies import require_super_admin, get_current_user
 from app.database import get_db
 from app.models.user import HubUser, UserRole
 from app.models.billing import Invoice, InvoiceStatus, InvoiceLineItem, SchoolSubscription, BillingCycle
+from app.models.school import School
 
 router = APIRouter(prefix="/api/billing", tags=["billing"])
 
+PDF_DIR = Path(os.getenv("PDF_DIR", "/app/data/invoices"))
+
+
+# ── Pydantic schemas ──────────────────────────────────────────────────────────
+
 class InvoiceCreate(BaseModel):
     school_id: str
     billing_period_start: date
@@ -31,15 +40,26 @@ class InvoiceUpdate(BaseModel):
     payment_reference: Optional[str] = None
     notes: Optional[str] = None
 
+class MarkPaidBody(BaseModel):
+    payment_method: str = "bank_transfer"
+    payment_reference: Optional[str] = None
+    paid_at: Optional[datetime] = None
+
 class SubscriptionUpsert(BaseModel):
     monthly_fee: float
     sms_cost_per_message: float = 1.0
     cycle: BillingCycle = BillingCycle.monthly
     next_billing_date: Optional[date] = None
 
-def _inv_out(inv: Invoice) -> dict:
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _inv_out(inv: Invoice, school_name: str | None = None) -> dict:
     return {
-        "id": inv.id, "school_id": inv.school_id, "invoice_number": inv.invoice_number,
+        "id": inv.id,
+        "school_id": inv.school_id,
+        "school_name": school_name,
+        "invoice_number": inv.invoice_number,
         "status": inv.status.value,
         "billing_period_start": inv.billing_period_start.isoformat(),
         "billing_period_end": inv.billing_period_end.isoformat(),
@@ -53,14 +73,17 @@ def _inv_out(inv: Invoice) -> dict:
         "payment_method": inv.payment_method,
         "payment_reference": inv.payment_reference,
         "email_sent_at": inv.email_sent_at.isoformat() if inv.email_sent_at else None,
+        "pdf_path": inv.pdf_path,
         "created_at": inv.created_at.isoformat(),
         "notes": inv.notes,
     }
 
 def _next_invoice_number(existing_count: int) -> str:
-    from datetime import date
     return f"INV-{date.today().strftime('%Y%m')}-{existing_count + 1:04d}"
 
+
+# ── Invoice list / create / update ────────────────────────────────────────────
+
 @router.get("/invoices")
 async def list_invoices(
     school_id: Optional[str] = Query(None),
@@ -77,9 +100,23 @@ async def list_invoices(
         stmt = stmt.where(Invoice.school_id == school_id)
     if status:
         stmt = stmt.where(Invoice.status == status)
+
     total = (await db.execute(select(func.count()).select_from(stmt.subquery()))).scalar_one()
     invoices = (await db.execute(stmt.offset((page - 1) * per_page).limit(per_page))).scalars().all()
-    return {"items": [_inv_out(i) for i in invoices], "total": total, "page": page, "per_page": per_page}
+
+    # Bulk-load school names
+    school_ids = {i.school_id for i in invoices}
+    school_map: dict[str, str] = {}
+    if school_ids:
+        schools = (await db.execute(select(School).where(School.id.in_(school_ids)))).scalars().all()
+        school_map = {s.id: s.name for s in schools}
+
+    return {
+        "items": [_inv_out(i, school_map.get(i.school_id)) for i in invoices],
+        "total": total,
+        "page": page,
+        "per_page": per_page,
+    }
 
 @router.post("/invoices", status_code=201)
 async def create_invoice(
@@ -129,6 +166,111 @@ async def update_invoice(
     await db.commit()
     return _inv_out(inv)
 
+
+# ── Mark as paid ──────────────────────────────────────────────────────────────
+
+@router.post("/invoices/{invoice_id}/mark-paid")
+async def mark_invoice_paid(
+    invoice_id: str,
+    body: MarkPaidBody,
+    _admin: HubUser = Depends(require_super_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    """Mark an invoice as paid with payment details."""
+    inv = (await db.execute(select(Invoice).where(Invoice.id == invoice_id))).scalar_one_or_none()
+    if not inv:
+        raise HTTPException(404, "Invoice not found")
+    if inv.status == InvoiceStatus.paid:
+        raise HTTPException(400, "Invoice is already marked as paid")
+    if inv.status == InvoiceStatus.cancelled:
+        raise HTTPException(400, "Cannot mark a cancelled invoice as paid")
+
+    inv.status = InvoiceStatus.paid
+    inv.paid_at = body.paid_at or datetime.now(timezone.utc)
+    inv.payment_method = body.payment_method
+    inv.payment_reference = body.payment_reference
+    await db.commit()
+    return _inv_out(inv)
+
+
+# ── Invoice PDF ───────────────────────────────────────────────────────────────
+
+@router.get("/invoices/{invoice_id}/pdf")
+async def get_invoice_pdf(
+    invoice_id: str,
+    current_user: HubUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    Serve the invoice PDF. Generates it on demand if not yet created.
+    Super admins can access any invoice; school admins only their own.
+    """
+    inv = (await db.execute(select(Invoice).where(Invoice.id == invoice_id))).scalar_one_or_none()
+    if not inv:
+        raise HTTPException(404, "Invoice not found")
+
+    # Authorization
+    if current_user.role != UserRole.super_admin and inv.school_id != current_user.school_id:
+        raise HTTPException(403, "Access denied")
+
+    pdf_path = PDF_DIR / f"{invoice_id}.pdf"
+
+    # Generate if not yet on disk
+    if not pdf_path.exists():
+        try:
+            from app.tasks.billing import generate_invoice_pdf_task
+            # Run synchronously for the HTTP request (small invoice = fast)
+            # The task is also available as an async Celery task for batch use
+            _generate_pdf_sync(invoice_id)
+            # Update db record
+            inv_fresh = (await db.execute(select(Invoice).where(Invoice.id == invoice_id))).scalar_one_or_none()
+            if inv_fresh:
+                inv_fresh.pdf_path = str(pdf_path)
+                await db.commit()
+        except Exception as e:
+            raise HTTPException(500, f"PDF generation failed: {e}")
+
+    if not pdf_path.exists():
+        raise HTTPException(500, "PDF generation failed — file not found after generation")
+
+    school = (await db.execute(select(School).where(School.id == inv.school_id))).scalar_one_or_none()
+    school_slug = school.slug if school else invoice_id[:8]
+    filename = f"invoice-{inv.invoice_number}-{school_slug}.pdf"
+
+    return FileResponse(
+        path=str(pdf_path),
+        media_type="application/pdf",
+        filename=filename,
+    )
+
+
+def _generate_pdf_sync(invoice_id: str) -> str:
+    """Synchronous PDF generation (for use from the HTTP request handler)."""
+    import os
+    from sqlalchemy import create_engine
+    from sqlalchemy.orm import sessionmaker
+    from app.services.invoice_pdf import generate_invoice_pdf
+
+    db_url = os.getenv("DATABASE_URL", "postgresql://postgres:postgres@db:5432/taptrack_hub")
+    engine = create_engine(db_url.replace("postgresql+asyncpg://", "postgresql://"), pool_pre_ping=True)
+    Session = sessionmaker(bind=engine)
+    db = Session()
+    try:
+        path = generate_invoice_pdf(invoice_id, db)
+        # Update pdf_path in the record
+        from app.models.billing import Invoice
+        inv = db.get(Invoice, invoice_id)
+        if inv:
+            inv.pdf_path = path
+            db.commit()
+        return path
+    finally:
+        db.close()
+        engine.dispose()
+
+
+# ── Email dispatch ────────────────────────────────────────────────────────────
+
 @router.post("/invoices/{invoice_id}/send-email")
 async def send_invoice_email(
     invoice_id: str,
@@ -142,6 +284,21 @@ async def send_invoice_email(
     send_invoice_email_task.delay(invoice_id)
     return {"message": "Email queued"}
 
+
+# ── Trigger monthly invoice generation ───────────────────────────────────────
+
+@router.post("/trigger-generate-invoices")
+async def trigger_generate_invoices(
+    _admin: HubUser = Depends(require_super_admin),
+):
+    """Manually trigger the monthly invoice generation Celery task."""
+    from app.tasks.billing import generate_monthly_invoices
+    generate_monthly_invoices.delay()
+    return {"message": "Invoice generation task queued"}
+
+
+# ── Subscriptions ─────────────────────────────────────────────────────────────
+
 @router.get("/subscriptions/{school_id}")
 async def get_subscription(
     school_id: str,
@@ -150,12 +307,15 @@ async def get_subscription(
 ):
     if current_user.role != UserRole.super_admin and current_user.school_id != school_id:
         raise HTTPException(403)
-    sub = (await db.execute(select(SchoolSubscription).where(SchoolSubscription.school_id == school_id))).scalar_one_or_none()
+    sub = (await db.execute(
+        select(SchoolSubscription).where(SchoolSubscription.school_id == school_id)
+    )).scalar_one_or_none()
     if not sub:
         raise HTTPException(404, "No subscription found")
     return {
         "id": sub.id, "school_id": sub.school_id, "cycle": sub.cycle.value,
-        "monthly_fee": float(sub.monthly_fee), "sms_cost_per_message": float(sub.sms_cost_per_message),
+        "monthly_fee": float(sub.monthly_fee),
+        "sms_cost_per_message": float(sub.sms_cost_per_message),
         "next_billing_date": sub.next_billing_date.isoformat() if sub.next_billing_date else None,
         "is_active": sub.is_active,
     }
@@ -167,7 +327,9 @@ async def upsert_subscription(
     _admin: HubUser = Depends(require_super_admin),
     db: AsyncSession = Depends(get_db),
 ):
-    sub = (await db.execute(select(SchoolSubscription).where(SchoolSubscription.school_id == school_id))).scalar_one_or_none()
+    sub = (await db.execute(
+        select(SchoolSubscription).where(SchoolSubscription.school_id == school_id)
+    )).scalar_one_or_none()
     if sub:
         sub.monthly_fee = body.monthly_fee
         sub.sms_cost_per_message = body.sms_cost_per_message

backend/app/services/invoice_pdf.py

@@ -0,0 +1,70 @@
+"""Invoice PDF generation using Jinja2 + WeasyPrint."""
+import logging
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# PDF output directory (mounted as a Docker volume in production)
+PDF_DIR = Path(os.getenv("PDF_DIR", "/app/data/invoices"))
+
+
+def generate_invoice_pdf(invoice_id: str, db_session) -> str:
+    """
+    Render the invoice HTML template and convert to PDF via WeasyPrint.
+
+    Args:
+        invoice_id: UUID of the Invoice to generate
+        db_session: synchronous SQLAlchemy session (used from Celery tasks)
+
+    Returns:
+        Absolute path to the generated PDF file.
+    """
+    from app.models.billing import Invoice, InvoiceLineItem
+    from app.models.school import School
+    from jinja2 import Environment, FileSystemLoader
+    from weasyprint import HTML
+
+    # Load invoice + line items + school
+    inv = db_session.get(Invoice, invoice_id)
+    if not inv:
+        raise ValueError(f"Invoice {invoice_id} not found")
+
+    school = db_session.get(School, inv.school_id)
+    line_items = db_session.query(InvoiceLineItem).filter_by(invoice_id=invoice_id).all()
+
+    # Format dates
+    def _fmt(d) -> str:
+        if not d:
+            return ""
+        if hasattr(d, "strftime"):
+            return d.strftime("%B %d, %Y")
+        return str(d)
+
+    context = {
+        "invoice": inv,
+        "school": school,
+        "line_items": line_items,
+        "issued_date": _fmt(inv.created_at),
+        "period_start": _fmt(inv.billing_period_start),
+        "period_end": _fmt(inv.billing_period_end),
+        "due_date": _fmt(inv.due_date),
+        "paid_date": _fmt(inv.paid_at),
+        "generated_date": datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC"),
+    }
+
+    # Render Jinja2 template
+    template_dir = Path(__file__).parent.parent / "templates"
+    env = Environment(loader=FileSystemLoader(str(template_dir)), autoescape=True)
+    template = env.get_template("invoice.html")
+    html_content = template.render(**context)
+
+    # Generate PDF
+    PDF_DIR.mkdir(parents=True, exist_ok=True)
+    output_path = PDF_DIR / f"{invoice_id}.pdf"
+
+    HTML(string=html_content).write_pdf(str(output_path))
+    logger.info("Generated PDF: %s", output_path)
+
+    return str(output_path)

backend/app/tasks/billing.py

@@ -1,45 +1,71 @@
-"""Celery tasks: invoice generation, email, overdue checks."""
+"""Celery tasks: invoice generation, PDF, email, overdue escalation."""
 import logging
-from datetime import date, timedelta
+from datetime import date, timedelta, datetime, timezone
 
 from app.worker import celery_app
 
 logger = logging.getLogger(__name__)
 
+
 def _make_session():
     import os
     from sqlalchemy import create_engine
     from sqlalchemy.orm import sessionmaker
     db_url = os.getenv("DATABASE_URL", "postgresql://postgres:postgres@db:5432/taptrack_hub")
-    engine = create_engine(db_url.replace("postgresql+asyncpg://", "postgresql://"), pool_pre_ping=True)
+    engine = create_engine(
+        db_url.replace("postgresql+asyncpg://", "postgresql://"),
+        pool_pre_ping=True,
+    )
     return sessionmaker(bind=engine)()
 
+
+def _hub_url() -> str:
+    import os
+    return os.getenv("HUB_BASE_URL", "http://localhost:8090")
+
+
 @celery_app.task(name="billing.generate_monthly_invoices")
 def generate_monthly_invoices():
     """On the 1st: create draft invoices for all active schools with a subscription."""
-    from app.models.billing import Invoice, SchoolSubscription, InvoiceLineItem, BillingCycle
+    from sqlalchemy import select, func
+    from app.models.billing import Invoice, SchoolSubscription, InvoiceLineItem
     from app.models.school import School, SchoolStatus
-    from sqlalchemy import select
-    from datetime import date
 
     db = _make_session()
     try:
         today = date.today()
         period_start = date(today.year, today.month, 1)
-        prev_month = (period_start - timedelta(days=1))
+        prev_month = period_start - timedelta(days=1)
         billing_start = date(prev_month.year, prev_month.month, 1)
         billing_end = period_start - timedelta(days=1)
 
-        subs = db.execute(select(SchoolSubscription).where(SchoolSubscription.is_active == True)).scalars().all()
+        subs = db.execute(
+            select(SchoolSubscription).where(SchoolSubscription.is_active == True)
+        ).scalars().all()
+
         count = db.execute(select(func.count()).select_from(Invoice)).scalar_one()
+        created = 0
 
         for sub in subs:
             school = db.get(School, sub.school_id)
             if not school or school.status != SchoolStatus.active:
                 continue
+
+            # Avoid duplicate invoices for the same period
+            existing = db.execute(
+                select(Invoice).where(
+                    Invoice.school_id == sub.school_id,
+                    Invoice.billing_period_start == billing_start,
+                )
+            ).scalar_one_or_none()
+            if existing:
+                continue
+
             total = float(sub.monthly_fee)
             inv_num = f"INV-{billing_start.strftime('%Y%m')}-{count + 1:04d}"
             count += 1
+            created += 1
+
             inv = Invoice(
                 school_id=sub.school_id,
                 invoice_number=inv_num,
@@ -51,6 +77,7 @@ def generate_monthly_invoices():
             )
             db.add(inv)
             db.flush()
+
             db.add(InvoiceLineItem(
                 invoice_id=inv.id,
                 description=f"Monthly subscription — {school.name}",
@@ -58,21 +85,47 @@ def generate_monthly_invoices():
                 unit_price=float(sub.monthly_fee),
                 amount=float(sub.monthly_fee),
             ))
+
+            # Auto-send invoice email
+            send_invoice_email_task.delay(inv.id)
+
         db.commit()
-        logger.info(f"Generated {len(subs)} invoices for {billing_start}")
+        logger.info("Generated %d invoices for %s", created, billing_start)
     except Exception as e:
         db.rollback()
-        logger.error(f"generate_monthly_invoices error: {e}")
+        logger.error("generate_monthly_invoices error: %s", e)
     finally:
         db.close()
 
+
+@celery_app.task(name="billing.generate_invoice_pdf")
+def generate_invoice_pdf_task(invoice_id: str):
+    """Generate PDF for a single invoice and update the pdf_path field."""
+    from app.services.invoice_pdf import generate_invoice_pdf
+    from app.models.billing import Invoice
+
+    db = _make_session()
+    try:
+        path = generate_invoice_pdf(invoice_id, db)
+        inv = db.get(Invoice, invoice_id)
+        if inv:
+            inv.pdf_path = path
+            db.commit()
+        logger.info("Invoice PDF generated: %s", path)
+        return path
+    except Exception as e:
+        logger.error("generate_invoice_pdf_task error for %s: %s", invoice_id, e)
+        raise
+    finally:
+        db.close()
+
+
 @celery_app.task(name="billing.send_invoice_email")
 def send_invoice_email_task(invoice_id: str):
-    """Send invoice email to school billing contact."""
+    """Send invoice email to school billing contact and set status to 'sent'."""
     from app.models.billing import Invoice, InvoiceStatus
     from app.models.school import School
     from app.services.email import send_email
-    from sqlalchemy import select
 
     db = _make_session()
     try:
@@ -82,44 +135,135 @@ def send_invoice_email_task(invoice_id: str):
         school = db.get(School, inv.school_id)
         if not school or not school.billing_email:
             return
-        body = f"""Dear {school.contact_name or school.name},
 
-Please find your invoice {inv.invoice_number} for the period {inv.billing_period_start} to {inv.billing_period_end}.
-
-Amount Due: PHP {float(inv.total_amount):,.2f}
-Due Date: {inv.due_date}
-
-Please log in to your TapTrack Hub portal to view and pay your invoice.
-
-Thank you,
-TapTrack Hub Team
-"""
-        send_email(to=school.billing_email, subject=f"Invoice {inv.invoice_number} — TapTrack Hub", body=body)
-        from datetime import datetime, timezone
+        body = (
+            f"Dear {school.contact_name or school.name},\n\n"
+            f"Please find your invoice {inv.invoice_number} for the period "
+            f"{inv.billing_period_start} to {inv.billing_period_end}.\n\n"
+            f"Amount Due: PHP {float(inv.total_amount):,.2f}\n"
+            f"Due Date: {inv.due_date or 'Upon receipt'}\n\n"
+            f"Please log in to your TapTrack Hub school portal to view and download your invoice:\n"
+            f"{_hub_url()}/portal/billing\n\n"
+            f"Thank you,\nTapTrack Hub Team"
+        )
+        send_email(
+            to=school.billing_email,
+            subject=f"Invoice {inv.invoice_number} — TapTrack Hub",
+            body=body,
+        )
         inv.email_sent_at = datetime.now(timezone.utc)
-        if inv.status.value == "draft":
+        if inv.status == InvoiceStatus.draft:
             inv.status = InvoiceStatus.sent
         db.commit()
     finally:
         db.close()
 
+
 @celery_app.task(name="billing.check_overdue")
 def check_overdue():
-    """Mark overdue invoices and send warning emails."""
-    from app.models.billing import Invoice, InvoiceStatus
+    """
+    Daily task: mark overdue invoices and escalate.
+    - sent + past due_date → overdue
+    - overdue 7+ days → warning email
+    - overdue 30+ days → suspend school + suspension email
+    """
     from sqlalchemy import select, and_
+    from app.models.billing import Invoice, InvoiceStatus
+    from app.models.school import School, SchoolStatus
+    from app.services.email import send_email
 
     db = _make_session()
     try:
         today = date.today()
-        overdue = db.execute(
+
+        # 1. Mark newly overdue
+        newly_overdue = db.execute(
             select(Invoice).where(
-                and_(Invoice.status == InvoiceStatus.sent, Invoice.due_date < today, Invoice.due_date != None)
+                and_(
+                    Invoice.status == InvoiceStatus.sent,
+                    Invoice.due_date != None,
+                    Invoice.due_date < today,
+                )
             )
         ).scalars().all()
-        for inv in overdue:
+        for inv in newly_overdue:
             inv.status = InvoiceStatus.overdue
         db.commit()
-        logger.info(f"Marked {len(overdue)} invoices as overdue")
+        logger.info("Marked %d invoices as overdue", len(newly_overdue))
+
+        # 2. Warning email: overdue 7+ days (but not yet 30)
+        warn_cutoff = today - timedelta(days=7)
+        suspend_cutoff = today - timedelta(days=30)
+
+        warn_invoices = db.execute(
+            select(Invoice).where(
+                and_(
+                    Invoice.status == InvoiceStatus.overdue,
+                    Invoice.due_date != None,
+                    Invoice.due_date <= warn_cutoff,
+                    Invoice.due_date > suspend_cutoff,
+                )
+            )
+        ).scalars().all()
+
+        for inv in warn_invoices:
+            school = db.get(School, inv.school_id)
+            if school and school.billing_email:
+                send_email(
+                    to=school.billing_email,
+                    subject=f"[TapTrack Hub] Overdue Invoice — {inv.invoice_number}",
+                    body=(
+                        f"Dear {school.contact_name or school.name},\n\n"
+                        f"Your invoice {inv.invoice_number} for PHP {float(inv.total_amount):,.2f} "
+                        f"was due on {inv.due_date} and is now overdue.\n\n"
+                        f"Please settle this invoice immediately to avoid account suspension.\n\n"
+                        f"Log in to your portal: {_hub_url()}/portal/billing\n\n"
+                        f"TapTrack Hub Team"
+                    ),
+                )
+        logger.info("Sent %d overdue warning emails", len(warn_invoices))
+
+        # 3. Suspend: overdue 30+ days
+        suspend_invoices = db.execute(
+            select(Invoice).where(
+                and_(
+                    Invoice.status == InvoiceStatus.overdue,
+                    Invoice.due_date != None,
+                    Invoice.due_date <= suspend_cutoff,
+                )
+            )
+        ).scalars().all()
+
+        suspended = 0
+        for inv in suspend_invoices:
+            school = db.get(School, inv.school_id)
+            if school and school.status == SchoolStatus.active:
+                school.status = SchoolStatus.suspended
+                suspended += 1
+                logger.warning(
+                    "Suspended school %s — overdue invoice %s (30+ days)",
+                    school.name, inv.invoice_number,
+                )
+                if school.billing_email:
+                    send_email(
+                        to=school.billing_email,
+                        subject=f"[TapTrack Hub] Account Suspended — Invoice {inv.invoice_number}",
+                        body=(
+                            f"Dear {school.contact_name or school.name},\n\n"
+                            f"Your TapTrack account has been suspended due to unpaid invoice "
+                            f"{inv.invoice_number} (PHP {float(inv.total_amount):,.2f}), "
+                            f"which was due on {inv.due_date}.\n\n"
+                            f"SMS notifications and automated reports are now disabled.\n\n"
+                            f"To restore service, please contact support@taptrack.io immediately.\n\n"
+                            f"TapTrack Hub Team"
+                        ),
+                    )
+
+        db.commit()
+        logger.info("Suspended %d schools for non-payment", suspended)
+
+    except Exception as e:
+        db.rollback()
+        logger.error("check_overdue error: %s", e)
     finally:
         db.close()

backend/app/templates/invoice.html

@@ -0,0 +1,226 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<style>
+  @page { size: A4; margin: 20mm 18mm 20mm 18mm; }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: "Helvetica Neue", Helvetica, Arial, sans-serif; font-size: 11pt; color: #1e293b; line-height: 1.5; }
+
+  /* Header */
+  .header { display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 32px; }
+  .brand { }
+  .brand h1 { font-size: 20pt; font-weight: 700; color: #1e40af; letter-spacing: -0.5px; }
+  .brand p { font-size: 9pt; color: #64748b; margin-top: 2px; }
+  .invoice-meta { text-align: right; }
+  .invoice-meta .invoice-number { font-size: 15pt; font-weight: 700; color: #1e293b; }
+  .invoice-meta .invoice-label { font-size: 8pt; text-transform: uppercase; letter-spacing: 1px; color: #94a3b8; }
+  .invoice-meta .date { font-size: 10pt; color: #475569; margin-top: 4px; }
+
+  /* Divider */
+  .divider { border: none; border-top: 2px solid #e2e8f0; margin: 20px 0; }
+  .divider-thin { border: none; border-top: 1px solid #e2e8f0; margin: 12px 0; }
+
+  /* Parties */
+  .parties { display: flex; gap: 40px; margin-bottom: 28px; }
+  .party { flex: 1; }
+  .party-label { font-size: 8pt; text-transform: uppercase; letter-spacing: 1px; color: #94a3b8; margin-bottom: 6px; }
+  .party-name { font-weight: 700; font-size: 12pt; color: #0f172a; }
+  .party p { font-size: 9.5pt; color: #475569; margin-top: 1px; }
+
+  /* Status pill */
+  .status-pill { display: inline-block; padding: 3px 10px; border-radius: 20px; font-size: 8.5pt; font-weight: 600; text-transform: uppercase; letter-spacing: 0.5px; }
+  .status-draft     { background: #f1f5f9; color: #64748b; }
+  .status-sent      { background: #eff6ff; color: #1d4ed8; }
+  .status-paid      { background: #f0fdf4; color: #15803d; }
+  .status-overdue   { background: #fef2f2; color: #dc2626; }
+  .status-cancelled { background: #f1f5f9; color: #94a3b8; }
+
+  /* Invoice info grid */
+  .info-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; margin-bottom: 28px; background: #f8fafc; border-radius: 8px; padding: 16px; }
+  .info-cell .info-label { font-size: 8pt; text-transform: uppercase; letter-spacing: 0.8px; color: #94a3b8; margin-bottom: 3px; }
+  .info-cell .info-value { font-size: 10.5pt; font-weight: 600; color: #0f172a; }
+
+  /* Line items table */
+  .items-table { width: 100%; border-collapse: collapse; margin-bottom: 20px; }
+  .items-table thead th { background: #1e40af; color: white; font-size: 8.5pt; text-transform: uppercase; letter-spacing: 0.8px; padding: 9px 12px; text-align: left; }
+  .items-table thead th:last-child,
+  .items-table thead th:nth-child(3),
+  .items-table thead th:nth-child(4) { text-align: right; }
+  .items-table tbody tr:nth-child(even) { background: #f8fafc; }
+  .items-table tbody td { padding: 10px 12px; font-size: 10pt; color: #334155; border-bottom: 1px solid #f1f5f9; }
+  .items-table tbody td.num { text-align: right; font-variant-numeric: tabular-nums; }
+
+  /* Totals */
+  .totals { float: right; width: 260px; margin-bottom: 32px; }
+  .totals table { width: 100%; border-collapse: collapse; }
+  .totals td { padding: 5px 0; font-size: 10pt; color: #475569; }
+  .totals td:last-child { text-align: right; font-variant-numeric: tabular-nums; }
+  .totals .total-row td { font-size: 13pt; font-weight: 700; color: #0f172a; border-top: 2px solid #e2e8f0; padding-top: 10px; margin-top: 4px; }
+  .totals .paid-row td { color: #15803d; font-weight: 600; }
+  .clearfix::after { content: ""; display: table; clear: both; }
+
+  /* Payment info */
+  .payment-info { background: #eff6ff; border: 1px solid #bfdbfe; border-radius: 8px; padding: 14px 16px; margin-bottom: 24px; }
+  .payment-info h3 { font-size: 9.5pt; font-weight: 700; color: #1e40af; margin-bottom: 6px; }
+  .payment-info p { font-size: 9.5pt; color: #1e3a8a; }
+  .payment-info .ref { font-family: monospace; background: #dbeafe; padding: 2px 6px; border-radius: 3px; font-size: 9pt; }
+
+  /* Footer */
+  .footer { margin-top: 32px; padding-top: 12px; border-top: 1px solid #e2e8f0; display: flex; justify-content: space-between; align-items: center; }
+  .footer p { font-size: 8.5pt; color: #94a3b8; }
+</style>
+</head>
+<body>
+
+<!-- Header -->
+<div class="header">
+  <div class="brand">
+    <h1>TapTrack Hub</h1>
+    <p>Cloud Control Plane for TapTrack Deployments</p>
+  </div>
+  <div class="invoice-meta">
+    <div class="invoice-label">Invoice</div>
+    <div class="invoice-number">{{ invoice.invoice_number }}</div>
+    <div class="date">Issued {{ issued_date }}</div>
+    <div style="margin-top:6px">
+      <span class="status-pill status-{{ invoice.status }}">{{ invoice.status }}</span>
+    </div>
+  </div>
+</div>
+
+<hr class="divider">
+
+<!-- Bill To / From -->
+<div class="parties">
+  <div class="party">
+    <div class="party-label">Bill To</div>
+    <div class="party-name">{{ school.name }}</div>
+    {% if school.address %}<p>{{ school.address }}</p>{% endif %}
+    {% if school.city %}<p>{{ school.city }}</p>{% endif %}
+    {% if school.billing_email %}<p>{{ school.billing_email }}</p>{% endif %}
+    {% if school.contact_phone %}<p>{{ school.contact_phone }}</p>{% endif %}
+  </div>
+  <div class="party">
+    <div class="party-label">From</div>
+    <div class="party-name">TapTrack Hub</div>
+    <p>Cloud Services</p>
+    <p>support@taptrack.io</p>
+  </div>
+</div>
+
+<!-- Invoice info -->
+<div class="info-grid">
+  <div class="info-cell">
+    <div class="info-label">Billing Period</div>
+    <div class="info-value">{{ period_start }} — {{ period_end }}</div>
+  </div>
+  <div class="info-cell">
+    <div class="info-label">Due Date</div>
+    <div class="info-value">{{ due_date if due_date else 'Upon receipt' }}</div>
+  </div>
+  <div class="info-cell">
+    <div class="info-label">Currency</div>
+    <div class="info-value">{{ invoice.currency }}</div>
+  </div>
+</div>
+
+<!-- Line items -->
+<table class="items-table">
+  <thead>
+    <tr>
+      <th style="width:55%">Description</th>
+      <th style="width:15%">Qty</th>
+      <th style="width:15%">Unit Price</th>
+      <th style="width:15%">Amount</th>
+    </tr>
+  </thead>
+  <tbody>
+    {% for item in line_items %}
+    <tr>
+      <td>{{ item.description }}</td>
+      <td class="num">{{ item.quantity }}</td>
+      <td class="num">{{ invoice.currency }} {{ "{:,.2f}".format(item.unit_price) }}</td>
+      <td class="num">{{ invoice.currency }} {{ "{:,.2f}".format(item.amount) }}</td>
+    </tr>
+    {% endfor %}
+    {% if not line_items %}
+    {% if invoice.subscription_amount > 0 %}
+    <tr>
+      <td>Monthly Subscription — {{ school.name }}</td>
+      <td class="num">1</td>
+      <td class="num">{{ invoice.currency }} {{ "{:,.2f}".format(invoice.subscription_amount) }}</td>
+      <td class="num">{{ invoice.currency }} {{ "{:,.2f}".format(invoice.subscription_amount) }}</td>
+    </tr>
+    {% endif %}
+    {% if invoice.sms_credit_amount > 0 %}
+    <tr>
+      <td>SMS Credits</td>
+      <td class="num">1</td>
+      <td class="num">{{ invoice.currency }} {{ "{:,.2f}".format(invoice.sms_credit_amount) }}</td>
+      <td class="num">{{ invoice.currency }} {{ "{:,.2f}".format(invoice.sms_credit_amount) }}</td>
+    </tr>
+    {% endif %}
+    {% if invoice.other_amount > 0 %}
+    <tr>
+      <td>Other Charges</td>
+      <td class="num">1</td>
+      <td class="num">{{ invoice.currency }} {{ "{:,.2f}".format(invoice.other_amount) }}</td>
+      <td class="num">{{ invoice.currency }} {{ "{:,.2f}".format(invoice.other_amount) }}</td>
+    </tr>
+    {% endif %}
+    {% endif %}
+  </tbody>
+</table>
+
+<!-- Totals + Payment info -->
+<div class="clearfix">
+  <div class="totals">
+    <table>
+      <tr>
+        <td>Subtotal</td>
+        <td>{{ invoice.currency }} {{ "{:,.2f}".format(invoice.total_amount) }}</td>
+      </tr>
+      <tr class="total-row">
+        <td>Total Due</td>
+        <td>{{ invoice.currency }} {{ "{:,.2f}".format(invoice.total_amount) }}</td>
+      </tr>
+      {% if invoice.paid_at %}
+      <tr class="paid-row">
+        <td>Paid</td>
+        <td>{{ invoice.currency }} {{ "{:,.2f}".format(invoice.total_amount) }}</td>
+      </tr>
+      {% endif %}
+    </table>
+  </div>
+</div>
+
+{% if invoice.paid_at %}
+<div class="payment-info" style="background:#f0fdf4;border-color:#bbf7d0">
+  <h3 style="color:#15803d">Payment Received</h3>
+  <p>Paid on {{ paid_date }} via {{ invoice.payment_method or 'N/A' }}
+  {% if invoice.payment_reference %} · Ref: <span class="ref">{{ invoice.payment_reference }}</span>{% endif %}</p>
+</div>
+{% else %}
+<div class="payment-info">
+  <h3>Payment Instructions</h3>
+  <p>Please log in to your TapTrack Hub school portal and submit payment by <strong>{{ due_date if due_date else 'the due date' }}</strong>.</p>
+  <p style="margin-top:4px">For questions, contact <strong>support@taptrack.io</strong></p>
+</div>
+{% endif %}
+
+{% if invoice.notes %}
+<div style="background:#fffbeb;border:1px solid #fde68a;border-radius:8px;padding:12px 14px;margin-bottom:16px">
+  <strong style="font-size:9pt;color:#92400e">Notes:</strong>
+  <p style="font-size:9.5pt;color:#78350f;margin-top:3px">{{ invoice.notes }}</p>
+</div>
+{% endif %}
+
+<!-- Footer -->
+<div class="footer">
+  <p>TapTrack Hub · support@taptrack.io</p>
+  <p>Generated {{ generated_date }} · {{ invoice.invoice_number }}</p>
+</div>
+
+</body>
+</html>