docs: README mit kompletter Tour durch Safety + Manuals + Reports

2026-05-12 00:56:24 -07:00
parent c54a9c55d2
commit 17910835ad
1 changed files with 114 additions and 85 deletions
@@ -1,23 +1,27 @@
 # 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.
+Vollständige Demo des [slohmaier Dev Process](https://gitea.slohmaier.com/slohmaier/dev-process) anhand einer EPB-Steuergerät-Software. Zeigt ASPICE 4.0 / ISO 26262-konforme Entwicklung im Monorepo: Anforderungen, Architektur, Code, Tests, Reviews, MISRA, Safety Case, Manuals — alles auf einen Pull-Request-Klick verifizierbar, alles in einem Release-Bundle.

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

 ## 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/` |
+| Kategorie | Inhalt |
+|-----------|--------|
+| **Pläne** (Word) | 5 (PID, PM-, QA-, SWE-, Test-Plan) |
+| **Safety-Doku** (Word) | 6 (HARA, Safety Case, FMEDA, MISRA-Compliance, Verification-Report, Tool-Qualification) |
+| **Manuals** (Word) | 2 (User-Manual, Service-Manual) |
+| **Audit-Artefakte** (Word) | 3 (Review-Protokoll, Non-Conformity, MISRA-Deviation-Record) |
+| **System-Anforderungen** | 10 in `reqs/sys/` (Markdown + Doorstop-Style) |
+| **Software-Anforderungen** | 25 in `reqs/swe/` |
+| **System-Architektur** | 5 in `arch/sys/` mit PlantUML |
+| **Software-Architektur** | 10 in `arch/swe/` mit PlantUML |
+| **Implementierte C-Komponenten** | 4 (Apply Ctrl D, Safety Mgr D, Actuator Drv B, Switch Db QM) |
+| **Stub-Komponenten** | 6 weitere (Header only) |
+| **Unit-Tests** | 41, alle grün |
+| **CI-Workflows** | 2 (validate + release) |
+| **CI-Artefakte** | Coverage HTML, Traceability Matrix, Diagramme SVG, Doxygen, Test-Report, Cppcheck-XML |
+| **Cross-Platform-Runner** | Linux + macOS + Windows |

 ## Quick Start

@@ -25,39 +29,67 @@ Vollstaendige Demo des [slohmaier Dev Process](https://gitea.slohmaier.com/slohm
 git clone https://gitea.slohmaier.com/slohmaier/demo-epb.git
 cd demo-epb

-# Build + Tests
-make test
+# Tests
+make test                  # 41 Tests, alle grün

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

-# Statische Analyse + MISRA (benoetigt cppcheck)
+# Test-Summary-Report (HTML)
+make test-report
+open build/test-report.html
+
+# Statische Analyse + MISRA (braucht cppcheck)
 make static
 make misra
+
+# API-Doku (braucht doxygen)
+make docs
+open build/api-doc/html/index.html
+
+# Traceability-Matrix (HTML)
+python3 tools/traceability.py publish docs/traceability
+open docs/traceability/index.html
+
+# PlantUML-Diagramme rendern (SVG)
+python3 tools/render_plantuml.py
 ```

-## Gefuehrte Tour (~30 min)
+## Geführte Tour (~30 min)

-### 1. Projektplanung
-Start in `docs/`:
+### 1. Projektplanung (Word)
+`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
+- **SWE-Plan.docx** — Sprache, Standards, Branching, Reviews, Coverage-Ziele
+- **QA-Plan.docx** — Qualitätsmaßnahmen, 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`
+### 2. Funktionale Sicherheit (Word — `docs/safety/`)
+- **HARA.docx** — Hazard Analysis & Risk Assessment. Leitet **ASIL-D** ab.
+- **Safety-Case.docx** — Argumentation in GSN-Style, warum die Sicherheitsziele erfüllt sind
+- **FMEDA.docx** — Pro-Komponente Failure Modes mit Diagnostic Coverage
+- **Tool-Qualification-Cppcheck.docx** — Tool-Qual für Cppcheck (TI2/TD2/TCL2)
+- **MISRA-Compliance-Statement.docx** — formaler Compliance-Nachweis
+- **Verification-Report.docx** — V-Modell rechte Seite zusammenfassend

-Das ist die Traceability-Kette: System-Sicherheitsziel → Software-Architektur → Code → Test.
+### 3. Manuals (Word — `docs/manuals/`)
+- **User-Manual.docx** — Fahrerhandbuch-Auszug (Apply, Release, Hill-Hold, LED-Codes)
+- **Service-Manual.docx** — Werkstatt-Doku mit UDS-DTCs, Service-Modus, Sensor-Prüfung

-### 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. Sicherheits-Logik (das ASIL-D Stück)
+Traceability-Kette:
+```
+reqs/sys/SYS-001.md  →  arch/swe/SWA-002.md  →  src/apply_controller.c  →  tests/unit/test_apply_controller.c
+```

-### 4. Code mit Mapping-Tags
-Jede `.c`-Datei traegt `@arch`, `@reqs` im Header:
+### 5. Anforderungen + Architektur (Doorstop in Markdown)
+- `reqs/sys/` + `reqs/swe/` — Anforderungen mit Mapping
+- `arch/sys/` + `arch/swe/` — Architektur mit Mapping per `links:` im Frontmatter
+- Eingebettete PlantUML-Diagramme rendern direkt in Gitea (UI) und als SVG im Release-Bundle
+
+### 6. Code mit Mapping-Tags
+Jede `.c`-Datei trägt `@arch`, `@reqs`, `@asil` im Header:

 ```c
 /**
@@ -69,76 +101,73 @@ Jede `.c`-Datei traegt `@arch`, `@reqs` im Header:
 */
 ```

-So ist Code -> Architektur -> Anforderung auf einen `grep` durchsuchbar.
+### 7. Tests mit Anforderungs-Tags
+`tests/unit/test_*.c` referenziert die Requirements per `@reqs`. Test-Report (`build/test-report.html`) macht das Mapping klickbar sichtbar.

-### 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.
+### 8. Audit-Artefakte
+- `docs/reviews/REV-001.docx` — Review-Protokoll für die ASIL-D-Komponente
+- `docs/non-conformities/NC-001.docx` — NC mit Korrekturmaßnahme
+- `misra/records/MISRA-REC-001.docx` — MISRA Advisory-Deviation

-### 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
+### 9. CI-Pipeline (`.gitea/workflows/validate.yml`)
+Bei jedem Push:
+1. **Cross-Platform Build + Test** auf Linux + macOS + Windows
+2. **Static Analysis** (Cppcheck)
+3. **MISRA-Check** (Cppcheck + MISRA-Addon)
+4. **Coverage** (gcov/lcov)
+5. **Traceability-Check** (bidirektional)
+6. **PlantUML-Render** (alle Diagramme als SVG)
+7. **Doxygen-API-Doc**
+8. **Test-Summary-Report**

-### 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
+Alles als Gitea-Artefakte abrufbar.

-## Architektur-Ueberblick
+### 10. Release-Workflow (`.gitea/workflows/release.yml`)
+Auf Tag-Push `v*.*.*`:
+- Vollständigen Build + alle Reports
+- Bündelt **Source-Archive + Artefakt-Archive** (CI-Output + alle Word-Docs)
+- Erzeugt Gitea-Release mit Release-Notes
+
+Beispiel: https://gitea.slohmaier.com/slohmaier/demo-epb/releases
+
+## Architektur-Überblick

 ```
-                +----------------------+
-                |     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)     | |
-                |  +-----------------+ |
-                +----------------------+
+                  EPB ECU (SA-001)
+       +----------------------------------+
+       | Safety Manager (D)               |  ← arch/swe/SWA-001.md
+       | Apply Controller (D)             |  ← arch/swe/SWA-002.md
+       | Actuator Driver (B)              |  ← arch/swe/SWA-003.md
+       | Wheel Speed Plausi (B) [stub]    |
+       | Inclino Filter (B) [stub]        |
+       | Switch Debouncer (QM)            |  ← arch/swe/SWA-006.md
+       | Display Manager (QM) [stub]      |
+       | Diag Manager (QM) [stub]         |
+       | Service Mode (QM) [stub]         |
+       | Logger (QM) [stub]               |
+       +----------------------------------+
              |                  |
-              Aktor L         Aktor R
-              (SA-002)        (SA-002)
+       Aktor L (SA-002)    Aktor R (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 |
+| Inhalt | Format | Begründung |
+|--------|--------|------------|
+| Pläne + Safety + Audit + Manuals | **Word** (.docx) | Industriestandard für ISO-9001-Freigabe |
+| Requirements + Architektur | **Markdown** (Doorstop-Stil) | Lebendig, diff-bar, Traceability per Skript |
 | Code, Tests, CI | C / YAML | klar |
+| Release-Bundle | tar.gz mit allem | Eine Datei für den Auditor |

-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 |
+Markdown ist Source of Truth, Word wird per pandoc daraus gebaut.

 ## Referenzen

- [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — die Methodik
+- [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — Methodik-Repo
 - ASPICE 4.0
- ISO 26262 (insbesondere Part 6 — Software)
+- ISO 26262 (insbesondere Part 2, 3, 5, 6, 8, 10)
 - MISRA C:2012

 ## Lizenz

 MIT — siehe [LICENSE](LICENSE).
-
-