Clarify why DocumentApi by-id endpoints require an explicit request-scope guard

[Copilot]

Document by-id endpoints were relying on behavior that looks similar to tenant API v2 scoping, but documents is not a v2-active table and Hibernate does not tenant-filter primary-key loads. This change makes that boundary explicit in DocumentApi and centralizes the guarded lookup used by by-id document endpoints.

• Problem made explicit

  • Document by-id reads/writes are loaded via findById(...)
  • @AccessControl authorizes capabilities, not tenant ownership
  • TxCtx does not scope this path yet because documents is not in openaev.tenant.active-tables

• Code change

  • Introduced findDocumentInRequestScope(ctx, documentId) as the single entrypoint for guarded by-id document lookup
  • Reused it across:
    • get
    • get tags
    • update tags
    • update
    • relations
    • download
    • delete

• Documentation / intent

  • Added focused Javadoc explaining why @Transactional + TxCtx is insufficient here
  • Kept assertDocumentInRequestScope(...) as the enforcement point for the current pre-v2 behavior

private Document findDocumentInRequestScope(TxCtx ctx, String documentId) {
  Document document =
      documentRepository
          .findById(documentId)
          .orElseThrow(() -> new ElementNotFoundException("Document not found"));
  assertDocumentInRequestScope(ctx, document);
  return document;
}

Original prompt

as part of tenant API v2 migration, i'm reviewing a PR in this branch with this description:
DocumentApi endpoints that take a document id now resolve the document within the request's tenant scope, the same way list and search endpoints are scoped. A document that belongs to another tenant gets the same 404 as a missing document.

Endpoints: get, get tags, update tags, update, relations, download and delete.

Details
The row is loaded by primary key, which the Hibernate tenant filter does not restrict, and accesscontrol checks capabilities. The new assertDocumentInRequestScope compares the document's tenant with the request TxCtx scope.
On the two PUT endpoints the scope check runs before the report-output rule, so a document outside the scope always answers 404.
A request with no scope (a caller without any tenant membership, on the non-prefixed route) is not checked and keeps today's behaviour; a document with no tenant is unaffected.
The non-prefixed X-Tenant-Ids route is handled with the v2 migration (see fix(multi-tenancy): attribute create writes from the request scope (#7958) #7959); the check itself reads the request scope and is not route specific.
Tests
DocumentByIdScopeTest (real stack, tenant path): for each endpoint, another tenant's document gets 404 and is left unchanged in the database, and a document of the request's tenant keeps working; plus the ordering of the report-output rule on both PUTs. DocumentByIdEmptyScopeTest pins the no-scope case. DocumentApiTest, AuditLoggerDocumentTest, ReportingApiTest and the multi-tenancy arch tests stay green.

Question: why dont we rely on @transactiona; + TxCtx filtering as all the toher pattern? why do we need "assertDocumentInRequestScope"

[github-actions]

📖 Documentation check — ✅ Passed

1 functional file(s), 0 doc file(s) changed.

No documentation gaps detected.