# 12 — Use Cases (team's Workflow book)

Source: `use_cases/UC1-Explorer.dc.html` (added 2026-10-30). This is an interactive explorer exported from a design tool. Its header says the use cases are **grouped from "เล่ม 02 Workflow" (Workflow book 02)**, a document the team has that is not in this repo yet.

**Review 2026-10-31:** all 162 cases were assessed; 60 have proposed step/outcome/branch corrections, with 47 decisions across 39 cases. See [full findings and open questions](16-use-case-review-2026-10-31.md). `review` notes and `wf` branches are proposals pending human confirmation, not approved institutional rules. In particular, W-41 already had conditional guardian consent in prose; the draft now shows a real bypass when it is unnecessary. Separate university admission from sports-school safeguarding, emergency contacts, payment helpers and Parent Portal access. Existing D-05/D-06 decisions remain authoritative; this review does not expand R1 or grant development approval.

- **Full catalog:** [use-cases/README.md](use-cases/README.md), with one file per module (`use-cases/ADM.md`, `use-cases/FIN.md`, …). Each use case has its trigger, outcome, actors, numbered steps (who does what), relations to other use cases, and screen codes.
- The catalog is **generated**. To refresh it after the team updates the export, run `python3 docs/agent/tools/gen_use_cases.py`. Do not edit `use-cases/*.md` by hand.
- To view the original explorer, serve the folder (`cd use_cases && python3 -m http.server`) and open `UC1-Explorer.dc.html`.

## Where this fits among the sources

| Source | Granularity | Use it for |
|---|---|---|
| **Use cases (this file)** | 35 modules · 162 use cases · 923 steps · 67 roles | **How things work**: actors, step order, approvals, business rules, edge cases. This is the most detailed source |
| BA module structure ([03-modules.md](03-modules.md)) | 23 modules split UNI / SS | The client-facing list of functions per education level |
| Proposal | 12 subsystems (TNSU-01…12) | Vision, channels, phasing |

When the use cases and the BA chart disagree on behaviour, follow the use cases and note the conflict in [11-open-questions-and-known-issues.md](11-open-questions-and-known-issues.md).

## Taxonomy

### Use-case IDs
`W-1` … `W-163` (W = Workflow). **W-63 is missing**, probably removed and kept as a gap so the numbers stay stable. IDs are not grouped by module.

### Modules (35, in 4 groups)

> ⚠️ **Code collision:** the use-case module **`SCH` = ทุนและ กยศ. (scholarships and student loans)**. It has nothing to do with sports schools. The BA sports-school branch is coded `SS-xx` in these docs for this reason.

| Group | Module codes |
|---|---|
| แพลตฟอร์มกลาง (platform) | IAM identity and permissions · ORG org units, campuses and calendar · NOTI notifications · ENG news, announcements, events · SVC e-Forms · CASE complaints and appeals · DOC documents and digital signatures · PRIV privacy and consent · AUD audit log · ANA executive analytics · RPT regulatory reporting · ADMIN system administration |
| งานวิชาการ (academic) | ADM admission · CUR curriculum · REG registration and timetable · ATT attendance · EXM exams · ASM assessment and grading · REC student records and status · GRD graduation and credentials · GRAD graduate studies · PRA teaching practicum and internships · SSC sports-school academics · LMS LMS integration |
| บริการนักศึกษา (student services) | FIN finance and fees · SCH scholarships and กยศ. · HOU dormitories · AFF student affairs · SAFE child and minor protection · HLT health · ALU alumni and careers |
| กีฬา (sports) | ATH athlete management · FAC venue and facility booking · LAB sports-science lab · REV revenue services (short courses and camps for outsiders) |

NOTI, AUD and LMS have **no use cases of their own**. They are background services that other use cases call.

