Dokumenty pionowe (verticals)
Warstwa pionowa Implementation Guide — konkretne profile dokumentów i kontrakty integracyjne, uzupełniająca oś poziomą (22 domeny w api-contracts.md §1–7).
Każdy wpis w rejestrze to samodzielny pakiet w podfolderze {slug}/ ze standardową strukturą (patrz _template/).
Odbiorcy: analitycy, architektura integracji, zespoły produktowe (KS-ZZL, KS-SOMED itd.).
Reguły pakietu pionowego
| Element | Opis |
|---|---|
Identyfikator (slug) |
kebab-case, np. mp, eod-bos |
| Typ nośnika | cda · rest-only · hybrid (CDA + REST) |
| Powierzchnie API | np. API.ERP, API.MED — jeden wspólny model kontraktu przy wielu API |
| Mapowanie domen | domain-taxonomy.md — indeks, bez wypełniania placeholderów domenowych |
| Terminologia | OID w profilu CDA; opcjonalnie ValueSet.url pod https://api-erp.kamsoft.pl/ns/{prefiks}-* |
| Status | draft · candidate · published |
Artefakty obowiązkowe
| Plik / katalog | Zawartość |
|---|---|
README.md |
indeks pionu: zakres, status, domeny, linki |
profile/ |
specyfikacja dokumentu (CDA HTML, OID) |
contracts/ |
kontrakt integracyjny (JSON schema, OpenAPI — według typu) |
scenarios/ |
przepływ procesowy |
Artefakty opcjonalne
| Plik / katalog | Zawartość |
|---|---|
models/ |
specyfikacja pól, diagram relacji |
samples/ |
przykładowe instancje XML/JSON |
reference/ |
materiały referencyjne (XSL, słowniki Excel) |
tools/ |
generator, testy smoke |
Rejestr dokumentów pionowych
| slug | Tytuł | Typ | API | Domeny (skrót) | Status | Ścieżka |
|---|---|---|---|---|---|---|
eod-bos |
EOD / FK + WMS (kanoniczne) | rest-only | API.ERP | 1, 2, 3, 4, 16 | published | canonical/README.md, openapi/API-ERP-Canonical-EOD.yaml; legacy: dokumentacja początkowa |
mp |
E-skierowanie medycyny pracy | hybrid (CDA v0.3) | API.ERP + API.MED | 15 (HR), 19 (integracja) | draft | mp/ |
Indeks skrócony: verticals-index.md.
Conformance (dokument pionowy)
Implementacja uznana za zgodną z pakietem verticals/{slug}/, gdy:
- Spełnia profil dokumentu opisany w
profile/(wersja profilu jawna w README pionu). - Stosuje kontrakt z
contracts/(JSON schema / OpenAPI — według typu). - Realizuje scenariusz z
scenarios/zgodnie z podziałem API (ERP emisja / MED intake itd.). - Stosuje konwencje z technical-conventions.md §14 (terminologia, namespace value setów).
Implementacje częściowe (np. tylko generacja CDA bez REST) należy jawnie opisać.
Dodanie nowego dokumentu pionowego
- Skopiuj _template/ →
{slug}/. - Uzupełnij
README.mdi artefakty w podkatalogach. - Dodaj wiersz do tabeli rejestru powyżej.
- Dodaj wpis w verticals-index.md.
- Jeśli jest scenariusz procesowy — nowa sekcja na końcu scenarios.md.
- Jeśli nowe prefiksy terminologii — uzupełnij technical-conventions.md §14.
- Dodaj pozycję w mkdocs.yml (nawigacja).