PRD 12 · Non-functional requirements

Proposed design

This PRD has no screens of its own: it is shared platform material. The design for each feature sits in the "Proposed design" section that opens every module PRD (00 to 10 and 13 to 19).

1Purpose and scope

Trường Số handles children's personal data, guardians' phone numbers and money. This document fixes the minimum bar for how the product behaves under load, how it protects data, and how it proves who did what. It covers the web app (Next.js 16 on Cloudflare Pages / Node), the FLYER Rust API (/v3), the v2 GraphQL gateway, the upload service, and the notification integrations (Zalo OA / ZNS, email, in-app). It does not cover the FLYER learner apps (exam.flyer.us, study.flyer.us) beyond the identity boundary.

2Performance and capacity

Design rules

• Every list endpoint is paginated (page, limit ≤ 200) and server-filtered; no client-side filtering of full datasets.
• Aggregates that are read often (on-hand stock, student balance, attendance rate) are stored as maintained summaries, not computed on every read.
• Long operations (import, export, bulk notify, timetable generation) are jobs with status polling; the pattern already exists for ImportJob.
• ISR/caching is not used for tenant data; all tenant reads are per-request with the auth token.

3Security

Authentication

• Staff sign in with the FLYER account (email or phone + password, OTP for phone) as today; session token is sent as the existing Auth Token header through the app's /api/v3 proxy so the token never reaches third-party origins.
• Tokens expire after 30 days of inactivity; changing password revokes all other sessions.
• Owner and accountant roles must enable a second factor (OTP by phone or TOTP) before accessing Finance exports and Settings → Users. Phase 2.
• Parents authenticate in the parent portal by phone OTP only; no password. Each OTP is valid 5 minutes, 5 attempts.

Authorisation

• Every request is scoped by tenant (school_id / center_id) resolved from the token, never from a client-supplied id. Cross-tenant ids return 404, not 403.
• Permission codes (PRD 10) are checked server-side per endpoint; the UI hides controls but never relies on hiding.
• Branch scope: users carry a list of branch ids; data rows carry branch_id; list endpoints apply the intersection automatically.
• Teachers see only their own classes and the students in them; parents see only linked learners.

Application security

• OWASP ASVS level 2 as the checklist. Input validation on the API with typed schemas (already OpenAPI-driven).
• File uploads: allow-list of MIME types (pdf, jpg, png, xlsx, docx), 20 MB per file, virus scan before serving, private bucket with signed URLs valid 15 minutes.
• Rate limits: 60 write requests/minute per user, 10 OTP requests/hour per phone, 5 login failures then 15-minute lock.
• Secrets (Zalo OA tokens, SePay keys, e-invoice provider credentials) stored encrypted at rest per tenant; never returned to the client after save (masked as last 4 characters).
• CSP, HSTS, SameSite=Lax cookies, no inline third-party scripts on authenticated pages.
• Dependencies scanned weekly; critical CVEs patched within 7 days.

4Personal data protection (Decree 13/2023/ND-CP)

Trường Số processes basic personal data (name, birthday, phone, address) and sensitive data of children under 16 (health notes, if entered). The center is the data controller; FLYER is the processor. The product must make the controller's obligations easy to meet.

Marketing consent is separate from service consent. Lead capture forms that feed PRD 01 must have an explicit marketing tick box; the lead record stores marketing_consent_at.

5Role-based access control

The full matrix lives in PRD 10. The platform-level rules are:

• Permissions are strings <module>.<action>, served by GET /v3/crm/permissions-catalog (EXISTING for CRM; extended with the new modules). Roles are tenant-defined bundles; FLYER ships defaults that cannot be deleted but can be cloned.
• Effective permissions = union of role permissions, intersected with branch scope and with record ownership rules (teacher-own-class, sales-own-lead).
• The owner role cannot be removed from the last owner; ownership transfer is an explicit action with email confirmation.
• Elevation events (role change, permission edit, branch scope change) are audited and the affected user is notified in-app.

6Audit log

The CRM already exposes GET /v3/crm/customers/{id}/audit-logs for one entity. The platform requirement generalises it.

