21a844cb8a
A previous `git pull --rebase origin main` dropped 177 local commits,
losing 3400+ files across admin-v2, backend, studio-v2, website,
klausur-service, and many other services. The partial restore attempt
(660295e2) only recovered some files.
This commit restores all missing files from pre-rebase ref 98933f5e
while preserving post-rebase additions (night-scheduler, night-mode UI,
NightModeWidget dashboard integration).
Restored features include:
- AI Module Sidebar (FAB), OCR Labeling, OCR Compare
- GPU Dashboard, RAG Pipeline, Magic Help
- Klausur-Korrektur (8 files), Abitur-Archiv (5+ files)
- Companion, Zeugnisse-Crawler, Screen Flow
- Full backend, studio-v2, website, klausur-service
- All compliance SDKs, agent-core, voice-service
- CI/CD configs, documentation, scripts
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
11 KiB
11 KiB
Zeugnis-System - Architecture Documentation
Overview
The Zeugnis (Certificate) System enables schools to generate official school certificates with grades, attendance data, and remarks. It extends the existing School-Service with comprehensive grade management and certificate generation workflows.
Architecture Diagram
┌─────────────────────────────────────┐
│ Python Backend (Port 8000) │
│ backend/frontend/modules/school.py │
│ │
│ ┌─────────────────────────────────┐ │
│ │ panel-school-certificates │ │
│ │ - Klassenauswahl │ │
│ │ - Notenspiegel │ │
│ │ - Zeugnis-Wizard (5 Steps) │ │
│ │ - Workflow-Status │ │
│ └─────────────────────────────────┘ │
└──────────────────┬──────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ School-Service (Go, Port 8084) │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────────────────┐ │
│ │ Grade Handlers │ │ Statistics Handlers │ │ Certificate Handlers │ │
│ │ │ │ │ │ │ │
│ │ GetClassGrades │ │ GetClassStatistics │ │ GetCertificateTemplates │ │
│ │ GetStudentGrades │ │ GetSubjectStatistics│ │ GetClassCertificates │ │
│ │ UpdateOralGrade │ │ GetStudentStatistics│ │ GenerateCertificate │ │
│ │ CalculateFinalGrades│ │ GetNotenspiegel │ │ BulkGenerateCertificates │ │
│ │ LockFinalGrade │ │ │ │ FinalizeCertificate │ │
│ │ UpdateGradeWeights │ │ │ │ GetCertificatePDF │ │
│ └─────────────────────┘ └─────────────────────┘ └─────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ PostgreSQL Database │
│ │
│ Tables: │
│ - grade_overview │
│ - exam_results │
│ - students │
│ - classes │
│ - subjects │
│ - certificates │
│ - attendance │
└─────────────────────────────────────┘
Zeugnis Workflow (Role Chain)
The certificate workflow follows a strict approval chain from subject teachers to school principal:
┌──────────────────┐ ┌──────────────────┐ ┌────────────────────────┐ ┌────────────────────┐ ┌──────────────────┐
│ FACHLEHRER │───▶│ KLASSENLEHRER │───▶│ ZEUGNISBEAUFTRAGTER │───▶│ SCHULLEITUNG │───▶│ SEKRETARIAT │
│ (Subject │ │ (Class │ │ (Certificate │ │ (Principal) │ │ (Secretary) │
│ Teacher) │ │ Teacher) │ │ Coordinator) │ │ │ │ │
└──────────────────┘ └──────────────────┘ └────────────────────────┘ └────────────────────┘ └──────────────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
Grades Entry Approve Quality Check Sign-off & Lock Print & Archive
(Oral/Written) Grades & Review
Workflow States
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ DRAFT │────▶│ SUBMITTED │────▶│ REVIEWED │────▶│ SIGNED │────▶│ PRINTED │
│ (Entwurf) │ │ (Eingereicht)│ │ (Geprueft) │ │(Unterzeichnet) │ (Gedruckt) │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│ │ │ │
▼ ▼ ▼ ▼
Fachlehrer Klassenlehrer Zeugnisbeauftragter Schulleitung
RBAC Integration
Certificate-Related Roles
| Role | German | Description |
|---|---|---|
FACHLEHRER |
Fachlehrer | Subject teacher - enters grades |
KLASSENLEHRER |
Klassenlehrer | Class teacher - approves class grades |
ZEUGNISBEAUFTRAGTER |
Zeugnisbeauftragter | Certificate coordinator - quality control |
SCHULLEITUNG |
Schulleitung | Principal - final sign-off |
SEKRETARIAT |
Sekretariat | Secretary - printing & archiving |
Certificate Resource Types
| ResourceType | Description |
|---|---|
ZEUGNIS |
Final certificate document |
ZEUGNIS_VORLAGE |
Certificate template (per Bundesland) |
ZEUGNIS_ENTWURF |
Draft certificate (before approval) |
FACHNOTE |
Subject grade |
KOPFNOTE |
Head grade (Arbeits-/Sozialverhalten) |
BEMERKUNG |
Certificate remarks |
STATISTIK |
Class/subject statistics |
NOTENSPIEGEL |
Grade distribution chart |
German Grading System
| Grade | Meaning | Points |
|---|---|---|
| 1 | sehr gut (excellent) | 15-13 |
| 2 | gut (good) | 12-10 |
| 3 | befriedigend (satisfactory) | 9-7 |
| 4 | ausreichend (adequate) | 6-4 |
| 5 | mangelhaft (poor) | 3-1 |
| 6 | ungenuegend (inadequate) | 0 |
Grade Calculation
Final Grade = (Written Weight * Written Avg) + (Oral Weight * Oral Avg)
Default weights:
- Written (Klassenarbeiten): 50%
- Oral (muendliche Note): 50%
Customizable per subject/student via UpdateGradeWeights endpoint.
API Routes (School-Service)
Grade Management
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/school/grades/:classId |
Get class grades |
| GET | /api/v1/school/grades/student/:studentId |
Get student grades |
| PUT | /api/v1/school/grades/:studentId/:subjectId/oral |
Update oral grade |
| POST | /api/v1/school/grades/calculate |
Calculate final grades |
| PUT | /api/v1/school/grades/:studentId/:subjectId/lock |
Lock final grade |
Statistics
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/school/statistics/:classId |
Class statistics |
| GET | /api/v1/school/statistics/:classId/subject/:subjectId |
Subject statistics |
| GET | /api/v1/school/statistics/student/:studentId |
Student statistics |
| GET | /api/v1/school/statistics/:classId/notenspiegel |
Grade distribution |
Certificates
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/school/certificates/templates |
List templates |
| GET | /api/v1/school/certificates/class/:classId |
Class certificates |
| POST | /api/v1/school/certificates/generate |
Generate single |
| POST | /api/v1/school/certificates/generate-bulk |
Generate bulk |
| GET | /api/v1/school/certificates/detail/:id/pdf |
Download PDF |
Security Considerations
- RBAC Enforcement: All certificate operations check user role permissions
- Tenant Isolation: Teachers only see their own classes/students
- Audit Trail: All grade changes and approvals logged
- Lock Mechanism: Finalized certificates cannot be modified
- Workflow Enforcement: Cannot skip approval steps