Enhance certificate management: add QR code generation, improve deletion scripts, and update README with new features

Co-authored-by: Copilot <copilot@github.com>

Author: orabe

backend/README.md

@@ -65,14 +65,51 @@ backend/
 ## Issuing a Certificate
 - Use the admin API or run `python scripts/create_certificate.py` interactively.
 - The script now asks for a `student_id` primary key and the student name.
+- After creation, it also generates a QR image in `backend/assets/qrcodes/` using the public verification URL.
 
 ## Removing a Certificate
-- Run `python scripts/remove_certificate.py S12345`
+- Preview deletion by student ID:
+  ```bash
+  ./venv/bin/python scripts/remove_certificate.py --student S12345
+  ```
+- Preview deletion by certificate ID:
+  ```bash
+  ./venv/bin/python scripts/remove_certificate.py --certificate MCL-2026-XXXXXXX
+  ```
+- Execute deletion with confirmation:
+  ```bash
+  ./venv/bin/python scripts/remove_certificate.py --student S12345 --yes
+  ./venv/bin/python scripts/remove_certificate.py --certificate MCL-2026-XXXXXXX --yes
+  ```
+- The script removes certificates only. It does not delete the student row.
+
+## Cleaning Broken Student IDs
+- Use this when rows contain `NULL`, empty, or literal `None` in `student_id`.
+- Dry-run:
+  ```bash
+  ./venv/bin/python scripts/clean_none_students.py
+  ```
+- Execute cleanup:
+  ```bash
+  ./venv/bin/python scripts/clean_none_students.py --yes
+  ```
+- This script deletes matching certificates and matching student rows.
 
 ## Looking Up a Student
-- Run `python scripts/view_student.py S12345`
+- Run `python scripts/view_student.py --student S12345`
 - Or call the admin API: `GET /admin/students/{student_id}`
 
+## Viewing Database Data
+- Show the latest certificates:
+  ```bash
+  ./venv/bin/python scripts/view_database.py
+  ```
+- Show a specific student and all of their certificates:
+  ```bash
+  ./venv/bin/python scripts/view_student.py --student S12345
+  ```
+- Both viewers print dates without time, using `YYYY.MM.DD`.
+
 ## Revocation
 Revocation support has been removed from this codebase. Certificates cannot be revoked via the API.
 
@@ -102,6 +139,11 @@ Revocation support has been removed from this codebase. Certificates cannot be r
   - (Optional) QR code to the same URL
 - The verification page confirms MathCodeLab as the issuer, not external accreditation.
 
+## QR Images
+- QR images are generated server-side as transparent PNG files.
+- Default output path: `backend/assets/qrcodes/{student_id}_{certificate_id}.png`
+- The QR payload is the public verification URL only.
+
 ## Wording Policy
 - Use “Certificate of Completion” or “Certificate of Participation”.
 - Do **not** use “accredited”, “state-recognized”, “official degree”, or “diploma”.

backend/app/crud.py

@@ -1,6 +1,6 @@
 from sqlalchemy.orm import Session
 from . import models, schemas
-from datetime import datetime
+from datetime import datetime, date
 import random, string
 
 def generate_certificate_id(year: int) -> str:
@@ -47,6 +47,7 @@ def create_certificate(db: Session, cert_in: schemas.CertificateCreate):
         course_title=cert_in.course_title,
         completion_date=cert_in.completion_date,
         duration_hours=cert_in.duration_hours,
+        created_at=_parse_created_at(cert_in.created_at),
         attendance_percentage=cert_in.attendance_percentage,
         assignment_completion_percentage=cert_in.assignment_completion_percentage,
         course_level=cert_in.course_level,
@@ -62,6 +63,19 @@ def create_certificate(db: Session, cert_in: schemas.CertificateCreate):
     db.refresh(cert)
     return cert
 
+
+def _parse_created_at(value: str | None):
+    """Parse a YYYY-MM-DD string and return a date object.
+
+    The system stores only the date (year-month-day). Return a
+    `datetime.date` instance or None.
+    """
+    if not value:
+        return None
+
+    parsed = datetime.strptime(value, "%Y-%m-%d")
+    return date(parsed.year, parsed.month, parsed.day)
+
 def revoke_certificate(db: Session, certificate_id: str, reason: str = None):
     cert = get_certificate_by_public_id(db, certificate_id)
     if not cert:

