juli06/training-software
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d2b673cc0f0804faa709f3ec36e201a0e188c8a8
training-software/docs/TRA-210-final-implementation-backlog.md
Paperclip CTO 8054c1e1e4 feat(TRA-233): Django M1 foundation scaffold 
- Environment-split settings: base/local/test/prod with django-environ
- Postgres + Redis + Celery wiring (broker, beat, result backend)
- All 9 domain app stubs: accounts, courses, cms, tracking, quizzes,
  training, certificates, reports, notifications
- api app: /healthz/ endpoint, custom DRF exception handler,
  SecurityAuditMiddleware, permissions/throttle/upload-validation stubs
- DRF global baseline: JWT+session auth, closed-by-default permissions,
  cursor/page pagination, drf-spectacular schema generation
- Dockerfile (multi-env build arg), docker-compose.yml (local),
  docker-compose.test.yml (CI-friendly tmpfs Postgres)
- pytest.ini with smoke + settings marker definitions
- tests/test_smoke.py: startup, URL resolution, healthcheck shape
- tests/test_settings_matrix.py: per-profile security assertions
- .github/workflows/ci.yml: test, lint, schema CI jobs
- .env.example with all required vars documented
- .gitignore

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-07 09:11:23 +02:00

10 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink