HamidX/demo.courses

1# Deferred Runtime Verification2 3> **Purpose.** We are working in an **implementation-first, deferred-verification**4> workflow because of limited/expensive internet. Source code and static review5> proceed now; every command that needs installed dependencies, Docker images,6> network downloads, migrations, or a running stack is **recorded here and left7> `pending`** until connectivity is available.8>9> **Rules:**10> - Nothing below is marked `verified` until it has actually been executed and observed to pass.11> - Unexecuted tests are **not** considered passing.12> - When a check is later run, update its **Status** to `verified` (with date) or `failed` (with notes).13 14Status legend: `pending` (not yet run) · `verified` (run and passed) · `failed` (run and failed) · `removed` (eliminated architecture-wise).15 16---17 18## ✅ S3.1 & S4–S7b Verification Run — Results (2026-06-12)19 20**Environment / path:** local-runtime path chosen. Python 3.12.8 venv (`.venv/`) with the pinned backend requirements; PostgreSQL via the cached `postgres:16.6-alpine` Docker image (host `:5432`, persistent `pgdata` volume). Frontend runs locally (non-Dockerized). Python/Node Docker **base images were NOT pulled** — those build checks stay `pending`.21 22**Backend dependency install:** `Django 5.1.4, DRF 3.15.2, psycopg[binary] 3.2.3, django-environ 0.11.2, django-cors-headers 4.6.0, djangorestframework-simplejwt 5.3.1` (+ transitive: asgiref, pyjwt 2.13.0, sqlparse, tzdata, typing-extensions). Mutually compatible — installed and import-clean.23 24**Migrations:** `makemigrations` generated `accounts.0001` (CustomUser), `organizations.0001`, `students.0001`, `academics.0001+0002`, `common.0001` (OrgSequence), `attendance.0001` (AttendanceSession/Record/Submission), `payments.0001` (FeeCharge/Payment). `migrate` applied all (accounts before dependents; all `token_blacklist` migrations applied) on PostgreSQL. `makemigrations --check` → *No changes detected*. `manage.py check` → *0 issues*. Conditional `uniq_active_enrollment`, `uniq_org_teacher_membership`, and CheckConstraints (`enrollment_agreed_fee_gte_0`, `classroom_default_fee_gte_0`) generated. PostgreSQL confirmed (engine `django.db.backends.postgresql`); SQLite not used.25 26**Tests:** **139 tests, 0 failures, 0 errors** (all test modules run explicitly and passed: accounts, organizations, students, academics, attendance, payments, dashboard). 27- **Attendance tests** verify idempotency, version increment, 409 conflict on stale base version, cross-org denial, and role scoping.28- **Payments tests** verify debt calculation, OrgSequence receipt number generation, cross-org membership rejection, and zero/negative amount checks.29- **Dashboard tests** verify organization scoping, top debtor limit and ordering, recent payment limits, and role permission visibility.30 31**Verified groups → marking VERIFIED below:**32- S1-03..19, S1-21 verified (all dependencies, local migrations, check, health, admin, TypeScript, Vite, Tailwind, RTL, Vite proxy, and database persistence).33- S2-* and S2.1-* and S2.2-* (auth/CSRF/membership/fail-closed — all passing).34- S3-* except S3-08 (true concurrency race — functionally verified, load test pending).35- S4-*, S5-*, S6-*, S7a-*, S7b-* (verified through local run and build).36 37**Still `pending`:** S1-01 Docker backend image build (local path chosen); S1-20 Docker restart recovery (running locally); S3-08 concurrency load; Vercel deployment verification (future pending item).38 39**Removed checks:** S1-02, S1-03 (Docker frontend part), S1-15 (Docker frontend part) - frontend Dockerization is completely eliminated.40 41---42 43## Phase S1 — Project Skeleton44 45| # | Unverified assumption | Required command | Expected result | Dependency required | Risk if deferred | Status |46|---|---|---|---|---|---|---|47| S1-01 | Backend image builds | `docker compose build backend` | Image builds; pip installs succeed | python:3.12-slim, pip deps | Build/runtime breakage undiscovered | pending |48| S1-02 | Frontend image builds | — | — | — | — | removed |49| S1-03 | npm install resolves | `npm install` | All deps resolve, no peer conflicts | npm registry | Version conflicts undiscovered | verified (2026-06-12) |50| S1-04 | package-lock generation | (result of `npm install`) | `frontend/package-lock.json` created | npm | Non-reproducible installs | verified (2026-06-12) |51| S1-05 | shadcn dependency verification | build + render | Button renders via cva/radix-slot/tailwind-merge | npm deps | shadcn wiring wrong | verified (2026-06-12) |52| S1-06 | Django dependency install | `pip install -r requirements/dev.txt` | All backend deps install | pip | Version incompat (e.g. simplejwt×Django 5.1) | verified (2026-06-12) |53| S1-07 | CustomUser migration generation | `python manage.py makemigrations accounts` | Initial migration created against `accounts.CustomUser` | Django | Wrong/absent user migration | verified (2026-06-12) |54| S1-08 | AUTH_USER_MODEL runtime resolution | `python manage.py shell -c "from django.contrib.auth import get_user_model; print(get_user_model())"` | `apps.accounts.models.CustomUser` | Django | Default User leaked into schema | verified (2026-06-12) |55| S1-09 | token_blacklist migrations | `python manage.py migrate token_blacklist` | Blacklist tables created | Django, simplejwt | JWT logout/rotation unusable | verified (2026-06-12) |56| S1-10 | PostgreSQL migrate | `python manage.py migrate` | All migrations apply on Postgres | Django, Postgres | Schema never validated | verified (2026-06-12) |57| S1-11 | `manage.py check` | `python manage.py check` | System check: 0 errors | Django | Config errors hidden | verified (2026-06-12) |58| S1-12 | `makemigrations --check` | `python manage.py makemigrations --check --dry-run` | No missing migrations | Django | Drift between models/migrations | verified (2026-06-12) |59| S1-13 | Health endpoint smoke | `curl http://localhost:8000/api/v1/health/` | `{"status":"ok",...}` 200 | running backend | Endpoint broken | verified (2026-06-12) |60| S1-14 | Django admin smoke | open `http://localhost:8000/admin/` | Login page loads; user admin works | running backend | Admin misconfig | verified (2026-06-12) |61| S1-15 | Frontend TypeScript build | `npm run build` (`tsc -b`) | Type-checks pass | npm deps | Type errors hidden | verified (2026-06-12) |62| S1-16 | Vite build | `npm run build` | Production bundle builds | npm deps | Build breakage | verified (2026-06-12) |63| S1-17 | Tailwind compile | (part of build/dev) | Utility classes emitted; styles apply | tailwind/postcss | Styling broken | verified (2026-06-12) |64| S1-18 | RTL/LTR runtime switch | run dev; toggle language | `document.dir` flips rtl↔ltr | running frontend | Direction switch broken | verified (2026-06-12) |65| S1-19 | Vite proxy health call | run dev; observe Backend status | "online" via `/api/v1/health/` proxy | running stack | Proxy/CORS misconfig | verified (2026-06-12) |66| S1-20 | Docker restart recovery | `docker compose restart` | All services recover cleanly | Docker | Fragile orchestration | pending |67| S1-21 | pgdata persistence | `docker compose down` then `up`; query DB | Data survives restart | Docker volume | Data loss risk | verified (2026-06-12) |68 69---70 71## Phase S2 — Organizations & Accounts72 73| # | Unverified assumption | Required command | Expected result | Dependency required | Status |74|---|---|---|---|---|---|75| S2-01 | Models import cleanly | `python manage.py check` | 0 errors; apps load | Django | verified (2026-06-12) |76| S2-02 | Migrations generate | `python manage.py makemigrations` | Migrations created | Django | verified (2026-06-12) |77| S2-03 | Migrations apply | `python manage.py migrate` | Applied to DB | Django, Postgres | verified (2026-06-12) |78| S2-04 | Membership uniqueness | Integration test | `unique(user, organization)` enforced | Django, Postgres | verified (2026-06-12) |79| S2-05 | Login sets refresh cookie | `test_auth.py` | HttpOnly refresh cookie set | Django, simplejwt | verified (2026-06-12) |80| S2-06 | Refresh from cookie | `test_auth.py` | Rotated cookies issued | Django, simplejwt | verified (2026-06-12) |81| S2-07 | Refresh rotation blacklist | `test_auth.py` | Replayed refresh rejected | Django, simplejwt | verified (2026-06-12) |82| S2-08 | Logout clears cookie | `test_auth.py` | Blacklisted and cookie deleted | Django, simplejwt | verified (2026-06-12) |83| S2-09 | `me` returns membership | `test_auth.py` | Identity info returned | Django | verified (2026-06-12) |84| S2-10 | Inactive membership denied | `test_auth.py` | 403 active-membership check | Django | verified (2026-06-12) |85| S2-11 | Tenant scoping foundation | `test_scoping.py` | Scoped to request membership | Django | verified (2026-06-12) |86| S2-12 | Public org endpoint | `test_public_org.py` | Returns branding, public AllowAny | Django | verified (2026-06-12) |87| S2-13 | Admin pages load | open `/admin/` | Admin views register and render | Django | verified (2026-06-12) |88| S2-14 | `makemigrations --check` clean | `python manage.py makemigrations --check` | 0 missing migrations | Django | verified (2026-06-12) |89 90---91 92## Phase S2.1 — Membership context & cookie-auth hardening93 94| # | Unverified assumption | Required command | Status |95|---|---|---|---|96| S2.1-01 | Tokens carry membership claims | `test_auth.py` | verified (2026-06-12) |97| S2.1-02 | Token claim verification on access | `test_scoping.py` | verified (2026-06-12) |98| S2.1-03 | Multi-membership selection choice | `test_membership_selection.py` | verified (2026-06-12) |99| S2.1-04 | Selected-membership login | `test_membership_selection.py` | verified (2026-06-12) |100| S2.1-05 | Foreign membership selection denied | `test_membership_selection.py` | verified (2026-06-12) |101| S2.1-06 | Inactive membership/org selection denied | `test_membership_selection.py` | verified (2026-06-12) |102| S2.1-07 | Selected-membership refresh rotation | `test_membership_selection.py` | verified (2026-06-12) |103| S2.1-08 | Membership deactivation invalidates refresh | `test_membership_selection.py` | verified (2026-06-12) |104| S2.1-09 | Scoped queryset uses selected org | `test_scoping.py` | verified (2026-06-12) |105| S2.1-10 | CSRF cookie endpoint | `test_csrf.py` | verified (2026-06-12) |106| S2.1-11 | CSRF-protected login | `test_csrf.py` | verified (2026-06-12) |107| S2.1-12 | CSRF-protected refresh | `test_csrf.py` | verified (2026-06-12) |108| S2.1-13 | CSRF-protected logout | `test_csrf.py` | verified (2026-06-12) |109| S2.1-14 | JWT-only DRF default auth | `python manage.py check` | verified (2026-06-12) |110| S2.1-15 | Public serializer field allowlist | `test_public_org.py` | verified (2026-06-12) |111| S2.1-16 | `me` returns selected org context | `test_auth.py` | verified (2026-06-12) |112 113---114 115## Phase S2.2 — Fail-closed membership authorization116 117| # | Unverified assumption | Required command | Status |118|---|---|---|---|119| S2.2-01 | `/me` valid context | `test_me_authorization.py` | verified (2026-06-12) |120| S2.2-02 | `/me` deactivation check | `test_auth.py` | verified (2026-06-12) |121| S2.2-03 | `/me` org deactivation check | `test_me_authorization.py` | verified (2026-06-12) |122| S2.2-04 | `/me` missing membership claim denied | `test_me_authorization.py` | verified (2026-06-12) |123| S2.2-05 | `/me` foreign membership claim denied | `test_me_authorization.py` | verified (2026-06-12) |124| S2.2-06 | Organization claim mismatch denied | `test_me_authorization.py` | verified (2026-06-12) |125| S2.2-07 | DB role overrides stale role claim | `test_me_authorization.py` | verified (2026-06-12) |126| S2.2-08 | Default internal API membership gating | `test_endpoint_access.py` | verified (2026-06-12) |127| S2.2-09 | Public org endpoint AllowAny | `test_endpoint_access.py` | verified (2026-06-12) |128| S2.2-10 | Health endpoint AllowAny | `test_endpoint_access.py` | verified (2026-06-12) |129| S2.2-11 | Auth endpoint AllowAny overrides | `test_endpoint_access.py` | verified (2026-06-12) |130| S2.2-12 | Django Admin session unaffected | open `/admin/` | verified (2026-06-12) |131| S2.2-13 | Centralized request membership helper | `test_scoping.py` | verified (2026-06-12) |132 133---134 135## Phase S3 — Core Academic Models136 137| # | Unverified assumption | Required command | Status |138|---|---|---|---|139| S3-01 | New apps import cleanly | `python manage.py check` | verified (2026-06-12) |140| S3-02 | Migration generation | `python manage.py makemigrations` | verified (2026-06-12) |141| S3-03 | Migration apply | `python manage.py migrate` | verified (2026-06-12) |142| S3-04 | `makemigrations --check` clean | `python manage.py makemigrations --check` | verified (2026-06-12) |143| S3-05 | Admin loads | open `/admin/` | verified (2026-06-12) |144| S3-06 | Student per-org uniqueness | `test_models.py` | verified (2026-06-12) |145| S3-07 | Student-code generation | `test_models.py` | verified (2026-06-12) |146| S3-08 | Student-code RACE behavior | Concurrency load test | pending |147| S3-09 | Student API permissions | `test_api.py` | verified (2026-06-12) |148| S3-10 | Student cross-tenant denial | `test_api.py` | verified (2026-06-12) |149| S3-11 | Student teacher scoping | `test_api.py` | verified (2026-06-12) |150| S3-12 | Teacher membership validation | `test_models.py` | verified (2026-06-12) |151| S3-13 | Classroom same-org + constraints | `test_models.py` | verified (2026-06-12) |152| S3-14 | Enrollment conditional uniqueness | `test_models.py` | verified (2026-06-12) |153| S3-15 | Withdrawn re-enrollment | `test_models.py` | verified (2026-06-12) |154| S3-16 | Enrollment defaulting from classroom | `test_api_enrollment.py` | verified (2026-06-12) |155| S3-17 | Classroom default change doesn't mutate existing enrollment | `test_api_teacher_classroom.py` | verified (2026-06-12) |156| S3-18 | Role permission matrix | `test_api_enrollment.py` | verified (2026-06-12) |157| S3-19 | Teacher-own scoping | `test_api_teacher_classroom.py` | verified (2026-06-12) |158| S3-20 | Org client-injection blocked | `test_api.py` | verified (2026-06-12) |159| S3-21 | API smoke (routes resolve) | `curl` backend routes | verified (2026-06-12) |160| S3-22 | classroom students action | `test_api_enrollment.py` | verified (2026-06-12) |161 162---163 164## Phase S4 — Attendance Backend165 166- **Verified:** All attendance models (`AttendanceSession`, `AttendanceRecord`, `AttendanceSubmission`), services, validation rules, API routes, and idempotency / version bump behaviors have been fully tested and are verified as of **2026-06-12**.167 168## Phase S5 — Billing and Payments Backend169 170- **Verified:** Financial models (`FeeCharge`, `Payment`), OrgSequence-based server-side receipt number generation, debt calculations, API void/list endpoints, and permission matrices have been fully verified as of **2026-06-12**.171 172## Phase S6 — Dashboard API173 174- **Verified:** Dashboard API summary route `/api/v1/dashboard/summary/` returns correct organization-scoped, role-permission gated aggregations and is verified as of **2026-06-12**.175 176## Phase S7a — Frontend Design Foundation177 178- **Verified:** RTL-friendly Tailwind tokens, Vazirmatn bundling, layout shells (`AdminLayout`, `AuthLayout`, `PublicLayout`), PageHeader, StatCard, and helper components compile cleanly as of **2026-06-12**.179 180## Phase S7b — visual Prototypes181 182- **Verified:** Lazy-split visual prototypes at `/preview/attendance` and `/login` render with complete realistic mock data and are verified as of **2026-06-12**. The `/dashboard` route serves as the main dashboard (preview dashboard removed as duplicate).183 184---185 186## Future Pending Items187 188- **Vercel Deploy:** Deploy the compiled SPA to Vercel and verify `VITE_API_BASE_URL` env variable resolution and `vercel.json` rewrite routing.189