demo-epb/README.md

# demo-epb — Elektrische Parkbremse

Vollstaendige Demo des [slohmaier Dev Process](https://gitea.slohmaier.com/slohmaier/dev-process) anhand einer EPB-Steuergeraet-Software. Zeigt ASPICE 4.0 / ISO 26262-konforme Entwicklung in einem Monorepo: Anforderungen, Architektur, Code, Tests, Reviews, MISRA — alles auf einen Pull-Request-Klick verifizierbar.

> Diese Software ist **bewusst kein Produktivcode** — sie ist die Demonstration des Engineering-Verfahrens. Code-Umfang absichtlich klein, Prozess-Tiefe vollstaendig.

## Was die Demo zeigt

| Artefakt-Typ        | Anzahl | Pfad                |
|---------------------|--------|---------------------|
| Plaene (Word)       | 5      | `docs/*.docx`       |
| Audit-Artefakte (Word) | 3   | `docs/reviews/`, `docs/non-conformities/`, `misra/records/` |
| System-Anforderungen| 10     | `reqs/sys/`         |
| Software-Anforderungen | 25  | `reqs/swe/`         |
| System-Architektur  | 5      | `arch/sys/`         |
| Software-Architektur| 10     | `arch/swe/`         |
| Implementierte Komponenten | 3 (1×ASIL-D, 1×ASIL-B, 1×QM) | `src/` |
| Stub-Komponenten    | 7      | `src/stubs/`        |
| Unit-Tests          | 28     | `tests/unit/`       |
| CI-Pipeline         | 1      | `.gitea/workflows/` |

## Quick Start

```bash
git clone https://gitea.slohmaier.com/slohmaier/demo-epb.git
cd demo-epb

# Build + Tests
make test

# Mit Coverage (benoetigt lcov)
make coverage
open build/coverage-html/index.html

# Statische Analyse + MISRA (benoetigt cppcheck)
make static
make misra
```

## Gefuehrte Tour (~30 min)

### 1. Projektplanung
Start in `docs/`:
- **PID.docx** — Was wird gebaut und warum
- **SWE-Plan.docx** — Wie wird gebaut: Sprache, Standards, Branching, Review-Regeln, Coverage-Ziele pro ASIL
- **QA-Plan.docx** — Qualitaetsmassnahmen, Reviews, NC-Management
- **PM-Plan.docx**, **Test-Plan.docx** — Arbeitspakete + Teststrategie

### 2. Sicherheits-Logik (das ASIL-D Stueck)
`reqs/sys/SYS-001.md` → `arch/swe/SWA-002.md` → `src/apply_controller.c` → `tests/unit/test_apply_controller.c`

Das ist die Traceability-Kette: System-Sicherheitsziel → Software-Architektur → Code → Test.

### 3. Anforderungen + Architektur (Doorstop in Markdown)
- `reqs/sys/` und `reqs/swe/` — alle Anforderungen mit Mapping
- `arch/sys/` und `arch/swe/` — Architektur mit Mapping per `links:` im Frontmatter
- Eingebettete PlantUML-Diagramme rendern direkt in Gitea

### 4. Code mit Mapping-Tags
Jede `.c`-Datei traegt `@arch`, `@reqs` im Header:

```c
/**
 * @file apply_controller.c
 * @arch SWA-002
 * @reqs SWE-001 SWE-002 SWE-003 SWE-004
 *
 * ASIL: D.
 */
```

So ist Code -> Architektur -> Anforderung auf einen `grep` durchsuchbar.

### 5. Tests mit Anforderungs-Tags
`tests/unit/test_apply_controller.c` referenziert die Requirements per `@reqs`. CI mit Coverage-Report belegt, dass jede Anforderung getestet ist.

### 6. Audit-Artefakte
- `docs/reviews/REV-001.docx` — Review-Protokoll fuer die ASIL-D-Komponente
- `docs/non-conformities/NC-001.docx` — Beispiel einer Non-Conformity mit Korrekturmassnahme
- `misra/records/MISRA-REC-001.docx` — MISRA Deviation Record fuer eine bewusste Advisory-Abweichung

### 7. CI-Pipeline
`.gitea/workflows/validate.yml` — bei jedem Push laeuft:
1. Cppcheck (Static Analysis)
2. Cppcheck + MISRA-Addon
3. Build + Unit Tests
4. Coverage (gcov/lcov)
5. Doorstop-Traceability-Check

## Architektur-Ueberblick

```
                +----------------------+
                |     EPB ECU (SA-001) |
                |  +-----------------+ |
                |  | Safety Mgr (D)  | |
                |  +-----------------+ |
                |  | Apply Ctrl (D)  | |
                |  +-----------------+ |
                |  | Actuator Drv (B)| |
                |  +-----------------+ |
                |  | Wheel Speed (B) | |
                |  | Inclino (B)     | |
                |  +-----------------+ |
                |  | Switch DB (QM)  | |
                |  | Display (QM)    | |
                |  | Diag (QM)       | |
                |  | Service (QM)    | |
                |  | Logger (QM)     | |
                |  +-----------------+ |
                +----------------------+
                     |        |
              Aktor L         Aktor R
              (SA-002)        (SA-002)
```

## Format-Strategie

| Inhalt              | Format           | Begruendung                                     |
|---------------------|-------------------|-------------------------------------------------|
| Plaene + Audit-Doku | **Word** (.docx)  | Industriestandard fuer ISO-9001-Freigabe        |
| Requirements + Arch | **Markdown** (Doorstop) | Lebendig, diff-bar, Traceability per Skript |
| Code, Tests, CI     | C / YAML          | klar                                            |

Beide Welten gehen ueber `tools/`-Skripte ineinander ueber: Markdown ist Source of Truth, Word wird per pandoc daraus gebaut.

## Generatoren

| Skript                                | Zweck                                              |
|---------------------------------------|----------------------------------------------------|
| `tools/generate_doorstop_items.py`    | Erzeugt alle 50 Requirements + Arch-Elemente aus Strukturdaten |

## Referenzen

- [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — die Methodik
- ASPICE 4.0
- ISO 26262 (insbesondere Part 6 — Software)
- MISRA C:2012

## Lizenz

MIT — siehe [LICENSE](LICENSE).