@open-mercato/documents 0.6.8-develop.7016.1.4ed7b1e49d

package/src/modules/documents/backend/documents/templates/useTemplatesPage.tsx

@@ -0,0 +1,148 @@
+"use client"
+
+import * as React from 'react'
+import { apiCall, apiCallOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { DOCUMENTS_ENTITY_IDS } from '../../../lib/constants'
+import { normalizeTemplates, type TemplateRow } from '../components/templateUi'
+import { readBoolean, readNumber, readRecord } from '../documentUi'
+
+const TEMPLATE_MANAGEMENT_PAGE_SIZE = 100
+
+function normalizePageSize(value: number): number {
+  return Math.min(TEMPLATE_MANAGEMENT_PAGE_SIZE, Math.max(1, Math.floor(value)))
+}
+
+export function useTemplatesPage() {
+  const t = useT()
+  const { confirm, ConfirmDialogElement } = useConfirmDialog()
+  const requestId = React.useRef(0)
+  const [rows, setRows] = React.useState<TemplateRow[]>([])
+  const [page, setPage] = React.useState(1)
+  const [pageSize, setPageSizeState] = React.useState(TEMPLATE_MANAGEMENT_PAGE_SIZE)
+  const [total, setTotal] = React.useState(0)
+  const [totalPages, setTotalPages] = React.useState(1)
+  const [search, setSearch] = React.useState('')
+  const [isLoading, setIsLoading] = React.useState(true)
+  const [loadError, setLoadError] = React.useState<string | null>(null)
+  const [canManageTemplates, setCanManageTemplates] = React.useState(false)
+  const [reloadToken, setReloadToken] = React.useState(0)
+  const mutationContextId = 'documents-templates-list:mutation'
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    resourceId: string
+    retryLastMutation: () => Promise<boolean>
+  }>({ contextId: mutationContextId, blockedMessage: t('ui.forms.flash.saveBlocked') })
+  const refresh = React.useCallback(() => setReloadToken((value) => value + 1), [])
+  const refreshFromFirstPage = React.useCallback(() => {
+    setPage(1)
+    setReloadToken((value) => value + 1)
+  }, [])
+  const changeSearch = React.useCallback((value: string) => {
+    setIsLoading(true)
+    setLoadError(null)
+    setSearch(value)
+    setPage(1)
+  }, [])
+  const changePageSize = React.useCallback((value: number) => {
+    setPageSizeState(normalizePageSize(value))
+    setPage(1)
+  }, [])
+
+  React.useEffect(() => {
+    const currentRequestId = ++requestId.current
+    setIsLoading(true)
+    setLoadError(null)
+    setCanManageTemplates(false)
+    const params = new URLSearchParams({
+      page: String(page),
+      pageSize: String(pageSize),
+      includeBody: 'false',
+    })
+    if (search.trim()) params.set('search', search.trim())
+    void apiCall<unknown>(`/api/documents/templates?${params.toString()}`, undefined, { fallback: { items: [] } })
+      .then((call) => {
+        if (requestId.current !== currentRequestId) return
+        if (!call.ok) {
+          setRows([])
+          setTotal(0)
+          setTotalPages(1)
+          setCanManageTemplates(false)
+          setLoadError(t('documents.templates.error.load'))
+          return
+        }
+        const nextRows = normalizeTemplates(call.result)
+        const root = readRecord(call.result)
+        const nextPageSize = normalizePageSize(root ? readNumber(root, 'pageSize', 'page_size') ?? pageSize : pageSize)
+        const nextTotal = Math.max(0, Math.floor(root ? readNumber(root, 'total', 'totalCount', 'total_count') ?? nextRows.length : nextRows.length))
+        const nextTotalPages = Math.max(1, Math.floor(root ? readNumber(root, 'totalPages', 'total_pages') ?? Math.ceil(nextTotal / nextPageSize) : 1))
+        const returnedPage = Math.max(1, Math.floor(root ? readNumber(root, 'page') ?? page : page))
+        setRows(nextRows)
+        setTotal(nextTotal)
+        setTotalPages(nextTotalPages)
+        if (nextPageSize !== pageSize) setPageSizeState(nextPageSize)
+        if (Math.min(returnedPage, nextTotalPages) !== page) setPage(Math.min(returnedPage, nextTotalPages))
+        const capabilities = readRecord(root?.capabilities)
+        setCanManageTemplates(capabilities ? readBoolean(capabilities, 'canManageTemplates', 'can_manage_templates') ?? false : false)
+      })
+      .catch(() => {
+        if (requestId.current !== currentRequestId) return
+        setRows([])
+        setTotal(0)
+        setTotalPages(1)
+        setCanManageTemplates(false)
+        setLoadError(t('documents.templates.error.load'))
+      })
+      .finally(() => { if (requestId.current === currentRequestId) setIsLoading(false) })
+  }, [page, pageSize, reloadToken, search, t])
+
+  const deleteTemplate = React.useCallback(async (template: TemplateRow) => {
+    if (!canManageTemplates) return
+    if (!await confirm({ title: t('documents.templates.confirmDelete', { name: template.name }), variant: 'destructive' })) return
+    try {
+      await runMutation({
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(template.updatedAt),
+          () => apiCallOrThrow(
+            '/api/documents/templates',
+            { method: 'DELETE', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id: template.id }) },
+            { errorMessage: t('documents.templates.error.delete') },
+          ),
+        ),
+        context: { formId: mutationContextId, resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate, resourceId: template.id, retryLastMutation },
+        mutationPayload: { id: template.id },
+      })
+      flash(t('documents.templates.success.delete'), 'success')
+      refreshFromFirstPage()
+    } catch (error) {
+      if (!surfaceRecordConflict(error, t, { onRefresh: refreshFromFirstPage })) {
+        flash(error instanceof Error ? error.message : t('documents.templates.error.delete'), 'error')
+      }
+    }
+  }, [canManageTemplates, confirm, mutationContextId, refreshFromFirstPage, retryLastMutation, runMutation, t])
+
+  return {
+    rows,
+    page,
+    setPage,
+    pageSize,
+    setPageSize: changePageSize,
+    total,
+    totalPages,
+    search,
+    setSearch: changeSearch,
+    isLoading,
+    loadError,
+    canManageTemplates,
+    refresh,
+    refreshFromFirstPage,
+    deleteTemplate,
+    ConfirmDialogElement,
+  }
+}

