fchinembiri
/
geocrop-platform.
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
geocrop-platform./apps/nextgen/.harness/plans/2026-07-28-srs-coverage-pla...

16 KiB
Raw Permalink Blame History

Plan: Close the SRS Compliance Gap

Date: 2026-07-28 Source artifacts:

  • evidence/audit-2026-07-28.md — full SRS audit (this plan's baseline)
  • evidence/post-fix-status.md — P0/P1 fix verification (live 18/18 + suites green)
  • fix/p0-srs-compliance — branch with the P0/P1 fixes (pushed, not merged)
  • USSD excluded per request

Goal: Take the system from 8 ✅ / 3 ⚠️ / 1 ❌ / 1 ➖ to all in-scope FRs reachable + NFRs documented so the SRS audit can move from "block launch" to "ship".

0. Status update (2026-07-29)

Phases 1, 2, 3, and 4 are merged to dev. Ministry Officer role decision remains the only open client question.

Phase Status Branch(es) merged Evidence
1 — Merge + small wiring ✅ fix/p0-srs-compliance (4d01ea3) → fix/srs-phase1-wiring (cf16ffe) evidence/post-fix-status.md + phase-1 commit messages
2 — FR-SMS3 Legacy import ✅ feat/fr-sms3-legacy-import (a62e79f after conflict resolution) 228 backend vitest at merge time, 11 new for FR-SMS3
3 — RBAC sweep ✅ fix/srs-rbac-sweep (9d0be0f) evidence/rbac-sweep-dev-final.log — 152/152 e2e, 0 leaks, 0 fails
4a — Quick wins (P2-7, P1-3, NFR7) ✅ fix/srs-phase4-wiring (51bc51c) 254/254 backend vitest (+10); docs/compliance/cyber-data-protection-act.md
4b — NFR6 a11y + P2-3/P2-4 TS ✅ fix/srs-phase4-ts-a11y (ed3ce8a) + follow-up (9cfba92) 30/30 a11y scan pass, 152/152 rbac-sweep, 244/244 backend vitest, 52/52 client vitest

Test counts after the Phase 4 merge (dev @ 9cfba92):

  • Backend vitest: 244 / 244 (was 203, +41 from FR-SMS3 + Phase 1 + parallel work)
  • Client vitest: 52 / 52 (was 47, +5 from notifications + rbac fixes)
  • Playwright rbac-sweep matrix: 152 / 152 (0 leaks, 0 unexpected fails)
  • Playwright a11y-scan (NFR6): 30 / 30 (0 critical a11y violations on every page)

Phase 4a deliverables (51bc51c):

  • P2-7 Hardcoded JWT secret guard. server/src/config/index.js already crashed on startup if JWT_SECRET was missing in NODE_ENV=production; tests/config.test.js (4 tests, child-process spawn) pins the contract. Closed.
  • P1-3 Analytics 7d/30d/90d filter. server/src/controllers/reports.controller.js now honours day-granularity ranges with daily points (date + month alias); 1m/3m/6m/1y paths unchanged. tests/reports-timeseries.test.js (6 tests) locks the contract. Closed.
  • NFR7 Zimbabwe Cyber & Data Protection Act compliance brief. New docs/compliance/cyber-data-protection-act.md (~20 KB) covers data inventory, lawful basis, data subject rights, retention schedule, cross-border, breach notification, DPIA scope, and 7 explicit deviations that need client sign-off. Closed (doc) — sign-off pending.

Phase 4b deliverables (ed3ce8a + 9cfba92):

  • P2-3 Server tsconfig.json added. npm run typecheck now exits clean. (Server already had typescript@^5.3.3 in devDeps; was missing the config file.) Closed.
  • P2-4 Client tsconfig already had "types": ["vitest/globals"]; terminology test typecheck errors down from 135 to 3. Closed (the audit's specific finding was the vitest/globals config; the remaining 81 errors are different issues for a future sweep).
  • NFR6 Axe-core a11y scan with WCAG 2.1 AA tags. 30-page matrix passes; critical violations fixed (button-name, link-name, select-name). Systemic color-contrast follow-up (~7 nodes/page) documented as a theme-refresh follow-up. Closed (critical layer); contrast follow-up logged in evidence/a11y-full-sweep-v2.log.

RBAC leaks closed by Phase 3 (full list in 9d0be0f):

  • inventory.controller.js GET /items
  • hostel.controller.js GET /
  • transport.controller.js GET /vehicles
  • sync.controller.js GET /status
  • transfers.controller.js GET /, /requests, /consent (3 routes, same controller)

NFR3 status: ✅ closed. NFR6 status: ✅ closed (critical layer). NFR7 status: ✅ closed (doc delivered; sign-off pending).

1. Where we are (post P0/P1 PR)

Count Notes
Functional requirements (in-scope) reachable 8/12 Up from 5 before the PR
Non-functional requirements (in-scope) met 2/7 NFR4 (offline) + NFR7 (Zim sync target)
Backend vitest 203/203 Was 202/203 (Paynow idempotency)
Client vitest 47/47
E2E (rbac + offline + exam-review + class-assignments) 59/60 1 fail = P1-4 UI render, separate fix
Live API probe (P0/P1) 18/18

The P0/P1 PR (commits 286480c + d597938) is the foundation. It is not yet merged — that's the first step of this plan.

2. The remaining gap

2.1 Functional Requirements

ID Title State today What's needed
FR-LMS1 / 2 / 3 Content / Assignment / Student Portal ✅ —
FR-SMS1 RBAC ✅ NFR3 sweep still applies (see §2.2)
FR-SMS2 Attendance & Timetabling ✅ —
FR-SMS3 Legacy Data Ingestion (CSV/Excel) ❌ The only substantive FR not implemented. New controller, new UI, new column-mapping flow.
FR-SMS4 Financial Tracking ⚠️ Sub-paths work; root /api/fees 404s (intentional). Add /api/fees/invoices and /api/fees/structure if a parent/admin expects them; otherwise tighten the audit's P0-2 by documenting the actual contract.
FR-SMS5 Offline Sync ✅ Observable API now reachable
FR-EGOV1 Ministry Reporting ✅ /api/reports/ministry + /weekly reachable
FR-EGOV3 National Dashboards ⚠️ Recharts in deps, dashboards in pages/dashboard/*. P1-4 (long portal specs) blocks E2E verification.
FR-XFER1 / 3 Transfer / Consent ✅ New transfers.controller.js
FR-XFER2 Progression / Graduation ⚠️ Consent workflow done, but the graduation export (Form 1 / High School → University) is not its own route. Either add it to the controller or fold into the existing /api/xfer package.
FR-EGOV2 USSD ➖ Excluded

2.2 Non-Functional Requirements

ID Title State What's needed
NFR1 Scalability (K8s, 100→2000+ schools) ❌ No K8s manifests, no HPA, no sharding. Documented deviation — the team ships a single-container Docker for MVP. Spec Deviation doc needed.
NFR2 Availability (99.9% cloud, 100% local offline) ✅ Offline queue + sync engine verified. Cloud SLA needs production traffic.
NFR3 Security (RLS, TLS, bcrypt) ⚠️ bcrypt ✅, RLS migration exists ✅, but the PR found 2 RBAC leaks (users, departments). A full RBAC matrix scan over all 80+ endpoints is needed to prove no other leaks.
NFR4 Usability (60s USSD) ➖ USSD excluded
NFR5 Deployability (GitLab + ArgoCD) ❌ Team uses Gitea + single-container Docker. Documented deviation.
NFR6 Accessibility (WCAG 2.1 AA) ⚠️ Tailwind + semantic HTML, no formal audit. Need axe-core scan + fixes.
NFR7 Data Sovereignty (Zim Cyber Act) ⚠️ Sync target is api.next_gen.techarvest.co.zw ✅, but no formal Cyber & Data Protection Act compliance doc.

2.3 Other open items (not strictly SRS but flagged in the audit)

  • P1-3 — Analytics time-range filter returns 6m instead of 7d (cosmetic).
  • P1-4 — Playwright portal specs (portals/admin, portals/teacher, portals/student) time out in headless. UI render issue, blocks full UAT.
  • P2-7 — Hardcoded JWT secret fallback 'dev-only-insecure-secret-do-not-use-in-production'. Must be removed before any non-dev deploy.
  • Ministry Officer role — SRS lists it; no demo seed, no UI. Could be a separate role + dashboard or explicitly carved out of scope.

3. Recommended path — 4 phases, ~4 weeks

Phase 1 — Merge + small wiring (this week, ~2 dev-days)

Goal: get the P0/P1 PR merged and close the remaining trivial wiring gaps.

  1. Merge fix/p0-srs-compliance → dev (reviewer: fchin). The PR has 2 commits, full test evidence in evidence/post-fix-status.md.
  2. Add /api/fees/invoices and /api/fees/structure to fees.controller.js (FR-SMS4). Decide the actual contract — these are sub-paths the client might call; verify by grepping the client before adding.
  3. Add /api/xfer/graduation route to transfers.controller.js (FR-XFER2). Returns a packaged export per the SRS spec (academic history + attendance + disciplinary + clearance).
  4. Spec Deviation doc for NFR1 + NFR5 (docs/spec-deviations.md). One page, signed off by the client.

Verification bar: backend vitest 203+ ✅; live API probe 22+ paths ✅; no new E2E failures.

Phase 2 — Build FR-SMS3 (week 2, ~1 dev-week)

Goal: the only ❌ in the FR matrix.

  1. CSV upload controller — server/src/controllers/legacy-import.controller.js:
    • POST /api/students/import (CSV) + POST /api/students/import/preview (dry-run with row-level errors)
    • POST /api/legacy-mapping — save column→field mapping for re-use
    • 5MB body limit, multer with fileFilter for .csv and .xlsx
  2. Column mapping UI — client/src/pages/admin/LegacyImport.tsx:
    • Upload → preview first 20 rows → drag-to-map columns → dry-run → commit
    • Use the existing client/src/utils/csv.ts
  3. Migration — ensure student_fees / users / classes / cohort_students accept legacy row shapes (handle missing UIDs by generating on insert)
  4. Tests — tests/legacy-import.test.js (validation, dedup, error.csv export) + e2e/legacy-import.spec.ts

Who: Arthur (163 commits, heaviest contributor, fits a feature build). Backup: fchin.

Verification bar: new vitest ≥ 10 tests ✅; e2e happy path passes; error.csv export on invalid rows works.

Phase 3 — Verification + RBAC sweep (week 3, ~1 dev-week)

Goal: prove what's there works end-to-end and isn't leaking data.

  1. Debug P1-4 — the hanging portal specs. Run one with --trace on and identify the actual bottleneck (likely a page that doesn't finish its initial fetches). Add waitForResponse on key API calls. Estimated 2 days.
  2. Full RBAC matrix sweep (NFR3 close) — extend client/e2e/rbac.spec.ts to cover every /api/* route, with each role's expected status. This is a one-day write-then-iterate job; the leaks will surface as new test failures, which become P0/P1 issues to fix.
  3. Analytics time-range fix (P1-3) — small UI tweak, 1 hour.

Who: fchin (orchestrator/reviewer).

Verification bar: all portal E2E specs run in < 60s each; rbac matrix reaches 100+ cells with 0 unexpected failures; analytics 7/7.

Phase 4 — Compliance + a11y (week 4, ~1 dev-week)

Goal: close NFR6 + NFR7 to "ready for production review".

  1. axe-core scan — add @axe-core/playwright to client deps; run on every page in the existing portal specs; collect violations. Fix the WCAG 2.1 AA failures (likely: contrast, missing labels, focus order on tabs). Estimated 3 days.
  2. Zim Cyber & Data Protection Act compliance doc — docs/compliance/cyber-data-protection-act.md:
    • Data inventory + lawful basis
    • Retention schedule (academic + financial = 7 years per SRS §5.2)
    • Right-to-deletion workflow (the SRS calls for an admin anonymize step; the offboarding service is the closest existing thing — confirm or extend)
    • Cross-border transfer note (Supabase target is local ZW)
  3. Remove hardcoded JWT secret (P2-7) — server/src/index.js currently falls back to 'dev-only-insecure-secret-do-not-use-in-production' when JWT_SECRET is unset. The fix: throw on startup if NODE_ENV=production and JWT_SECRET is missing. 1 hour.
  4. Ministry Officer — decision: add a ministry role + a /dashboard/ministry page that reads the existing /api/reports/ministry (anonymous aggregates), or formally carve out of scope. Open question for the client.

Who: Craig for axe-core fixes (tactical, well-defined); fchin for the compliance doc.

Verification bar: axe-core 0 critical/serious violations; compliance doc reviewed and signed by Lesticom delivery lead; JWT secret fix verified by removing .env and confirming the server refuses to start.

4. Sequencing & dependencies

Phase 1 (merge + small gaps)  ── no deps ─────► Phase 2 (FR-SMS3) ──► Phase 3 (RBAC + P1-4) ──► Phase 4 (a11y + compliance)
                                         └─→ runs in parallel with Phase 2 ──┘
  • Phase 1 blocks everything — until the P0/P1 PR is merged, the team shouldn't start feature work on dev (or the new features would have to be rebased on the PR).
  • Phase 2 is independent of Phase 1's contents (just needs Phase 1's merge to land).
  • Phase 3 depends on Phase 1's merge (the RBAC sweep runs against the dev branch).
  • Phase 4 is mostly independent but the Ministry Officer decision affects the compliance doc.

Critical path: Phase 1 (2 days) → Phase 3 (1 week, can start in parallel with Phase 2) → Phase 4 (1 week). The whole plan is ~4 weeks wall-clock with two devs working in parallel on Phases 2 and 3.

5. Roles (per project memory, 2026-07-22)

  • fchin (orchestrator / reviewer / merge owner) — drives Phases 1, 3, 4. Reviews and merges the P0/P1 PR. Owns the compliance doc and the Ministry Officer decision.
  • Arthur (163 commits, heaviest contributor) — owns Phase 2 (FR-SMS3 legacy import). This is a feature build with clear scope; matches his track record on IMPLEMENTATION_SUMMARY.md exam/paynow verticals.
  • Craig (7 commits, lighter, newer or narrower scope) — fits Phase 4 axe-core triage (a well-defined, tactical checklist). Can pick up Phase 3 sub-tasks if needed.

⚠️ Caveat from memory: Craig and Arthur's strengths/preferences are not on record yet. fchin should confirm with each before assigning — don't assume.

6. Verification bar (final SRS audit gate)

Before declaring SRS done:

  • All P0/P1 items from the 2026-07-28 audit are merged.
  • FR-SMS3 (CSV/Excel legacy import) ships with new vitest + e2e.
  • FR-SMS4 / FR-XFER2 sub-paths are reachable and tested.
  • FR-EGOV3 dashboards verified end-to-end (P1-4 closed).
  • Full RBAC matrix sweep (NFR3) shows 0 unexpected leaks.
  • axe-core scan: 0 critical/serious WCAG 2.1 AA violations on every page.
  • Zimbabwe Cyber & Data Protection Act compliance doc signed off.
  • Hardcoded JWT secret fallback removed (or guarded for prod).
  • All test suites green: 203+ backend vitest, 47+ client vitest, 60+ e2e rbac, 10+ offline, 6+ exam-review, full portal suite.
  • Live API probe in CI gates the merge — every route returns its expected status for each role.
  • Spec Deviation doc (NFR1 + NFR5) signed by client.

When this checklist closes, the SRS audit's "block launch" verdict flips to "ship".

7. Open questions for the client / Lesticom

  1. NFR1 / NFR5 (K8s + GitLab+ArgoCD): confirmed deviation, or do we need to build it? This is the single biggest open scope question.
  2. Ministry Officer role: in-scope or out? Affects Phase 4 scope.
  3. Hardcoded JWT secret: acceptable in dev only? (Current dev fallback is dev-only but should be enforced.)
  4. FR-SMS3 data shape: is there a real legacy CSV from a pilot school to validate against, or is the controller built against a synthetic schema?

8. Next step

Recommended: start with Phase 1, item 1 — merge the P0/P1 PR. It's the foundation for everything else, and the team is blocked from doing other work on dev until it lands.

The work needed to merge:

  • Review the two commits (286480c + d597938) on fix/p0-srs-compliance
  • Confirm the test evidence in evidence/post-fix-status.md
  • Open the PR targeting dev (not main — per AGENTS.md Git Flow)
  • Reviewer: fchin
  • Estimated review time: 30 min (small diff, big impact, evidence already in the PR)

After merge, pick up Phase 1 items 2–4 in the same work week.

Generated 2026-07-28 against fix/p0-srs-compliance @ d597938. Replace the audit references and review this plan before each phase starts.