Expose reworked File Link (backlinks, fileid resolution, value validation) via OCS API

[Rikdekker]

Summary

The reworked File Link field type (v2.2.0: multiple files per field, stable fileid references, and a "Referenced by" backlink view) is only partially reachable through the OCS API. External integrations can store a raw File Link value, but cannot resolve paths to file ids, cannot read backlinks, and have no documented/validated value format to work against.

Sister issue to #82 (same theme: v2.2.0 features that lack external-API parity).

Current state

A File Link value is "<fileid>:<path>", multiple references joined with the ;# delimiter (e.g. 12:/a.pdf;#34:/b.docx). The fileid is canonical and survives renames/moves; the path is a display cache. A single bare path is still accepted (legacy). Contract lives in lib/Service/FileReferenceService.php (parseToken/parseValue/formatToken) and src/components/fields/filelinkUtils.js.

Gaps on the OCS surface:

1. Backlinks endpoint is web-only. GET /api/groupfolders/{groupfolderId}/files/{fileId}/backlinks (FieldController::getFileBacklinks) lives in the CSRF-protected web routes block, not ocs. External clients can't read which items reference a given file.

2. No path↔fileId resolution on OCS. FileReferenceService already has resolvePathToFileId(), resolveFileIdToInfo(), resolveMany(), and resolvePathToFileIdInGroupfolder(), but they're only reachable internally via the web controllers. An external client has no endpoint to turn a path into a valid fileid — yet it needs that to build a correct File Link value.

3. Value format is opaque/unvalidated over OCS. The existing OCS metadata write endpoints (POST /api/v1/.../metadata) store the File Link string as-is, so a client can set one — but only if it already knows the fileid, with no guarantee the fileid exists or lives in the right folder, and the "<fileid>:<path>" + ;# format is documented nowhere in the API.

Proposal

Mirror the existing Api*Controller + BaseOCSController pattern:

• GET /api/v1/groupfolders/{groupfolderId}/files/{fileId}/backlinks — OCS twin of the web backlinks endpoint (delegates to FileReferenceService::getBacklinks).
• GET /api/v1/files/resolve?path=... (and/or ?fileId=...) — resolve a path to { fileId, path, name, ... } and back, so clients can construct/verify File Link values. Delegates to the existing resolvePathToFileId* / resolveFileIdToInfo methods.
• For File Link writes through the existing OCS metadata endpoints: validate filelink values on save (each referenced fileid exists and is accessible / in-scope), accept either fileid- or path-form input and normalise to the canonical "<fileid>:<path>" (;#-joined) format via FileReferenceService::formatToken. Reject malformed values with a clear per-field error, consistent with how date values are already validated.

Implementation notes:

• New OCS endpoints in an ApiField/new controller extending BaseOCSController, delegating to FileReferenceService — no logic duplication, no behavioural drift vs. the web path.
• Same authorization model as the rest of the OCS API (app-password/Bearer, per-document permission inheritance).
• Document the value format and the new endpoints under docs/ (EN + NL docs/*.nl.md source-of-truth).

Why

External/migration tooling that links documents to each other (e.g. SharePoint "lookup"/related-document columns) needs to: resolve target paths to stable ids, write multi-file File Link values that survive renames/moves, and read backlinks — all without a browser session. This completes File Link parity on OCS, alongside fields/metadata/filters/views.

Acceptance criteria

• OCS backlinks endpoint (twin of the web one)
• OCS path↔fileId resolution endpoint(s)
• filelink value validation + path/fileid normalisation on OCS metadata writes
• Shared logic via FileReferenceService, no behavioural drift
• Value format + endpoints documented (EN + NL source)

Spun off from the v2.2.0 release work — targeted at a future release. Related: #82 (defaults via OCS), #73 (File Link multi-file feature).