ValueSet

ValueSet (zbiór wartości) definiuje dopuszczalne kody dla konkretnego kontekstu biznesowego: pola, zasobu, profilu lub endpointu. Model jest inspirowany FHIR ValueSet i upraszcza ten wzorzec do potrzeb API.ERP.

Rozszerza DomainResource.

1. Zakres i zastosowanie

ValueSet służy do:

publikowania dopuszczalnych kodów dla pól typu CodeableConcept,
wersjonowania i stabilizacji słowników w integracjach,
jawnego mapowania kontekstu walidacji (np. typ dokumentu księgowego, status dokumentu majątkowego),
zarządzania słownikami bez zmiany modelu danych zasobów biznesowych.

Typowe scenariusze:

DocumentReference.type ograniczony do słownika typów dokumentów danej dziedziny,
FixedAsset.status ograniczony do ValueSet fixed-asset-status,
FixedAssetAllocation.dimension ograniczony do ValueSet fixed-asset-allocation-dimension.

2. Zawartość (struktura)

Oprócz elementów DomainResource (id, resourceType, meta, owner, comment, category, status, type, contained, attribute):

Nazwa	Kard.	Typ	Opis
identifier	0..*	Identifier	Identyfikatory ValueSet
url	0..1	uri	Kanoniczny URI ValueSet; w profilach słowników wdrożeniowych (§2d) pole wymagane
version	0..1	string	Wersja definicji
title	0..1	string	Tytuł
experimental	0..1	boolean	Eksperymentalny (wersja robocza)
immutable	0..1	boolean	Niezmienny po publikacji
description	0..1	string	Opis
compose	0..1	obiekt	Skład (include/system/concept) – dołączone systemy kodów i koncepty

2a. Struktura compose

Nazwa	Kard.	Typ	Opis
include	0..*	lista obiektów	Źródła kodów włączonych do ValueSet

2b. Struktura compose.include[]

Nazwa	Kard.	Typ	Opis
system	0..1	uri	URL code systemu (np. `https://api-erp.kamsoft.pl/vs/hr/document-type`)
version	0..1	string	Wersja code systemu
concept	0..*	lista obiektów	Jawnie dopuszczone koncepty (code/display)

2c. Struktura compose.include[].concept[]

Nazwa	Kard.	Typ	Opis
code	0..1	string	Kod dopuszczony w danym kontekście
display	0..1	string	Opis kodu do prezentacji

2d. Słowniki wdrożeniowe i ich profile

Część słowników ma treść ustalaną przy wdrożeniu, a nie w standardzie: typ zatrudnienia, typ dokumentu skrzynki kadrowej, poziom hierarchii przypisań organizacyjnych, specjalności, jednostki miary, cechy majątku, rodzaj majątku i typ dokumentu majątkowego. Każdy z nich ma własny profil rozpoznawany po url słownika, więc GET /v1/value-sets?url=… oddaje treść z właściwego źródła.

Słownik	Profil	`url`
typ zatrudnienia	`EmploymentTypeValueSet`	`https://api-erp.kamsoft.pl/vs/employment-type`
typ dokumentu skrzynki kadrowej	`InboxDocumentTypeValueSet`	`https://api-erp.kamsoft.pl/vs/hr-inbox-document-type`
poziom hierarchii przypisań	`OrganizationAssignmentHierarchyLevelValueSet`	`https://api-erp.kamsoft.pl/vs/organization-assignment-hierarchy-level`
specjalności	`SpecialtyValueSet`	`https://api-erp.kamsoft.pl/vs/specialty`
jednostki miary	`UnitOfMeasureValueSet`	`https://api-erp.kamsoft.pl/vs/unit-of-measure`
cechy majątku	`AssetAttributeValueSet`	`https://api-erp.kamsoft.pl/vs/esm-attribute`
rodzaj majątku	`AssetKindValueSet`	`https://api-erp.kamsoft.pl/vs/asset-kind`
typ dokumentu majątkowego	`AssetDocumentTypeValueSet`	`https://api-erp.kamsoft.pl/vs/esm-document-type`

Pozostałe słowniki pochodzą z pakietu terminologii i są jednakowe u wszystkich klientów. Schematy: profile kanoniczne.

3. Operacje

Odpowiedź to koperta { "items": [...], "nextToken": null }, stronicowana parametrami count (domyślnie 20) i offset (domyślnie 0).

Operacja	Parametry	Odpowiedź
`GET /v1/value-sets`	brak `url`	`200` lista słowników dostępnych w instalacji: `items[] = { "url", "version" }` (słowniki wdrożeniowe mają `version: null`)
`GET /v1/value-sets?url=<url>`	`url` (alias: `system`); dla słowników wdrożeniowych dodatkowo `id`, `owner` (`system\|value`), `status` (`system\|value`), `attribute[]` (`code\|value`)	`200` koperta z `ValueSet[]`; `404`, gdy słownik nie jest dostępny w instalacji

Zasób jest tylko do odczytu; brak POST/PATCH i tras z {id}.