@open-mercato/core 0.10.1-develop.7716.1.cefe7975df → 0.10.1-develop.7721.1.b5c4a00a68

package/src/modules/staff/lib/time-tracking/projectAssignment.ts

@@ -0,0 +1,172 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { StaffTeamMember, StaffTimeProjectMember } from '../../data/entities'
+import { DEFAULT_ASSIGNMENT_GRACE_DAYS, MAX_ASSIGNMENT_GRACE_DAYS } from './settingKeys'
+
+const MS_PER_DAY = 86_400_000
+const ISO_DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})/
+
+export function normalizeAssignmentGraceDays(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value)) return DEFAULT_ASSIGNMENT_GRACE_DAYS
+  if (value < 0 || value > MAX_ASSIGNMENT_GRACE_DAYS) return DEFAULT_ASSIGNMENT_GRACE_DAYS
+  return value
+}
+
+/**
+ * `assigned_start_date` / `assigned_end_date` are `date` columns, so both bounds
+ * are compared as whole days rather than timestamps. Date instances are read
+ * through their local calendar fields because the postgres driver materialises a
+ * `date` as local midnight, and "today" likewise means the server's local day.
+ */
+export function toDayIndex(value: unknown): number | null {
+  if (value == null) return null
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return null
+    return Date.UTC(value.getFullYear(), value.getMonth(), value.getDate()) / MS_PER_DAY
+  }
+  if (typeof value === 'string') {
+    const match = ISO_DATE_PREFIX.exec(value.trim())
+    if (!match) return null
+    return Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])) / MS_PER_DAY
+  }
+  return null
+}
+
+/**
+ * An entry date is a calendar day the client sent as `YYYY-MM-DD`, which
+ * `z.coerce.date()` turns into UTC midnight — so a Date is read through its UTC
+ * fields here, the same way the grid addresses a cell (D-8).
+ */
+export function toEntryDayIndex(value: unknown): number | null {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return null
+    return Date.UTC(value.getUTCFullYear(), value.getUTCMonth(), value.getUTCDate()) / MS_PER_DAY
+  }
+  return toDayIndex(value)
+}
+
+/**
+ * A membership only grants access inside its assignment window: from
+ * `assigned_start_date` until `assigned_end_date` plus the tenant's grace days.
+ * A null end date is open-ended and never expires.
+ */
+export function isWithinAssignmentWindow(
+  membership: Pick<StaffTimeProjectMember, 'assignedStartDate' | 'assignedEndDate'>,
+  todayIndex: number,
+  graceDays: number,
+): boolean {
+  if (membership.assignedStartDate != null) {
+    const startIndex = toDayIndex(membership.assignedStartDate)
+    if (startIndex === null || todayIndex < startIndex) return false
+  }
+  if (membership.assignedEndDate == null) return true
+  const endIndex = toDayIndex(membership.assignedEndDate)
+  if (endIndex === null) return false
+  return todayIndex <= endIndex + graceDays
+}
+
+
+export type ProjectAssignmentScope = {
+  tenantId: string
+  organizationId: string
+}
+
+export type ActiveProjectMember = {
+  membershipId: string
+  staffMemberId: string
+  userId: string | null
+  isAssigner: boolean
+}
+
+type MembershipLike = Pick<
+  StaffTimeProjectMember,
+  'status' | 'deletedAt' | 'assignedStartDate' | 'assignedEndDate'
+>
+
+export function isActiveAssignment(membership: MembershipLike, now: Date, graceDays: number): boolean {
+  if (membership.status !== 'active' || membership.deletedAt) return false
+  const todayIndex = toDayIndex(now)
+  if (todayIndex === null) return false
+  return isWithinAssignmentWindow(membership, todayIndex, normalizeAssignmentGraceDays(graceDays))
+}
+
+export async function loadActiveProjectMembers(
+  em: EntityManager,
+  scope: ProjectAssignmentScope,
+  timeProjectId: string,
+  options: { graceDays?: number | null; now?: Date; assignersOnly?: boolean } = {},
+): Promise<ActiveProjectMember[]> {
+  const where: Record<string, unknown> = {
+    timeProjectId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    status: 'active',
+    deletedAt: null,
+  }
+  if (options.assignersOnly) where.isAssigner = true
+  const memberships = await em.find(StaffTimeProjectMember, where)
+  const now = options.now ?? new Date()
+  const graceDays = normalizeAssignmentGraceDays(options.graceDays)
+  const active = memberships.filter((membership) => isActiveAssignment(membership, now, graceDays))
+  if (active.length === 0) return []
+  const staffMembers = await findWithDecryption(
+    em,
+    StaffTeamMember,
+    {
+      id: { $in: Array.from(new Set(active.map((membership) => membership.staffMemberId))) },
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      deletedAt: null,
+    },
+    {},
+    scope,
+  )
+  const userByMember = new Map(staffMembers.map((member) => [member.id, member.userId ?? null]))
+  return active
+    .filter((membership) => userByMember.has(membership.staffMemberId))
+    .map((membership) => ({
+      membershipId: membership.id,
+      staffMemberId: membership.staffMemberId,
+      userId: userByMember.get(membership.staffMemberId) ?? null,
+      isAssigner: membership.isAssigner === true,
+    }))
+}
+
+export async function resolveUsableDefaultAssignee(
+  em: EntityManager,
+  scope: ProjectAssignmentScope,
+  project: { id: string; defaultAssigneeStaffMemberId?: string | null },
+  options: { graceDays?: number | null; now?: Date } = {},
+): Promise<string | null> {
+  const candidate = project.defaultAssigneeStaffMemberId ?? null
+  if (!candidate) return null
+  const members = await loadActiveProjectMembers(em, scope, project.id, options)
+  return members.some((member) => member.staffMemberId === candidate) ? candidate : null
+}
+
+export async function isActiveProjectAssigner(
+  em: EntityManager,
+  scope: ProjectAssignmentScope,
+  timeProjectId: string,
+  staffMemberId: string,
+  options: { graceDays?: number | null; now?: Date } = {},
+): Promise<boolean> {
+  const assigners = await loadActiveProjectMembers(em, scope, timeProjectId, { ...options, assignersOnly: true })
+  return assigners.some((member) => member.staffMemberId === staffMemberId)
+}
+
+type ConfigContainer = { resolve: (name: string) => unknown }
+
+export async function resolveAssignmentGraceDaysFromContainer(
+  container: ConfigContainer,
+  tenantId: string,
+): Promise<number | null> {
+  try {
+    const { readTimeTrackingSettings } = await import('./settings')
+    const configService = container.resolve('moduleConfigService') as Parameters<typeof readTimeTrackingSettings>[0]
+    const settings = await readTimeTrackingSettings(configService, { tenantId })
+    return settings.access.assignmentGraceDays
+  } catch {
+    return null
+  }
+}

