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

package/src/modules/staff/migrations/Migration20261009180543_staff.ts

@@ -0,0 +1,50 @@
+import { Migration } from '@mikro-orm/migrations';
+import { buildEncryptionMapBackfillSql } from '@open-mercato/shared/lib/encryption/migration-backfill';
+
+export class Migration20261009180543_staff extends Migration {
+
+  override name = 'Migration20261009180543';
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "staff_support_routing_rules" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "category_value" text null, "time_project_id" uuid not null, "is_active" boolean not null default true, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create index "staff_support_routing_rules_tenant_org_idx" on "staff_support_routing_rules" ("tenant_id", "organization_id");`);
+    this.addSql(`create unique index "staff_support_routing_rules_category_unique_idx" on "staff_support_routing_rules" ("tenant_id", "organization_id", coalesce("category_value", '')) where "deleted_at" is null;`);
+
+    this.addSql(`create table "staff_support_tickets" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "task_id" uuid not null, "customer_snapshot" jsonb null, "reported_by_customer_user_id" uuid null, "support_reference" text not null, "support_sequence_number" int not null, "category_value" text not null, "category_snapshot" jsonb not null, "routed_via" text not null, "customer_request_snapshot" jsonb not null, "unnotified_at" timestamptz null, "portal_status_published" text null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create unique index "staff_support_tickets_reference_unique_idx" on "staff_support_tickets" ("tenant_id", "organization_id", "support_reference") where "deleted_at" is null;`);
+    this.addSql(`create index "staff_support_tickets_sequence_idx" on "staff_support_tickets" ("tenant_id", "organization_id", "support_sequence_number");`);
+    this.addSql(`create unique index "staff_support_tickets_task_unique_idx" on "staff_support_tickets" ("tenant_id", "organization_id", "task_id") where "deleted_at" is null;`);
+    this.addSql(`create index "staff_support_tickets_tenant_org_idx" on "staff_support_tickets" ("tenant_id", "organization_id");`);
+
+    this.addSql(`alter table "staff_time_projects" add "default_assignee_staff_member_id" uuid null;`);
+
+    this.addSql(`alter table "staff_time_project_members" add "is_assigner" boolean not null default false;`);
+    this.addSql(`create index "staff_time_project_members_assigner_idx" on "staff_time_project_members" ("tenant_id", "organization_id", "time_project_id") where "is_assigner" = true and "status" = 'active' and "deleted_at" is null;`);
+
+    this.addSql(`alter table "staff_time_tasks" add "source" text not null default 'internal', add "customer_id" uuid null;`);
+    this.addSql(`create index "staff_time_tasks_portal_customer_idx" on "staff_time_tasks" ("tenant_id", "organization_id", "customer_id", "updated_at") where "source" = 'portal' and "deleted_at" is null;`);
+
+    this.addSql(`alter table "staff_time_task_comments" add "visibility" text not null default 'internal', add "author_kind" text not null default 'staff', add "author_customer_user_id" uuid null, add "author_display_snapshot" jsonb null;`);
+
+    this.addSql(buildEncryptionMapBackfillSql({
+      entityId: 'staff:staff_support_ticket',
+      fields: [{ field: 'customer_request_snapshot' }],
+    }));
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "staff_support_tickets";`);
+    this.addSql(`drop table if exists "staff_support_routing_rules";`);
+
+    this.addSql(`drop index "staff_time_project_members_assigner_idx";`);
+    this.addSql(`alter table "staff_time_project_members" drop column "is_assigner";`);
+
+    this.addSql(`alter table "staff_time_projects" drop column "default_assignee_staff_member_id";`);
+
+    this.addSql(`alter table "staff_time_task_comments" drop column "visibility", drop column "author_kind", drop column "author_customer_user_id", drop column "author_display_snapshot";`);
+
+    this.addSql(`drop index "staff_time_tasks_portal_customer_idx";`);
+    this.addSql(`alter table "staff_time_tasks" drop column "source", drop column "customer_id";`);
+  }
+
+}