backend/app/database.py

@@ -52,13 +52,16 @@ def ensure_certificate_schema(bind=None):
     if "student_name" not in student_columns:
         missing_statements.append("ALTER TABLE students ADD COLUMN student_name VARCHAR")
     if "created_at" not in student_columns:
-        missing_statements.append("ALTER TABLE students ADD COLUMN created_at TIMESTAMP")
+        missing_statements.append("ALTER TABLE students ADD COLUMN created_at DATE")
     if "updated_at" not in student_columns:
         missing_statements.append("ALTER TABLE students ADD COLUMN updated_at TIMESTAMP")
 
     if "student_id" not in existing_columns:
         missing_statements.append("ALTER TABLE certificates ADD COLUMN student_id VARCHAR")
 
+    if "created_at" not in existing_columns:
+        missing_statements.append("ALTER TABLE certificates ADD COLUMN created_at DATE")
+
     if "attendance_percentage" not in existing_columns:
         missing_statements.append("ALTER TABLE certificates ADD COLUMN attendance_percentage INTEGER")
     if "assignment_completion_percentage" not in existing_columns:

backend/app/main.py

@@ -3,7 +3,7 @@
 from fastapi.middleware.cors import CORSMiddleware
 from sqlalchemy.orm import Session
 from starlette.responses import JSONResponse
-from datetime import datetime
+from datetime import datetime, date
 from . import models, schemas, crud, database, security
 import os
 
@@ -67,6 +67,13 @@ def verify_certificate(certificate_id: str, db: Session = Depends(get_db)):
 
     student = getattr(cert, "student", None)
 
+    def _format_ts(val):
+        if val is None:
+            return None
+        if isinstance(val, (datetime, date)):
+            return val.isoformat()
+        return str(val)
+
     return {
         "status": "valid",
         "certificate_id": cert.certificate_id,
@@ -83,10 +90,7 @@ def verify_certificate(certificate_id: str, db: Session = Depends(get_db)):
         "course_level": cert.course_level,
         "course_format": cert.course_format,
         "instruction_language": cert.instruction_language,
-        "certificate_created_at": cert.created_at,
-        "certificate_updated_at": cert.updated_at,
-        "student_created_at": getattr(student, "created_at", None) if student else None,
-        "student_updated_at": getattr(student, "updated_at", None) if student else None,
+        "certificate_created_at": _format_ts(cert.created_at),
         "verified_at": datetime.utcnow().isoformat() + "Z",
         "verification_url": f"https://mathcodelab.de/verify/?id={cert.certificate_id}"
     }
@@ -107,6 +111,13 @@ def list_certificates(
     api_key: str = Depends(security.verify_api_key)
 ):
     certs = db.query(models.Certificate).all()