package/src/modules/staff/lib/time-tracking/settingKeys.ts

@@ -26,6 +26,9 @@ export const TIME_TRACKING_DEFAULTS_GROUP = 'defaults'
 export const TIME_TRACKING_TARGETS_GROUP = 'targets'
 export const TIME_TRACKING_WARNINGS_GROUP = 'warnings'
 export const TIME_TRACKING_ACCESS_GROUP = 'access'
+export const TIME_TRACKING_SUPPORT_GROUP = 'support'
+export const DEFAULT_SUPPORT_REFERENCE_PREFIX = 'SUP'
+export const supportReferencePrefixSchema = z.string().regex(/^[A-Z][A-Z0-9]{1,9}$/)
 
 /**
  * Days past `assigned_end_date` that project access survives (spec D-12). The
@@ -198,6 +201,14 @@ const BUILT_IN_SETTING_KEYS: readonly TimeTrackingSettingKeyInput[] = [
     labelKey: 'staff.time_tracking.settings.access.graceDays',
     priority: BUILT_IN_STRATEGY_PRIORITY,
   },
+  {
+    group: TIME_TRACKING_SUPPORT_GROUP,
+    key: 'referencePrefix',
+    schema: supportReferencePrefixSchema,
+    default: DEFAULT_SUPPORT_REFERENCE_PREFIX,
+    labelKey: 'staff.support.settings.referencePrefix',
+    priority: BUILT_IN_STRATEGY_PRIORITY,
+  },
 ]
 
 for (const input of BUILT_IN_SETTING_KEYS) {

package/src/modules/staff/lib/time-tracking/settings.ts

@@ -8,10 +8,12 @@ import {
 import {
   DEFAULT_ASSIGNMENT_GRACE_DAYS,
   MAX_ASSIGNMENT_GRACE_DAYS,
+  TIME_TRACKING_SUPPORT_GROUP,
   buildDefaultTimeTrackingSettings,
   listTimeTrackingSettingKeys,
   normalizeTimeTrackingSettingsRecord,
   registerTimeTrackingSettingKey,
+  supportReferencePrefixSchema,
   timeTrackingSettingKeyIds,
   type TimeTrackingSettingKeyDefinition,
   type TimeTrackingSettingKeyInput,
@@ -32,9 +34,10 @@ export const TIME_TRACKING_TARGETS_DAILY_HOURS_KEY = 'targets.dailyHours'
 export const TIME_TRACKING_WARNINGS_OVERLAP_KEY = 'warnings.overlap'
 export const TIME_TRACKING_WARNINGS_RUNNING_TIMER_KEY = 'warnings.runningTimer'
 export const TIME_TRACKING_ACCESS_ASSIGNMENT_GRACE_DAYS_KEY = 'access.assignmentGraceDays'
+export const TIME_TRACKING_SUPPORT_REFERENCE_PREFIX_KEY = 'support.referencePrefix'
 
 /**
- * The eight keys the module shipped. FROZEN — a stored config row is named after one
+ * The built-in keys the module ships. FROZEN — a stored config row is named after one
  * of these, so none may be renamed or removed. The list is no longer the whole truth:
  * `timeTrackingSettingKeyIds()` returns these plus every contributed key (EP-42).
  */
