ad111d5e69
Docker Compose with 24+ services: - PostgreSQL (PostGIS), Valkey, MinIO, Qdrant - Vault (PKI/TLS), Nginx (Reverse Proxy) - Backend Core API, Consent Service, Billing Service - RAG Service, Embedding Service - Gitea, Woodpecker CI/CD - Night Scheduler, Health Aggregator - Jitsi (Web/XMPP/JVB/Jicofo), Mailpit Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
170 lines
11 KiB
Markdown
170 lines
11 KiB
Markdown
# 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
|
|
|
|
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
|