package/src/modules/staff/notifications.ts

@@ -235,6 +235,98 @@ export const notificationTypes: NotificationTypeDefinition[] = [
     linkHref: '/backend/staff/time-tracking/timesheet',
     expiresAfterHours: 168, // 7 days
   },
+  {
+    // Customer support tickets: raised for every portal ticket. The audience is the
+    // assignee (when the project default applied) plus the project's active
+    // assigners, falling back through owner and organization project managers.
+    type: 'staff.support_ticket.created',
+    channels: ['in_app', 'email'],
+    module: 'staff',
+    titleKey: 'staff.notifications.supportTicket.created.title',
+    bodyKey: 'staff.notifications.supportTicket.created.body',
+    icon: 'life-buoy',
+    severity: 'info',
+    actions: [
+      {
+        id: 'open-ticket',
+        labelKey: 'staff.notifications.supportTicket.actions.open',
+        variant: 'default',
+        icon: 'external-link',
+        href: '/backend/staff/time-tracking/support?task={sourceEntityId}',
+      },
+    ],
+    primaryActionId: 'open-ticket',
+    linkHref: '/backend/staff/time-tracking/support?task={sourceEntityId}',
+    expiresAfterHours: 336,
+  },
+  {
+    type: 'staff.support_ticket.customer_replied',
+    channels: ['in_app', 'email'],
+    module: 'staff',
+    titleKey: 'staff.notifications.supportTicket.customerReplied.title',
+    bodyKey: 'staff.notifications.supportTicket.customerReplied.body',
+    icon: 'message-square',
+    severity: 'info',
+    actions: [
+      {
+        id: 'open-ticket',
+        labelKey: 'staff.notifications.supportTicket.actions.open',
+        variant: 'default',
+        icon: 'external-link',
+        href: '/backend/staff/time-tracking/support?task={sourceEntityId}',
+      },
+    ],
+    primaryActionId: 'open-ticket',
+    linkHref: '/backend/staff/time-tracking/support?task={sourceEntityId}',
+    expiresAfterHours: 336,
+  },
+  {
+    // A task in the project became unassigned (released or cleared): tells the
+    // project's assigners there is claimable work.
+    type: 'staff.timesheets.time_task.released',
+    channels: ['in_app'],
+    module: 'staff',
+    titleKey: 'staff.notifications.timeTask.released.title',
+    bodyKey: 'staff.notifications.timeTask.released.body',
+    icon: 'hand',
+    severity: 'info',
+    actions: [
+      {
+        id: 'open-task',
+        labelKey: 'staff.notifications.timeTask.actions.open',
+        variant: 'default',
+        icon: 'external-link',
+        href: '/backend/staff/time-tracking/board?task={sourceEntityId}',
+      },
+    ],
+    primaryActionId: 'open-task',
+    linkHref: '/backend/staff/time-tracking/board?task={sourceEntityId}',
+    expiresAfterHours: 168,
+  },
+  {
+    // Someone else assigned the recipient to a task through the task editor. Not sent
+    // for claims (self-assignment) or for the portal default assignee, who hears
+    // about the intake once through `staff.support_ticket.created`.
+    type: 'staff.timesheets.time_task.assigned',
+    channels: ['in_app'],
+    module: 'staff',
+    titleKey: 'staff.notifications.timeTask.assigned.title',
+    bodyKey: 'staff.notifications.timeTask.assigned.body',
+    icon: 'user-check',
+    severity: 'info',
+    actions: [
+      {
+        id: 'open-task',
+        labelKey: 'staff.notifications.timeTask.actions.open',
+        variant: 'default',
+        icon: 'external-link',
+        href: '/backend/staff/time-tracking/board?task={sourceEntityId}',
+      },
+    ],
+    primaryActionId: 'open-task',
+    linkHref: '/backend/staff/time-tracking/board?task={sourceEntityId}',
+    expiresAfterHours: 168,
+  },
 ]
 
 export default notificationTypes