### Lifecycle tags
Each use case also carries one lifecycle tag (shown as "feature" groups in the explorer): สมัครและคัดเลือก (21) · เข้าเรียนปีแรก (9) · ทุกภาคการศึกษา (19) · ระหว่างเรียน (22) · นักกีฬา (18) · โรงเรียนกีฬา (12) · บัณฑิตศึกษา (8) · จบการศึกษา (4) · ศิษย์เก่า (4) · ปัญหาและกรณีพิเศษ (18) · งานบริหารและกำกับ (27).

### Relation types
`เรียกใช้` (calls / includes) · `ถูกเรียกจาก` (called by) · `ต่อจาก` (follows) · `ขยายเมื่อมีเงื่อนไข` (extends conditionally).

### Screens
Each use case lists screen codes for designs that already exist (in a separate design file not in this repo). Prefixes: `A` applicant, `G` guardian, `S` staff admission, `T` judge tablet, `P` public, `U` student app, `C` coach, `L` lecturer, `B` backoffice, `E` executive, `M` minor mode, `X` help. The remaining codes are named after use cases (`W070`, `W123`, …).

## Mapping: use-case modules ↔ BA modules ↔ proposal

| UC module | BA (03-modules) | Proposal | Note |
|---|---|---|---|
| ADM | UNI-02, SS-01 | TNSU-01/02 | 21 UCs. The largest module: quotas, multi-judge skill tests, clearing, appeals, TCAS, transfer, foreign applicants, grad admission |
| CUR | UNI-04, SS-03 | TNSU-01/02 | Curriculum revision and closure (teach-out) |
| REG | UNI-05 | TNSU-01 | |
| ATT | SS-06 (school roll call) | TNSU-01/02 | Includes มส. (barred from exam) |
| EXM | UNI-05.3 | TNSU-01 | Makeup exams, exam misconduct |
| ASM | UNI-06, UNI-07 (W-56 teaching evaluation), SS-04 | TNSU-01/02 | |
| REC | UNI-03, SS-02 | TNSU-01/02 | 17 UCs: status changes, guardians, court orders, deaths, lifecycle cascade |
| GRD | UNI-06.8, UNI-08 (partly) | TNSU-01 | Graduation, credentials, verification, revocation |
| GRAD | — | — | ➕ **Graduate studies (ป.โท/ป.เอก)**. Not in BA chart or proposal |
| PRA | — | — | ➕ **Teaching practicum and internships**. Not in BA chart or proposal |
| SSC | SS-02, SS-04 | TNSU-02 | ปพ.1/2/3/5/6, promotion, transfer, athlete retention review |
| FIN | UNI-01.1 | TNSU-05 | Thai QR, instalments, refunds, write-off, GFMIS export |
| SCH | — | TNSU-05 | กยศ. via DSL, scholarships, volunteer-hour ledger |
| HOU | SS-05, SS-07 | TNSU-04 | University dorms **and** sports-school boarding |
| AFF | SS-13 | TNSU-02/04 | Orientation, disability accommodation, military deferment, discipline, mental-health referral |
| SAFE | SS-09.4 (partly) | — | ➕ **Child safeguarding / safe sport**. Not in the proposal |
| HLT | SS-09 | TNSU-04 | Health vault, injuries, concussion, medication for minors |
| ALU | UNI-08 | TNSU-01 | |
| ATH | SS-10, SS-11, SS-12 | TNSU-03 | Applies to **university** athletes too: competition leave, batch leave, eligibility, team selection, weight management, para classification |
| FAC, LAB, REV | — | — | ➕ Facility booking, sports-science lab, external revenue courses |
| IAM, ORG, ADMIN, AUD | UNI-01.2, UNI-01.3 | TNSU-11 | Much deeper than the BA chart: delegation, recertification, PAM, break-glass, data-fix |
| NOTI, ENG | SS-14.4 | cross-cutting | |
| SVC, CASE, DOC | UNI-03.3, UNI-06.7 | TNSU-09 | e-Forms, appeals, complaints, official-information requests, e-signature, records destruction |
| PRIV | — | — | ➕ PDPA consent and data-subject rights |
| ANA, RPT | SS-15 | TNSU-10 | SAR quality assessment, regulatory submissions, ITA/OIT publishing |
| LMS | — | TNSU-12 | Background integration |

