# Phase 12 — Transcripts and certificates

Phase 12 implements official academic-document requests, controlled issuance, PDF
generation, QR verification, revocation, and delivery. It stops before clearance and
graduation-list processing.

## Delivered

### Transcript processing

- Student/alumni transcript requests for electronic or printed delivery.
- Destination institution, email, postal address, and private supporting documents.
- Automatic transcript-fee invoices integrated with the Phase 11 ledger.
- Payment verification from a fully settled invoice, never from browser claims.
- Request states for payment pending, review, correction, rejection, approval,
  generation, email completion, and courier dispatch.
- Append-only request events with officers, comments, timestamps, and dispatch data.
- Officer preview/review, digital registrar name, seal, approval, PDF generation,
  email delivery, courier name, and tracking number.
- Academic snapshots built only from published results.
- Course codes/titles, units, grades, grade points, semester GPA, CGPA, classification,
  programme, department, faculty, admission date, and institutional identity.

### Certificates

- Templates for degree, diploma, academic, course-completion, professional,
  attendance, ordination-training, ministerial-training, and statement-of-result
  documents.
- Configurable orientation, font, primary/accent colors, field spacing, signature
  placement, and optional private JPEG/PNG backgrounds.
- Live PDF template previews.
- Single or bulk issuance for eligible graduates only.
- Unique certificate numbers and immutable document snapshots.
- Registrar and principal signatures, official seal, watermark, QR code, and issue
  metadata.
- Revocation with a mandatory reason and immediate public status change.
- Reissue only from a revoked certificate, with a new number, token, PDF, and linkage
  to the superseded record.
- Append-only certificate issuance, revocation, and reissue events.

## Security model

- Transcript and certificate files use private storage.
- Supporting documents are private, MIME allowlisted, size limited, randomly named,
  and SHA-256 hashed.
- Every generated PDF has a stored SHA-256 fingerprint.
- Each verification URL contains a random 64-character token. Its lookup hash is
  stored separately and the reusable token is encrypted at rest and hidden from model
  serialization.
- Public verification requires both document number and token.
- Verification pages expose only institution, holder initials, programme, award,
  issue date, status, and file fingerprint. Grades, addresses, email addresses, and
  full names are excluded.
- Revoked certificates visibly return `REVOKED` and the recorded reason.
- PDFs contain security watermarks and QR codes.
- PDF owner encryption permits printing while disabling casual copying, modification,
  and annotation.
- Student downloads are owner-only; officer access requires the correct institution
  and transcript/certificate permission.

## PDF implementation and visual QA

Runtime generation uses `dompdf/dompdf` 3.1 and `endroid/qr-code` 6 with the SVG
writer, avoiding a GD runtime dependency. The representative documents were rendered
at 150 DPI with Poppler and visually inspected.

The first certificate render exposed a signature-block overflow and blank second page.
The layout was corrected and re-rendered. Final results:

- transcript: one A4 portrait page, no clipping or overlap;
- certificate: one A4 landscape page, no clipping or overflow;
- readable typography, tables, signatures, seal, watermark, QR codes, and metadata;
- PDF encryption confirmed with print allowed and copy/change disabled.

Representative development artifacts:

- `output/pdf/sample-official-transcript.pdf`
- `output/pdf/sample-degree-certificate.pdf`

## Demonstration data

The development seed creates a transcript service fee and schedule, publishes one
result workflow to establish an eligible graduate, creates a standard degree template,
issues one protected certificate, creates and settles a transcript invoice, approves
the request, and generates one official transcript.

Document PDF generation is intentionally skipped by the shared seeder in the testing
environment so unrelated module tests do not repeatedly render PDFs. The dedicated
document tests explicitly invoke the document seeder.

## Verification

- Academic-document tests: 7 passed, 38 assertions.
- Full application suite: 100 passed, 380 assertions.
- Phase migration rollback and reapplication completed successfully.
- Standalone academic-document reseeding completed successfully after explicitly
  setting the tenant permission context.
- Document and verification route inventories completed successfully.
- Composer manifest valid; dependency audit found no advisories.
- npm audit found zero vulnerabilities.
- Vite production bundle built successfully.

Run locally:

```powershell
C:\xampp\php\php.exe artisan migrate:fresh --seed
C:\xampp\php\php.exe artisan test --filter=AcademicDocumentTest
C:\xampp\php\php.exe artisan test
```

## Phase gate

Phase 12 is complete. Phase 13 (clearance and graduation) requires explicit approval
before implementation.