+    def _format_ts(val):
+        if val is None:
+            return None
+        if isinstance(val, (datetime, date)):
+            return val.isoformat()
+        return str(val)
+
     return [
         {
             "certificate_id": cert.certificate_id,
@@ -123,8 +134,7 @@ def list_certificates(
             "instruction_language": cert.instruction_language,
             "issuer": cert.issuer,
             "instructor": cert.instructor,
-            "created_at": cert.created_at,
-            "updated_at": cert.updated_at,
+            "created_at": _format_ts(cert.created_at),
         }
         for cert in certs
     ]
@@ -147,12 +157,17 @@ def get_student_by_student_id(
         .all()
     )
 
+    def _format_ts(val):
+        if val is None:
+            return None
+        if isinstance(val, (datetime, date)):
+            return val.isoformat()
+        return str(val)
+
     return {
         "student": {
             "student_id": student.student_id,
             "student_name": student.student_name,
-            "created_at": student.created_at,
-            "updated_at": student.updated_at,
         },
         "certificates": certificates,
     }

backend/app/models.py

@@ -1,4 +1,4 @@
-from sqlalchemy import Column, Integer, String, DateTime, ForeignKey
+from sqlalchemy import Column, Integer, String, DateTime, Date, ForeignKey
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 from .database import Base
@@ -7,7 +7,7 @@ class Student(Base):
     __tablename__ = "students"
     student_id = Column(String, primary_key=True, index=True, nullable=False)
     student_name = Column(String, nullable=False)
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(Date, server_default=func.current_date())
     updated_at = Column(DateTime(timezone=True), onupdate=func.now(), server_default=func.now())
 
 class Certificate(Base):
@@ -30,6 +30,6 @@ class Certificate(Base):
     issuer = Column(String, default="MathCodeLab", nullable=False)
     instructor = Column(String, default="Mohammad Orabe", nullable=False)
     student = relationship("Student")
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(Date, server_default=func.current_date())
     updated_at = Column(DateTime(timezone=True), onupdate=func.now(), server_default=func.now())
 

backend/app/qr.py

@@ -0,0 +1,67 @@
+import os
+import re
+
+try:
+    import qrcode
+except ModuleNotFoundError as exc:
+    raise ModuleNotFoundError(
+        "qrcode is required for QR generation. Install backend requirements first."
+    ) from exc
+
+
+PROJECT_ROOT = os.path.dirname(os.path.dirname(__file__))
+DEFAULT_QR_DIR = os.path.join(PROJECT_ROOT, "assets", "qrcodes")
+DEFAULT_VERIFICATION_BASE_URL = os.getenv(
+    "VERIFICATION_BASE_URL",
+    "https://mathcodelab.de/verify/?id=",
+)
+
+
+def _safe_filename_part(value: str) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "_", value.strip())
+    return cleaned.strip("._-") or "certificate"
+
+
+def build_verification_url(certificate_id: str, base_url: str | None = None) -> str:
+    base = (base_url or DEFAULT_VERIFICATION_BASE_URL).rstrip()
+    if not base.endswith("="):
+        base = base.rstrip("/") + "/"
+    return f"{base}{certificate_id}"
+
+
+def generate_certificate_qr(
+    certificate_id: str,
+    student_id: str | None = None,
+    verification_url: str | None = None,
+    output_dir: str | None = None,
+) -> str:
+    """Generate a QR image for the certificate verification URL and return its file path."""
+    target_url = verification_url or build_verification_url(certificate_id)
+    qr = qrcode.QRCode(
+        version=None,
+        error_correction=qrcode.constants.ERROR_CORRECT_M,
+        box_size=10,
+        border=4,
+    )
+    qr.add_data(target_url)
+    qr.make(fit=True)
+
+    image = qr.make_image(fill_color="black", back_color="white").convert("RGBA")
+    pixels = image.getdata()
+    transparent_pixels = []
+    for red, green, blue, alpha in pixels:
+        if red >= 250 and green >= 250 and blue >= 250:
+            transparent_pixels.append((255, 255, 255, 0))
+        else:
+            transparent_pixels.append((red, green, blue, 255))
+    image.putdata(transparent_pixels)
+
+    target_dir = output_dir or DEFAULT_QR_DIR
+    os.makedirs(target_dir, exist_ok=True)
+    filename_parts = []
+    if student_id:
+        filename_parts.append(_safe_filename_part(student_id))
+    filename_parts.append(_safe_filename_part(certificate_id))
+    file_path = os.path.join(target_dir, "_".join(filename_parts) + ".png")
+    image.save(file_path)
+    return file_path

backend/app/schemas.py

@@ -7,6 +7,7 @@ class CertificateBase(BaseModel):
     course_title: str
     completion_date: str
     duration_hours: int
+    created_at: Optional[str] = None
     attendance_percentage: Optional[int] = None
     assignment_completion_percentage: Optional[int] = None
     course_level: Optional[str] = None
@@ -28,8 +29,6 @@ class Config:
 class StudentOut(BaseModel):
     student_id: str
     student_name: str
-    created_at: Optional[str] = None
-    updated_at: Optional[str] = None
 
 
 class StudentLookupResponse(BaseModel):
@@ -55,12 +54,8 @@ class CertificateVerificationResponse(BaseModel):
     course_level: Optional[str] = None
     course_format: Optional[str] = None
     instruction_language: Optional[str] = None
-    # Certificate timestamps
+    # Certificate creation date (date-only)
     certificate_created_at: Optional[str] = None
-    certificate_updated_at: Optional[str] = None
-    # Student timestamps
-    student_created_at: Optional[str] = None
-    student_updated_at: Optional[str] = None
 
 
 class CertificateDeleteResponse(BaseModel):

backend/requirements.txt

@@ -4,3 +4,4 @@ sqlalchemy
 pydantic
 python-dotenv
 psycopg2
+qrcode[pil]