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. 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, 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

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.

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.

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

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

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:

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.

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.

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.