# 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 │ │ │ │ TransferApprovedGrades│ │ │ │ FinalizeCertificate │ │ │ │ LockFinalGrade │ │ │ │ GetCertificatePDF │ │ │ │ UpdateGradeWeights │ │ │ │ │ │ │ └─────────────────────┘ └─────────────────────┘ └─────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────────────────┐│ │ │ Grade Service Layer ││ │ │ ││ │ │ - ClassStatistics struct (average, pass_rate, at_risk_count, grade_distribution) ││ │ │ - SubjectStatistics struct (class average, best/worst, exam results) ││ │ │ - StudentStatistics struct (overall average, subject performance) ││ │ │ - Notenspiegel struct (grade 1-6 distribution) ││ │ └─────────────────────────────────────────────────────────────────────────────────────┘│ └─────────────────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ 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 | ### Permission Matrix | Role | ZEUGNIS | ZEUGNIS_ENTWURF | ZEUGNIS_VORLAGE | FACHNOTE | Actions | |------|---------|-----------------|-----------------|----------|---------| | FACHLEHRER | R | CRUD | R | CRUD | Create/Update grades | | KLASSENLEHRER | CRU | CRUD | R | CRUD | Approve class grades | | ZEUGNISBEAUFTRAGTER | RU | RU | RUU | RU | Quality review | | SCHULLEITUNG | R/SIGN/LOCK | RU | RU | R | Final approval | | SEKRETARIAT | RD | R | R | R | Print & archive | Legend: C=Create, R=Read, U=Update, D=Delete, SIGN=Sign-off, LOCK=Lock final ### VerfahrenType for Certificates ```python class VerfahrenType(str, Enum): # Exam types ABITUR = "abitur" KLAUSUR = "klausur" ... # Certificate types HALBJAHRESZEUGNIS = "halbjahreszeugnis" # Mid-year certificate JAHRESZEUGNIS = "jahreszeugnis" # End-of-year certificate ABSCHLUSSZEUGNIS = "abschlusszeugnis" # Graduation certificate ABGANGSZEUGNIS = "abgangszeugnis" # Leaving certificate ``` ## Statistics API ### Endpoints | 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 | ### Response Structures **ClassStatistics:** ```json { "class_id": "uuid", "class_name": "5a", "semester": 1, "average": 2.4, "pass_rate": 92.8, "at_risk_count": 2, "student_count": 25, "subjects": [ { "subject_id": "uuid", "subject_name": "Mathematik", "average": 2.8 } ], "grade_distribution": { "1": 3, "2": 8, "3": 10, "4": 5, "5": 2, "6": 0 } } ``` **Notenspiegel:** ```json { "class_id": "uuid", "subject_id": "uuid", "exam_id": "uuid", "distribution": { "1": 2, "2": 5, "3": 8, "4": 6, "5": 3, "6": 1 }, "total_students": 25, "average": 3.1, "median": 3.0 } ``` ## Frontend Components ### Certificate Panel (`panel-school-certificates`) Located in: `backend/frontend/modules/school.py` Features: - **Statistik-Karten**: Overview cards showing class average, pass rate, at-risk students - **Notenspiegel Chart**: Bar chart visualization of grade distribution (1-6) - **Workflow-Status**: Visual display of certificate approval chain - **Student Table**: List of students with grades, attendance, certificate status ### Zeugnis-Wizard (5 Steps) ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Zeugnis-Wizard Modal │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Step 1: Klasse auswaehlen │ │ ├── Dropdown: Klasse (5a, 5b, 6a, ...) │ │ ├── Dropdown: Halbjahr (1 oder 2) │ │ └── Vorschau: Anzahl Schueler, Durchschnitt │ │ │ │ Step 2: Noten pruefen │ │ ├── Tabelle: Schueler | Fach1 | Fach2 | ... | Status │ │ ├── Fehlende Noten markiert │ │ └── Edit-Moeglichkeit direkt in Tabelle │ │ │ │ Step 3: Vorlage waehlen │ │ ├── Dropdown: Bundesland (Niedersachsen, Bayern, ...) │ │ ├── Dropdown: Schulform (Gymnasium, Realschule, ...) │ │ └── Vorschau: Template-Preview │ │ │ │ Step 4: Bemerkungen │ │ ├── Textarea pro Schueler │ │ ├── Textbausteine / Vorlagen │ │ └── KI-generierte Vorschlaege (optional) │ │ │ │ Step 5: Zusammenfassung & Generieren │ │ ├── Uebersicht aller Einstellungen │ │ ├── Checkbox: Alle Zeugnisse generieren │ │ └── Button: Zeugnisse erstellen (mit Fortschrittsbalken) │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ## Seed Data Generator Located in: `school-service/internal/seed/` ### Usage ```bash # Run seed data generation go run cmd/seed/main.go -teacher-id= # Or with default teacher ID go run cmd/seed/main.go ``` ### Generated Data | Entity | Count | Details | |--------|-------|---------| | School Years | 3 | 2022/23, 2023/24, 2024/25 | | Classes per Year | 6 | 5a, 5b, 6a, 6b, 7a, 7b | | Students per Class | 15-25 | Realistic German names | | Subjects | 10 | Deutsch, Mathe, Englisch, ... | | Exams per Class/Subject | 3-5 | With grade distribution | | Attendance Records | Variable | 0-10 absence days | ### German Name Generator ```go var firstNames = []string{ "Anna", "Emma", "Mia", "Sophie", "Marie", "Lena", "Lea", "Emily", "Ben", "Paul", "Leon", "Luis", "Max", "Felix", "Noah", "Elias", ... } var lastNames = []string{ "Mueller", "Schmidt", "Schneider", "Fischer", "Weber", "Meyer", "Wagner", "Becker", "Schulz", "Hoffmann", "Koch", "Richter", ... } ``` ## File Structure ``` school-service/ ├── cmd/ │ ├── server/ │ │ └── main.go # Main server with all routes │ └── seed/ │ └── main.go # Seed data CLI ├── internal/ │ ├── config/ │ │ └── config.go │ ├── database/ │ │ └── database.go │ ├── handlers/ │ │ ├── handlers.go # Base handler │ │ ├── grade_handlers.go # Grade + Statistics endpoints │ │ └── certificate_handlers.go │ ├── services/ │ │ └── grade_service.go # Statistics calculations │ ├── models/ │ │ └── models.go │ └── seed/ │ └── seed_data.go # Fake data generator └── go.mod backend/frontend/modules/ └── school.py # Zeugnis-UI (panel-school-certificates) klausur-service/backend/ ├── rbac.py # RBAC with certificate roles └── tests/ └── test_rbac.py # RBAC unit tests ``` ## 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 | | POST | `/api/v1/school/grades/transfer` | Transfer approved grades | | PUT | `/api/v1/school/grades/:studentId/:subjectId/lock` | Lock final grade | | PUT | `/api/v1/school/grades/:studentId/:subjectId/weights` | Update grade weights | ### 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` | Get certificate | | PUT | `/api/v1/school/certificates/detail/:id` | Update certificate | | PUT | `/api/v1/school/certificates/detail/:id/finalize` | Finalize | | GET | `/api/v1/school/certificates/detail/:id/pdf` | Download PDF | | DELETE | `/api/v1/school/certificates/detail/:id` | Delete | | GET | `/api/v1/school/certificates/feedback/:studentId` | AI feedback | ## 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. ``` ## Integration with BYOEH The Zeugnis system can optionally integrate with BYOEH for: - AI-generated certificate remarks - Template suggestion based on student performance - Feedback text generation (`/certificates/feedback/:studentId`) ## Security Considerations 1. **RBAC Enforcement**: All certificate operations check user role permissions 2. **Tenant Isolation**: Teachers only see their own classes/students 3. **Audit Trail**: All grade changes and approvals logged 4. **Lock Mechanism**: Finalized certificates cannot be modified 5. **Workflow Enforcement**: Cannot skip approval steps ## Future Enhancements - [ ] PDF template editor (LaTeX/HTML) - [ ] Bundesland-specific templates (all 16 states) - [ ] Kopfnoten (head grades) support - [ ] Digital signatures for certificates - [ ] Parent portal access to certificates - [ ] Archive/retention policies