@@ -47,6 +50,7 @@ export const TIME_TRACKING_SETTING_KEYS = [
   TIME_TRACKING_WARNINGS_OVERLAP_KEY,
   TIME_TRACKING_WARNINGS_RUNNING_TIMER_KEY,
   TIME_TRACKING_ACCESS_ASSIGNMENT_GRACE_DAYS_KEY,
+  TIME_TRACKING_SUPPORT_REFERENCE_PREFIX_KEY,
 ] as const
 
 export type TimeTrackingSettingKey = (typeof TIME_TRACKING_SETTING_KEYS)[number]
@@ -69,12 +73,21 @@ export type TimeTrackingAccess = {
   assignmentGraceDays: number
 }
 
+export type TimeTrackingSupport = {
+  referencePrefix: string
+}
+
 export type TimeTrackingBuiltInSettings = {
   rounding: RoundingSettings
   defaults: TimeTrackingEntryDefaults
   targets: TimeTrackingTargets
   warnings: TimeTrackingWarnings
   access: TimeTrackingAccess
+  /**
+   * Optional in the type so code that builds a settings object without the support
+   * group keeps compiling; a normalized read always carries it.
+   */
+  support?: TimeTrackingSupport
 }
 
 /**
@@ -166,3 +179,35 @@ export async function writeTimeTrackingSettings(
 
   return settings
 }
+
+function readSettingsGroup(input: Record<string, unknown>, group: string): Record<string, unknown> | null {
+  const value = input[group]
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
+/**
+ * A settings payload from a client that predates the support group omits it. That
+ * omission keeps the tenant's stored reference prefix instead of resetting it to the
+ * default, so an older settings screen cannot silently rename future ticket references.
+ */
+export async function preserveOmittedSupportSettings(
+  configService: ModuleConfigService,
+  scope: TimeTrackingSettingsScope,
+  input: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const supportGroup = readSettingsGroup(input, TIME_TRACKING_SUPPORT_GROUP)
+  if (supportGroup && supportGroup.referencePrefix !== undefined) return input
+  const record = await configService.getRecord(
+    STAFF_TIME_TRACKING_MODULE_ID,
+    TIME_TRACKING_SUPPORT_REFERENCE_PREFIX_KEY,
+    { tenantId: scope.tenantId },
+  )
+  if (!record) return input
+  const storedPrefix = supportReferencePrefixSchema.safeParse(record.value)
+  if (!storedPrefix.success) return input
+  return {
+    ...input,
+    [TIME_TRACKING_SUPPORT_GROUP]: { ...(supportGroup ?? {}), referencePrefix: storedPrefix.data },
+  }
+}