• Retention 5 years; exportable per tenant by owner as CSV.
• Mandatory audited actions: any write to finance (create, pay, void, refund, discount), attendance edits after the session day, student status changes, guardian contact changes, permission and role changes, exports of personal data, login from a new device.
• Viewer: Settings → Audit log (PRD 10) with filters actor, action, entity, date; row expands to a before/after diff.

7Backup, recovery and data portability

• Postgres: continuous WAL archiving, point-in-time recovery to any minute within 14 days; nightly full snapshot kept 35 days; monthly snapshot kept 12 months.
• Object storage (documents, receipts PDF): versioned bucket, 30-day soft delete.
• Recovery objectives: RPO 5 minutes, RTO 4 hours for a full region failure; tested twice a year with a written report.
• Tenant export: owner can request a full export (CSV per entity plus documents zip) from Settings; produced within 24 hours as a signed download; this also serves as the contractual off-boarding deliverable.
• Tenant deletion: 30-day grace period after contract end, then hard delete with certificate on request.

8Localisation (vi / en)

• The app ships two locales via next-intl: vi (default, product UI) and en. Every new string is added to both src/i18n/messages/vi.json and en.json under the module namespace; a CI check fails the build when keys diverge.
• API labels (statuses, permission labels, error messages) respect X-Locale, as existing endpoints already do.
• Dates display dd/MM/yyyy, times HH:mm 24-hour, timezone Asia/Ho_Chi_Minh by default per tenant; stored in UTC.
• Money: VND with no decimals, thousands separator "." in vi and "," in en; the symbol "đ" follows the number in vi.
• Vietnamese names: display order is "Họ Tên" as entered; sorting uses locale-aware collation (ICU vi) so "Đ" and "D" order correctly and accents are ignored in search.
• Phone numbers normalised to E.164 (+84...) on save; displayed as 0xxx xxx xxx.
• The Vietnamese UI glossary (link in hub) is the source of truth for labels; product copy uses the formal register (Quý phụ huynh, học viên, giáo viên).

9Accessibility and device support

• WCAG 2.1 AA for staff web: contrast ≥ 4.5:1 (the Cloud palette passes with ink #212B36 on white and #637381 for secondary text), focus rings visible, all actions reachable by keyboard, tables with proper headers, forms with labels and error text linked by aria-describedby.
• Status is never conveyed by colour alone; attendance chips carry text (Có mặt / Muộn / Vắng / Có phép) and an icon.
• Minimum supported viewport 1280 px for the staff console; the teacher attendance flow and the parent portal are mobile-first (360 px) and installable as a PWA. A native app is not in scope for phase 1.
• Browsers: last two versions of Chrome, Edge, Safari, Firefox; Zalo in-app browser for parent links.
• Font sizes follow the Cloud theme (13.5 px base in dense tables, 15.5 px in documents); a tenant-level "Cỡ chữ lớn" toggle scales the console 110%.

10Observability and operations

• Structured logs with tenant_id, user_id, request_id; no personal data in logs (phone and names masked).
• Error tracking on the front end with source maps; user-facing errors show a short code (e.g. TS-4021) that support can look up.
• Product analytics events listed per PRD are sent to the existing analytics pipeline with tenant_id and role; no student personal data in event payloads.
• Health endpoint /api/health checks database, queue and object storage.
• Feature flags per tenant (existing GET /v3/teacher/feature-configs pattern) gate phase 2 modules: attendance, finance v2, staff, inventory, parent portal.

11Release acceptance checklist

1. Performance targets in section 2 met on the seeded "Big Center" tenant, with the numbers recorded in the release note.
2. Security: automated dependency scan clean of critical issues; manual check of tenant isolation on every new endpoint (attempt cross-tenant id returns 404).
3. PDPD: consent capture present on every new data-entry point for guardians and students; anonymise flow tested.
4. Audit: every mandatory action in section 6 writes a log entry; verified by test plan (see test plan seed).
5. i18n: vi and en key sets identical; screenshots of both locales attached.
6. Accessibility: axe run with zero serious violations on the module's main screens; keyboard walkthrough recorded.
7. Backup: restore drill of the release week's snapshot succeeded on staging.