GrottoCenter / grottocenter-api / 40732589200

91%

Build Type

push

github

Committed by web-flow

Commit Message

feat(document): support PDF page offsets for URL identifiers and attached files (#1936)

## 🤔 What

- One optional signed PDF page offset per PDF source: `t_document.identifier_pdf_page_offset` for the PDF URL in `identifier`, and `t_file.pdf_page_offset` for each attached file (migration `sql/9_27_2026_10_26_pdf_page_offset.sql`; `h_document` keeps the identifier offset in the history).
- Convention: `PDF position = printed page number + offset` (printed page 29 at PDF position 30 gives `+1`). Bibliographic `pages` are unchanged.
- Write: `identifierPdfPageOffset`, `newFilesMetadata[i][pdfPageOffset]` and `modifiedFiles[i][pdfPageOffset]` on `POST /documents` and `PUT /documents/{id}`; `identifierPdfPageOffset` on `PUT /documents/{id}/new-entities`.
- Read: `identifierPdfPageOffset` on documents and on the embedded `parent`, `pdfPageOffset` on files, as an integer or `null`, in details and in `?requireUpdate=true` previews. An article's details carry its parent's identifier and file offsets, with no extra request.
- OpenAPI updated (request fields, `Document`, `ParentDocument`, `File`, new `NewFileMetadata`, 400 cases).

Closes #1936

## 🤷‍♂️ Why

Printed page numbers often differ from positions in the PDF (cover, front matter, extract of a larger publication). The frontend (GrottoCenter/grottocenter-front#1588) must open the right PDF page while citations keep the printed numbers.

## 🔍 How

- `api/utils/parsePdfPageOffset.js`: omitted (`undefined`) → unchanged; `null` or `""` (multipart) → explicit clear; integer or integer string between -2147483647 and 2147483647 → offset, `0` included; anything else → 400.
- `DocumentService.resolveIdentifierPdfPageOffset` / `readNewFileOffsets` / `readChangedFiles`, called by the controllers **before** the document is created or any file is uploaded:
  - the identifier offset needs an effective `url` identifier. The URL itself is not inspected, since many PDF URLs have no `.pdf` extension;
  - a file offset nee... (continued)

Coverage Stats

6327 of 7377 branches covered (85.77%)

Branch coverage included in aggregate %.

132 of 137 new or added lines in 6 files covered. (96.35%)

1 existing line in 1 file now uncovered.

11615 of 12675 relevant lines covered (91.64%)

258570.66 hits per line