package/src/modules/documents/backend/documents/useDocumentsList.tsx

@@ -0,0 +1,305 @@
+"use client"
+
+import * as React from 'react'
+import { useRouter } from 'next/navigation'
+import { apiCall, apiCallOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import {
+  hasActiveTemplate,
+  canWriteToFolder,
+  EMPTY_COLLECTION_CAPABILITIES,
+  normalizeCollectionCapabilities,
+  normalizeDocuments,
+  normalizeFolders,
+  readCreatedId,
+  type DocumentRow,
+  type FolderRow,
+  type CollectionCapabilities,
+} from './documentsListTypes'
+import { readNumber, readRecord } from './documentUi'
+
+export function useDocumentsList() {
+  const t = useT()
+  const router = useRouter()
+  const { confirm, ConfirmDialogElement } = useConfirmDialog()
+  const requestId = React.useRef(0)
+  const createInFlight = React.useRef(false)
+  const [rows, setRows] = React.useState<DocumentRow[]>([])
+  const [folders, setFolders] = React.useState<FolderRow[]>([])
+  const [selectedFolderId, setSelectedFolderId] = React.useState<string | null>(null)
+  const [page, setPage] = React.useState(1)
+  const [pageSize, setPageSize] = React.useState(25)
+  const [total, setTotal] = React.useState(0)
+  const [totalPages, setTotalPages] = React.useState(1)
+  const [search, setSearch] = React.useState('')
+  const [archivedFilter, setArchivedFilter] = React.useState<'exclude' | 'include' | 'only'>('exclude')
+  const [favoritesOnly, setFavoritesOnly] = React.useState(false)
+  const [isLoading, setIsLoading] = React.useState(true)
+  const [isCreating, setIsCreating] = React.useState(false)
+  const [loadError, setLoadError] = React.useState<string | null>(null)
+  const [hasTemplates, setHasTemplates] = React.useState(false)
+  const [collectionCapabilities, setCollectionCapabilities] = React.useState<CollectionCapabilities>(EMPTY_COLLECTION_CAPABILITIES)
+  const [reloadToken, setReloadToken] = React.useState(0)
+  const mutationContextId = 'documents-list:mutation'
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    resourceId: string
+    retryLastMutation: () => Promise<boolean>
+  }>({ contextId: mutationContextId, blockedMessage: t('ui.forms.flash.saveBlocked') })
+
+  const refresh = React.useCallback(() => setReloadToken((token) => token + 1), [])
+  React.useEffect(() => {
+    const currentRequestId = ++requestId.current
+    setIsLoading(true)
+    setLoadError(null)
+    const params = new URLSearchParams({ page: String(page), pageSize: String(pageSize) })
+    if (search.trim()) params.set('search', search.trim())
+    if (selectedFolderId) params.set('folderId', selectedFolderId)
+    if (archivedFilter !== 'exclude') params.set('archived', archivedFilter)
+    if (favoritesOnly) params.set('favorite', 'true')
+    void Promise.all([
+      apiCall<unknown>('/api/documents/folders', undefined, { fallback: { items: [] } }),
+      apiCall<unknown>(`/api/documents?${params.toString()}`, undefined, { fallback: { items: [] } }),
+    ]).then(([foldersCall, documentsCall]) => {
+      if (requestId.current !== currentRequestId) return
+      if (!foldersCall.ok || !documentsCall.ok) {
+        setRows([])
+        setFolders([])
+        setTotal(0)
+        setTotalPages(1)
+        setCollectionCapabilities(EMPTY_COLLECTION_CAPABILITIES)
+        setLoadError(t('documents.list.error.load'))
+        return
+      }
+      const nextFolders = normalizeFolders(foldersCall.result)
+      const nextRows = normalizeDocuments(documentsCall.result, nextFolders, t('documents.list.unknownOwner'))
+      const root = readRecord(documentsCall.result)
+      const nextTotal = root ? readNumber(root, 'total', 'totalCount', 'total_count') ?? nextRows.length : nextRows.length
+      setFolders(nextFolders)
+      setRows(nextRows)
+      setCollectionCapabilities(normalizeCollectionCapabilities(documentsCall.result))
+      setTotal(nextTotal)
+      setTotalPages(root ? readNumber(root, 'totalPages', 'total_pages') ?? Math.max(1, Math.ceil(nextTotal / pageSize)) : 1)
+    }).catch(() => {
+      if (requestId.current !== currentRequestId) return
+      setRows([])
+      setFolders([])
+      setTotal(0)
+      setTotalPages(1)
+      setCollectionCapabilities(EMPTY_COLLECTION_CAPABILITIES)
+      setLoadError(t('documents.list.error.load'))
+    }).finally(() => {
+      if (requestId.current === currentRequestId) setIsLoading(false)
+    })
+  }, [archivedFilter, favoritesOnly, page, pageSize, reloadToken, search, selectedFolderId, t])
+
+  React.useEffect(() => {
+    let active = true
+    void apiCall<unknown>('/api/documents/templates?page=1&pageSize=1&isActive=true', undefined, { fallback: { items: [] } })
+      .then((call) => { if (active) setHasTemplates(call.ok && hasActiveTemplate(call.result)) })
+    return () => { active = false }
+  }, [])
+
+  const createDocument = React.useCallback(async () => {
+    const selectedFolder = selectedFolderId ? folders.find((folder) => folder.id === selectedFolderId) ?? null : null
+    if (createInFlight.current || !collectionCapabilities.canCreateDocument || !canWriteToFolder(selectedFolderId, selectedFolder)) return
+    createInFlight.current = true
+    setIsCreating(true)
+    try {
+      const call = await runMutation({
+        operation: () => apiCallOrThrow<unknown>(
+          '/api/documents',
+          { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ title: t('documents.documents.untitled'), folderId: selectedFolderId }) },
+          { errorMessage: t('documents.list.error.create') },
+        ),
+        context: { formId: mutationContextId, resourceKind: 'documents.document', resourceId: selectedFolderId ?? 'new', retryLastMutation },
+        mutationPayload: { folderId: selectedFolderId },
+      })
+      const id = readCreatedId(call.result)
+      if (!id) throw new Error(t('documents.list.error.missingCreatedId'))
+      router.push(`/backend/documents/${id}`)
+    } catch (error) {
+      flash(error instanceof Error ? error.message : t('documents.list.error.create'), 'error')
+      createInFlight.current = false
+      setIsCreating(false)
+    }
+  }, [collectionCapabilities.canCreateDocument, folders, mutationContextId, retryLastMutation, router, runMutation, selectedFolderId, t])
+
+  const deleteDocument = React.useCallback(async (row: DocumentRow) => {
+    if (!await confirm({ title: t('documents.list.confirmDelete', { title: row.title }), variant: 'destructive' })) return
+    try {
+      await runMutation({
+        operation: () => withScopedApiRequestHeaders(buildOptimisticLockHeader(row.updatedAt), () => apiCallOrThrow(`/api/documents/${encodeURIComponent(row.id)}`, { method: 'DELETE' })),
+        context: { formId: mutationContextId, resourceKind: 'documents.document', resourceId: row.id, retryLastMutation },
+        mutationPayload: { id: row.id },
+      })
+      flash(t('documents.list.success.delete'), 'success')
+      refresh()
+    } catch (error) {
+      if (!surfaceRecordConflict(error, t, { onRefresh: refresh })) {
+        flash(error instanceof Error ? error.message : t('documents.list.error.delete'), 'error')
+      }
+    }
+  }, [confirm, mutationContextId, refresh, retryLastMutation, runMutation, t])
+
+  const moveDocument = React.useCallback(async (row: DocumentRow, folderId: string | null) => {
+    if (!row.capabilities.canEdit || row.folderId === folderId) return false
+    try {
+      await runMutation({
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(row.updatedAt),
+          () => apiCallOrThrow(
+            `/api/documents/${encodeURIComponent(row.id)}`,
+            {
+              method: 'PUT',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ folderId }),
+            },
+            { errorMessage: t('documents.folders.error.moveDocument') },
+          ),
+        ),
+        context: { formId: mutationContextId, resourceKind: 'documents.document', resourceId: row.id, retryLastMutation },
+        mutationPayload: { id: row.id, folderId },
+      })
+      flash(t('documents.folders.success.moveDocument'), 'success')
+      refresh()
+      return true
+    } catch (error) {
+      if (!surfaceRecordConflict(error, t, { onRefresh: refresh })) {
+        flash(error instanceof Error ? error.message : t('documents.folders.error.moveDocument'), 'error')
+      }
+      return false
+    }
+  }, [mutationContextId, refresh, retryLastMutation, runMutation, t])
+
+  const saveFolder = React.useCallback(async (input: { folder?: FolderRow; parentFolderId?: string | null; name: string }) => {
+    const isRename = Boolean(input.folder)
+    const folder = input.folder
+    const operation = () => apiCallOrThrow(
+      '/api/documents/folders',
+      {
+        method: isRename ? 'PUT' : 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(isRename ? { id: folder?.id, name: input.name, parentFolderId: folder?.parentFolderId } : { name: input.name, parentFolderId: input.parentFolderId ?? null }),
+      },
+      { errorMessage: t(isRename ? 'documents.folders.error.rename' : 'documents.folders.error.create') },
+    )
+    try {
+      await runMutation({
+        operation: () => isRename ? withScopedApiRequestHeaders(buildOptimisticLockHeader(folder?.updatedAt), operation) : operation(),
+        context: { formId: mutationContextId, resourceKind: 'documents.document_folder', resourceId: folder?.id ?? input.parentFolderId ?? 'new', retryLastMutation },
+        mutationPayload: input,
+      })
+      flash(t(isRename ? 'documents.folders.success.rename' : 'documents.folders.success.create'), 'success')
+      refresh()
+      return true
+    } catch (error) {
+      if (!surfaceRecordConflict(error, t, { onRefresh: refresh })) {
+        flash(error instanceof Error ? error.message : t(isRename ? 'documents.folders.error.rename' : 'documents.folders.error.create'), 'error')
+      }
+      return false
+    }
+  }, [mutationContextId, refresh, retryLastMutation, runMutation, t])
+
+  const deleteFolder = React.useCallback(async (folder: FolderRow) => {
+    if (!await confirm({ title: t('documents.folders.confirmDelete', { name: folder.name }), variant: 'destructive' })) return
+    try {
+      await runMutation({
+        operation: () => withScopedApiRequestHeaders(buildOptimisticLockHeader(folder.updatedAt), () => apiCallOrThrow('/api/documents/folders', { method: 'DELETE', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id: folder.id }) })),
+        context: { formId: mutationContextId, resourceKind: 'documents.document_folder', resourceId: folder.id, retryLastMutation },
+        mutationPayload: { id: folder.id },
+      })
+      if (selectedFolderId === folder.id) setSelectedFolderId(null)
+      flash(t('documents.folders.success.delete'), 'success')
+      refresh()
+    } catch (error) {
+      if (!surfaceRecordConflict(error, t, { onRefresh: refresh })) {
+        flash(error instanceof Error ? error.message : t('documents.folders.error.delete'), 'error')
+      }
+    }
+  }, [confirm, mutationContextId, refresh, retryLastMutation, runMutation, selectedFolderId, t])
+
+  const pendingFavoriteIds = React.useRef<Set<string>>(new Set())
+  const toggleFavorite = React.useCallback(async (row: DocumentRow) => {
+    if (pendingFavoriteIds.current.has(row.id)) return
+    pendingFavoriteIds.current.add(row.id)
+    const nextActive = !row.isFavorite
+    setRows((current) => current.map((candidate) => candidate.id === row.id
+      ? { ...candidate, isFavorite: nextActive }
+      : candidate))
+    try {
+      await runMutation({
+        operation: () => apiCallOrThrow(
+          `/api/documents/${encodeURIComponent(row.id)}/favorite`,
+          { method: nextActive ? 'POST' : 'DELETE' },
+        ),
+        context: { formId: mutationContextId, resourceKind: 'documents.document_favorite', resourceId: row.id, retryLastMutation },
+        mutationPayload: { id: row.id, active: nextActive },
+      })
+      if (favoritesOnly && !nextActive) refresh()
+    } catch (error) {
+      setRows((current) => current.map((candidate) => candidate.id === row.id
+        ? { ...candidate, isFavorite: !nextActive }
+        : candidate))
+      flash(error instanceof Error ? error.message : t('documents.list.error.load'), 'error')
+    } finally {
+      pendingFavoriteIds.current.delete(row.id)
+    }
+  }, [favoritesOnly, mutationContextId, refresh, retryLastMutation, runMutation, t])
+
+  const pendingDuplicateIds = React.useRef<Set<string>>(new Set())
+  const duplicateDocument = React.useCallback(async (row: DocumentRow) => {
+    if (pendingDuplicateIds.current.has(row.id)) return
+    pendingDuplicateIds.current.add(row.id)
+    try {
+      const created = await runMutation({
+        operation: () => apiCallOrThrow<{ id: string }>(
+          `/api/documents/${encodeURIComponent(row.id)}/duplicate`,
+          { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({}) },
+        ),
+        context: { formId: mutationContextId, resourceKind: 'documents.document', resourceId: row.id, retryLastMutation },
+        mutationPayload: { action: 'duplicate', sourceDocumentId: row.id },
+      })
+      flash(t('documents.duplicate.success'), 'success')
+      const createdId = created?.result?.id
+      if (createdId) router.push(`/backend/documents/${encodeURIComponent(createdId)}`)
+    } catch (error) {
+      flash(error instanceof Error ? error.message : t('documents.duplicate.error'), 'error')
+    } finally {
+      pendingDuplicateIds.current.delete(row.id)
+    }
+  }, [mutationContextId, retryLastMutation, router, runMutation, t])
+
+  const archiveToggle = React.useCallback(async (row: DocumentRow) => {
+    const action = row.archivedAt ? 'unarchive' : 'archive'
+    try {
+      await runMutation({
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(row.updatedAt),
+          () => apiCallOrThrow(`/api/documents/${encodeURIComponent(row.id)}/${action}`, { method: 'POST' }),
+        ),
+        context: { formId: mutationContextId, resourceKind: 'documents.document', resourceId: row.id, retryLastMutation },
+        mutationPayload: { action, id: row.id },
+      })
+      flash(t(row.archivedAt ? 'documents.archive.success.unarchive' : 'documents.archive.success.archive'), 'success')
+      refresh()
+    } catch (error) {
+      if (!surfaceRecordConflict(error, t, { onRefresh: refresh })) {
+        flash(error instanceof Error ? error.message : t('documents.archive.error'), 'error')
+      }
+    }
+  }, [mutationContextId, refresh, retryLastMutation, runMutation, t])
+
+  return {
+    rows, folders, selectedFolderId, setSelectedFolderId, page, setPage, pageSize, setPageSize,
+    total, totalPages, search, setSearch, isLoading, isCreating, loadError, hasTemplates, collectionCapabilities, refresh,
+    archivedFilter, setArchivedFilter, favoritesOnly, setFavoritesOnly,
+    createDocument, deleteDocument, moveDocument, saveFolder, deleteFolder, ConfirmDialogElement,
+    toggleFavorite, duplicateDocument, archiveToggle,
+  }
+}