**BA functions without a use case yet:** SS-08 nutrition (menus, meal log, ingredients and food cost; only referral W-109 exists), SS-05.3 duty-teacher roster, SS-05.4 dorm maintenance requests, SS-03.4 lesson plans, and SS-13.1 conduct points.

**Proposal features without a use case:** **AI bot and AI analytics** (no use case mentions AI), and a student web portal as a separate channel (use cases assume one app plus backoffice). (Legacy E-Education integration is not needed: there is no legacy system.)

## Key cross-cutting concepts

These recur across many use cases and should shape the domain model. Names are the team's (from the Workflow book). Find the use cases with `grep -rn "<term>" docs/agent/use-cases/`.

### People, guardians and consent
- **GuardianRelation types:** `LEGAL`, `CAREGIVER` (actual carer without legal custody, with delegated rights and expiry), `LOCAL_GUARDIAN` (for foreign minors), `OBSERVER` (parent of an adult student, consent-based), `EMERGENCY_CONTACT`, `PICKUP`. Each has a **verification_level**: provisional (ID + OTP, own-verification status and explicitly shared payment links only; no learner-data access or notifications) → level 1 (in-person document check) → level 2 (ThaID + online document check). See W-127, W-160.
- **Age of majority** (20 years, or married) automatically turns `LEGAL`/`CAREGIVER` into `OBSERVER`, which needs new consent (W-127, W-128).
- **ABAC grants** per relation and data category. Adult students approve or revoke parent access **per category, with an expiry** (W-128).
- **CustodyRestriction / ContactRestriction** from court orders or safeguarding cases block pickups, notifications and contact (W-93, W-22).
- **Authorised pickup list**, **LeavePass** (exeat with QR) and dorm roll call (W-13, W-90, W-86).
- **requires_guardian_cosign**: a DMN rule based on age on the submission date (W-03).
- Minors get a **minor mode** UI (screen M01).

### Governance rules
- **SoD (separation of duties)** rules referenced: SoD-01 (head who teaches the course is skipped when approving its grades), SoD-02 (requester ≠ approver), SoD-05 (fee-schedule setter ≠ approver), SoD-06 (policy editor ≠ publisher), SoD-09 (scholarship committee ≠ the advisor who commented), SoD-10 (finance maker ≠ checker ≠ approver; approval by amount limit, above the limit goes to the campus VP), SoD-14 (admission overrides), SoD-18 (thesis-exam chair ≠ main advisor). The full SoD list is in the Workflow book.
- **4-eyes approval** for sensitive actions: policy publishing, data fixes, pickup by others, caregiver certification, break-glass.
- **PolicySet (DMN)**: academic rules (dismissal, honours, credit limits, advisor load, consent policy) are **versioned decision tables applied per cohort** (W-15). Do not hard-code them.
- **Signed snapshots (hash)** of approved grade sets and regulatory submissions. Data fixes record before/after in **WORM** storage (W-01, W-35, W-137).
- **Privileged access:** JIT PAM (W-124), break-glass accounts (W-125), access recertification (W-126), MFA reset (W-142), acting/delegation of signing authority (W-123), external accounts (W-139).

### Lifecycle and status
- **LifecycleCase (review proposal):** scope tasks by leave/withdrawal/graduation/death and effective date. Temporary leave does not close everything. Successful appeals create authorized, feasible compensation requests; settled payments, external actions and seat allocation cannot simply be undone together (W-133).
- **ENROLLED_PENDING_APPEAL** appears in W-11, but legal effect and eligibility to continue must be verified against the applicable order/regulations (UR-Q04); it is not yet a confirmed universal stay.
- **Term rollover** with a dry run (W-122). **Post-standing re-validation** of registrations when grades or status change (W-162).
- **Holds** block services until cleared (payment, documents).

