@open-mercato/core 0.10.1-develop.7717.1.2befe9c634 → 0.10.1-develop.7721.1.b5c4a00a68

package/src/modules/staff/data/enrichers.ts

@@ -5,11 +5,13 @@ import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacS
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { CustomerEntity } from '@open-mercato/core/modules/customers/data/entities'
 import {
+  StaffSupportTicket,
   StaffTeamMember,
   StaffTimeProject,
   StaffTimeReport,
   StaffTimeReportEntry,
   StaffTimeReportEvent,
+  StaffTimeProjectMember,
   StaffTimeTask,
   StaffTimeTaskStatus,
 } from './entities'
@@ -22,8 +24,15 @@ import {
   type MemberPreview,
 } from '../lib/timesheets-projects/listProjectMembersPreview'
 import { computeTaskRollups, EMPTY_TASK_ROLLUP } from '../lib/timesheets-tasks/computeTaskRollups'
+import { derivePortalStatus } from '../lib/support/portalStatus'
+import {
+  isActiveAssignment,
+  normalizeAssignmentGraceDays,
+  resolveAssignmentGraceDaysFromContainer,
+} from '../lib/time-tracking/projectAssignment'
 
 const MANAGE_FEATURE = 'staff.timesheets.projects.manage'
+const TASKS_VIEW_FEATURE = 'staff.timesheets.tasks.view'
 const RATES_FEATURE = 'staff.timesheets.rates.view'
 
 /**
@@ -635,6 +644,198 @@ const taskContextEnricher: ResponseEnricher<EntityRecord, TaskContextEnrichment>
   },
 }
 
+export type SupportTicketEnrichment = {
+  _staffSupport: {
+    ticket: {
+      id: string
+      supportReference: string
+      category: { value: string; label: string }
+      routedVia: string
+      portalStatus: string
+      customerSnapshot: Record<string, unknown> | null
+      reportedByCustomerUserId: string | null
+      unnotifiedAt: string | null
+      customerRequest: { subject: string; body: string } | null
+    } | null
+  }
+}
+
+const EMPTY_SUPPORT_TICKET: SupportTicketEnrichment = { _staffSupport: { ticket: null } }
+
+/**
+ * The customer request behind a portal ticket. Internal tasks get `ticket: null`.
+ * `customerRequest` is the encrypted original the portal shows, read here so the
+ * drawer can show staff exactly what the customer sees.
+ */
+const supportTicketEnricher: ResponseEnricher<EntityRecord, SupportTicketEnrichment> = {
+  id: 'staff.timesheets-tasks-support-ticket',
+  targetEntity: 'staff:staff_time_task',
+  priority: 4,
+  timeout: 3000,
+  critical: false,
+  fallback: { ...EMPTY_SUPPORT_TICKET },
+  cacheableOnListHit: false,
+
+  async enrichOne(record, context) {
+    const enriched = await this.enrichMany!([record], context)
+    return enriched[0]
+  },
+
+  async enrichMany(records, context) {
+    if (records.length === 0) return records as (EntityRecord & SupportTicketEnrichment)[]
+    const ctx = context as InternalContext
+    if (!ctx.tenantId || !ctx.organizationId) {
+      return records.map((record) => ({ ...record, ...EMPTY_SUPPORT_TICKET }))
+    }
+    const scope = { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
+    const portalRecordIds = records
+      .filter((record) => record.source === 'portal' || record.source === undefined)
+      .map((record) => record.id)
+      .filter((id): id is string => typeof id === 'string')
+    if (portalRecordIds.length === 0) {
+      return records.map((record) => ({ ...record, ...EMPTY_SUPPORT_TICKET }))
+    }
+    const tickets = await findWithDecryption(
+      ctx.em.fork(),
+      StaffSupportTicket,
+      { taskId: { $in: portalRecordIds }, ...scope, deletedAt: null },
+      undefined,
+      scope,
+    )
+    if (tickets.length === 0) {
+      return records.map((record) => ({ ...record, ...EMPTY_SUPPORT_TICKET }))
+    }
+    const ticketByTask = new Map(tickets.map((ticket) => [ticket.taskId, ticket]))
+    const tasks = await ctx.em.fork().find(
+      StaffTimeTask,
+      { id: { $in: tickets.map((ticket) => ticket.taskId) }, ...scope },
+      { fields: ['id', 'taskStatusId'] },
+    )
+    const statusIds = [...new Set(tasks.map((task) => task.taskStatusId))]
+    const statuses = statusIds.length
+      ? await ctx.em.fork().find(StaffTimeTaskStatus, { id: { $in: statusIds }, ...scope }, { fields: ['id', 'isDefault', 'isDone'] })
+      : []
+    const statusById = new Map(statuses.map((status) => [status.id, status]))
+    const statusByTask = new Map(tasks.map((task) => [task.id, statusById.get(task.taskStatusId) ?? null]))
+
+    return records.map((record) => {
+      const ticket = typeof record.id === 'string' ? ticketByTask.get(record.id) : undefined
+      if (!ticket) return { ...record, ...EMPTY_SUPPORT_TICKET }
+      const request = ticket.customerRequestSnapshot
+      return {
+        ...record,
+        _staffSupport: {
+          ticket: {
+            id: ticket.id,
+            supportReference: ticket.supportReference,
+            category: ticket.categorySnapshot,
+            routedVia: ticket.routedVia,
+            portalStatus: derivePortalStatus(statusByTask.get(ticket.taskId) ?? null),
+            customerSnapshot: ticket.customerSnapshot ?? null,
+            reportedByCustomerUserId: ticket.reportedByCustomerUserId ?? null,
+            unnotifiedAt: ticket.unnotifiedAt ? ticket.unnotifiedAt.toISOString() : null,
+            customerRequest:
+              request && typeof request === 'object' && typeof request.subject === 'string'
+                ? { subject: request.subject, body: typeof request.body === 'string' ? request.body : '' }
+                : null,
+          },
+        },
+      }
+    })
+  },
+}
+
+/**
+ * Whether the CALLER may claim or release each task right now, decided by the same
+ * rule the claim and release commands enforce: claiming needs an active assigner
+ * membership of the task's project inside its assignment window (plus the tenant's
+ * grace days), an unassigned task and a column that is not done; releasing needs the
+ * caller to be the current assignee. The drawer reads these instead of guessing from
+ * a page of project members, so it never offers an action the server refuses.
+ */
+export type TaskAssignmentEnrichment = {
+  _staffAssignment: {
+    canClaim: boolean
+    canRelease: boolean
+  }
+}
+
+const NO_TASK_ASSIGNMENT: TaskAssignmentEnrichment = { _staffAssignment: { canClaim: false, canRelease: false } }
+
+const taskAssignmentEnricher: ResponseEnricher<EntityRecord, TaskAssignmentEnrichment> = {
+  id: 'staff.timesheets-tasks-assignment',
+  targetEntity: 'staff:staff_time_task',
+  features: [TASKS_VIEW_FEATURE],
+  priority: 3,
+  timeout: 3000,
+  critical: false,
+  fallback: { ...NO_TASK_ASSIGNMENT },
+  cacheableOnListHit: false,
+
+  async enrichOne(record, context) {
+    const enriched = await this.enrichMany!([record], context)
+    return enriched[0]
+  },
+
+  async enrichMany(records, context) {
+    if (records.length === 0) return records as (EntityRecord & TaskAssignmentEnrichment)[]
+    const ctx = context as InternalContext
+    if (!ctx.tenantId || !ctx.organizationId || !ctx.userId) {
+      return records.map((record) => ({ ...record, ...NO_TASK_ASSIGNMENT }))
+    }
+    const scope = { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
+    const callerStaffMemberId = await resolveCallerStaffMemberId(ctx)
+    if (!callerStaffMemberId) return records.map((record) => ({ ...record, ...NO_TASK_ASSIGNMENT }))
+
+    const taskIds = records.map((record) => record.id).filter((id): id is string => typeof id === 'string')
+    const tasks = await ctx.em.fork().find(
+      StaffTimeTask,
+      { id: { $in: taskIds }, ...scope, deletedAt: null },
+      { fields: ['id', 'timeProjectId', 'taskStatusId', 'assigneeStaffMemberId'] },
+    )
+    const taskById = new Map(tasks.map((task) => [task.id, task]))
+    const projectIds = [...new Set(tasks.map((task) => task.timeProjectId).filter(Boolean))]
+    const statusIds = [...new Set(tasks.map((task) => task.taskStatusId).filter(Boolean))]
+
+    const [statuses, memberships, graceDays] = await Promise.all([
+      statusIds.length
+        ? ctx.em.fork().find(StaffTimeTaskStatus, { id: { $in: statusIds }, ...scope }, { fields: ['id', 'isDone'] })
+        : Promise.resolve([]),
+      projectIds.length
+        ? ctx.em.fork().find(StaffTimeProjectMember, {
+            timeProjectId: { $in: projectIds },
+            staffMemberId: callerStaffMemberId,
+            isAssigner: true,
+            status: 'active',
+            deletedAt: null,
+            ...scope,
+          })
+        : Promise.resolve([]),
+      resolveAssignmentGraceDaysFromContainer(ctx.container, ctx.tenantId),
+    ])
+    const doneStatusIds = new Set(statuses.filter((status) => status.isDone).map((status) => status.id))
+    const now = new Date()
+    const assignerProjectIds = new Set(
+      memberships
+        .filter((membership) => isActiveAssignment(membership, now, normalizeAssignmentGraceDays(graceDays)))
+        .map((membership) => membership.timeProjectId),
+    )
+
+    return records.map((record) => {
+      const task = taskById.get(record.id)
+      if (!task) return { ...record, ...NO_TASK_ASSIGNMENT }
+      const assignee = task.assigneeStaffMemberId ?? null
+      return {
+        ...record,
+        _staffAssignment: {
+          canClaim: !assignee && assignerProjectIds.has(task.timeProjectId) && !doneStatusIds.has(task.taskStatusId),
+          canRelease: assignee === callerStaffMemberId,
+        },
+      }
+    })
+  },
+}
+
 /**
  * What a report row cannot say about itself: whether it is frozen, how many entries
  * the freeze holds, and whether anyone has taken a file out of it.
@@ -787,6 +988,8 @@ const apiEnrichers: ResponseEnricher[] = [
   taskRollupEnricher,
   taskTagEnricher,
   taskContextEnricher,
+  supportTicketEnricher,
+  taskAssignmentEnricher,
   timeEntryEnricher,
   reportEnricher,
 ]

package/src/modules/staff/data/entities.ts

@@ -376,6 +376,11 @@ export class StaffTeamMemberAddress {
 export type StaffTimeEntrySource = TimeEntrySource
 export type StaffTimeProjectStatus = 'active' | 'on_hold' | 'completed'
 export type StaffTimeProjectMemberStatus = 'active' | 'inactive'
+export type StaffTimeTaskSource = 'internal' | 'portal'
+export type StaffTimeTaskCommentVisibility = 'internal' | 'customer'
+export type StaffTimeTaskCommentAuthorKind = 'staff' | 'customer'
+export type StaffSupportRoutedVia = 'category' | 'fallback'
+export type StaffSupportPortalStatus = 'received' | 'in_progress' | 'resolved'
 export type StaffTimeEntrySegmentType = 'work' | 'break'
 export type StaffTimeProjectBudgetKind = 'none' | 'hours' | 'amount'
 export type StaffTimeReportPeriodKind = 'week' | 'month' | 'year' | 'custom'
@@ -572,6 +577,9 @@ export class StaffTimeProject {
   @Property({ name: 'budget_alerted_at_percent', type: 'integer', nullable: true })
   budgetAlertedAtPercent?: number | null
 
+  @Property({ name: 'default_assignee_staff_member_id', type: 'uuid', nullable: true })
+  defaultAssigneeStaffMemberId?: string | null
+
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
@@ -587,7 +595,10 @@ export class StaffTimeProject {
 @Index({ name: 'staff_time_project_members_project_idx', properties: ['organizationId', 'timeProjectId'] })
 @Index({ name: 'staff_time_project_members_member_idx', properties: ['organizationId', 'staffMemberId'] })
 @Index({ name: 'staff_time_project_members_unique_idx', properties: ['organizationId', 'tenantId', 'timeProjectId', 'staffMemberId'], options: { unique: true, where: 'deleted_at IS NULL' } })
+@Index({ name: 'staff_time_project_members_assigner_idx', properties: ['tenantId', 'organizationId', 'timeProjectId'], options: { where: "is_assigner = true AND status = 'active' AND deleted_at IS NULL" } })
 export class StaffTimeProjectMember {
+  [OptionalProps]?: 'status' | 'showInGrid' | 'isAssigner' | 'createdAt' | 'updatedAt'
+
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
 
@@ -612,6 +623,9 @@ export class StaffTimeProjectMember {
   @Property({ name: 'show_in_grid', type: 'boolean', default: false })
   showInGrid: boolean = false
 
+  @Property({ name: 'is_assigner', type: 'boolean', default: false })
+  isAssigner: boolean = false
+
   @Property({ name: 'assigned_start_date', type: 'date' })
   assignedStartDate!: Date
 
@@ -684,8 +698,9 @@ export class StaffTimeTaskStatus {
 @Index({ name: 'staff_time_tasks_assignee_idx', properties: ['organizationId', 'assigneeStaffMemberId'] })
 @Index({ name: 'staff_time_tasks_sequence_unique_idx', properties: ['organizationId', 'tenantId', 'timeProjectId', 'sequenceNumber'], options: { unique: true, where: 'deleted_at IS NULL' } })
 @Index({ name: 'staff_time_tasks_reference_unique_idx', properties: ['organizationId', 'tenantId', 'reference'], options: { unique: true, where: 'deleted_at IS NULL' } })
+@Index({ name: 'staff_time_tasks_portal_customer_idx', properties: ['tenantId', 'organizationId', 'customerId', 'updatedAt'], options: { where: "source = 'portal' AND deleted_at IS NULL" } })
 export class StaffTimeTask {
-  [OptionalProps]?: 'sequenceNumber' | 'position' | 'createdAt' | 'updatedAt'
+  [OptionalProps]?: 'sequenceNumber' | 'position' | 'source' | 'createdAt' | 'updatedAt'
 
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
@@ -729,6 +744,110 @@ export class StaffTimeTask {
   @Property({ name: 'closed_at', type: Date, nullable: true })
   closedAt?: Date | null
 
+  @Property({ type: 'text', default: 'internal' })
+  source: StaffTimeTaskSource = 'internal'
+
+  @Property({ name: 'customer_id', type: 'uuid', nullable: true })
+  customerId?: string | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
+@Entity({ tableName: 'staff_support_tickets' })
+@Index({ name: 'staff_support_tickets_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'staff_support_tickets_task_unique_idx', properties: ['tenantId', 'organizationId', 'taskId'], options: { unique: true, where: 'deleted_at IS NULL' } })
+@Index({ name: 'staff_support_tickets_reference_unique_idx', properties: ['tenantId', 'organizationId', 'supportReference'], options: { unique: true, where: 'deleted_at IS NULL' } })
+@Index({ name: 'staff_support_tickets_sequence_idx', properties: ['tenantId', 'organizationId', 'supportSequenceNumber'] })
+export class StaffSupportTicket {
+  [OptionalProps]?: 'createdAt' | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'task_id', type: 'uuid' })
+  taskId!: string
+
+  @Property({ name: 'customer_snapshot', type: 'jsonb', nullable: true })
+  customerSnapshot?: Record<string, unknown> | null
+
+  @Property({ name: 'reported_by_customer_user_id', type: 'uuid', nullable: true })
+  reportedByCustomerUserId?: string | null
+
+  @Property({ name: 'support_reference', type: 'text' })
+  supportReference!: string
+
+  @Property({ name: 'support_sequence_number', type: 'integer' })
+  supportSequenceNumber!: number
+
+  @Property({ name: 'category_value', type: 'text' })
+  categoryValue!: string
+
+  @Property({ name: 'category_snapshot', type: 'jsonb' })
+  categorySnapshot!: { value: string; label: string }
+
+  @Property({ name: 'routed_via', type: 'text' })
+  routedVia!: StaffSupportRoutedVia
+
+  @Property({ name: 'customer_request_snapshot', type: 'jsonb' })
+  customerRequestSnapshot!: { subject: string; body: string }
+
+  @Property({ name: 'unnotified_at', type: Date, nullable: true })
+  unnotifiedAt?: Date | null
+
+  @Property({ name: 'portal_status_published', type: 'text', nullable: true })
+  portalStatusPublished?: StaffSupportPortalStatus | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
+@Entity({ tableName: 'staff_support_routing_rules' })
+@Index({ name: 'staff_support_routing_rules_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({
+  name: 'staff_support_routing_rules_category_unique_idx',
+  expression:
+    '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',
+})
+export class StaffSupportRoutingRule {
+  [OptionalProps]?: 'isActive' | 'createdAt' | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'category_value', type: 'text', nullable: true })
+  categoryValue?: string | null
+
+  @Property({ name: 'time_project_id', type: 'uuid' })
+  timeProjectId!: string
+
+  @Property({ name: 'is_active', type: 'boolean', default: true })
+  isActive: boolean = true
+
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
@@ -743,7 +862,7 @@ export class StaffTimeTask {
 @Index({ name: 'staff_time_task_comments_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
 @Index({ name: 'staff_time_task_comments_task_idx', properties: ['organizationId', 'taskId', 'createdAt'] })
 export class StaffTimeTaskComment {
-  [OptionalProps]?: 'createdAt' | 'updatedAt'
+  [OptionalProps]?: 'visibility' | 'authorKind' | 'createdAt' | 'updatedAt'
 
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
@@ -763,6 +882,18 @@ export class StaffTimeTaskComment {
   @Property({ name: 'author_user_id', type: 'uuid', nullable: true })
   authorUserId?: string | null
 
+  @Property({ type: 'text', default: 'internal' })
+  visibility: StaffTimeTaskCommentVisibility = 'internal'
+
+  @Property({ name: 'author_kind', type: 'text', default: 'staff' })
+  authorKind: StaffTimeTaskCommentAuthorKind = 'staff'
+
+  @Property({ name: 'author_customer_user_id', type: 'uuid', nullable: true })
+  authorCustomerUserId?: string | null
+
+  @Property({ name: 'author_display_snapshot', type: 'jsonb', nullable: true })
+  authorDisplaySnapshot?: { displayName: string } | null
+
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 

package/src/modules/staff/data/extensions.ts

@@ -8,7 +8,7 @@ import type { EntityExtension } from '@open-mercato/shared/modules/entities'
  * `staff_time_projects.customer_id` are plain uuid columns; the declarations below are
  * the traversal contract over them and nothing more. They contain **string ids only** —
  * no import of a customers or sales symbol — so they add no load-time dependency and
- * staff's `requires: ['planner', 'resources']` in `index.ts` does not grow. That matters:
+ * staff's `requires` in `index.ts` never gains `customers` or `sales`. That matters:
  * staff is slated for extraction into a standalone package, and a link that pulled in
  * `@open-mercato/core/modules/customers` would break the extraction.
  *
@@ -62,6 +62,14 @@ const entityExtensions: EntityExtension[] = [
     cardinality: 'one-to-many',
     description: 'Time projects owned by a customer record (D-9: the customers supertype)',
   },
+  {
+    base: 'customers:customer_entity',
+    extension: 'staff:staff_time_task',
+    join: { baseKey: 'id', extensionKey: 'customer_id' },
+    table: 'staff_time_tasks',
+    cardinality: 'one-to-many',
+    description: 'Tasks filed for a customer record, such as customer portal support tickets',
+  },
 ]
 
 export const extensions = entityExtensions

package/src/modules/staff/data/validators.ts

@@ -476,6 +476,7 @@ export const staffTimeProjectUpdateSchema = z.object({
   budgetKind: timeProjectBudgetKindSchema.optional(),
   budgetValue: numericAmountSchema.optional().nullable(),
   budgetWarnAtPercent: z.number().int().min(1).max(100).optional(),
+  defaultAssigneeStaffMemberId: z.string().uuid().optional().nullable(),
 })
 
 export const staffTimeProjectMemberAssignSchema = z.object({
@@ -486,6 +487,7 @@ export const staffTimeProjectMemberAssignSchema = z.object({
   status: timeProjectMemberStatusSchema.optional().default('active'),
   assignedStartDate: z.coerce.date(),
   assignedEndDate: z.coerce.date().optional().nullable(),
+  isAssigner: z.boolean().optional(),
 })
 
 export const staffTimeProjectMemberUpdateSchema = z.object({
@@ -493,6 +495,7 @@ export const staffTimeProjectMemberUpdateSchema = z.object({
   role: z.string().max(100).optional().nullable(),
   status: timeProjectMemberStatusSchema.optional(),
   assignedEndDate: z.coerce.date().optional().nullable(),
+  isAssigner: z.boolean().optional(),
 })
 
 export const staffMyProjectVisibilityUpdateSchema = z.object({
@@ -596,13 +599,24 @@ export const staffTimeTaskCommentCreateSchema = z.object({
   taskId: z.string().uuid(),
   body: z.string().trim().min(1).max(5000),
   authorUserId: z.string().uuid().optional().nullable(),
+  visibility: z.enum(['internal', 'customer']).optional(),
 })
 
 export const staffTimeTaskCommentUpdateSchema = z.object({
   ...scopedUpdateFields,
   body: z.string().trim().min(1).max(5000),
+  visibility: z.enum(['internal', 'customer']).optional(),
 })
 
+export const staffTimeTaskCommentUpdateRequestSchema = staffTimeTaskCommentUpdateSchema
+  .extend({
+    body: z.string().trim().min(1).max(5000).optional(),
+  })
+  .refine((value) => value.body !== undefined || value.visibility !== undefined, {
+    message: 'body or visibility is required',
+    path: ['body'],
+  })
+
 export const staffTimeTagCreateSchema = z.object({
   ...scopedCreateFields,
   slug: timeSlugSchema,
@@ -721,6 +735,7 @@ export type StaffTimeTaskUpdateInput = z.infer<typeof staffTimeTaskUpdateSchema>
 export type StaffTimeTaskStatusChangeInput = z.infer<typeof staffTimeTaskStatusChangeSchema>
 export type StaffTimeTaskCommentCreateInput = z.infer<typeof staffTimeTaskCommentCreateSchema>
 export type StaffTimeTaskCommentUpdateInput = z.infer<typeof staffTimeTaskCommentUpdateSchema>
+export type StaffTimeTaskCommentUpdateRequestInput = z.infer<typeof staffTimeTaskCommentUpdateRequestSchema>
 export type StaffTimeTagCreateInput = z.infer<typeof staffTimeTagCreateSchema>
 export type StaffTimeTaskTagAssignmentInput = z.infer<typeof staffTimeTaskTagAssignmentSchema>
 export type StaffTimeEntryTagAssignmentInput = z.infer<typeof staffTimeEntryTagAssignmentSchema>
@@ -731,3 +746,24 @@ export type StaffTimeReportCloseInput = z.infer<typeof staffTimeReportCloseSchem
 export type StaffTimeReportUnlockInput = z.infer<typeof staffTimeReportUnlockSchema>
 export type StaffTimeProjectChangeCurrencyInput = z.infer<typeof staffTimeProjectChangeCurrencySchema>
 export type StaffTimeTrackingSettingsInput = z.infer<typeof staffTimeTrackingSettingsSchema>
+
+export const staffSupportRoutingRuleCreateSchema = z.object({
+  ...scopedCreateFields,
+  categoryValue: z.string().trim().min(1).max(150).optional().nullable(),
+  timeProjectId: z.string().uuid(),
+  isActive: z.boolean().optional().default(true),
+})
+
+export const staffSupportRoutingRuleUpdateSchema = z.object({
+  ...scopedUpdateFields,
+  timeProjectId: z.string().uuid().optional(),
+  isActive: z.boolean().optional(),
+})
+
+export const staffSupportFallbackProjectCreateSchema = z.object({
+  ...scopedCreateFields,
+})
+
+export type StaffSupportRoutingRuleCreateInput = z.infer<typeof staffSupportRoutingRuleCreateSchema>
+export type StaffSupportRoutingRuleUpdateInput = z.infer<typeof staffSupportRoutingRuleUpdateSchema>
+export type StaffSupportFallbackProjectCreateInput = z.infer<typeof staffSupportFallbackProjectCreateSchema>

package/src/modules/staff/encryption.ts

@@ -9,6 +9,12 @@ export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
       { field: 'unavailability_reason_value' },
     ],
   },
+  {
+    entityId: 'staff:staff_support_ticket',
+    fields: [
+      { field: 'customer_request_snapshot' },
+    ],
+  },
 ]
 
 export default defaultEncryptionMaps

package/src/modules/staff/events.payloads.ts

@@ -1,5 +1,5 @@
 /**
- * Payload contracts for the `staff.timesheets.*` event family.
+ * Payload contracts for the `staff.timesheets.*` and `staff.support_ticket.*` event families.
  *
  * **Why this file exists.** Outbound webhooks in this platform are not registered
  * per event: `packages/webhooks` subscribes once with `event: '*'`
@@ -109,6 +109,18 @@ const taskStatusChanged = scope
   })
   .passthrough()
 
+/** Ids only: the event is `clientBroadcast: true`, so no names, no customer and no text. */
+const taskAssigneeChanged = scope
+  .extend({
+    id: z.string(),
+    timeProjectId: z.string(),
+    previousAssigneeStaffMemberId: z.string().nullable(),
+    assigneeStaffMemberId: z.string().nullable(),
+    changeKind: z.enum(['default', 'claim', 'release', 'manual']),
+    actorUserId: z.string().nullable().optional(),
+  })
+  .passthrough()
+
 /**
  * No `customerId`: the event is `clientBroadcast: true` and the DOM Event Bridge
  * applies no feature check, so the one field linking a report to a named client is
@@ -241,6 +253,7 @@ export const staffTimeTrackingEventPayloadSchemas = {
   'staff.timesheets.time_task.updated': crudPayload,
   'staff.timesheets.time_task.deleted': crudPayload,
   'staff.timesheets.time_task.status_changed': taskStatusChanged,
+  'staff.timesheets.time_task.assignee_changed': taskAssigneeChanged,
   'staff.timesheets.time_task_status.created': crudPayload,
   'staff.timesheets.time_task_status.updated': crudPayload,
   'staff.timesheets.time_task_status.deleted': crudPayload,
@@ -266,3 +279,76 @@ export type StaffTimeTrackingEventId = keyof typeof staffTimeTrackingEventPayloa
 export type StaffTimeTrackingEventPayload<TEventId extends StaffTimeTrackingEventId> = z.infer<
   typeof staffTimeTrackingEventPayloadSchemas[TEventId]
 >
+
+/**
+ * Names the customer and the ticket reference, so the event stays server-side
+ * (no `clientBroadcast`); webhooks and the notification subscriber read it.
+ */
+const supportTicketCreated = scope
+  .extend({
+    id: z.string(),
+    taskId: z.string(),
+    projectId: z.string(),
+    customerId: z.string(),
+    supportReference: z.string(),
+    categoryValue: z.string(),
+  })
+  .passthrough()
+
+const supportTicketCustomerReplied = scope
+  .extend({
+    id: z.string(),
+    taskId: z.string(),
+    projectId: z.string(),
+    commentId: z.string(),
+    supportReference: z.string(),
+  })
+  .passthrough()
+
+/** Ids only: the event is `clientBroadcast: true`, so no customer, no reference and no text. */
+const supportTicketActivityRecorded = scope
+  .extend({
+    id: z.string(),
+    taskId: z.string(),
+    projectId: z.string(),
+    kind: z.enum(['created', 'customer_replied', 'portal_status', 'attachment_added', 'attachment_removed']),
+    /** The changed attachment for `attachment_added` / `attachment_removed`, so distinct changes stay distinct for the 500 ms duplicate filter. */
+    attachmentId: z.string().optional(),
+  })
+  .passthrough()
+
+const supportTicketPortalUpdated = scope
+  .extend({
+    id: z.string(),
+    ticketId: z.string(),
+    supportReference: z.string(),
+    portalStatus: z.enum(['received', 'in_progress', 'resolved']),
+    kind: z.enum(['status', 'reply']),
+    /** The change announced: the task version for `status`, the comment id for `reply`. Keeps distinct changes distinct for the portal bridge's 500 ms duplicate filter. */
+    version: z.string().optional(),
+    /**
+     * The portal SSE stream narrows a broadcast to these customer-user ids. The
+     * emitter never publishes this event with an empty list, so a ticket update can
+     * only ever reach the portal users of the ticket's own customer.
+     */
+    recipientUserIds: z.array(z.string()).min(1),
+  })
+  .passthrough()
+
+/**
+ * Every declared `staff.support_ticket.*` event id and the payload a webhook endpoint
+ * subscribed to it receives. Same rules as the time-tracking map above: `tenantId` is
+ * required and every schema is `passthrough()`.
+ */
+export const staffSupportTicketEventPayloadSchemas = {
+  'staff.support_ticket.created': supportTicketCreated,
+  'staff.support_ticket.customer_replied': supportTicketCustomerReplied,
+  'staff.support_ticket.activity_recorded': supportTicketActivityRecorded,
+  'staff.support_ticket.portal_updated': supportTicketPortalUpdated,
+} as const
+
+export type StaffSupportTicketEventId = keyof typeof staffSupportTicketEventPayloadSchemas
+
+export type StaffSupportTicketEventPayload<TEventId extends StaffSupportTicketEventId> = z.infer<
+  typeof staffSupportTicketEventPayloadSchemas[TEventId]
+>