package/src/modules/documents/ce.ts

@@ -0,0 +1,6 @@
+import type { CustomEntitySpec } from '@open-mercato/shared/modules/entities'
+
+const documentEntities: CustomEntitySpec[] = []
+
+export const entities = documentEntities
+export default documentEntities

package/src/modules/documents/commands/aggregate.ts

@@ -0,0 +1,128 @@
+import { LockMode } from '@mikro-orm/core'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import {
+  findOneWithDecryption,
+  findWithDecryption,
+} from '@open-mercato/shared/lib/encryption/find'
+import {
+  Document,
+  DocumentAttachment,
+  DocumentComment,
+  DocumentContent,
+  DocumentEntityLink,
+  DocumentShare,
+  DocumentVersion,
+} from '../data/entities'
+import type { DocumentsCommandScope } from './shared'
+
+export async function lockDocumentAggregateRoot(
+  em: EntityManager,
+  documentId: string,
+  scope: DocumentsCommandScope,
+  options: { includeDeleted?: boolean } = {},
+): Promise<Document> {
+  const document = await findOneWithDecryption(
+    em,
+    Document,
+    {
+      id: documentId,
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      ...(options.includeDeleted ? {} : { deletedAt: null }),
+    },
+    {
+      lockMode: LockMode.PESSIMISTIC_WRITE,
+      ...(options.includeDeleted ? { filters: false } : {}),
+    },
+    scope,
+  )
+  if (!document) throw new CrudHttpError(404, { error: 'Document not found' })
+  return document
+}
+
+export async function loadLockedDocumentContent(
+  em: EntityManager,
+  documentId: string,
+  scope: DocumentsCommandScope,
+  options: { includeDeleted?: boolean } = {},
+): Promise<DocumentContent | null> {
+  return findOneWithDecryption(
+    em,
+    DocumentContent,
+    {
+      documentId,
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      ...(options.includeDeleted ? {} : { deletedAt: null }),
+    },
+    {
+      lockMode: LockMode.PESSIMISTIC_WRITE,
+      ...(options.includeDeleted ? { filters: false } : {}),
+    },
+    scope,
+  )
+}
+
+async function hasScopedRows<TEntity extends object>(
+  em: EntityManager,
+  entity: { new (...args: never[]): TEntity },
+  where: Record<string, unknown>,
+  scope: DocumentsCommandScope,
+): Promise<boolean> {
+  const rows = await findWithDecryption(
+    em,
+    entity,
+    where,
+    { limit: 1 },
+    scope,
+  )
+  return rows.length > 0
+}
+
+export async function assertNoPostCreateDocumentDependents(
+  em: EntityManager,
+  documentId: string,
+  scope: DocumentsCommandScope,
+  options: { allowedLinkIds?: readonly string[]; allowedAttachmentIds?: readonly string[] } = {},
+): Promise<void> {
+  const base = {
+    documentId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+  }
+  const links = await findWithDecryption(
+    em,
+    DocumentEntityLink,
+    { ...base, deletedAt: null },
+    undefined,
+    scope,
+  )
+  const allowedLinkIds = new Set(options.allowedLinkIds ?? [])
+  if (links.some((link) => !allowedLinkIds.has(link.id))) {
+    throw new CrudHttpError(409, { error: 'Record changed by another user' })
+  }
+
+  const attachments = await findWithDecryption(
+    em,
+    DocumentAttachment,
+    { ...base, deletedAt: null },
+    undefined,
+    scope,
+  )
+  const allowedAttachmentIds = new Set(options.allowedAttachmentIds ?? [])
+  if (attachments.some((attachment) => !allowedAttachmentIds.has(attachment.id))) {
+    throw new CrudHttpError(409, { error: 'Record changed by another user' })
+  }
+
+  // Keep dependent reads sequential on the transaction's single connection.
+  // Every write path locks the parent document first, so the root lock closes
+  // the check-then-delete window while these scoped probes run.
+  if (
+    await hasScopedRows(em, DocumentShare, { ...base, deletedAt: null }, scope)
+    || await hasScopedRows(em, DocumentComment, { ...base, deletedAt: null }, scope)
+    || await hasScopedRows(em, DocumentVersion, base, scope)
+  ) {
+    throw new CrudHttpError(409, { error: 'Record changed by another user' })
+  }
+}