### Admission mechanics
- **AdmissionPlan → AdmissionRound** per campus. The **seat matrix** follows the program/round scheme; sport/gender/weight sub-buckets apply only where justified and published, within **AccreditedIntakeCap** (W-69, review proposal).
- **Admission rights:** uniqueness applies to the approved cycle/level/scheme. In R1, staff review expiry, reconciliation, extensions and appeal holds before releasing seats/calling reserves. Contact windows and cutoffs follow the approved round policy, not fixed job intervals. Automatic cross-campus ClearingRun remains **outside R1** (D-06); local actions do not replace central TCAS rights (W-74, W-18, review proposal).
- Multi-judge skill scoring with moderation (W-76). Accommodations for disabled applicants (W-79).

### Athletes and health
- **LeaveTier** T1 (national/international, auto-approved) / T2 (regional) / T3 (outside the master list or training camps, needs dean approval). **CompetitionLeaveBatch** gives one approval per faculty (W-04, W-114). Approved leave makes attendance **excused** and auto-creates a **MakeupExam** (W-05).
- **Readiness status** `FULL` / `MODIFIED` / `UNAVAILABLE` is always visible to the squad coach without consent (**D-05**). Diagnosis details need the athlete's consent (W-39, W-130).
- **hlt_vault**: health data in a separate vault. Access outside the care relationship needs 2 approvers (lead physician + DPO). Life-threatening cases can self-activate and must be reviewed within 24 hours (W-14).
- Concussion protocol (W-152), heat stress via WBGT (W-153), weight management (W-154), para classification (W-157), talent pathway (W-112) and retention review for sports-school athletes (W-151).

