training-software/docs/TRA-210-final-implementation-backlog.md

# TRA-210 Final Implementation Plan and Execution Backlog (Django)

Source:
- Lastenheft from parent issue TRA-207 (2026-05-06)
- Constraint: backend is Django-first

## 1) Scope Boundaries

### v1 In Scope
- Course hierarchy: Course -> Module -> Lesson -> Page with ordering and required page dwell-time.
- CMS authoring for rich text, media uploads, PDF/download embeds, per-course/page theme settings.
- Server-side dwell-time enforcement with reconnect tolerance and manipulation heuristics.
- Quiz engine: SC/MC, short-answer regex/answer-set validation, attempts/time limits/pass thresholds.
- Training modes: online/offline/blended including trainer signoff and evidence support.
- OIDC login via Authentik with group-to-role mapping and object-level permissions.
- Certificate generation pipeline (LaTeX -> PDF), archive, verification endpoint via hash/QR.
- Reporting and CSV export (progress, attempts, pass/fail rates, time-on-page).
- Notifications (assigned/due/certificate events).
- Audit trail, accessibility baseline (WCAG 2.1 AA core), i18n framework (de/en), security hardening.

### Later Phases (Not v1)
- SCORM/xAPI import/export.
- Full external/public API coverage beyond required internal integrations.
- Advanced gamification.
- AI-generated content or long-form AI grading.
- Webcam proctoring.

## 2) Open Ambiguities and Risks
- Ambiguity: exact anti-manipulation threshold policy (focus loss, idle tolerance).
- Ambiguity: required certificate data retention/expiry windows per compliance policy.
- Ambiguity: blended evidence requirements (photo-only vs file set + metadata).
- Risk: short-answer false positives/negatives from regex-only grading.
- Risk: media pipeline complexity (transcoding, quotas, S3 latency).
- Risk: high-cardinality event tracking impacting DB/storage costs.

## 3) Milestones and Critical Path

### Milestone M1: Foundation and Access
- Deliver Django scaffold, OIDC, role/permission model, baseline infra.

### Milestone M2: Content and Tracking
- Deliver course model, CMS primitives, page dwell-time tracking + navigation gate.

### Milestone M3: Quiz and Assessment
- Deliver question bank, attempt engine, grading and policy controls.

### Milestone M4: Training Modes and Certification
- Deliver trainer workflows (offline/blended) and certificate pipeline.

### Milestone M5: Reporting, Notifications, Hardening
- Deliver analytics, exports, notifications, security/a11y/compliance hardening.

### Critical Path
- M1 auth/permissions -> M2 domain model + tracking -> M3 quiz engine -> M4 certification -> M5 reporting/hardening -> release.

## 4) Architecture Decisions Needed Now
- Use modular Django apps: `accounts`, `courses`, `cms`, `tracking`, `quizzes`, `training`, `certificates`, `reports`, `notifications`, `api`.
- Use DRF for API contract and permission gates.
- Use Celery + Redis for async jobs (certificate render, notifications, media tasks).
- Use PostgreSQL as system of record; S3-compatible storage for media/certificate artifacts.
- Use object-level authorization (e.g. django-guardian/rules).
- Use append-only audit event model for compliance-critical actions.
- Use presigned upload flow and strict file scanning/type/size controls.

## 5) Execution-Ready Implementation Issues

### TRA-210-I01 - Django Foundation and Environment Baseline
- Objective: create production-structured Django project with env split, Postgres, Redis, Celery wiring.
- Acceptance Criteria:
  - Local/dev/test environments run consistently.
  - Healthcheck endpoint and CI sanity checks available.
- Out of Scope: feature domain models.
- Test Notes: startup smoke tests; settings matrix tests.

### TRA-210-I02 - OIDC and Role Mapping
- Objective: implement Authentik OIDC login and group -> role synchronization.
- Acceptance Criteria:
  - OIDC login/logout works.
  - Group claim changes update local role bindings.
- Out of Scope: external SSO providers beyond Authentik.
- Test Notes: integration tests with mocked OIDC claims.

### TRA-210-I03 - Object-Level Authorization Matrix
- Objective: define and enforce permissions for courses, quizzes, attempts, reports, certificates.
- Acceptance Criteria:
  - Access control matrix documented and enforced in API/admin.
  - Unauthorized access attempts rejected.
- Out of Scope: enterprise ABAC policy engine.
- Test Notes: permission tests per role and object owner/non-owner.

### TRA-210-I04 - Core Course Domain Model
- Objective: implement Course -> Module -> Lesson -> Page schema with ordering and version fields.
- Acceptance Criteria:
  - Schema migrations succeed from clean DB.
  - Ordering and required-page constraints enforced.
- Out of Scope: SCORM packaging.
- Test Notes: migration, relation, and ordering constraint tests.

### TRA-210-I05 - CMS Content and Media Pipeline
- Objective: implement rich-text content blocks, media upload flows, embeds, and theme attributes.
- Acceptance Criteria:
  - Authors can create/update structured lesson pages with media.
  - Upload controls enforce size/type limits and scan hooks.
