Przejdź do treści

DocumentPosition

DocumentPosition (segment/pozycja dokumentu) to typ opisujący jedną pozycję lub segment w ramach Document (tablica position[]). Stosuje się w CRM, FK, HR, EOD oraz przy dokumentach WMS niebędących ruchem magazynowym (np. zapotrzebowanie). Przyjęcie i wydanie towaru (GR / GI) oraz pozostałe ruchy stanów nie są modelowane jako Document ani DocumentPosition — wyłącznie InventoryDocument i InventoryDocumentPosition. Wzorowany na FHIR Observation.component (code + value[x] + rozszerzenia).

DocumentPosition nie jest osobnym zasobem (DomainResource) – jest typem zagnieżdżonym w Document.

1. Cel: jedna struktura dla wielu przestrzeni

Wspólny zestaw pól pozwala bez mnożenia typów obsłużyć m.in.:

  • CRM – wiersz zamówienia (produkt, ilość, cena), segment oferty, kontakt.
  • FK – wiersz faktury na Document (legacy/unifikacja), linia podsumowania VAT itd.; dekretacja faktury w kanonie API.ERP — wyłącznie PostingInstruction (postingLine[]), nie decree-line na Document.
  • WMS (bez GR/GI) – np. wiersze zapotrzebowania na dokumencie typu żądanie; GR/GI → zawsze InventoryDocument.
  • HR – segment dokumentu kadrowego (szkolenie, umowa, uprawnienie itd.).
  • EOD – segment obiegu (powiązanie z dokumentem źródłowym, krok workflow).

Różnice między domenami są wyrażane przez code (rodzaj segmentu) oraz użycie pól value i attribute w profilu.

2. Zawartość (struktura)

Nazwa Kard. Typ Opis
code 1..1 CodeableConcept Rodzaj segmentu/pozycji (invoice-line, order-line, decree-line, vat-summary-line, request-line, hr-segment itd. — nie kody pozycji GR/GI; system document-position-type)
positionNo 1..1 integer Numer pozycji w dokumencie; unikalny w ramach dokumentu, numerowany od 1. Służy do referencji z zewnątrz (np. w danych księgowych).
valueQuantity 0..1 Quantity Jedna wartość niepieniężna (ilość szt., waga, czas – UCUM); dla kwot pieniężnych używać valueMoney
valueMoney 0..1 Money Jedna kwota pieniężna (value + currency); cena, kwota netto, suma itd.
value 0..* ValueItem Lista wartości pozycji z opcjonalnym type: elementy ilościowe, pieniężne, kody, odniesienia, tekst, liczby, wartości logiczne. Uzupełnienie dla pól valueQuantity i valueMoney — gdy potrzeba wielu wartości lub wartości z typem.
status 0..1 CodeableConcept Status pozycji/wiersza (np. otwarta, zrealizowana, anulowana)
attachment 0..* Attachment Załączniki do pozycji (skan, plik)
attribute 0..* Attribute Właściwości specyficzne dla profilu (np. drugi numer konta, data dostawy, lokalizacja)

Wartości pozycji: valueQuantity, valueMoney i value[]

Pozycja może nieść wartości trzema polami:

  • valueQuantity (0..1) – pojedyncza wartość niepieniężna (ilość, waga, czas – UCUM).
  • valueMoney (0..1) – pojedyncza kwota pieniężna (value + currency).
  • value[] (0..) – lista elementów ValueItem; każdy element niesie opcjonalny type* (CodeableConcept) i dokładnie jeden wariant value*: valueQuantity, valueMoney, valueString, valueInteger, valueBoolean, valueCodeableConcept, valueReference.

Pola valueQuantity i valueMoney pokrywają najprostsze przypadki (jedna wartość); value[] stosuje się gdy potrzeba wielu wartości, wartości z typem lub kombinacji.

Referencja do produktu: Pozycja dokumentu odnosi się do pozycji katalogu lub do konkretnej instancji przez element value[] z wariantem valueReference:

  • ProductDefinition – gdy wystarczy pozycja katalogu (np. zamówienie, faktura bez partii/serii): reference (np. ProductDefinition/123) lub identifier; opcjonalnie type = ProductDefinition, display = nazwa.
  • Product – gdy wymagana jest konkretna instancja (partia, numer seryjny, data ważności; np. reklamacja z serią): reference (np. Product/456) lub identifier; opcjonalnie type = Product, display = nazwa lub identyfikator partii/serii.

W tablicy value[] może być wiele elementów z wariantem valueReference (np. produkt/definicja, kontrahent); konwencja lub profil ustala, który element odnosi się do produktu (np. przy order-line, invoice-line, lub referencja z type=ProductDefinition / type=Product).

3. Mapowanie: przestrzeń → code → pola

Poniższa tabela pokazuje, jak ten sam DocumentPosition jest używany w różnych przestrzeniach i dla różnych code. Dla każdego wiersza: które pola value*/attribute są typowo używane.

Przestrzeń code (przykład) valueQuantity valueMoney value[] attribute / profil
CRM order-line ilość cena (jedna) ilość + cena + status linii + produkt, kontrahent (gdy obie lub wiele) data dostawy, jednostka
CRM offer-line ilość cena (jedna) ilość + cena + typ pozycji + produkt (gdy obie) ważność oferty
FK invoice-line – – ilość, cena jedn., netto, VAT, stawka VAT, wariant, produkt, kontrahent odliczenie VAT
FK decree-line (nie stosować do dekretacji faktury w kanonie API.ERP) — — Dekret faktury → PostingInstruction.postingLine
FK vat-summary-line – – netto, VAT (po stawce), stawka VAT, odliczenie –
WMS (GR / GI / MM — nie przez Document) — — — Pozycje ruchu: InventoryDocumentPosition
HR hr-segment – – typ segmentu, status, pracownik, szkolenie, umowa, treść daty, uprawnienia (profil)
EOD workflow-segment – – status kroku, dokument źródłowy, komentarz data, użytkownik (profil)

Dzięki temu jeden typ DocumentPosition z valueQuantity, valueMoney (pola skalarne) i tablicą value (lista ValueItem z typem), oraz attribute pokrywa CRM, FK, dokumenty WMS oparte na Document (bez GR/GI), HR i EOD; profile ustalają, które pola wartości są wymagane i jakie code są dozwolone.

4. Zgodność z systemami wzorcowymi

System Odpowiednik pozycji/segmentu Uwagi
UBL 2.3 InvoiceLine, OrderLine, DespatchLine… ID, Quantity, LineExtensionAmount, Item (Reference), Price; mapowanie na code + valueQuantity + valueMoney + value[]
OAGIS Line w BOD (np. PurchaseOrderLine) Quantity, Amount, ItemID, Party; odpowiednik code + value*
SAP Pozycja dokumentu (FI line, MM/SD item) Kwota, konto, materiał, magazyn; odpowiednik valueQuantity, valueMoney, value[]
FHIR Observation.component code + value[x] (jedna wartość na component); u nas valueQuantity / valueMoney (skalarne) oraz value[] (lista ValueItem); osobno attribute

5. Odniesienia