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

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

@@ -0,0 +1,94 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260813073131_staff extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "staff_time_entry_tags" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "tag_id" uuid not null, "time_entry_id" uuid not null, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create unique index "staff_time_entry_tags_unique_idx" on "staff_time_entry_tags" ("tag_id", "time_entry_id");`);
+    this.addSql(`create index "staff_time_entry_tags_entry_idx" on "staff_time_entry_tags" ("organization_id", "time_entry_id");`);
+    this.addSql(`create index "staff_time_entry_tags_tenant_org_idx" on "staff_time_entry_tags" ("tenant_id", "organization_id");`);
+
+    this.addSql(`create table "staff_time_reports" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "customer_id" uuid not null, "customer_snapshot" jsonb null, "reference" text not null, "title" text not null, "period_kind" text not null default 'month', "period_from" date not null, "period_to" date not null, "currency_code" text not null, "grouping" text not null default 'project_task', "nonbillable_mode" text not null default 'separate', "include_already_reported" boolean not null default false, "show_rates" boolean not null default true, "rounding_unit_minutes" int not null default 0, "rounding_direction" text not null default 'up', "status" text not null default 'draft', "total_billable_minutes" int null, "total_nonbillable_minutes" int null, "total_amount" numeric(14,2) null, "closed_at" timestamptz null, "closed_by_user_id" uuid null, "created_by_user_id" uuid null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create unique index "staff_time_reports_reference_unique_idx" on "staff_time_reports" ("organization_id", "tenant_id", "reference") where "deleted_at" is null;`);
+    this.addSql(`create index "staff_time_reports_status_idx" on "staff_time_reports" ("organization_id", "status", "period_from");`);
+    this.addSql(`create index "staff_time_reports_customer_idx" on "staff_time_reports" ("organization_id", "customer_id");`);
+    this.addSql(`create index "staff_time_reports_tenant_org_idx" on "staff_time_reports" ("tenant_id", "organization_id");`);
+
+    this.addSql(`create table "staff_time_report_entries" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "report_id" uuid not null, "time_entry_id" uuid not null, "frozen_raw_minutes" int not null default 0, "frozen_rounded_minutes" int not null default 0, "frozen_rate_amount" numeric(14,4) null, "frozen_currency_code" text not null, "frozen_amount" numeric(14,2) null, "frozen_is_billable" boolean not null default true, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create unique index "staff_time_report_entries_unique_idx" on "staff_time_report_entries" ("report_id", "time_entry_id");`);
+    this.addSql(`create index "staff_time_report_entries_entry_idx" on "staff_time_report_entries" ("organization_id", "time_entry_id");`);
+    this.addSql(`create index "staff_time_report_entries_tenant_org_idx" on "staff_time_report_entries" ("tenant_id", "organization_id");`);
+
+    this.addSql(`create table "staff_time_report_events" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "report_id" uuid not null, "event_type" text not null, "reason" text null, "actor_user_id" uuid null, "metadata" jsonb null, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "staff_time_report_events_report_idx" on "staff_time_report_events" ("organization_id", "report_id", "created_at");`);
+    this.addSql(`create index "staff_time_report_events_tenant_org_idx" on "staff_time_report_events" ("tenant_id", "organization_id");`);
+
+    this.addSql(`create table "staff_time_report_projects" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "report_id" uuid not null, "time_project_id" uuid not null, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create unique index "staff_time_report_projects_unique_idx" on "staff_time_report_projects" ("report_id", "time_project_id");`);
+    this.addSql(`create index "staff_time_report_projects_project_idx" on "staff_time_report_projects" ("organization_id", "time_project_id");`);
+    this.addSql(`create index "staff_time_report_projects_tenant_org_idx" on "staff_time_report_projects" ("tenant_id", "organization_id");`);
+
+    this.addSql(`create table "staff_time_tags" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "slug" text not null, "label" text not null, "color" 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_time_tags_slug_unique_idx" on "staff_time_tags" ("organization_id", "tenant_id", "slug") where "deleted_at" is null;`);
+    this.addSql(`create index "staff_time_tags_tenant_org_idx" on "staff_time_tags" ("tenant_id", "organization_id");`);
+
+    this.addSql(`create table "staff_time_tasks" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "time_project_id" uuid not null, "parent_task_id" uuid null, "task_status_id" uuid not null, "sequence_number" int not null default 0, "reference" text not null, "title" text not null, "description" text null, "assignee_staff_member_id" uuid null, "position" int not null default 0, "created_by_user_id" uuid null, "closed_at" timestamptz null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create unique index "staff_time_tasks_reference_unique_idx" on "staff_time_tasks" ("organization_id", "tenant_id", "reference") where "deleted_at" is null;`);
+    this.addSql(`create unique index "staff_time_tasks_sequence_unique_idx" on "staff_time_tasks" ("organization_id", "tenant_id", "time_project_id", "sequence_number") where "deleted_at" is null;`);
+    this.addSql(`create index "staff_time_tasks_assignee_idx" on "staff_time_tasks" ("organization_id", "assignee_staff_member_id");`);
+    this.addSql(`create index "staff_time_tasks_parent_idx" on "staff_time_tasks" ("organization_id", "parent_task_id");`);
+    this.addSql(`create index "staff_time_tasks_board_idx" on "staff_time_tasks" ("organization_id", "time_project_id", "task_status_id", "position");`);
+    this.addSql(`create index "staff_time_tasks_tenant_org_idx" on "staff_time_tasks" ("tenant_id", "organization_id");`);
+
+    this.addSql(`create table "staff_time_task_comments" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "task_id" uuid not null, "body" text not null, "author_user_id" uuid null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create index "staff_time_task_comments_task_idx" on "staff_time_task_comments" ("organization_id", "task_id", "created_at");`);
+    this.addSql(`create index "staff_time_task_comments_tenant_org_idx" on "staff_time_task_comments" ("tenant_id", "organization_id");`);
+
+    this.addSql(`create table "staff_time_task_statuses" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "time_project_id" uuid not null, "name" text not null, "slug" text not null, "color" text null, "position" int not null default 0, "is_default" boolean not null default false, "is_done" boolean not null default false, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create unique index "staff_time_task_statuses_slug_unique_idx" on "staff_time_task_statuses" ("organization_id", "tenant_id", "time_project_id", "slug") where "deleted_at" is null;`);
+    this.addSql(`create index "staff_time_task_statuses_project_idx" on "staff_time_task_statuses" ("organization_id", "time_project_id", "position");`);
+    this.addSql(`create index "staff_time_task_statuses_tenant_org_idx" on "staff_time_task_statuses" ("tenant_id", "organization_id");`);
+
+    this.addSql(`create table "staff_time_task_tags" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid not null, "tag_id" uuid not null, "task_id" uuid not null, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create unique index "staff_time_task_tags_unique_idx" on "staff_time_task_tags" ("tag_id", "task_id");`);
+    this.addSql(`create index "staff_time_task_tags_task_idx" on "staff_time_task_tags" ("organization_id", "task_id");`);
+    this.addSql(`create index "staff_time_task_tags_tenant_org_idx" on "staff_time_task_tags" ("tenant_id", "organization_id");`);
+
+    this.addSql(`alter table "staff_time_reports" add constraint "staff_time_reports_period_kind_check" check ("period_kind" in ('week', 'month', 'year', 'custom'));`);
+    this.addSql(`alter table "staff_time_reports" add constraint "staff_time_reports_grouping_check" check ("grouping" in ('project_task', 'project_person', 'project_day'));`);
+    this.addSql(`alter table "staff_time_reports" add constraint "staff_time_reports_nonbillable_mode_check" check ("nonbillable_mode" in ('separate', 'exclude'));`);
+    this.addSql(`alter table "staff_time_reports" add constraint "staff_time_reports_status_check" check ("status" in ('draft', 'closed'));`);
+
+    this.addSql(`alter table "staff_time_report_events" add constraint "staff_time_report_events_event_type_check" check ("event_type" in ('closed', 'unlocked', 'exported'));`);
+
+    this.addSql(`alter table "staff_time_entries" add "task_id" uuid null, add "is_billable" boolean not null default true, add "rounded_minutes" int null, add "rate_override_amount" numeric(14,4) null, add "rate_currency_code" text null, add "locked_report_id" uuid null, add "locked_at" timestamptz null;`);
+    this.addSql(`create index "staff_time_entries_locked_report_idx" on "staff_time_entries" ("organization_id", "locked_report_id");`);
+    this.addSql(`create index "staff_time_entries_member_overlap_idx" on "staff_time_entries" ("organization_id", "staff_member_id", "date", "started_at");`);
+    this.addSql(`create index "staff_time_entries_task_idx" on "staff_time_entries" ("organization_id", "task_id");`);
+
+    this.addSql(`alter table "staff_time_projects" add "customer_snapshot" jsonb null, add "hourly_rate" numeric(14,4) null, add "currency_code" text null, add "billable_by_default" boolean not null default true, add "budget_kind" text not null default 'none', add "budget_value" numeric(14,4) null, add "budget_warn_at_percent" int not null default 80, add "budget_alerted_at_percent" int null;`);
+    this.addSql(`alter table "staff_time_projects" add constraint "staff_time_projects_budget_kind_check" check ("budget_kind" in ('none', 'hours', 'amount'));`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "staff_time_entry_tags" cascade;`);
+    this.addSql(`drop table if exists "staff_time_report_entries" cascade;`);
+    this.addSql(`drop table if exists "staff_time_report_events" cascade;`);
+    this.addSql(`drop table if exists "staff_time_report_projects" cascade;`);
+    this.addSql(`drop table if exists "staff_time_reports" cascade;`);
+    this.addSql(`drop table if exists "staff_time_task_tags" cascade;`);
+    this.addSql(`drop table if exists "staff_time_tags" cascade;`);
+    this.addSql(`drop table if exists "staff_time_task_comments" cascade;`);
+    this.addSql(`drop table if exists "staff_time_tasks" cascade;`);
+    this.addSql(`drop table if exists "staff_time_task_statuses" cascade;`);
+
+    this.addSql(`drop index "staff_time_entries_locked_report_idx";`);
+    this.addSql(`drop index "staff_time_entries_member_overlap_idx";`);
+    this.addSql(`drop index "staff_time_entries_task_idx";`);
+    this.addSql(`alter table "staff_time_entries" drop column "task_id", drop column "is_billable", drop column "rounded_minutes", drop column "rate_override_amount", drop column "rate_currency_code", drop column "locked_report_id", drop column "locked_at";`);
+
+    this.addSql(`alter table "staff_time_projects" drop constraint if exists "staff_time_projects_budget_kind_check";`);
+    this.addSql(`alter table "staff_time_projects" drop column "customer_snapshot", drop column "hourly_rate", drop column "currency_code", drop column "billable_by_default", drop column "budget_kind", drop column "budget_value", drop column "budget_warn_at_percent", drop column "budget_alerted_at_percent";`);
+  }
+
+}

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

@@ -0,0 +1,17 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260824143357_staff extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "staff_time_entries" drop constraint if exists "staff_time_entries_source_check";`);
+
+    this.addSql(`alter table "staff_time_reports" drop constraint if exists "staff_time_reports_grouping_check";`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "staff_time_entries" add constraint "staff_time_entries_source_check" check ("source" in ('manual', 'timer', 'kiosk', 'mobile'));`);
+
+    this.addSql(`alter table "staff_time_reports" add constraint "staff_time_reports_grouping_check" check ("grouping" in ('project_task', 'project_person', 'project_day'));`);
+  }
+
+}

package/src/modules/staff/notifications.client.ts

@@ -0,0 +1,16 @@
+'use client'
+
+import type { NotificationTypeDefinition } from '@open-mercato/shared/modules/notifications/types'
+import { notificationTypes } from './notifications'
+import { TimeProjectAccessRequestedRenderer } from './widgets/notifications/TimeProjectAccessRequestedRenderer'
+
+const rendererMap: Record<string, NotificationTypeDefinition['Renderer']> = {
+  'staff.timesheets.project_access.requested': TimeProjectAccessRequestedRenderer,
+}
+
+export const staffNotificationTypes: NotificationTypeDefinition[] = notificationTypes.map((type) => ({
+  ...type,
+  Renderer: rendererMap[type.type],
+}))
+
+export default staffNotificationTypes

package/src/modules/staff/notifications.handlers.ts

@@ -0,0 +1,88 @@
+import type { NotificationHandler } from '@open-mercato/shared/modules/notifications/handler'
+
+/**
+ * EP-48. Reactive browser handlers for the time-tracking notification types.
+ *
+ * A handler is the module's own reaction to one of its notifications arriving in
+ * the browser: it re-broadcasts on the DOM Event Bridge so an open screen can
+ * refetch, and toasts the ones a person needs to see even when the bell is
+ * collapsed. Each `id` is the override key — `notifications.handlers.<id>` — so
+ * an app can disable or replace one without patching this file.
+ *
+ * `features` is checked with the wildcard-aware policy before `handle` runs, so
+ * a handler never fires for a caller who could not open the screen it points at.
+ */
+
+export const TIME_REPORT_APPROVED_EVENT = 'om:staff:time-report-approved'
+export const TIME_REPORT_READY_FOR_APPROVAL_EVENT = 'om:staff:time-report-ready-for-approval'
+export const TIMER_RUNNING_LONG_EVENT = 'om:staff:timer-running-long'
+export const TIMESHEET_PERIOD_INCOMPLETE_EVENT = 'om:staff:timesheet-period-incomplete'
+
+export const notificationHandlers: NotificationHandler[] = [
+  {
+    id: 'staff.time-report-approved-event',
+    notificationType: 'staff.timesheets.time_report.approved',
+    features: ['staff.timesheets.reports.view'],
+    priority: 100,
+    handle(notification, context) {
+      context.emitEvent(TIME_REPORT_APPROVED_EVENT, {
+        notificationId: notification.id,
+        reportId: notification.sourceEntityId ?? null,
+        reference: notification.bodyVariables?.reference ?? null,
+      })
+      context.refreshNotifications()
+    },
+  },
+  {
+    id: 'staff.time-report-ready-for-approval-event',
+    notificationType: 'staff.timesheets.time_report.ready_for_approval',
+    features: ['staff.timesheets.reports.view'],
+    priority: 100,
+    handle(notification, context) {
+      context.emitEvent(TIME_REPORT_READY_FOR_APPROVAL_EVENT, {
+        notificationId: notification.id,
+        reportId: notification.sourceEntityId ?? null,
+        reference: notification.bodyVariables?.reference ?? null,
+      })
+    },
+  },
+  {
+    /**
+     * A running timer keeps billing until somebody stops it, so this one toasts
+     * as well as broadcasting — the bell alone is too quiet for a notification
+     * whose whole point is that the person has forgotten something.
+     */
+    id: 'staff.timer-running-long-toast',
+    notificationType: 'staff.timesheets.time_entry.timer_running_long',
+    features: ['staff.timesheets.view'],
+    priority: 110,
+    debounceMs: 60_000,
+    handle(notification, context) {
+      context.toast({
+        title: notification.title,
+        body: notification.body ?? undefined,
+        severity: 'warning',
+      })
+      context.emitEvent(TIMER_RUNNING_LONG_EVENT, {
+        notificationId: notification.id,
+        timeEntryId: notification.sourceEntityId ?? null,
+      })
+    },
+  },
+  {
+    id: 'staff.timesheet-period-incomplete-event',
+    notificationType: 'staff.timesheets.timesheet.period_incomplete',
+    features: ['staff.timesheets.view'],
+    priority: 90,
+    handle(notification, context) {
+      context.emitEvent(TIMESHEET_PERIOD_INCOMPLETE_EVENT, {
+        notificationId: notification.id,
+        staffMemberId: notification.sourceEntityId ?? null,
+        periodFrom: notification.bodyVariables?.periodFrom ?? null,
+        periodTo: notification.bodyVariables?.periodTo ?? null,
+      })
+    },
+  },
+]
+
+export default notificationHandlers

package/src/modules/staff/notifications.ts

@@ -72,6 +72,169 @@ export const notificationTypes: NotificationTypeDefinition[] = [
     linkHref: '/backend/staff/leave-requests/{sourceEntityId}',
     expiresAfterHours: 168, // 7 days
   },
+  {
+    // Spec D-6: the "Request access" button on screens 2 and 17 raises a real
+    // notification for every `staff.timesheets.projects.manage` holder. The
+    // subscriber overrides `linkHref` with the requester-specific deep link so
+    // the project team drawer opens with the requester pre-selected.
+    type: 'staff.timesheets.project_access.requested',
+    channels: ['in_app', 'email'],
+    module: 'staff',
+    titleKey: 'staff.notifications.timeProjectAccess.requested.title',
+    bodyKey: 'staff.notifications.timeProjectAccess.requested.body',
+    icon: 'user-plus',
+    severity: 'info',
+    actions: [
+      {
+        id: 'open-team',
+        labelKey: 'staff.notifications.timeProjectAccess.actions.openTeam',
+        variant: 'default',
+        icon: 'users',
+        href: '/backend/staff/time-tracking/projects/{sourceEntityId}?panel=team',
+      },
+    ],
+    primaryActionId: 'open-team',
+    linkHref: '/backend/staff/time-tracking/projects',
+    expiresAfterHours: 168, // 7 days
+  },
+  {
+    // Screen 4 budget card: "Ostrzezenie przy 80% i 100% wykorzystania". One type
+    // covers both thresholds — the subscriber raises the severity to `error` for the
+    // 100% crossing and carries the numbers in `bodyVariables`, so the two alerts
+    // read differently without splitting the notification id.
+    type: 'staff.timesheets.time_project.budget_threshold_reached',
+    channels: ['in_app', 'email'],
+    module: 'staff',
+    titleKey: 'staff.notifications.timeProjectBudget.thresholdReached.title',
+    bodyKey: 'staff.notifications.timeProjectBudget.thresholdReached.body',
+    icon: 'gauge',
+    severity: 'warning',
+    actions: [
+      {
+        id: 'open-project',
+        labelKey: 'staff.notifications.timeProjectBudget.actions.openProject',
+        variant: 'default',
+        icon: 'external-link',
+        href: '/backend/staff/time-tracking/projects/{sourceEntityId}',
+      },
+    ],
+    primaryActionId: 'open-project',
+    linkHref: '/backend/staff/time-tracking/projects/{sourceEntityId}',
+    expiresAfterHours: 168, // 7 days
+  },
+  {
+    /**
+     * EP-48. Raised by `subscribers/time-report-approved-notification.ts` when a
+     * report is closed — closing IS the approval in this module: it freezes every
+     * per-entry value and locks the entries, and `staff.timesheets.lock` is the
+     * feature that gates it. The recipient is the person who drafted the report,
+     * who otherwise learns about it only by reopening the screen.
+     */
+    type: 'staff.timesheets.time_report.approved',
+    channels: ['in_app', 'email'],
+    module: 'staff',
+    titleKey: 'staff.notifications.timeReport.approved.title',
+    bodyKey: 'staff.notifications.timeReport.approved.body',
+    icon: 'file-check',
+    severity: 'success',
+    actions: [
+      {
+        id: 'open-report',
+        labelKey: 'staff.notifications.timeReport.actions.openReport',
+        variant: 'default',
+        icon: 'external-link',
+        href: '/backend/staff/time-tracking/reports/{sourceEntityId}',
+      },
+    ],
+    primaryActionId: 'open-report',
+    linkHref: '/backend/staff/time-tracking/reports/{sourceEntityId}',
+    expiresAfterHours: 168, // 7 days
+  },
+  {
+    /**
+     * EP-48, contributable-only by design. The module has exactly one report
+     * transition — draft → closed — so there is no "submitted, awaiting a second
+     * pair of eyes" state for core to announce. This id exists so the multi-step
+     * approval a `registerReportApprovalPolicy` contribution (EP-41) implements
+     * has a published notification to raise instead of inventing its own, and so
+     * the renderer and delivery preferences are already in place when it does.
+     */
+    type: 'staff.timesheets.time_report.ready_for_approval',
+    channels: ['in_app', 'email'],
+    module: 'staff',
+    titleKey: 'staff.notifications.timeReport.readyForApproval.title',
+    bodyKey: 'staff.notifications.timeReport.readyForApproval.body',
+    icon: 'file-clock',
+    severity: 'info',
+    actions: [
+      {
+        id: 'review-report',
+        labelKey: 'staff.notifications.timeReport.actions.reviewReport',
+        variant: 'default',
+        icon: 'external-link',
+        href: '/backend/staff/time-tracking/reports/{sourceEntityId}',
+      },
+    ],
+    primaryActionId: 'review-report',
+    linkHref: '/backend/staff/time-tracking/reports/{sourceEntityId}',
+    expiresAfterHours: 168, // 7 days
+  },
+  {
+    /**
+     * EP-48, contributable-only by design. "This timer has been running for six
+     * hours" needs something that wakes up on a schedule and looks at open
+     * timers; the module ships no periodic job and inventing one to justify an id
+     * would be the tail wagging the dog. The id is the contract for a module that
+     * does ship one.
+     */
+    type: 'staff.timesheets.time_entry.timer_running_long',
+    channels: ['in_app'],
+    module: 'staff',
+    titleKey: 'staff.notifications.timeEntryTimer.runningLong.title',
+    bodyKey: 'staff.notifications.timeEntryTimer.runningLong.body',
+    icon: 'timer',
+    severity: 'warning',
+    actions: [
+      {
+        id: 'open-timesheet',
+        labelKey: 'staff.notifications.timesheet.actions.openTimesheet',
+        variant: 'default',
+        icon: 'external-link',
+        href: '/backend/staff/time-tracking/timesheet',
+      },
+    ],
+    primaryActionId: 'open-timesheet',
+    linkHref: '/backend/staff/time-tracking/timesheet',
+    expiresAfterHours: 24,
+  },
+  {
+    /**
+     * EP-48, contributable-only by design. Whether a period is "incomplete" is
+     * the capacity provider's question (EP-40), and the built-in provider spreads
+     * one flat daily number over the caller's working days on demand — it has no
+     * schedule and no opinion about when to complain. A contributed provider that
+     * knows contract hours and leave is the thing that can raise this honestly.
+     */
+    type: 'staff.timesheets.timesheet.period_incomplete',
+    channels: ['in_app', 'email'],
+    module: 'staff',
+    titleKey: 'staff.notifications.timesheet.periodIncomplete.title',
+    bodyKey: 'staff.notifications.timesheet.periodIncomplete.body',
+    icon: 'calendar-clock',
+    severity: 'warning',
+    actions: [
+      {
+        id: 'open-timesheet',
+        labelKey: 'staff.notifications.timesheet.actions.openTimesheet',
+        variant: 'default',
+        icon: 'external-link',
+        href: '/backend/staff/time-tracking/timesheet',
+      },
+    ],
+    primaryActionId: 'open-timesheet',
+    linkHref: '/backend/staff/time-tracking/timesheet',
+    expiresAfterHours: 168, // 7 days
+  },
 ]
 
 export default notificationTypes

package/src/modules/staff/search.ts

@@ -118,6 +118,74 @@ function buildIndexSource(
   }
 }
 
+/**
+ * EP-46. The four time-tracking entities below join `staff:staff_time_project`
+ * in the index, and every one of them carries a gate that is deliberately
+ * stricter than the feature its REST route declares.
+ *
+ * The reason is a property of the search layer, not of this module: an entity's
+ * `aclFeatures` is the ONLY authorization the search pipeline applies. It is
+ * enforced twice per query — `resolveReadableEntityTypes` narrows the entity
+ * list before the query and `filterSearchResultsByEntityAccess` filters the
+ * results after it — but both decide **per entity type**, never per record.
+ * `SearchEntityConfig` has no row-level hook and `SearchOptions` has no record-id
+ * allowlist, so a search gate cannot reproduce the per-project membership
+ * intersection that `resolveProjectAccess` applies on every time-tracking route.
+ *
+ * So each gate below names the feature set whose holder already sees **every**
+ * record of that entity through the API. `staff.timesheets.projects.manage` is
+ * that feature for entries, tasks and reports: it is what makes
+ * `resolveProjectAccess` answer `canManageAll: true`, which is the only state in
+ * which those routes stop intersecting with the caller's project membership.
+ * A project member without it gets no hits at all rather than hits for projects
+ * they cannot open — the failure mode that costs a support ticket, not the one
+ * that discloses a client's work.
+ */
+const UNRESTRICTED_PROJECT_ACCESS_FEATURE = 'staff.timesheets.projects.manage'
+
+function buildTimeTaskPresenter(t: TranslateFn, record: Record<string, unknown>): SearchResultPresenter {
+  const title =
+    pickString(record.title, record.reference) ?? (record.id as string | undefined) ?? t('staff.search.badge.timeTask', 'Task')
+  return {
+    title: String(title),
+    subtitle: formatSubtitle(record.reference, snippet(record.description, 80)),
+    icon: 'list-checks',
+    badge: t('staff.search.badge.timeTask', 'Task'),
+  }
+}
+
+function buildTimeReportPresenter(t: TranslateFn, record: Record<string, unknown>): SearchResultPresenter {
+  const title =
+    pickString(record.title, record.reference) ?? (record.id as string | undefined) ?? t('staff.search.badge.timeReport', 'Report')
+  return {
+    title: String(title),
+    subtitle: formatSubtitle(record.reference, record.period_from ?? record.periodFrom, record.period_to ?? record.periodTo),
+    icon: 'file-text',
+    badge: t('staff.search.badge.timeReport', 'Report'),
+  }
+}
+
+function buildTimeTagPresenter(t: TranslateFn, record: Record<string, unknown>): SearchResultPresenter {
+  const title =
+    pickString(record.label, record.slug) ?? (record.id as string | undefined) ?? t('staff.search.badge.timeTag', 'Tag')
+  return {
+    title: String(title),
+    subtitle: formatSubtitle(record.slug),
+    icon: 'tag',
+    badge: t('staff.search.badge.timeTag', 'Tag'),
+  }
+}
+
+function buildTimeEntryPresenter(t: TranslateFn, record: Record<string, unknown>): SearchResultPresenter {
+  const title = snippet(record.notes, 80) ?? t('staff.search.badge.timeEntry', 'Time entry')
+  return {
+    title,
+    subtitle: formatSubtitle(record.date, record.duration_minutes ?? record.durationMinutes),
+    icon: 'timer',
+    badge: t('staff.search.badge.timeEntry', 'Time entry'),
+  }
+}
+
 export const searchConfig: SearchModuleConfig = {
   entities: [
     {
@@ -222,11 +290,133 @@ export const searchConfig: SearchModuleConfig = {
           badge: t('staff.search.badge.timeProject', 'Project'),
         }
       },
-      resolveUrl: async (ctx) => `/backend/staff/timesheets/projects/${encodeURIComponent(String(ctx.record.id))}`,
+      resolveUrl: async (ctx) => `/backend/staff/time-tracking/projects/${encodeURIComponent(String(ctx.record.id))}`,
       fieldPolicy: {
         searchable: ['name', 'code', 'description', 'project_type', 'cost_center'],
       },
     },
+    {
+      entityId: 'staff:staff_time_task',
+      aclFeatures: ['staff.timesheets.tasks.view', UNRESTRICTED_PROJECT_ACCESS_FEATURE],
+      enabled: true,
+      priority: 7,
+      buildSource: async (ctx) => {
+        const { t } = await resolveTranslations()
+        const record = ctx.record
+        const lines: string[] = []
+        appendLine(lines, 'Reference', record.reference)
+        appendLine(lines, 'Title', record.title)
+        appendLine(lines, 'Description', record.description)
+        return buildIndexSource(ctx, buildTimeTaskPresenter(t, record), lines)
+      },
+      formatResult: async (ctx) => {
+        const { t } = await resolveTranslations()
+        return buildTimeTaskPresenter(t, ctx.record)
+      },
+      resolveUrl: async (ctx) => {
+        const projectId = pickString(ctx.record.time_project_id, ctx.record.timeProjectId)
+        if (!projectId) return null
+        return `/backend/staff/time-tracking/board?projectId=${encodeURIComponent(projectId)}&task=${encodeURIComponent(String(ctx.record.id))}`
+      },
+      fieldPolicy: {
+        searchable: ['title', 'description', 'reference'],
+      },
+    },
+    {
+      entityId: 'staff:staff_time_report',
+      aclFeatures: ['staff.timesheets.reports.view', UNRESTRICTED_PROJECT_ACCESS_FEATURE],
+      enabled: true,
+      priority: 7,
+      buildSource: async (ctx) => {
+        const { t } = await resolveTranslations()
+        const record = ctx.record
+        const lines: string[] = []
+        appendLine(lines, 'Reference', record.reference)
+        appendLine(lines, 'Title', record.title)
+        appendLine(lines, 'Status', record.status)
+        return buildIndexSource(ctx, buildTimeReportPresenter(t, record), lines)
+      },
+      formatResult: async (ctx) => {
+        const { t } = await resolveTranslations()
+        return buildTimeReportPresenter(t, ctx.record)
+      },
+      resolveUrl: async (ctx) => `/backend/staff/time-tracking/reports/${encodeURIComponent(String(ctx.record.id))}`,
+      /**
+       * `total_amount` and the denormalised `customer_snapshot` are excluded, not
+       * merely left out of `searchable`: money in a time-tracking response is
+       * gated on `staff.timesheets.rates.view`, and the search pipeline has no way
+       * to apply a second feature to a subset of an indexed record's fields.
+       */
+      fieldPolicy: {
+        searchable: ['reference', 'title'],
+        excluded: ['total_amount', 'customer_snapshot'],
+      },
+    },
+    {
+      entityId: 'staff:staff_time_tag',
+      aclFeatures: ['staff.timesheets.view'],
+      enabled: true,
+      priority: 5,
+      buildSource: async (ctx) => {
+        const { t } = await resolveTranslations()
+        const record = ctx.record
+        const lines: string[] = []
+        appendLine(lines, 'Label', record.label)
+        appendLine(lines, 'Slug', record.slug)
+        return buildIndexSource(ctx, buildTimeTagPresenter(t, record), lines)
+      },
+      formatResult: async (ctx) => {
+        const { t } = await resolveTranslations()
+        return buildTimeTagPresenter(t, ctx.record)
+      },
+      /**
+       * A tag has no detail screen and the entries list deep-links only `taskId`
+       * and `ids`, so there is no honest destination to send the caller to. The
+       * presenter still answers the question a tag search asks — "does this label
+       * exist, and what is it spelled" — and `url` is optional in the result
+       * contract, so an unlinked hit renders rather than pointing somewhere wrong.
+       */
+      resolveUrl: async () => null,
+      fieldPolicy: {
+        searchable: ['label', 'slug'],
+      },
+    },
+    {
+      /**
+       * Entry notes are the most sensitive text time tracking holds — they are
+       * where a consultant writes what they did for a named client. The gate is
+       * therefore the strictest one the module has for entries: `staff.timesheets.view`
+       * AND `staff.timesheets.projects.manage`, the pair that makes
+       * `resolveProjectAccess` return `canManageAll`, which is the only state in
+       * which `/api/staff/timesheets/time-entries` stops narrowing to the caller's
+       * own entries plus their project memberships. A consultant with
+       * `staff.timesheets.manage_own` gets no entry hits at all — including their
+       * own — because the gate cannot express "own" and half a gate is worse than
+       * none.
+       */
+      entityId: 'staff:staff_time_entry',
+      aclFeatures: ['staff.timesheets.view', UNRESTRICTED_PROJECT_ACCESS_FEATURE],
+      enabled: true,
+      priority: 4,
+      buildSource: async (ctx) => {
+        const { t } = await resolveTranslations()
+        const record = ctx.record
+        const lines: string[] = []
+        appendLine(lines, 'Notes', record.notes)
+        appendLine(lines, 'Date', record.date)
+        return buildIndexSource(ctx, buildTimeEntryPresenter(t, record), lines)
+      },
+      formatResult: async (ctx) => {
+        const { t } = await resolveTranslations()
+        return buildTimeEntryPresenter(t, ctx.record)
+      },
+      resolveUrl: async (ctx) =>
+        `/backend/staff/time-tracking/entries?ids=${encodeURIComponent(String(ctx.record.id))}`,
+      fieldPolicy: {
+        searchable: ['notes'],
+        excluded: ['rate_override_amount', 'rate_currency_code'],
+      },
+    },
   ],
 }
 

package/src/modules/staff/setup.ts

@@ -1,6 +1,7 @@
 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'
 
 const TIMESHEETS_DASHBOARD_WIDGET_IDS = [
   'staff.timesheets.timeReporting',
@@ -22,6 +23,9 @@ export const setup: ModuleSetupConfig = {
   seedExamples: async (ctx) => {
     const scope = { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
     await seedStaffTeamExamples(ctx.em, scope)
+    // Runs after the team examples because every project it staffs, every task it
+    // assigns and every hour it logs points at a staff member those seeds create.
+    await seedStaffTimeTrackingExamples(ctx.em, scope)
   },
 
   defaultRoleFeatures: {
@@ -35,8 +39,26 @@ export const setup: ModuleSetupConfig = {
       'staff.timesheets.view',
       'staff.timesheets.manage_own',
       'staff.timesheets.projects.view',
+      'staff.timesheets.tasks.view',
+      'staff.timesheets.tasks.manage',
+      'staff.timesheets.rates.view',
     ],
   },
+
+  /**
+   * EP-50. `portal.time_reports.view` is a **customer** feature, granted through
+   * `CustomerRoleAcl`, and it is deliberately absent from `acl.ts` — that file is
+   * the staff feature catalog and the two namespaces are graded by different RBAC
+   * services.
+   *
+   * `viewer` gets it as well as `buyer`: reading the hours already delivered is a
+   * read, and a client who may see their invoices may see what they paid for.
+   * `portal_admin` holds `portal.*` and needs no entry.
+   */
+  defaultCustomerRoleFeatures: {
+    buyer: ['portal.time_reports.view'],
+    viewer: ['portal.time_reports.view'],
+  },
 }
 
 export default setup