### UX and technical behaviour stated in use cases
- Registration: virtual waiting room, synchronous transaction with an **idempotency key**, a reloadable "latest result" page, and no double-submit (W-49).
- Payment: Thai QR with "save QR", copyable reference, bank-app deeplink, a shareable link for parents, bank callback/statement auto-reconciliation, and a pollable status page (W-51).
- Notifications go through NOTI with **no PII in payloads**. Emergency announcements have "ฉันปลอดภัย" (I'm safe) acknowledgement (W-36).
- Parent channel: **LIFF / PWA** (LINE front-end) (W-127).

## External systems named in use cases

| System | Use | UCs |
|---|---|---|
| ThaID | Identity for applicants, guardians (level 2), alumni, data-subject requests, bank-account change step-up, MFA recovery | W-41, W-127, W-160, W-21, W-66, W-108, W-131, W-139, W-142, W-143 |
| Thai QR / PromptPay + bank callback | Application fees, tuition, refunds to PromptPay | W-41, W-51, W-143 |
| e-Receipt | Electronic receipts | W-41, W-43, W-51, W-37 |
| myTCAS / ทปอ. | Optional TCAS adapter (file/API) | W-73, W-43 |
| กยศ. DSL | Loan applications, per-term confirmation, status notices (portal-assist) | W-48, W-119, W-133 |
| สป.อว. / CHECO | Curriculum registration, graduate employment survey, degree revocation | W-08, W-65, W-132, W-141 |
| GFMIS / accounting | Fiscal-year close export | W-116 |
| ตม.30 (immigration) | Report foreigners staying in dorms | W-38, W-46, W-147 |
| ทะเบียนราษฎร์ | Name-change verification (if connectable) | W-131 |
| LMS | Score import; account provisioning | W-01, W-44 |
| SSO, e-mail, Wi-Fi, digital student card | Provisioned at enrolment | W-44 |
| LINE, e-mail, SMS, in-app | Notification channels | W-36, W-49, W-13 |
| Digital signature with LTV and revocation | Credential verification by employers | W-67, W-132 |
| Reporting Hub | Regulatory submissions | W-35, W-65 |

## Release and decision references
- **R1**: the first release. Automatic cross-campus ClearingRun is out of R1 (D-06).
- **D-05**: readiness status goes to the coach without consent.
- **D-06** / **REL-09** / **v1.1**: all LAB (basic and advanced) moves to a **separate contract, 2574+ (2031+)**. W-110 is kept only so the numbering stays continuous.
- `C-5`, `SoD-xx`, `RefundRule.*`, `FeePolicy`, `MakeupPolicy`, `FinePolicy`, `SelectionPolicy` are defined in the Workflow book.

## Items marked "[ต้องตรวจสอบ]" (to verify) in the use cases
There are 18 of them:

| Topic | UC |
|---|---|
| Whether TNSU joins TCAS, and for which programs | W-73 |
| Transfer-credit ceiling set by regulation | W-82, W-25 |
| Review window for the มส. (barred-from-exam) list | W-104 |
| RefundRule values: APPEAL_DISMISSED, MEDICAL | W-17, W-161 |
| Disclosure-exemption section for official-information requests | W-20 |
| Minimum GPA for competition eligibility | W-30 |
| Default trip-supervision rule (staff sharing rooms with minors) | W-31 |
| Weight-loss threshold before competition | W-154 |
| WBGT heat thresholds | W-153 |
| Advisor load ceiling (number) | W-95 |
| Plan-B comprehensive exam / IS detail | W-158 |
| PDPA §26(5)(a) wording for injury records | W-39 |
| Concussion assessment tool (SCAT6 / Child SCAT6) | W-152 |
| Civil-code (ป.พ.พ.) limits on caregiver consent | W-160 |
| Legal reporting timeframe for safeguarding referrals | W-22 |
| ปพ.3 format sent to the education authority | W-88 |

Find them with `grep -rn "ต้องตรวจสอบ" docs/agent/use-cases/`.

## Internal tracker catalog and editable workflow drafts (2026-10-30)

The project owner requested a **table view** at tracker `/use-cases`, with per-use-case editable workflow diagrams and **shared server storage** (choice 1). This is an internal discovery tool, not a delivered TNSU product feature. The catalog reads the authoritative explorer directly; saved diagrams live separately in `tracker/data/diagrams/`. Initial diagrams preserve source steps plus explicit proposed `wf` decisions/loops/alternate outcomes where supplied; cases without metadata retain a linear draft. They are **workflow drafts**, not approved UML actor/use-case diagrams or confirmed institutional policies. Diagram edits do not change behavioural requirements or generated documentation. See [tracker instructions](../../tracker/README.md#use-cases-และ-workflow-diagram).

The internal catalog also offers preliminary **Frontend / Backoffice / Integration** tabs, requested by the owner. Tags overlap: external and internal actor participation uses the roles document, and integration tags require a named external system in the original use-case text. Generic “ระบบ” steps alone do not count. The data-subject actor may be internal or external. These are discovery navigation aids, **not confirmed screen ownership or API scope**. Classification reasons are visible in table tag tooltips; rules live in `tracker/usecase_channels.go`.

### Confirmation gate for development (owner request, 2026-10-30)

Each use case now has a human **Approve use case** action in the internal tracker. The audit record includes reviewer, time, note and hashes of the authoritative source and exact diagram revision. Agents may implement TNSU product behaviour only when the current approval API reports `approved: true`; an earlier confirmation is stale after a source change, save or rollback. Agents must not approve real use cases for the human. Discovery, documentation and internal tracker maintenance are exempt from this product implementation gate. See `AGENTS.md` and [tracker workflow](../../tracker/README.md#horizontal-layout-revisions-and-development-approval).

Workflow diagrams default to left-to-right and preserve snapshots of every save. Restoring a snapshot creates a new revision and requires confirmation again; source explorer files remain read-only through the tracker. Module group headers expose full names and can collapse/expand independently of channel filters.