- Out of Scope: advanced WYSIWYG plugin ecosystem.
- Test Notes: upload endpoint tests and content rendering tests.

### TRA-210-I06 - Dwell-Time Tracking and Navigation Guard
- Objective: enforce minimum page dwell-time via server-side heartbeat/event accumulation.
- Acceptance Criteria:
  - Next-step progression blocked until required seconds met.
  - Reconnect tolerance prevents progress loss from brief disconnects.
- Out of Scope: webcam proctoring.
- Test Notes: event replay tests; anti-idle heuristic tests.

### TRA-210-I07 - Quiz Engine (SC/MC + Short Answer)
- Objective: implement question models, randomization, scoring, and short-answer validation.
- Acceptance Criteria:
  - SC/MC grading and short-answer validation work per quiz policy.
  - Shuffle/randomization reproducible per attempt seed.
- Out of Scope: AI grading.
- Test Notes: deterministic grading and edge-case validation tests.

### TRA-210-I08 - Attempt Policy Enforcement
- Objective: enforce attempt limits, timer, pass thresholds, and feedback mode controls.
- Acceptance Criteria:
  - Attempts lock after max usage.
  - Time-expired attempts auto-finalize.
- Out of Scope: adaptive testing algorithms.
- Test Notes: policy boundary tests and timer expiry tests.

### TRA-210-I09 - Training Modes and Trainer Signoff
- Objective: implement online/offline/blended completion state machine and trainer approval workflow.
- Acceptance Criteria:
  - Blended completion requires online pass plus trainer signoff.
  - Offline completion can be trainer-marked with evidence.
- Out of Scope: live conferencing tools.
- Test Notes: state transition tests and trainer action audits.

### TRA-210-I10 - Certificate Generation and Archive
- Objective: render certificates from LaTeX templates, store PDF, generate hash/QR verification metadata.
- Acceptance Criteria:
  - Certificate PDFs generated asynchronously and retriable.
  - Verification data stored immutably.
- Out of Scope: custom visual designer for templates.
- Test Notes: render job tests, hash consistency checks.

### TRA-210-I11 - Certificate Verification Endpoint
- Objective: provide public verification endpoint with minimal PII exposure.
- Acceptance Criteria:
  - Hash/QR lookup validates authenticity.
  - Response contains only approved verification fields.
- Out of Scope: full public user profile lookup.
- Test Notes: endpoint privacy and tamper tests.

### TRA-210-I12 - Reporting and CSV Export
- Objective: implement progress/completion/time/attempt reports with filterable CSV export.
- Acceptance Criteria:
  - Reports filter by date range, department, course.
  - CSV export matches UI aggregates.
- Out of Scope: BI dashboards outside app.
- Test Notes: aggregate accuracy tests and export format tests.

### TRA-210-I13 - Notification Service
- Objective: send assignment/due/attempt/certificate notifications (email + in-app queue hooks).
- Acceptance Criteria:
  - Trigger rules fire reliably for supported events.
  - Delivery status is auditable.
- Out of Scope: SMS/push channels.
- Test Notes: event-trigger and idempotency tests.

### TRA-210-I14 - Audit Logging and Compliance Controls
- Objective: capture auth, progression, attempts, trainer decisions, certificate issuance in audit trail.
- Acceptance Criteria:
  - Mandatory events are recorded with actor/object/timestamp.
  - Retention strategy configurable.
- Out of Scope: SIEM integration.
- Test Notes: required-event coverage tests.

### TRA-210-I15 - Security Hardening and Upload Defense
- Objective: implement CSRF/CSP/rate limits, secure headers, presigned upload policy, file scanning.
- Acceptance Criteria:
  - Security checklist passes for v1 baseline.
  - Abuse scenarios are rate-limited and logged.
- Out of Scope: zero-trust network rollout.
- Test Notes: security regression and abuse tests.

### TRA-210-I16 - Accessibility and Internationalization Baseline
- Objective: implement WCAG 2.1 AA essentials and de/en localization framework.
- Acceptance Criteria:
  - Keyboard navigation, alt text rules, contrast checks pass for core flows.
  - UI and content model support language switching.
- Out of Scope: full localization to additional languages.
- Test Notes: a11y audits and localization snapshot tests.

### TRA-210-I17 - Observability, SLOs, Backup and Release Readiness
- Objective: establish logs/metrics/alerts, backup policy, release checklist, and rollback runbook.
- Acceptance Criteria:
  - API p95 and error metrics visible.
  - Backup and restore drill documented and verified.
- Out of Scope: multi-region active-active architecture.
- Test Notes: synthetic monitoring and restore drill validation.

## 6) Cross-Functional Asks
- UX/Design: player UX for dwell-time feedback, quiz timer UX, trainer dashboard usability pass.
- CMO/Comms: certificate wording templates and notification copy review.
- Compliance: confirm retention/deletion policy and verification data exposure constraints.

## 7) Recommended Next Actions
1. Approve this decomposition baseline.
2. Split I01-I17 into execution issues and assign by milestone.
3. Start M1 immediately (I01-I03), with M2 design prep in parallel.