@open-mercato/core 0.7.1-develop.7178.1.ab93fbaf4e → 0.7.1-develop.7180.1.9717fbbb43

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

@@ -1,4 +1,7 @@
+import { OptionalProps } from '@mikro-orm/core'
 import { Entity, Enum, Index, ManyToOne, PrimaryKey, Property } from '@mikro-orm/decorators/legacy'
+import type { TimeEntrySource } from '../lib/time-tracking/timeEntrySources'
+import type { ReportGrouping } from '../lib/timesheets-reports/reportGroupings'
 
 export type StaffLeaveRequestStatus = 'pending' | 'approved' | 'rejected'
 
@@ -365,16 +368,33 @@ export class StaffTeamMemberAddress {
 
 // --- Timesheets entities (Phase 1) ---
 
-export type StaffTimeEntrySource = 'manual' | 'timer' | 'kiosk' | 'mobile'
+/**
+ * EP-37: the accepted values are the time-entry source registry, not a database
+ * enum, so an import integration can ship its own source. Re-exported from the
+ * registry so the entity and the registry cannot drift.
+ */
+export type StaffTimeEntrySource = TimeEntrySource
 export type StaffTimeProjectStatus = 'active' | 'on_hold' | 'completed'
 export type StaffTimeProjectMemberStatus = 'active' | 'inactive'
 export type StaffTimeEntrySegmentType = 'work' | 'break'
+export type StaffTimeProjectBudgetKind = 'none' | 'hours' | 'amount'
+export type StaffTimeReportPeriodKind = 'week' | 'month' | 'year' | 'custom'
+/** EP-36: the accepted values are the report grouping registry, not a DB enum. */
+export type StaffTimeReportGrouping = ReportGrouping
+export type StaffTimeReportNonBillableMode = 'separate' | 'exclude'
+export type StaffTimeReportStatus = 'draft' | 'closed'
+export type StaffTimeReportEventType = 'closed' | 'unlocked' | 'exported'
 
 @Entity({ tableName: 'staff_time_entries' })
 @Index({ name: 'staff_time_entries_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
 @Index({ name: 'staff_time_entries_member_date_idx', properties: ['organizationId', 'staffMemberId', 'date'] })
 @Index({ name: 'staff_time_entries_project_date_idx', properties: ['organizationId', 'timeProjectId', 'date'] })
+@Index({ name: 'staff_time_entries_task_idx', properties: ['organizationId', 'taskId'] })
+@Index({ name: 'staff_time_entries_member_overlap_idx', properties: ['organizationId', 'staffMemberId', 'date', 'startedAt'] })
+@Index({ name: 'staff_time_entries_locked_report_idx', properties: ['organizationId', 'lockedReportId'] })
 export class StaffTimeEntry {
+  [OptionalProps]?: 'durationMinutes' | 'isBillable' | 'source' | 'createdAt' | 'updatedAt'
+
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
 
@@ -405,6 +425,9 @@ export class StaffTimeEntry {
   @Property({ name: 'time_project_id', type: 'uuid', nullable: true })
   timeProjectId?: string | null
 
+  @Property({ name: 'task_id', type: 'uuid', nullable: true })
+  taskId?: string | null
+
   @Property({ name: 'customer_id', type: 'uuid', nullable: true })
   customerId?: string | null
 
@@ -414,7 +437,25 @@ export class StaffTimeEntry {
   @Property({ name: 'order_id', type: 'uuid', nullable: true })
   orderId?: string | null
 
-  @Enum({ items: ['manual', 'timer', 'kiosk', 'mobile'], type: 'text', name: 'source', default: 'manual' })
+  @Property({ name: 'is_billable', type: 'boolean', default: true })
+  isBillable: boolean = true
+
+  @Property({ name: 'rounded_minutes', type: 'integer', nullable: true })
+  roundedMinutes?: number | null
+
+  @Property({ name: 'rate_override_amount', type: 'numeric', precision: 14, scale: 4, nullable: true })
+  rateOverrideAmount?: string | null
+
+  @Property({ name: 'rate_currency_code', type: 'text', nullable: true })
+  rateCurrencyCode?: string | null
+
+  @Property({ name: 'locked_report_id', type: 'uuid', nullable: true })
+  lockedReportId?: string | null
+
+  @Property({ name: 'locked_at', type: Date, nullable: true })
+  lockedAt?: Date | null
+
+  @Property({ name: 'source', type: 'text', default: 'manual' })
   source: StaffTimeEntrySource = 'manual'
 
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
@@ -466,6 +507,8 @@ export class StaffTimeEntrySegment {
 @Index({ name: 'staff_time_projects_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
 @Index({ name: 'staff_time_projects_code_unique_idx', properties: ['organizationId', 'tenantId', 'code'], options: { unique: true, where: 'deleted_at IS NULL' } })
 export class StaffTimeProject {
+  [OptionalProps]?: 'status' | 'billableByDefault' | 'budgetKind' | 'budgetWarnAtPercent' | 'createdAt' | 'updatedAt'
+
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
 
@@ -481,6 +524,9 @@ export class StaffTimeProject {
   @Property({ name: 'customer_id', type: 'uuid', nullable: true })
   customerId?: string | null
 
+  @Property({ name: 'customer_snapshot', type: 'jsonb', nullable: true })
+  customerSnapshot?: Record<string, unknown> | null
+
   @Property({ type: 'text' })
   code!: string
 
@@ -505,6 +551,27 @@ export class StaffTimeProject {
   @Property({ name: 'start_date', type: 'date', nullable: true })
   startDate?: Date | null
 
+  @Property({ name: 'hourly_rate', type: 'numeric', precision: 14, scale: 4, nullable: true })
+  hourlyRate?: string | null
+
+  @Property({ name: 'currency_code', type: 'text', nullable: true })
+  currencyCode?: string | null
+
+  @Property({ name: 'billable_by_default', type: 'boolean', default: true })
+  billableByDefault: boolean = true
+
+  @Enum({ items: ['none', 'hours', 'amount'], type: 'text', name: 'budget_kind', default: 'none' })
+  budgetKind: StaffTimeProjectBudgetKind = 'none'
+
+  @Property({ name: 'budget_value', type: 'numeric', precision: 14, scale: 4, nullable: true })
+  budgetValue?: string | null
+
+  @Property({ name: 'budget_warn_at_percent', type: 'integer', default: 80 })
+  budgetWarnAtPercent: number = 80
+
+  @Property({ name: 'budget_alerted_at_percent', type: 'integer', nullable: true })
+  budgetAlertedAtPercent?: number | null
+
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
@@ -560,3 +627,428 @@ export class StaffTimeProjectMember {
   @Property({ name: 'deleted_at', type: Date, nullable: true })
   deletedAt?: Date | null
 }
+
+// --- Time tracking consulting suite entities ---
+
+@Entity({ tableName: 'staff_time_task_statuses' })
+@Index({ name: 'staff_time_task_statuses_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'staff_time_task_statuses_project_idx', properties: ['organizationId', 'timeProjectId', 'position'] })
+@Index({ name: 'staff_time_task_statuses_slug_unique_idx', properties: ['organizationId', 'tenantId', 'timeProjectId', 'slug'], options: { unique: true, where: 'deleted_at IS NULL' } })
+export class StaffTimeTaskStatus {
+  [OptionalProps]?: 'position' | 'isDefault' | 'isDone' | '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: 'time_project_id', type: 'uuid' })
+  timeProjectId!: string
+
+  @Property({ type: 'text' })
+  name!: string
+
+  @Property({ type: 'text' })
+  slug!: string
+
+  @Property({ type: 'text', nullable: true })
+  color?: string | null
+
+  @Property({ type: 'integer', default: 0 })
+  position: number = 0
+
+  @Property({ name: 'is_default', type: 'boolean', default: false })
+  isDefault: boolean = false
+
+  @Property({ name: 'is_done', type: 'boolean', default: false })
+  isDone: boolean = false
+
+  @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_time_tasks' })
+@Index({ name: 'staff_time_tasks_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'staff_time_tasks_board_idx', properties: ['organizationId', 'timeProjectId', 'taskStatusId', 'position'] })
+@Index({ name: 'staff_time_tasks_parent_idx', properties: ['organizationId', 'parentTaskId'] })
+@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' } })
+export class StaffTimeTask {
+  [OptionalProps]?: 'sequenceNumber' | 'position' | '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: 'time_project_id', type: 'uuid' })
+  timeProjectId!: string
+
+  @Property({ name: 'parent_task_id', type: 'uuid', nullable: true })
+  parentTaskId?: string | null
+
+  @Property({ name: 'task_status_id', type: 'uuid' })
+  taskStatusId!: string
+
+  @Property({ name: 'sequence_number', type: 'integer', default: 0 })
+  sequenceNumber: number = 0
+
+  @Property({ type: 'text' })
+  reference!: string
+
+  @Property({ type: 'text' })
+  title!: string
+
+  @Property({ type: 'text', nullable: true })
+  description?: string | null
+
+  @Property({ name: 'assignee_staff_member_id', type: 'uuid', nullable: true })
+  assigneeStaffMemberId?: string | null
+
+  @Property({ type: 'integer', default: 0 })
+  position: number = 0
+
+  @Property({ name: 'created_by_user_id', type: 'uuid', nullable: true })
+  createdByUserId?: string | null
+
+  @Property({ name: 'closed_at', type: Date, nullable: true })
+  closedAt?: Date | 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_time_task_comments' })
+@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'
+
+  @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({ type: 'text' })
+  body!: string
+
+  @Property({ name: 'author_user_id', type: 'uuid', nullable: true })
+  authorUserId?: 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_time_tags' })
+@Index({ name: 'staff_time_tags_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'staff_time_tags_slug_unique_idx', properties: ['organizationId', 'tenantId', 'slug'], options: { unique: true, where: 'deleted_at IS NULL' } })
+export class StaffTimeTag {
+  [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({ type: 'text' })
+  slug!: string
+
+  @Property({ type: 'text' })
+  label!: string
+
+  @Property({ type: 'text', nullable: true })
+  color?: 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_time_task_tags' })
+@Index({ name: 'staff_time_task_tags_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'staff_time_task_tags_task_idx', properties: ['organizationId', 'taskId'] })
+@Index({ name: 'staff_time_task_tags_unique_idx', properties: ['tagId', 'taskId'], options: { unique: true } })
+export class StaffTimeTaskTag {
+  [OptionalProps]?: 'createdAt'
+
+  @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: 'tag_id', type: 'uuid' })
+  tagId!: string
+
+  @Property({ name: 'task_id', type: 'uuid' })
+  taskId!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+}
+
+@Entity({ tableName: 'staff_time_entry_tags' })
+@Index({ name: 'staff_time_entry_tags_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'staff_time_entry_tags_entry_idx', properties: ['organizationId', 'timeEntryId'] })
+@Index({ name: 'staff_time_entry_tags_unique_idx', properties: ['tagId', 'timeEntryId'], options: { unique: true } })
+export class StaffTimeEntryTag {
+  [OptionalProps]?: 'createdAt'
+
+  @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: 'tag_id', type: 'uuid' })
+  tagId!: string
+
+  @Property({ name: 'time_entry_id', type: 'uuid' })
+  timeEntryId!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+}
+
+@Entity({ tableName: 'staff_time_reports' })
+@Index({ name: 'staff_time_reports_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'staff_time_reports_customer_idx', properties: ['organizationId', 'customerId'] })
+@Index({ name: 'staff_time_reports_status_idx', properties: ['organizationId', 'status', 'periodFrom'] })
+@Index({ name: 'staff_time_reports_reference_unique_idx', properties: ['organizationId', 'tenantId', 'reference'], options: { unique: true, where: 'deleted_at IS NULL' } })
+export class StaffTimeReport {
+  [OptionalProps]?: 'periodKind' | 'grouping' | 'nonbillableMode' | 'includeAlreadyReported' | 'showRates' | 'roundingUnitMinutes' | 'roundingDirection' | 'status' | '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: 'customer_id', type: 'uuid' })
+  customerId!: string
+
+  @Property({ name: 'customer_snapshot', type: 'jsonb', nullable: true })
+  customerSnapshot?: Record<string, unknown> | null
+
+  @Property({ type: 'text' })
+  reference!: string
+
+  @Property({ type: 'text' })
+  title!: string
+
+  @Enum({ items: ['week', 'month', 'year', 'custom'], type: 'text', name: 'period_kind', default: 'month' })
+  periodKind: StaffTimeReportPeriodKind = 'month'
+
+  @Property({ name: 'period_from', type: 'date' })
+  periodFrom!: Date
+
+  @Property({ name: 'period_to', type: 'date' })
+  periodTo!: Date
+
+  @Property({ name: 'currency_code', type: 'text' })
+  currencyCode!: string
+
+  @Property({ name: 'grouping', type: 'text', default: 'project_task' })
+  grouping: StaffTimeReportGrouping = 'project_task'
+
+  @Enum({ items: ['separate', 'exclude'], type: 'text', name: 'nonbillable_mode', default: 'separate' })
+  nonbillableMode: StaffTimeReportNonBillableMode = 'separate'
+
+  @Property({ name: 'include_already_reported', type: 'boolean', default: false })
+  includeAlreadyReported: boolean = false
+
+  @Property({ name: 'show_rates', type: 'boolean', default: true })
+  showRates: boolean = true
+
+  @Property({ name: 'rounding_unit_minutes', type: 'integer', default: 0 })
+  roundingUnitMinutes: number = 0
+
+  @Property({ name: 'rounding_direction', type: 'text', default: 'up' })
+  roundingDirection: string = 'up'
+
+  @Enum({ items: ['draft', 'closed'], type: 'text', name: 'status', default: 'draft' })
+  status: StaffTimeReportStatus = 'draft'
+
+  @Property({ name: 'total_billable_minutes', type: 'integer', nullable: true })
+  totalBillableMinutes?: number | null
+
+  @Property({ name: 'total_nonbillable_minutes', type: 'integer', nullable: true })
+  totalNonbillableMinutes?: number | null
+
+  @Property({ name: 'total_amount', type: 'numeric', precision: 14, scale: 2, nullable: true })
+  totalAmount?: string | null
+
+  @Property({ name: 'closed_at', type: Date, nullable: true })
+  closedAt?: Date | null
+
+  @Property({ name: 'closed_by_user_id', type: 'uuid', nullable: true })
+  closedByUserId?: string | null
+
+  @Property({ name: 'created_by_user_id', type: 'uuid', nullable: true })
+  createdByUserId?: 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_time_report_projects' })
+@Index({ name: 'staff_time_report_projects_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'staff_time_report_projects_project_idx', properties: ['organizationId', 'timeProjectId'] })
+@Index({ name: 'staff_time_report_projects_unique_idx', properties: ['reportId', 'timeProjectId'], options: { unique: true } })
+export class StaffTimeReportProject {
+  [OptionalProps]?: 'createdAt'
+
+  @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: 'report_id', type: 'uuid' })
+  reportId!: string
+
+  @Property({ name: 'time_project_id', type: 'uuid' })
+  timeProjectId!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+}
+
+@Entity({ tableName: 'staff_time_report_entries' })
+@Index({ name: 'staff_time_report_entries_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'staff_time_report_entries_entry_idx', properties: ['organizationId', 'timeEntryId'] })
+@Index({ name: 'staff_time_report_entries_unique_idx', properties: ['reportId', 'timeEntryId'], options: { unique: true } })
+export class StaffTimeReportEntry {
+  [OptionalProps]?: 'frozenRawMinutes' | 'frozenRoundedMinutes' | 'frozenIsBillable' | 'createdAt'
+
+  @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: 'report_id', type: 'uuid' })
+  reportId!: string
+
+  @Property({ name: 'time_entry_id', type: 'uuid' })
+  timeEntryId!: string
+
+  @Property({ name: 'frozen_raw_minutes', type: 'integer', default: 0 })
+  frozenRawMinutes: number = 0
+
+  @Property({ name: 'frozen_rounded_minutes', type: 'integer', default: 0 })
+  frozenRoundedMinutes: number = 0
+
+  @Property({ name: 'frozen_rate_amount', type: 'numeric', precision: 14, scale: 4, nullable: true })
+  frozenRateAmount?: string | null
+
+  @Property({ name: 'frozen_currency_code', type: 'text' })
+  frozenCurrencyCode!: string
+
+  @Property({ name: 'frozen_amount', type: 'numeric', precision: 14, scale: 2, nullable: true })
+  frozenAmount?: string | null
+
+  @Property({ name: 'frozen_is_billable', type: 'boolean', default: true })
+  frozenIsBillable: boolean = true
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+}
+
+@Entity({ tableName: 'staff_time_report_events' })
+@Index({ name: 'staff_time_report_events_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+@Index({ name: 'staff_time_report_events_report_idx', properties: ['organizationId', 'reportId', 'createdAt'] })
+export class StaffTimeReportEvent {
+  [OptionalProps]?: 'createdAt'
+
+  @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: 'report_id', type: 'uuid' })
+  reportId!: string
+
+  @Enum({ items: ['closed', 'unlocked', 'exported'], type: 'text', name: 'event_type' })
+  eventType!: StaffTimeReportEventType
+
+  @Property({ type: 'text', nullable: true })
+  reason?: string | null
+
+  @Property({ name: 'actor_user_id', type: 'uuid', nullable: true })
+  actorUserId?: string | null
+
+  @Property({ type: 'jsonb', nullable: true })
+  metadata?: Record<string, unknown> | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+}

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

@@ -0,0 +1,68 @@
+import type { EntityExtension } from '@open-mercato/shared/modules/entities'
+
+/**
+ * EP-44 — cross-module entity links declared by the staff module.
+ *
+ * Per root `AGENTS.md`, modules do NOT form direct ORM relationships across boundaries.
+ * `staff_time_entries.customer_id` / `.deal_id` / `.order_id` and
+ * `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 is slated for extraction into a standalone package, and a link that pulled in
+ * `@open-mercato/core/modules/customers` would break the extraction.
+ *
+ * `base` is the OTHER module's entity and `extension` is the staff entity that carries
+ * the foreign key, matching every other `data/extensions.ts` in the repo — the query
+ * engine only ever looks a link up by `base` (`shared/lib/query/engine.ts`,
+ * `opts.includeExtensions`), joining the extension table onto the base entity's query.
+ *
+ * NOTE — declaration-only extension point, exactly as in
+ * `apps/mercato/src/modules/example/data/extensions.ts`. Nothing in the platform passes
+ * `includeExtensions` to a query today, the basic engine's extension join adds no
+ * projection and exposes no filterable or sortable alias, and the hybrid engine DI
+ * registers ignores the flag outside its basic-engine fallback. The declaration is still
+ * the live contract: it is what `yarn generate` emits into the module registry as
+ * `entityExtensions`, and it is what a reverse-navigation or join feature will read.
+ *
+ * `table` is declared rather than derived. The engine would reach the same names with
+ * its regular pluralizer (`staff_time_entry` → `staff_time_entries`), but the explicit
+ * form is pinned against the physical schema by `__tests__/entityExtensions.test.ts`.
+ */
+const entityExtensions: EntityExtension[] = [
+  {
+    base: 'customers:customer_entity',
+    extension: 'staff:staff_time_entry',
+    join: { baseKey: 'id', extensionKey: 'customer_id' },
+    table: 'staff_time_entries',
+    cardinality: 'one-to-many',
+    description: 'Time logged directly against a customer record',
+  },
+  {
+    base: 'customers:customer_deal',
+    extension: 'staff:staff_time_entry',
+    join: { baseKey: 'id', extensionKey: 'deal_id' },
+    table: 'staff_time_entries',
+    cardinality: 'one-to-many',
+    description: 'Time logged against a CRM deal',
+  },
+  {
+    base: 'sales:sales_order',
+    extension: 'staff:staff_time_entry',
+    join: { baseKey: 'id', extensionKey: 'order_id' },
+    table: 'staff_time_entries',
+    cardinality: 'one-to-many',
+    description: 'Time logged against a sales order',
+  },
+  {
+    base: 'customers:customer_entity',
+    extension: 'staff:staff_time_project',
+    join: { baseKey: 'id', extensionKey: 'customer_id' },
+    table: 'staff_time_projects',
+    cardinality: 'one-to-many',
+    description: 'Time projects owned by a customer record (D-9: the customers supertype)',
+  },
+]
+
+export const extensions = entityExtensions
+export default entityExtensions