package/src/modules/staff/lib/time-tracking/taskAssignmentRoute.ts

@@ -0,0 +1,165 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { CrudHttpError, forbidden, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { runRouteMutationGuards } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { StaffTimeTask } from '../../data/entities'
+import { STAFF_TIME_TRACKING_RESOURCE_KINDS } from '../../api/guards'
+import {
+  staffTimeTaskAssignmentCommandIds,
+  type StaffTimeTaskAssignmentInput,
+  type StaffTimeTaskAssignmentResult,
+} from '../../commands/timesheets-task-assignment'
+import { resolveFeatureAccess } from './featureAccess'
+import { assertProjectAccess } from './access'
+import { resolveListProjectAccess } from './listProjectAccess'
+
+export type TaskAssignmentAction = keyof typeof staffTimeTaskAssignmentCommandIds
+
+export const TASK_ASSIGNMENT_VIEW_FEATURE = 'staff.timesheets.tasks.view'
+
+const FAILURE_CODES: Record<TaskAssignmentAction, string> = {
+  claim: 'staff.task_claim_failed',
+  release: 'staff.task_release_failed',
+}
+
+export type TaskAssignmentRouteContext = {
+  params?: Promise<Record<string, string | string[]>> | Record<string, string | string[]>
+}
+
+export const taskAssignmentResponseSchema = z.object({
+  id: z.string().uuid(),
+  timeProjectId: z.string().uuid(),
+  assigneeStaffMemberId: z.string().uuid().nullable(),
+  updatedAt: z.string().nullable(),
+})
+
+async function resolveTaskId(req: Request, action: TaskAssignmentAction, context?: TaskAssignmentRouteContext): Promise<string | null> {
+  const params = context?.params ? await context.params : null
+  const fromParams = params?.id
+  if (typeof fromParams === 'string' && fromParams.length > 0) return fromParams
+  try {
+    const match = new URL(req.url).pathname.match(new RegExp(`/tasks/([^/]+)/${action}`))
+    return match?.[1] ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The `POST /api/staff/timesheets/tasks/{id}/claim|release` handler. Both actions
+ * share every step — scope, project access (the tasks list rule), optimistic lock,
+ * mutation guards, the command and the undo header — and differ only in the command.
+ */
+export function createTaskAssignmentPostHandler(action: TaskAssignmentAction) {
+  const logger = createLogger('staff').child({ component: `api/timesheets/tasks/${action}` })
+  return async function POST(req: Request, context?: TaskAssignmentRouteContext): Promise<Response> {
+    try {
+      const container = await createRequestContainer()
+      const auth = await getAuthFromRequest(req)
+      const { translate } = await resolveTranslations()
+      if (!auth) throw new CrudHttpError(401, { error: translate('staff.errors.unauthorized', 'Unauthorized') })
+
+      const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+      const tenantId = scope?.tenantId ?? auth.tenantId ?? null
+      const organizationId = scope?.selectedId ?? auth.orgId ?? null
+      if (!tenantId || !organizationId) {
+        throw new CrudHttpError(400, { error: translate('staff.errors.missingScope', 'Missing tenant or organization scope.') })
+      }
+      const taskId = await resolveTaskId(req, action, context)
+      if (!taskId || !z.string().uuid().safeParse(taskId).success) {
+        throw new CrudHttpError(400, { error: translate('staff.time_tracking.tasks.errors.idRequired', 'Task id is required.') })
+      }
+
+      const actorId = auth.sub ?? ''
+      const viewAccess = await resolveFeatureAccess(container, actorId, [TASK_ASSIGNMENT_VIEW_FEATURE], { tenantId, organizationId })
+      if (!viewAccess.allowed) throw forbidden(translate('staff.errors.forbidden', 'Forbidden'))
+
+      const routeCtx: CommandRuntimeContext = {
+        container,
+        auth,
+        organizationScope: scope,
+        selectedOrganizationId: organizationId,
+        organizationIds: scope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
+        request: req,
+      }
+
+      const em = (container.resolve('em') as EntityManager).fork()
+      const task = await em.findOne(StaffTimeTask, { id: taskId, tenantId, organizationId, deletedAt: null })
+      const access = task ? await resolveListProjectAccess(routeCtx) : null
+      if (!task || !access || !assertProjectAccess(access, task.timeProjectId)) {
+        throw new CrudHttpError(404, {
+          error: translate('staff.time_tracking.tasks.errors.notFound', 'Task not found or not accessible.'),
+        })
+      }
+
+      await enforceCommandOptimisticLockWithGuards(container, {
+        resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeTask,
+        resourceId: task.id,
+        current: task.updatedAt,
+        request: req,
+      })
+
+      const input: StaffTimeTaskAssignmentInput = { id: taskId }
+      const guardResult = await runRouteMutationGuards({
+        container,
+        req,
+        auth: { userId: actorId, tenantId, organizationId, userFeatures: viewAccess.grantedFeatures },
+        input: {
+          resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeTask,
+          resourceId: taskId,
+          operation: 'update',
+          mutationPayload: input,
+        },
+      })
+      if (!guardResult.ok) return guardResult.response
+
+      const commandBus = container.resolve('commandBus') as CommandBus
+      const { result, logEntry } = await commandBus.execute<StaffTimeTaskAssignmentInput, StaffTimeTaskAssignmentResult>(
+        staffTimeTaskAssignmentCommandIds[action],
+        { input, ctx: routeCtx },
+      )
+      await guardResult.runAfterSuccess()
+
+      const response = NextResponse.json({
+        id: result?.taskId ?? taskId,
+        timeProjectId: result?.timeProjectId ?? task.timeProjectId,
+        assigneeStaffMemberId: result?.assigneeStaffMemberId ?? null,
+        updatedAt: result?.updatedAt ?? null,
+      })
+      if (logEntry?.undoToken && logEntry?.id && logEntry?.commandId) {
+        response.headers.set(
+          'x-om-operation',
+          serializeOperationMetadata({
+            id: logEntry.id,
+            undoToken: logEntry.undoToken,
+            commandId: logEntry.commandId,
+            actionLabel: logEntry.actionLabel ?? null,
+            resourceKind: logEntry.resourceKind ?? STAFF_TIME_TRACKING_RESOURCE_KINDS.timeTask,
+            resourceId: logEntry.resourceId ?? taskId,
+            executedAt: logEntry.createdAt instanceof Date ? logEntry.createdAt.toISOString() : undefined,
+          }),
+        )
+      }
+      return response
+    } catch (err) {
+      if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+      const interceptorRejection = getCommandInterceptorHttpRejection(err)
+      if (interceptorRejection) return NextResponse.json(interceptorRejection.body, { status: interceptorRejection.status })
+      const { translate } = await resolveTranslations()
+      logger.error(`staff.timesheets.tasks.${action} POST failed`, { err })
+      getTelemetryRuntime()?.reportError(err, { module: 'staff', code: FAILURE_CODES[action] })
+      return NextResponse.json({ error: translate('staff.errors.internal', 'Internal server error') }, { status: 500 })
+    }
+  }
+}

package/src/modules/staff/lib/time-tracking/workRecipients.ts

@@ -0,0 +1,183 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { NotificationTypeDefinition } from '@open-mercato/shared/modules/notifications/types'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { resolveNotificationService } from '../../../notifications/lib/notificationService'
+import {
+  buildBatchNotificationFromType,
+  buildFeatureNotificationFromType,
+} from '../../../notifications/lib/notificationBuilder'
+import { StaffTimeProject } from '../../data/entities'
+import { loadActiveProjectMembers, type ProjectAssignmentScope } from './projectAssignment'
+
+const logger = createLogger('staff').child({ component: 'lib/time-tracking/workRecipients' })
+
+export const PROJECT_MANAGERS_FEATURE = 'staff.timesheets.projects.manage'
+
+export type WorkRecipientStep = 1 | 2 | 3 | 4
+
+export type ResolvedWorkRecipients =
+  | { step: 1 | 2 | 3; userIds: string[] }
+  | { step: 4; userIds: [] }
+
+export type WorkRecipientsInput = {
+  timeProjectId: string
+  /** Step 1: the type's own audience. Empty or omitted starts the chain at step 2. */
+  audienceUserIds?: readonly (string | null | undefined)[]
+  /** Excluded from steps 1–3. Step 4 hands resolution to `createForFeature`, which cannot exclude a user. */
+  actorUserId?: string | null
+  graceDays?: number | null
+  now?: Date
+}
+
+function uniqueExcluding(ids: readonly (string | null | undefined)[], actorUserId: string | null): string[] {
+  const seen = new Set<string>()
+  for (const id of ids) {
+    if (typeof id !== 'string' || id.length === 0) continue
+    if (actorUserId && id === actorUserId) continue
+    seen.add(id)
+  }
+  return [...seen]
+}
+
+/**
+ * The escalation chain shared by every project-work notification: the type's own
+ * audience, then the project's active assigners, then the project owner, then the
+ * organization's project managers. Each step is used only when the one before it
+ * is empty. Steps 1–3 are resolved here; step 4 is returned as a marker for
+ * `notifyProjectWork`, which sends it through `createForFeature`.
+ */
+export async function resolveProjectWorkRecipients(
+  em: EntityManager,
+  scope: ProjectAssignmentScope,
+  input: WorkRecipientsInput,
+): Promise<ResolvedWorkRecipients> {
+  const actorUserId = input.actorUserId ?? null
+  const audience = uniqueExcluding(input.audienceUserIds ?? [], actorUserId)
+  if (audience.length > 0) return { step: 1, userIds: audience }
+
+  const assigners = await loadActiveProjectMembers(em, scope, input.timeProjectId, {
+    graceDays: input.graceDays,
+    now: input.now,
+    assignersOnly: true,
+  })
+  const assignerUserIds = uniqueExcluding(assigners.map((member) => member.userId), actorUserId)
+  if (assignerUserIds.length > 0) return { step: 2, userIds: assignerUserIds }
+
+  const project = await em.findOne(
+    StaffTimeProject,
+    { id: input.timeProjectId, tenantId: scope.tenantId, organizationId: scope.organizationId },
+    { fields: ['id', 'ownerUserId'] },
+  )
+  const owner = uniqueExcluding([project?.ownerUserId], actorUserId)
+  if (owner.length > 0) return { step: 3, userIds: owner }
+
+  return { step: 4, userIds: [] }
+}
+
+export type ActiveAssignerUserIdsInput = {
+  timeProjectId: string
+  graceDays?: number | null
+  now?: Date
+}
+
+export async function loadActiveAssignerUserIds(
+  em: EntityManager,
+  scope: ProjectAssignmentScope,
+  input: ActiveAssignerUserIdsInput,
+): Promise<string[]> {
+  const assigners = await loadActiveProjectMembers(em, scope, input.timeProjectId, {
+    graceDays: input.graceDays,
+    now: input.now,
+    assignersOnly: true,
+  })
+  return uniqueExcluding(assigners.map((member) => member.userId), null)
+}
+
+export type ProjectRecipientProbe = {
+  id: string
+  ownerUserId?: string | null
+  defaultAssigneeStaffMemberId?: string | null
+}
+
+/**
+ * Whether new project work reaches somebody before the chain falls through to the
+ * organization's project managers (step 4): an active assigner with a user account,
+ * a usable default assignee with a user account (the ticket's step-1 audience), or
+ * the project owner. `false` is the state the support routing settings warn about.
+ */
+export async function projectReachesRecipientBeforeManagers(
+  em: EntityManager,
+  scope: ProjectAssignmentScope,
+  project: ProjectRecipientProbe,
+  options: { graceDays?: number | null; now?: Date } = {},
+): Promise<boolean> {
+  if (typeof project.ownerUserId === 'string' && project.ownerUserId.length > 0) return true
+  const members = await loadActiveProjectMembers(em, scope, project.id, options)
+  const hasUser = (member: { userId: string | null }) => typeof member.userId === 'string' && member.userId.length > 0
+  if (members.some((member) => member.isAssigner && hasUser(member))) return true
+  const defaultAssigneeId = project.defaultAssigneeStaffMemberId ?? null
+  if (!defaultAssigneeId) return false
+  return members.some((member) => member.staffMemberId === defaultAssigneeId && hasUser(member))
+}
+
+type ContainerLike = { resolve: <T = unknown>(name: string) => T }
+
+export type NotifyProjectWorkOptions = {
+  typeDef: NotificationTypeDefinition
+  recipients: ResolvedWorkRecipients
+  build: {
+    titleVariables?: Record<string, string>
+    bodyVariables?: Record<string, string>
+    sourceEntityType?: string
+    sourceEntityId?: string
+    linkHref?: string
+    groupKey?: string
+  }
+}
+
+export type NotifyProjectWorkResult = {
+  step: WorkRecipientStep
+  notifiedCount: number
+}
+
+/**
+ * Sends one notification to the resolved recipients. Step 4 always passes
+ * `restrictRecipientsToOrganization: true`: without it `createForFeature` notifies
+ * every holder of the feature in the whole tenant. With the flag on, the service
+ * returns no recipients (and logs) when the organization is missing, more than 200
+ * tenant-wide candidates hold the feature, the container is unavailable, the RBAC
+ * check throws, or nobody in the organization holds it; `notifiedCount` is then 0
+ * and the caller decides what "nobody notified" means for its record.
+ */
+export async function notifyProjectWork(
+  container: ContainerLike,
+  scope: ProjectAssignmentScope,
+  options: NotifyProjectWorkOptions,
+): Promise<NotifyProjectWorkResult> {
+  const notificationService = resolveNotificationService(container)
+  const context = { tenantId: scope.tenantId, organizationId: scope.organizationId }
+  const { typeDef, recipients, build } = options
+  if (recipients.step === 4) {
+    const created = await notificationService.createForFeature(
+      {
+        ...buildFeatureNotificationFromType(typeDef, { ...build, requiredFeature: PROJECT_MANAGERS_FEATURE }),
+        restrictRecipientsToOrganization: true,
+      },
+      context,
+    )
+    return { step: 4, notifiedCount: created.length }
+  }
+  if (recipients.userIds.length === 0) return { step: recipients.step, notifiedCount: 0 }
+  try {
+    const created = await notificationService.createBatch(
+      buildBatchNotificationFromType(typeDef, { ...build, recipientUserIds: recipients.userIds }),
+      context,
+    )
+    return { step: recipients.step, notifiedCount: created.length }
+  } catch (err) {
+    logger.error('staff project-work notification failed', { err, type: typeDef.type, step: recipients.step })
+    getTelemetryRuntime()?.reportError(err, { module: 'staff', code: 'staff.project_work_notification_failed' })
+    return { step: recipients.step, notifiedCount: 0 }
+  }
+}