package/src/modules/staff/setup.ts

@@ -2,6 +2,8 @@ import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
 import { appendWidgetsToRoles } from '@open-mercato/core/modules/dashboards/lib/role-widgets'
 import { seedStaffAddressTypes, seedStaffTeamExamples } from './lib/seeds'
 import { seedStaffTimeTrackingExamples } from './lib/timeTrackingSeeds'
+import { resolveContainerProjectCodeGenerator, seedSupportDefaults } from './lib/support/seedDefaults'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 
 const TIMESHEETS_DASHBOARD_WIDGET_IDS = [
   'staff.timesheets.timeReporting',
@@ -12,6 +14,8 @@ export const setup: ModuleSetupConfig = {
   seedDefaults: async (ctx) => {
     const scope = { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
     await seedStaffAddressTypes(ctx.em, scope)
+    const { translate } = await resolveTranslations()
+    await seedSupportDefaults(ctx.em, scope, { translate, generateCode: resolveContainerProjectCodeGenerator(ctx.container) })
     await appendWidgetsToRoles(ctx.em, {
       tenantId: ctx.tenantId,
       organizationId: ctx.organizationId,
@@ -56,8 +60,8 @@ export const setup: ModuleSetupConfig = {
    * `portal_admin` holds `portal.*` and needs no entry.
    */
   defaultCustomerRoleFeatures: {
-    buyer: ['portal.time_reports.view'],
-    viewer: ['portal.time_reports.view'],
+    buyer: ['portal.time_reports.view', 'portal.support_tickets.view', 'portal.support_tickets.manage'],
+    viewer: ['portal.time_reports.view', 'portal.support_tickets.view'],
   },
 }
 

package/src/modules/staff/subscribers/support-portal-comment-created.ts

@@ -0,0 +1,35 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { publishTicketReply, readEventScope } from '../lib/support/portalBroadcast'
+
+const logger = createLogger('staff').child({ component: 'subscribers/support-portal-comment-created' })
+
+/**
+ * Ephemeral on purpose: `portal_updated` is portal-only, and the event bus does not
+ * relay portal-only events across processes (open issue #2973). Run inline in the web
+ * process that executed the command, where the portal SSE stream lives. Make this
+ * persistent again once #2973 lands.
+ */
+export const metadata = {
+  event: 'staff.timesheets.time_task_comment.created',
+  persistent: false,
+  id: 'staff:support-portal-comment-created',
+}
+
+type ResolverContext = { resolve: <T = unknown>(name: string) => T }
+
+type Payload = Record<string, unknown>
+
+export default async function handle(payload: Payload, ctx: ResolverContext): Promise<void> {
+  try {
+    if (payload.portalVisible !== true) return
+    const scope = readEventScope(payload)
+    const commentId = typeof payload.id === 'string' ? payload.id : null
+    if (!scope || !commentId) return
+    await publishTicketReply((ctx.resolve('em') as EntityManager).fork(), commentId, scope)
+  } catch (err) {
+    logger.error('staff:support-portal-comment-created failed', { err, id: payload?.id ?? null })
+    getTelemetryRuntime()?.reportError(err, { module: 'staff', code: 'staff.support_portal_comment_created_failed' })
+  }
+}

package/src/modules/staff/subscribers/support-portal-comment-deleted.ts

@@ -0,0 +1,35 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { publishTicketReply, readEventScope } from '../lib/support/portalBroadcast'
+
+const logger = createLogger('staff').child({ component: 'subscribers/support-portal-comment-deleted' })
+
+/**
+ * Ephemeral on purpose: `portal_updated` is portal-only, and the event bus does not
+ * relay portal-only events across processes (open issue #2973). Run inline in the web
+ * process that executed the command, where the portal SSE stream lives. Make this
+ * persistent again once #2973 lands.
+ */
+export const metadata = {
+  event: 'staff.timesheets.time_task_comment.deleted',
+  persistent: false,
+  id: 'staff:support-portal-comment-deleted',
+}
+
+type ResolverContext = { resolve: <T = unknown>(name: string) => T }
+
+type Payload = Record<string, unknown>
+
+export default async function handle(payload: Payload, ctx: ResolverContext): Promise<void> {
+  try {
+    if (payload.portalVisible !== true) return
+    const scope = readEventScope(payload)
+    const commentId = typeof payload.id === 'string' ? payload.id : null
+    if (!scope || !commentId) return
+    await publishTicketReply((ctx.resolve('em') as EntityManager).fork(), commentId, scope)
+  } catch (err) {
+    logger.error('staff:support-portal-comment-deleted failed', { err, id: payload?.id ?? null })
+    getTelemetryRuntime()?.reportError(err, { module: 'staff', code: 'staff.support_portal_comment_deleted_failed' })
+  }
+}

package/src/modules/staff/subscribers/support-portal-comment-updated.ts

@@ -0,0 +1,35 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { publishTicketReply, readEventScope } from '../lib/support/portalBroadcast'
+
+const logger = createLogger('staff').child({ component: 'subscribers/support-portal-comment-updated' })
+
+/**
+ * Ephemeral on purpose: `portal_updated` is portal-only, and the event bus does not
+ * relay portal-only events across processes (open issue #2973). Run inline in the web
+ * process that executed the command, where the portal SSE stream lives. Make this
+ * persistent again once #2973 lands.
+ */
+export const metadata = {
+  event: 'staff.timesheets.time_task_comment.updated',
+  persistent: false,
+  id: 'staff:support-portal-comment-updated',
+}
+
+type ResolverContext = { resolve: <T = unknown>(name: string) => T }
+
+type Payload = Record<string, unknown>
+
+export default async function handle(payload: Payload, ctx: ResolverContext): Promise<void> {
+  try {
+    if (payload.portalVisible !== true) return
+    const scope = readEventScope(payload)
+    const commentId = typeof payload.id === 'string' ? payload.id : null
+    if (!scope || !commentId) return
+    await publishTicketReply((ctx.resolve('em') as EntityManager).fork(), commentId, scope)
+  } catch (err) {
+    logger.error('staff:support-portal-comment-updated failed', { err, id: payload?.id ?? null })
+    getTelemetryRuntime()?.reportError(err, { module: 'staff', code: 'staff.support_portal_comment_updated_failed' })
+  }
+}

package/src/modules/staff/subscribers/support-portal-status-column-updated.ts

@@ -0,0 +1,36 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { fanOutStatusColumn, readEventScope } from '../lib/support/portalBroadcast'
+
+const logger = createLogger('staff').child({ component: 'subscribers/support-portal-status-column-updated' })
+
+/**
+ * Persistent, unlike the other support-portal subscribers: re-deriving every portal
+ * ticket in a column is the one potentially expensive fan-out, so it runs on the
+ * queue (retried on failure; `publishTaskPortalStatus` is compare-and-publish, so a
+ * retry is idempotent) instead of inside the admin's request. Column flag edits are
+ * rare, and until #2973 lands a `portal_updated` emitted from the worker may not
+ * reach an open portal page live; the portal derives status on read, so the page is
+ * correct on its next load.
+ */
+export const metadata = {
+  event: 'staff.timesheets.time_task_status.updated',
+  persistent: true,
+  id: 'staff:support-portal-status-column-updated',
+}
+
+type ResolverContext = { resolve: <T = unknown>(name: string) => T }
+
+type Payload = Record<string, unknown>
+
+export default async function handle(payload: Payload, ctx: ResolverContext): Promise<void> {
+  try {
+    const scope = readEventScope(payload)
+    const statusId = typeof payload.id === 'string' ? payload.id : null
+    if (!scope || !statusId) return
+    await fanOutStatusColumn((ctx.resolve('em') as EntityManager).fork(), statusId, scope)
+  } catch (err) {
+    logger.error('staff:support-portal-status-column-updated failed', { err, id: payload?.id ?? null })
+    throw err
+  }
+}

package/src/modules/staff/subscribers/support-portal-task-status-changed.ts

@@ -0,0 +1,34 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { publishTaskPortalStatus, readEventScope } from '../lib/support/portalBroadcast'
+
+const logger = createLogger('staff').child({ component: 'subscribers/support-portal-task-status-changed' })
+
+/**
+ * Ephemeral on purpose: `portal_updated` is portal-only, and the event bus does not
+ * relay portal-only events across processes (open issue #2973). Run inline in the web
+ * process that executed the command, where the portal SSE stream lives. Make this
+ * persistent again once #2973 lands.
+ */
+export const metadata = {
+  event: 'staff.timesheets.time_task.status_changed',
+  persistent: false,
+  id: 'staff:support-portal-task-status-changed',
+}
+
+type ResolverContext = { resolve: <T = unknown>(name: string) => T }
+
+type Payload = Record<string, unknown>
+
+export default async function handle(payload: Payload, ctx: ResolverContext): Promise<void> {
+  try {
+    const scope = readEventScope(payload)
+    const taskId = typeof payload.id === 'string' ? payload.id : null
+    if (!scope || !taskId) return
+    await publishTaskPortalStatus((ctx.resolve('em') as EntityManager).fork(), taskId, scope, { always: true })
+  } catch (err) {
+    logger.error('staff:support-portal-task-status-changed failed', { err, id: payload?.id ?? null })
+    getTelemetryRuntime()?.reportError(err, { module: 'staff', code: 'staff.support_portal_task_status_changed_failed' })
+  }
+}

package/src/modules/staff/subscribers/support-portal-task-updated.ts

@@ -0,0 +1,34 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { publishTaskPortalStatus, readEventScope } from '../lib/support/portalBroadcast'
+
+const logger = createLogger('staff').child({ component: 'subscribers/support-portal-task-updated' })
+
+/**
+ * Ephemeral on purpose: `portal_updated` is portal-only, and the event bus does not
+ * relay portal-only events across processes (open issue #2973). Run inline in the web
+ * process that executed the command, where the portal SSE stream lives. Make this
+ * persistent again once #2973 lands.
+ */
+export const metadata = {
+  event: 'staff.timesheets.time_task.updated',
+  persistent: false,
+  id: 'staff:support-portal-task-updated',
+}
+
+type ResolverContext = { resolve: <T = unknown>(name: string) => T }
+
+type Payload = Record<string, unknown>
+
+export default async function handle(payload: Payload, ctx: ResolverContext): Promise<void> {
+  try {
+    const scope = readEventScope(payload)
+    const taskId = typeof payload.id === 'string' ? payload.id : null
+    if (!scope || !taskId) return
+    await publishTaskPortalStatus((ctx.resolve('em') as EntityManager).fork(), taskId, scope)
+  } catch (err) {
+    logger.error('staff:support-portal-task-updated failed', { err, id: payload?.id ?? null })
+    getTelemetryRuntime()?.reportError(err, { module: 'staff', code: 'staff.support_portal_task_updated_failed' })
+  }
+}

package/src/modules/staff/subscribers/support-ticket-created-notification.ts

@@ -0,0 +1,27 @@
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { notifySupportTicket } from '../lib/support/notifications'
+
+const logger = createLogger('staff').child({ component: 'subscribers/support-ticket-created-notification' })
+
+export const metadata = {
+  event: 'staff.support_ticket.created',
+  persistent: true,
+  id: 'staff:support-ticket-created-notification',
+}
+
+type ResolverContext = { resolve: <T = unknown>(name: string) => T }
+
+type Payload = Record<string, unknown>
+
+export default async function handle(payload: Payload, ctx: ResolverContext): Promise<void> {
+  try {
+    const taskId = typeof payload.taskId === 'string' ? payload.taskId : null
+    const tenantId = typeof payload.tenantId === 'string' ? payload.tenantId : null
+    const organizationId = typeof payload.organizationId === 'string' ? payload.organizationId : null
+    if (!taskId || !tenantId || !organizationId) return
+    await notifySupportTicket(ctx, { taskId, tenantId, organizationId, kind: 'created' })
+  } catch (err) {
+    logger.error('staff:support-ticket-created-notification failed', { err, id: payload?.id ?? null })
+    throw err
+  }
+}

package/src/modules/staff/subscribers/support-ticket-customer-replied-notification.ts

@@ -0,0 +1,27 @@
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { notifySupportTicket } from '../lib/support/notifications'
+
+const logger = createLogger('staff').child({ component: 'subscribers/support-ticket-customer-replied-notification' })
+
+export const metadata = {
+  event: 'staff.support_ticket.customer_replied',
+  persistent: true,
+  id: 'staff:support-ticket-customer-replied-notification',
+}
+
+type ResolverContext = { resolve: <T = unknown>(name: string) => T }
+
+type Payload = Record<string, unknown>
+
+export default async function handle(payload: Payload, ctx: ResolverContext): Promise<void> {
+  try {
+    const taskId = typeof payload.taskId === 'string' ? payload.taskId : null
+    const tenantId = typeof payload.tenantId === 'string' ? payload.tenantId : null
+    const organizationId = typeof payload.organizationId === 'string' ? payload.organizationId : null
+    if (!taskId || !tenantId || !organizationId) return
+    await notifySupportTicket(ctx, { taskId, tenantId, organizationId, kind: 'customer_replied' })
+  } catch (err) {
+    logger.error('staff:support-ticket-customer-replied-notification failed', { err, id: payload?.id ?? null })
+    throw err
+  }
+}

package/src/modules/staff/subscribers/support-ticket-unnotified-clear.ts

@@ -0,0 +1,29 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { clearSupportTicketUnnotified } from '../lib/support/notifications'
+
+const logger = createLogger('staff').child({ component: 'subscribers/support-ticket-unnotified-clear' })
+
+export const metadata = {
+  event: 'staff.timesheets.time_task.assignee_changed',
+  persistent: true,
+  id: 'staff:support-ticket-unnotified-clear',
+}
+
+type ResolverContext = { resolve: <T = unknown>(name: string) => T }
+
+type Payload = Record<string, unknown>
+
+export default async function handle(payload: Payload, ctx: ResolverContext): Promise<void> {
+  try {
+    const taskId = typeof payload.id === 'string' ? payload.id : null
+    const tenantId = typeof payload.tenantId === 'string' ? payload.tenantId : null
+    const organizationId = typeof payload.organizationId === 'string' ? payload.organizationId : null
+    if (!taskId || !tenantId || !organizationId || !payload.assigneeStaffMemberId) return
+    const em = (ctx.resolve('em') as EntityManager).fork()
+    await clearSupportTicketUnnotified(em, { taskId, tenantId, organizationId })
+  } catch (err) {
+    logger.error('staff:support-ticket-unnotified-clear failed', { err, id: payload?.id ?? null })
+    throw err
+  }
+}

package/src/modules/staff/subscribers/time-task-assignee-notification.ts

@@ -0,0 +1,102 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { notificationTypes } from '../notifications'
+import { StaffTeamMember, StaffTimeTask } from '../data/entities'
+import { resolveAssignmentGraceDaysFromContainer } from '../lib/time-tracking/projectAssignment'
+import { notifyProjectWork, resolveProjectWorkRecipients } from '../lib/time-tracking/workRecipients'
+
+const logger = createLogger('staff').child({ component: 'subscribers/time-task-assignee-notification' })
+
+const RELEASED_TYPE = 'staff.timesheets.time_task.released'
+const ASSIGNED_TYPE = 'staff.timesheets.time_task.assigned'
+
+export const metadata = {
+  event: 'staff.timesheets.time_task.assignee_changed',
+  persistent: true,
+  id: 'staff:time-task-assignee-notification',
+}
+
+export type TaskAssigneeChangedPayload = {
+  id?: string | null
+  tenantId?: string | null
+  organizationId?: string | null
+  timeProjectId?: string | null
+  previousAssigneeStaffMemberId?: string | null
+  assigneeStaffMemberId?: string | null
+  changeKind?: 'default' | 'claim' | 'release' | 'manual' | null
+  actorUserId?: string | null
+}
+
+type ResolverContext = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export type AssigneeNotificationPlan = 'released' | 'assigned' | null
+
+export function planAssigneeNotification(payload: TaskAssigneeChangedPayload): AssigneeNotificationPlan {
+  const kind = payload.changeKind ?? null
+  const next = payload.assigneeStaffMemberId ?? null
+  if (kind === 'release') return 'released'
+  if (kind === 'manual') return next ? 'assigned' : 'released'
+  return null
+}
+
+export default async function handle(payload: TaskAssigneeChangedPayload, ctx: ResolverContext): Promise<void> {
+  try {
+    const plan = planAssigneeNotification(payload)
+    const taskId = payload.id ?? null
+    const tenantId = payload.tenantId ?? null
+    const organizationId = payload.organizationId ?? null
+    if (!plan || !taskId || !tenantId || !organizationId) return
+    const scope = { tenantId, organizationId }
+    const em = (ctx.resolve('em') as EntityManager).fork()
+    const task = await em.findOne(StaffTimeTask, { id: taskId, tenantId, organizationId, deletedAt: null })
+    if (!task) return
+    const build = {
+      bodyVariables: { reference: task.reference, title: task.title },
+      sourceEntityType: 'staff:staff_time_task',
+      sourceEntityId: task.id,
+      linkHref: `/backend/staff/time-tracking/board?projectId=${encodeURIComponent(task.timeProjectId)}&task=${encodeURIComponent(task.id)}`,
+      groupKey: `staff:time-task-${plan}:${task.id}`,
+    }
+
+    if (plan === 'assigned') {
+      const typeDef = notificationTypes.find((type) => type.type === ASSIGNED_TYPE)
+      if (!typeDef || !task.assigneeStaffMemberId) return
+      const assignee = await findOneWithDecryption(
+        em,
+        StaffTeamMember,
+        { id: task.assigneeStaffMemberId, tenantId, organizationId, deletedAt: null },
+        undefined,
+        scope,
+      )
+      const assigneeUserId = assignee?.userId ?? null
+      if (!assigneeUserId || assigneeUserId === (payload.actorUserId ?? null)) return
+      await notifyProjectWork(ctx, scope, { typeDef, recipients: { step: 1, userIds: [assigneeUserId] }, build })
+      return
+    }
+
+    const typeDef = notificationTypes.find((type) => type.type === RELEASED_TYPE)
+    if (!typeDef) return
+    const graceDays = await resolveAssignmentGraceDaysFromContainer(ctx, tenantId)
+    const recipients = await resolveProjectWorkRecipients(em, scope, {
+      timeProjectId: task.timeProjectId,
+      actorUserId: payload.actorUserId ?? null,
+      graceDays,
+    })
+    const result = await notifyProjectWork(ctx, scope, { typeDef, recipients, build })
+    if (result.notifiedCount === 0) {
+      logger.warn('staff released-task notification reached nobody', {
+        tenantId,
+        organizationId,
+        timeProjectId: task.timeProjectId,
+        taskId: task.id,
+        step: result.step,
+      })
+    }
+  } catch (err) {
+    logger.error('staff task assignee notification failed', { err, taskId: payload.id ?? null })
+    throw err
+  }
+}