1. Wprowadzenie
2. Potrzeba: Zastosować PDF Annotator
3. Realizacja. Wariant 1
4. Realizacja. Wariant 2
5. Specyfikacja. Zadanie dla programisty
6. Tematy powiązane
1. Wprowadzenie
Adnotacja to inaczej dopisek, notatka, uwaga lub komentarz umieszczony na marginesie lub w tekście
Czym jest PDF Annotator?
To program komputerowy dla systemu Windows do dodawania notatek i adnotacji w plikach PDF.
Pozwala pisać i rysować odręcznie za pomocą piórka na tabletach.
[1] (https://www.grahl-software.com/en/),
[2] (https://www.pdfannotator.com/en/)
Główne funkcje
Komentarze i rysunki:
Wpisywanie tekstu, zakreślanie, rysowanie kształtów i linii.
Podpisy i formularze:
Wypełnianie i podpisywanie umów oraz dokumentów.
Edycja strony:
Wstawianie obrazów, numerów stron, nagłówków, stopek i znaków wodnych.
Trwałość adnotacji:
Zapisywanie notatek w pliku lub ich wytapianie na stałe w strukturę PDF
Słowo 'annotator' oznacza po polsku osobę, która tworzy adnotacje, komentarze objaśniające lub przypisy do tekstu
2. Potrzeba: Zastosować PDF Annotator
Umożliwić zastosowanie w Trawersie programu PDF Annotator do redagowania treści
plików PDF - załączników [&] w module dokumentów powiązanych.
Patrz też:
Załączniki [&]. Dokumenty powiązane
Wstępna analiza
W Trawersie już jest:
Mechanizm Dokumentów powiązanych / Załączników - pozwala łączyć pliki PDF
z konkretnymi rekordami: fakturami, zamówieniami, kartami KIM itd.
Z jednym rekordem można powiązać wiele plików.
PDF można otworzyć z poziomu Trawersa, np. przez F10-pokaż.
Sam Trawers nie renderuje PDF - przekazuje plik do programu skojarzonego z PDF w Windows/Linux.
To jest bardzo ważne, ponieważ oznacza, że zamiast zwykłego Acrobat Readera można użyć
programu potrafiącego edytować i komentować PDF, np. Adobe Acrobat, PDF-XChange itp.
Trawers potrafi również uruchomić program zewnętrzny i przekazać mu jako argument
nazwę pliku oraz nazwy załączników, wykorzystując urządzenie wyjściowe rodzaju [Polecenie].
Do tego Trawers ma już dość dobre zabezpieczenia załączników: osobno można przydzielać prawa:
Dopisywanie, Korekta, Usuwanie, Przeglądanie dla określonych grup załączników.
W Trawersie nie ma automatycznego wersjonowania załącznikow.
Co ciekawe, dokumentacja Trawersa zaleca już organizacyjnie, aby kolejne wersje plików
miały rosnącą numerację, datę zmiany i identyfikację autora.
Karta załącznika ma przy tym dane bardzo przydatne do takiego rozwiązania:
SYMOP - operator,
DATA - data załączenia,
CZAS - godzina załączenia,
PLIK - nazwa pliku,
NAZWA - opis.
Czyli część metadanych wymaganych do historii wersji już istnieje.
3. Realizacja. Wariant 1
Wariant 1 - można zrobić praktycznie od razu
Najprostszy wariant nie wymaga modyfikacji programu Trawers.
Proponozycja:
1. Utworzyć grupę załączników, np. `PA - PDF adnotowane`.
2. Nadać odpowiednim operatorom prawa: Przeglądanie + Dopisywanie,
a tylko wybranym Usuwanie.
3. Na stanowiskach zainstalować program do adnotowania PDF i skojarzyć z nim `.pdf`.
4. Operator wybiera PDF w załącznikach.
5. `F3-zapisz` kopiuje plik z katalogu załączników do `/trInOut`.
Trawers właśnie ten katalog przewiduje jako obszar dostępny dla użytkownika.
6. Operator otwiera PDF, zaznacza kwoty, dodaje komentarze, rysunki itd.
7. Zapisuje nową nazwę, np.:
`FZ_2026_008721_v01.pdf`
`FZ_2026_008721_v02.pdf`
`FZ_2026_008721_v03.pdf`
8. Przez `F8-dodaj` dodaje nowy plik jako kolejny załącznik.
Trawers zachowuje poprzednie wersje i zapisuje operatora oraz czas dodania.
Warto również ustawić poziom logowania operacji na załącznikach na poziom `[2]`.
Wtedy w kronice zapisywane są m.in. usuwanie, zmiana grupy, pobieranie,
zapis do \TrInOut oraz wyświetlanie załączników.
4. Realizacja. Wariant 2
Wariant 2 - rozwiązanie rozbudowane
To jest ciekawszy kierunek dla rozwoju Trawersa.
Można przygotować małą aplikację, roboczo:
TrPdfAnnotator
i wywoływać ją z Trawersa przez istniejący mechanizm `[Polecenie]`.
Schemat działania byłby taki:
Trawers -> Załączniki -> Adnotuj PDF -> TrPdfAnnotator -> edycja -> Zapis -> nowa wersja w Trawersie
Trawers przekazywałby do aplikacji np.:
`ZBIOR`
`KLUCZ / RefNo`
`PLIK`
`SYMOP`
czyli identyfikację rekordu, aktualnego PDF i operatora.
Aplikacja nie powinna nadpisywać oryginału. Przy `Zapisz` tworzyłaby:
`..._v002.pdf`
i wiązała nowy plik z tym samym rekordem Trawersa.
Można nawet wykorzystać bardzo interesujący mechanizm, który już występuje w Trawersie:
katalog synchronizowany rekordu.
Dokumentacja mówi, że każdy rekord/karta lub dokument mogący mieć załączniki
ma synchronizowany podkatalog, a Trawers automatycznie rozpoznaje pliki dodawane
i usuwane z takiego katalogu.
To może znacznie uprościć integrację:
`PDF v1` -> katalog dokumentu
`PDF v2` -> zapis przez Annotator do tego samego katalogu
`PDF v3` -> kolejny zapis
a Trawers automatycznie widzi kolejne pliki.
Wersjonowanie warto zrobić trochę lepiej
Nie opierać całej logiki wyłącznie na nazwach plików.
Dodać małą tabelę, np.
`PDFVERSION`
z polami:
`ZBIOR`
`KLUCZ`
`PLIK`
`VERSION`
`PARENT_VERSION`
`SYMOP`
`DATA`
`CZAS`
`COMMENT`
`STATUS`
Wtedy można pokazywać użytkownikowi:
> Faktura zakupu FA12345
>
> v4 - AA - 14.09.2026 15:32 - Sprawdzono kwotę VAT
> v3 - MK - 14.09.2026 14:05 - Uwagi do pozycji 3
> v2 - AA - 13.09.2026 11:42
> v1 - dokument oryginalny
i przycisk Otwórz najnowszą wersję.
Adobe PDF Embed API
Można również rozważyć inny kierunek, czyli
Adobe PDF Embed API / PDF Services, ale tutaj potrzebna
byłaby już aplikacja webowa lub odpowiedni komponent UI.
Nie próbować osadzać Adobe bezpośrednio w obecnym terminalowym ekranie Trawersa.
Znacznie czystsza architektura wyglądałaby:
Trawers -> funkcja Adnotuj PDF -> przeglądarka/miniaplikacja WWW -> Adobe PDF viewer-> zapis wersji -> Trawers
Trawers ma już możliwość uruchamiania zewnętrznego programu oraz przekazywania plików
jako parametrów, więc punkt wejścia do takiej integracji już istnieje.
Rekomendacje
Nie zaczynać od pełnej integracji Adobe.
Najpierw zrobić prototyp oparty na istniejących załącznikach + programie zewnętrznym
+ automatycznym tworzeniu nowej wersji PDF.
Trawers ma już około 70-80% infrastruktury potrzebnej do takiej funkcji:
powiązanie pliku z rekordem, operator/data/czas, grupy, uprawnienia, katalogi synchronizowane,
log oraz możliwość wywoływania programu zewnętrznego.
Dopiero drugim etapem byłoby zastąpienie zewnętrznego edytora osadzonym PDF Annotatorem,
aby użytkownik otrzymał doświadczenie praktycznie takie samo jak w Acumatica.
Następny krok - specyfikacja funkcji PDF Annotator dla Trawersa:
ekran, przyciski, struktura tabeli wersji, algorytm `Zapisz`, blokada równoczesnej edycji
i sposób wywołania przez `[Polecenie]`.
To może być materiał nadający się bezpośrednio jako zadanie dla programisty Trawersa.
NOTE: Specyfikacja rozbudowana - poniżej w .prg
5. Specyfikacja. Zadanie dla programisty
(Krótsza wersja specyfikacji w formie zadania dla programisty)
Zadanie: Adnotowanie i wersjonowanie PDFCel
Rozszerzyć istniejący mechanizm załączników Trawersa o możliwość
edycji/adnotowania plików PDF oraz automatycznego tworzenia kolejnych wersji dokumentu.
Założenia
Nie tworzymy nowego systemu przechowywania dokumentów. Wykorzystujemy obecne:
* załączniki powiązane z rekordami,
* grupy załączników i uprawnienia,
* pola operatora, daty i czasu,
* katalogi załączników / katalog synchronizowany,
* możliwość uruchomienia programu zewnętrznego.
Funkcja 'Adnotuj PDF'
Na liście załączników dodać operację:
> Adnotuj PDF
Po jej wybraniu program:
1. sprawdza, czy plik jest PDF,
2. sprawdza prawo użytkownika do przeglądania i dopisywania załączników,
3. otwiera aktualną wersję PDF w zewnętrznym edytorze/annotatorze,
4. po zapisie nie nadpisuje oryginału,
5. tworzy nowy plik, np.: `faktura_v0002.pdf`,
6. przypisuje go do tego samego rekordu Trawersa,
7. zapisuje operatora, datę i czas,
8. oznacza nową wersję jako aktualną.
Historia wersji
Dodać funkcję:
> Historia wersji
Widok:
```
Wer Data Operator Status Komentarz
4 15.09.2026 AA Aktualna Akceptacja
3 15.09.2026 MK Historia Poprawiono VAT
2 14.09.2026 AA Historia Uwagi
1 14.09.2026 AA Oryginał
```
Użytkownik powinien móc otworzyć dowolną wersję.
Dane wersji
Dodać tabelę, np. `PDFVERSION`, zawierającą minimum:
```
ROOTID
ZBIOR
KLUCZ
GRUPAID
PLIK
VERSION
PARENTID
SYMOP
DATA
CZAS
COMMENT
STATUS
```
`ROOTID` identyfikuje jeden logiczny dokument.
`PARENTID` wskazuje wersję, z której powstała kolejna wersja.
Równoczesna edycja
Jeżeli dwóch operatorów otworzy tę samą wersję:
```
v5
o- v6 AA
o- v7 MK
```
nie wolno nadpisywać zmian.
Drugi zapis należy zachować jako wersję równoległą i wyświetlić komunikat:
Podczas edycji powstała nowsza wersja dokumentu. Twoje zmiany zapisano jako osobną wersję.
Uprawnienia
Wykorzystać istniejące prawa do grup załączników:
* Przeglądanie - otwarcie PDF i historii,
* Dopisywanie - utworzenie nowej wersji,
* Korekta - zmiana komentarza / wskazanie wersji aktualnej,
* Usuwanie - usunięcie wersji.
MVP
Pierwsza wersja nie musi posiadać Adobe Embed.
Może działać:
```
Trawers
-> Adnotuj PDF
-> zewnętrzny program PDF
-> zapis nowego pliku
-> nowa wersja w Trawersie
```
W kolejnym etapie zewnętrzny program można zastąpić dedykowanym `TrPdfAnnotator` lub aplikacją WWW z osadzonym annotatorem PDF.
Kryteria odbioru
Funkcja jest gotowa, gdy:
* można otworzyć PDF z załącznika,
* zapis nie zmienia oryginału,
* powstaje kolejna wersja,
* nowa wersja jest przypisana do tego samego rekordu,
* zapisywany jest operator oraz data/czas,
* można przeglądać historię,
* wiadomo, która wersja jest aktualna,
* równoczesna edycja nie powoduje utraty danych,
* dotychczasowa obsługa zwykłych załączników działa bez zmian.
Tę wersję można już praktycznie wkleić jako zadanie do systemu zgłoszeń
programistycznych.