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) + jedno z pól value* (Quantity, Money, CodeableConcept, Reference, string lub valueItem – lista wartości dowolnego typu). 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 + valueCodeableConcept, Quantity dla ilości/miar, Money dla kwot, Reference).
  • Cech instancji produktu – w Product: batch-number, serial-number, expiry-date, production-date, location (code + valueString, valueCodeableConcept lub valueReference).
  • Atrybuty dokumentu – w Document (attribute[]): np. podsumowanie pozycji faktury – total-net, total-vat, total-gross (code + valueMoney); system np. https://api-erp.kamsoft.pl/ns/document-attribute-type.
  • Cechy lokalizacji – w Location (attribute[]): np. powierzchnia (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: code (1..1) określa rodzaj cechy; przynajmniej jedno z pól value* powinno być ustawione. Dla ilości/miary (niepieniężnej) – valueQuantity; dla kwoty pieniężnej – valueMoney; dla wielu wartości dowolnego typu (w tym Quantity/Money z opcjonalnym type) – valueItem; dla kodu/słownika – valueCodeableConcept; dla referencji – valueReference; dla tekstu/daty – valueString.

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)
valueQuantity 0..1 Quantity Jedna wartość niepieniężna (czas trwania, waga, ilość – UCUM)
valueMoney 0..1 Money Jedna kwota pieniężna (np. cena, limit); dla walut używać Money
valueItem 0..* AttributeValueItem Wiele wartości; każdy element – jeden typ (valueBoolean, valueString, valueQuantity, valueMoney, valueCodeableConcept, valueReference…); opcjonalnie type (CodeableConcept) dla Quantity/Money (np. net/gross)
valueCodeableConcept 0..* CodeableConcept Wartość kodowana (np. stawka VAT 23%, kolor, kategoria)
valueReference 0..* Reference Odniesienie (np. producent → Party)
valueString 0..1 string Tekst lub data w formacie tekstowym (np. numer partii, data ważności ISO 8601)

AttributeValueItem (jeden element valueItem): w każdym elemencie dokładnie jedno z pól value + opcjonalnie type*:

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 (UCUM)
valueMoney 0..1 Money Kwota pieniężna
valueCodeableConcept 0..1 CodeableConcept Wartość kodowana
valueReference 0..1 Reference Odniesienie

Reguła: przynajmniej jedno pole value (valueQuantity, valueMoney, valueItem, valueCodeableConcept, valueReference, valueString) powinno być ustawione. Dla dat (expiry-date, production-date) często 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; valueQuantity/valueMoney/valueString → wartość; 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* → wartość; valueItem → wiele wartości z type (np. net/gross); Product.attribute → Lot/Serial attributes
UBL 2.3 Item Property (Name, Value); ClassifiedTaxCategory; AdditionalItemProperty code → Item Property name; valueString/valueCodeableConcept/valueQuantity → Value; Batch/Serial w ItemInstance
OAGIS Item IDs, Quantity, Amount, Classification; Lot/Serial w BOD code → Classification/Property; value* → wartość; ProductDefinition.attribute ↔ Item master; Product.attribute ↔ Lot/Serial
FHIR Observation.component (code + value[x]); Medication (batch, expirationDate) Bezpośrednie: code + valueQuantity, valueCodeableConcept, valueString, valueReference; valueItem = wiele componentów w jednym atrybucie

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