DocumentPosition
DocumentPosition (segment/pozycja dokumentu) to typ opisujący jedną pozycję lub segment w ramach DocumentReference (tablica position[]). Stosuje się w CRM, księgowości, kadrach oraz przy dokumentach magazynowych niebędących ruchem towaru (np. zapotrzebowanie). Przyjęcie i wydanie towaru oraz pozostałe ruchy stanów nie są modelowane jako DocumentReference ani DocumentPosition — wyłącznie InventoryDocument i jego pozycje. Wzorowany na FHIR Observation.component (code + value[x] + rozszerzenia).
DocumentPosition nie jest osobnym zasobem (DomainResource) – jest typem zagnieżdżonym w DocumentReference.
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.
- Księgowość – pozycja opisu do dekretacji, podsumowanie VAT itd.; dekretacja faktury w kanonie API.ERP — wyłącznie PostingInstruction (postingLine[]), nie pozycja na DocumentReference.
- Magazyn (bez ruchu towaru) – np. wiersze zapotrzebowania na dokumencie typu żądanie; ruch towaru → zawsze InventoryDocument.
- Kadry – segment dokumentu kadrowego (szkolenie, umowa, uprawnienie itd.).
Różnice między domenami są wyrażane przez code (rodzaj segmentu) oraz użycie value[] w profilu.
2. Zawartość (struktura)
| Nazwa | Kard. | Typ | Opis |
|---|---|---|---|
| positionNo | 0..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). |
| code | 0..1 | CodeableConcept | Rodzaj segmentu/pozycji – słownik document-position-type: finance (accounting-item, vat-summary) · warehouse (order-line, vat-summary-line, goods-receipt-line, goods-issue-line) |
| value | 0..* | ValueItem | Wartości złożone pozycji, każda z opcjonalnym type: elementy ilościowe, pieniężne, kody, odniesienia, tekst, liczby, wartości logiczne. |
| status | 0..1 | CodeableConcept | Status pozycji/wiersza – warehouse/document-position-status |
| attachment | 0..* | Attachment | Załączniki pozycji (skan, plik) |
Wartości pozycji: value[]
Pozycja niesie wartości wyłącznie tablicą value[] (0..): każdy element to ValueItem z opcjonalnym type (CodeableConcept, słownik value-item-type: finance · warehouse) i jednym wariantem value*: valueQuantity, valueMoney, valueString, valueInteger, valueBoolean, valueCodeableConcept, valueReference. Ilość i cena to dwa elementy value[] z różnymi type*.
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 lub identifier; opcjonalnie type =
ProductDefinition, display = nazwa. - Egzemplarz (partia, numer seryjny, data ważności; np. reklamacja z serią) – nie jest osobnym zasobem: valueReference wskazuje ProductDefinition, a cechy egzemplarza idą jako kolejne elementy value[] z odpowiednim type (np. numer partii jako valueString).
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, lub referencja z type=ProductDefinition).
3. Mapowanie: przestrzeń → code → wartości
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 elementy value[] są typowo używane.
| Przestrzeń | code (słownik) | value[] |
|---|---|---|
| Magazyn | order-line (warehouse) |
ilość (valueQuantity) + cena (valueMoney) + produkt (valueReference → ProductDefinition) |
| Magazyn | vat-summary-line (warehouse) |
netto, VAT, brutto (valueMoney po stawce) + stawka VAT (valueCodeableConcept) |
| Magazyn | goods-receipt-line, goods-issue-line (warehouse) |
metryka pozycji dokumentu; sam ruch towaru → InventoryDocument |
| Księgowość | accounting-item (finance) |
opis do dekretacji (valueString) – nie dekret faktury (→ PostingInstruction.postingLine) |
| Księgowość | vat-summary (finance) |
netto, VAT (valueMoney), stawka VAT (valueCodeableConcept) |
| Kadry | – | dokument skrzynki kadrowej nie używa pozycji; treść w attachment[] i attribute[] nagłówka |
Dzięki temu jeden typ DocumentPosition z tablicą value (lista ValueItem z typem) pokrywa CRM, księgowość, dokumenty magazynowe oparte na DocumentReference (bez ruchu towaru) i kadry; profile ustalają, które 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 + 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 value[] z type |
| FHIR | Observation.component | code + value[x] (jedna wartość na component); u nas value[] (lista ValueItem z type) |