Przejdź do treści

Attribute

Attribute (atrybut) to typ danych oznaczający cechę opisaną kodem (rodzaj) i wartością – np. jednostka miary, stawka VAT, kolor, numer partii, data ważności. Używany w ProductDefinition (cechy definicji: jednostka, VAT, producent, grupa), Product (cechy instancji: batch-number, serial-number, expiry-date), Document (attribute[] – atrybuty dokumentu, np. podsumowanie pozycji: suma netto, VAT, brutto) oraz Location (attribute[] – cechy lokalizacji: powierzchnia, temperatura, typ strefy). Jedna struktura: code (rodzaj atrybutu) + value (ValueItem) — typ danych niosący opcjonalny rodzaj wartości (type: CodeableConcept) oraz dokładnie jeden wariant: valueQuantity, valueMoney, valueString, valueInteger, valueBoolean, valueCodeableConcept lub valueReference. Wzorowany na podejściu code + value[x] z FHIR (Observation.component).

Attribute nie jest zasobem (DomainResource) – jest typem zagnieżdżonym w tablicy attribute[] w ProductDefinition, Product, Document i Location. W sensie DDD to Value Object: brak własnej identyfikacji (id), tożsamość wyłącznie przez wartość (code + value), zagnieżdżenie w rodzicu.

1. Zakres i zastosowanie

Attribute służy do:

  • Cech definicji produktu – w ProductDefinition: unit-of-measure, vat-rate, color, size, training-duration, producer, product-group (code + value z wariantem valueCodeableConcept, valueQuantity dla ilości/miar, valueMoney dla kwot, valueReference dla odniesień).
  • Cech instancji produktu – w Product: batch-number, serial-number, expiry-date, production-date, location (code + value — typowo wariant valueString, valueCodeableConcept albo valueReference, zależnie od cechy).
  • Atrybuty dokumentu – w Document (attribute[]): np. podsumowanie pozycji faktury – total-net, total-vat, total-gross (code + value z wariantem valueMoney); system np. https://api-erp.kamsoft.pl/ns/document-attribute-type.
  • Cechy lokalizacji – w Location (attribute[]): np. powierzchnia (value z wariantem valueQuantity), temperatura, typ strefy (valueCodeableConcept); system np. https://api-erp.kamsoft.pl/ns/location-attribute-type.
  • Rozszerzalności – nowe rodzaje atrybutów przez code (system zależny od zasobu: product-attribute-type, document-attribute-type, location-attribute-type) bez zmiany struktury.

Reguła na poziomie modelu: code (1..1) i value (0..1, ValueItem). W ValueItem jest dokładnie jeden wariant value*; opcjonalnie type precyzuje rodzaj wartości (np. net, gross). Profil konformance może zawęzić dopuszczalne warianty dla konkretnego kodu cechy.

2. Zawartość (struktura)

Nazwa Kard. Typ Opis
code 1..1 CodeableConcept Rodzaj atrybutu (unit-of-measure, vat-rate, color, batch-number, expiry-date, producer… – system https://api-erp.kamsoft.pl/ns/product-attribute-type)
value 0..1 ValueItem Wartość cechy – opcjonalny type (CodeableConcept) oraz dokładnie jeden wariant value* (patrz tabela ValueItem poniżej)

ValueItem (struktura wartości)

ValueItem to typ polimorficzny: opcjonalny type precyzujący rodzaj wartości (np. net, gross) oraz dokładnie jeden wariant value* (wzór jak value[x] w FHIR). W JSON Schema odzwierciedlany jako oneOf nad wariantami.

Nazwa Kard. Typ Opis
type 0..1 CodeableConcept Rodzaj wartości (np. net, gross) – sensowne przy valueQuantity/valueMoney
valueBoolean 0..1 boolean Wartość logiczna
valueString 0..1 string Tekst lub data (np. ISO 8601)
valueInteger 0..1 integer Liczba całkowita
valueQuantity 0..1 Quantity Ilość / miara niepieniężna (UCUM)
valueMoney 0..1 Money Kwota pieniężna
valueCodeableConcept 0..1 CodeableConcept Wartość kodowana (np. stawka VAT 23%, kolor, kategoria)
valueReference 0..1 Reference Odniesienie (np. producent → Party)

Reguła: dokładnie jeden wariant value* w ValueItem; opcjonalnie type. Dla dat (expiry-date, production-date) używa się valueString (ISO 8601) lub valueCodeableConcept; rozszerzenie może dodać valueDate.

3. Przykłady code (system zależny od zasobu)

  • ProductDefinition: unit-of-measure, vat-rate, color, size, training-duration, producer, product-group (system product-attribute-type).
  • Product (instancja): batch-number, serial-number, expiry-date, production-date, location (system product-attribute-type).

4. Zgodność atrybutów z systemami ERP

Model atrybutów (code + value: ValueItem) pozwala uzupełnić dane z systemów ERP i odwrotnie – bez utraty informacji.

System Odpowiednik cech Mapowanie
SAP Characteristic (CLASS), Batch (Charge), Serial Number; Material master – jednostka, grupa, VAT code → Char. name / tabela; value.valueQuantity/valueMoney/valueString → wartość; value.valueReference → np. producent (Vendor/BP); batch-number, expiry-date w Product.attribute
Oracle EBS / Fusion Descriptive Flexfields (DFF), Item Attributes; Lot/Serial; UOM, Category, VAT code → DFF segment / Item Attribute; value.value* → wartość; value.type → precyzja wariantu (np. net/gross); Product.attribute → Lot/Serial attributes
UBL 2.3 Item Property (Name, Value); ClassifiedTaxCategory; AdditionalItemProperty code → Item Property name; value.valueString/valueCodeableConcept/valueQuantity → Value; Batch/Serial w ItemInstance
OAGIS Item IDs, Quantity, Amount, Classification; Lot/Serial w BOD code → Classification/Property; value.value* → wartość; ProductDefinition.attribute ↔ Item master; Product.attribute ↔ Lot/Serial
FHIR Observation.component (code + value[x]); Medication (batch, expirationDate) Bezpośrednie: code + value (ValueItem odpowiada value[x] z opcjonalnym type); warianty valueQuantity, valueCodeableConcept, valueString, valueReference

Podsumowanie: Ten sam zestaw danych (jednostka, VAT, partia, seria, data ważności, producent, grupa, cechy niestandardowe) da się wyrazić w naszym modelu i w SAP/Oracle/UBL/OAGIS. Różnice dotyczą nazewnictwa (code/system) i miejsca przechowania (Material vs Item vs Batch) – mapowanie jest możliwe w obie strony; atrybuty pozwalają uzupełnić dane z ERP (import do API) i eksportować do ERP (export z API).

5. Odniesienia