@open-mercato/core 0.6.8-develop.6882.1.cd042ac354 → 0.6.8-develop.6889.1.af4501ca97

package/src/modules/dashboards/lib/aggregations.ts

@@ -173,6 +173,21 @@ function normalizeSetFilterValues(value: unknown): unknown[] {
   return values
 }
 
+/**
+ * Builds the shared WHERE clause every aggregation query reads from, together with its parameters.
+ *
+ * The `eq` / `neq` cases branch on a null value instead of binding it (#5016). Under SQL
+ * three-valued logic neither `column = NULL` nor `column != NULL` is ever `TRUE`, so binding a raw
+ * null selected zero rows and rendered as a legitimate-looking empty aggregation — a silent zero on
+ * a reporting surface. Nullness has to be asked with the `IS NULL` / `IS NOT NULL` keywords, which
+ * take no parameter; that is also what the dedicated `is_null` / `is_not_null` operators emit, and
+ * it mirrors how the query index builds column filters (`query_index/lib/engine.ts`).
+ *
+ * The ordering operators (`gt`/`gte`/`lt`/`lte`) deliberately keep binding the value: comparing an
+ * ordering against NULL is genuinely undefined rather than a mistake, so their never-`TRUE` result
+ * is the correct answer. Set operators refuse null members outright — see
+ * `normalizeSetFilterValues`.
+ */
 function buildWhereClause(
   options: Pick<BuildAggregationQueryOptions, 'entityType' | 'dateRange' | 'filters' | 'scope' | 'registry'>,
 ): { clause: string; params: unknown[] } {
@@ -207,10 +222,18 @@ function buildWhereClause(
 
       switch (filter.operator) {
         case 'eq':
+          if (filter.value === null) {
+            whereClauses.push(`${filterMapping.dbColumn} IS NULL`)
+            break
+          }
           whereClauses.push(`${filterMapping.dbColumn} = ?`)
           params.push(filter.value)
           break
         case 'neq':
+          if (filter.value === null) {
+            whereClauses.push(`${filterMapping.dbColumn} IS NOT NULL`)
+            break
+          }
           whereClauses.push(`${filterMapping.dbColumn} != ?`)
           params.push(filter.value)
           break

package/src/modules/query_index/lib/engine.ts

@@ -1386,12 +1386,18 @@ export class HybridQueryEngine implements QueryEngine {
 
     switch (op) {
       case 'eq':
-        return builder.where((eb: any) => eb.or([
-          sql<boolean>`${textExpr} = ${value}`,
-          arrContains(value),
-        ]))
+        // An unset custom field has no array element to contain, so the
+        // arrContains branch cannot match it — compare the text value only.
+        return value === null
+          ? builder.where(sql<boolean>`${textExpr} is null`)
+          : builder.where((eb: any) => eb.or([
+              sql<boolean>`${textExpr} = ${value}`,
+              arrContains(value),
+            ]))
       case 'ne':
-        return builder.where(sql<boolean>`${textExpr} <> ${value}`)
+        return value === null
+          ? builder.where(sql<boolean>`${textExpr} is not null`)
+          : builder.where(sql<boolean>`${textExpr} <> ${value}`)
       case 'in': {
         const values = this.toArray(value)
         return builder.where((eb: any) => eb.or(
@@ -1517,12 +1523,18 @@ export class HybridQueryEngine implements QueryEngine {
     }
     switch (op) {
       case 'eq':
-        return q.where((eb: any) => eb.or([
-          sql<boolean>`${textExpr} = ${value}`,
-          arrContains(value),
-        ]))
+        // An unset custom field has no array element to contain, so the
+        // arrContains branch cannot match it — compare the text value only.
+        return value === null
+          ? q.where(sql<boolean>`${textExpr} is null`)
+          : q.where((eb: any) => eb.or([
+              sql<boolean>`${textExpr} = ${value}`,
+              arrContains(value),
+            ]))
       case 'ne':
-        return q.where(sql<boolean>`${textExpr} <> ${value}`)
+        return value === null
+          ? q.where(sql<boolean>`${textExpr} is not null`)
+          : q.where(sql<boolean>`${textExpr} <> ${value}`)
       case 'in': {
         const vals = this.toArray(value)
         return q.where((eb: any) => eb.or(
@@ -1589,9 +1601,13 @@ export class HybridQueryEngine implements QueryEngine {
     }
     switch (op) {
       case 'eq':
-        return q.where(sql<boolean>`${textExpr} = ${value}`)
+        return value === null
+          ? q.where(sql<boolean>`${textExpr} is null`)
+          : q.where(sql<boolean>`${textExpr} = ${value}`)
       case 'ne':
-        return q.where(sql<boolean>`${textExpr} <> ${value}`)
+        return value === null
+          ? q.where(sql<boolean>`${textExpr} is not null`)
+          : q.where(sql<boolean>`${textExpr} <> ${value}`)
       case 'in': {
         const vals = this.toArray(value)
         return q.where(sql<boolean>`${textExpr} in (${sql.join(vals.map((v) => sql`${v}`), sql`, `)})`)
@@ -1709,8 +1725,8 @@ export class HybridQueryEngine implements QueryEngine {
   ): any {
     const textExpr = sql<string | null>`(${sql.ref(alias + '.doc')} ->> ${key})`
     switch (op) {
-      case 'eq': return sql<boolean>`${textExpr} = ${value}`
-      case 'ne': return sql<boolean>`${textExpr} <> ${value}`
+      case 'eq': return value === null ? sql<boolean>`${textExpr} is null` : sql<boolean>`${textExpr} = ${value}`
+      case 'ne': return value === null ? sql<boolean>`${textExpr} is not null` : sql<boolean>`${textExpr} <> ${value}`
       case 'gt':
       case 'gte':
       case 'lt':

package/src/modules/staff/api/timesheets/time-entries/[id]/timer-start/route.ts

@@ -17,6 +17,7 @@ import {
   runStaffMutationGuards,
 } from '../../../../guards'
 import { emitStaffEvent } from '../../../../../events'
+import { invalidateStaffTimeEntryCache } from '../../../../../lib/timesheets/timeEntryCacheInvalidation'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('staff')
@@ -170,6 +171,13 @@ export async function POST(req: Request) {
       return startedAt
     })
 
+    await invalidateStaffTimeEntryCache(
+      container,
+      { id: entry.id, organizationId: entry.organizationId, tenantId: entry.tenantId },
+      tenantId,
+      'timer_started',
+    )
+
     void emitStaffEvent('staff.timesheets.time_entry.timer_started', {
       id: entry.id,
       staffMemberId: entry.staffMemberId,

package/src/modules/staff/api/timesheets/time-entries/[id]/timer-stop/route.ts

@@ -17,6 +17,7 @@ import {
   runStaffMutationGuards,
 } from '../../../../guards'
 import { emitStaffEvent } from '../../../../../events'
+import { invalidateStaffTimeEntryCache } from '../../../../../lib/timesheets/timeEntryCacheInvalidation'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('staff')
@@ -152,6 +153,13 @@ export async function POST(req: Request) {
       return { now: stoppedAt, durationMinutes: computedMinutes }
     })
 
+    await invalidateStaffTimeEntryCache(
+      container,
+      { id: entry.id, organizationId: entry.organizationId, tenantId: entry.tenantId },
+      tenantId,
+      'timer_stopped',
+    )
+
     void emitStaffEvent('staff.timesheets.time_entry.timer_stopped', {
       id: entry.id,
       staffMemberId: entry.staffMemberId,

package/src/modules/staff/api/timesheets/time-entries/bulk/route.ts

@@ -14,6 +14,7 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { StaffTimeEntry, StaffTeamMember, StaffTimeProject } from '../../../../data/entities'
 import { staffTimeEntryBulkSaveSchema } from '../../../../data/validators'
 import { staffTimeEntryCrudEvents } from '../../../../lib/crud'
+import { invalidateStaffTimeEntryCache } from '../../../../lib/timesheets/timeEntryCacheInvalidation'
 import {
   resolveUserFeatures,
   runStaffMutationGuardAfterSuccess,
@@ -230,6 +231,22 @@ export async function POST(req: Request) {
     }
     await flushCrudSideEffects(dataEngine)
 
+    const invalidatedRecordIds = new Set<string>()
+    for (const change of pendingChanges) {
+      if (invalidatedRecordIds.has(change.entity.id)) continue
+      invalidatedRecordIds.add(change.entity.id)
+      await invalidateStaffTimeEntryCache(
+        container,
+        {
+          id: change.entity.id,
+          organizationId: change.entity.organizationId,
+          tenantId: change.entity.tenantId,
+        },
+        tenantId,
+        `bulk:${change.action}`,
+      )
+    }
+
     if (guardResult.afterSuccessCallbacks.length) {
       await runStaffMutationGuardAfterSuccess(guardResult.afterSuccessCallbacks, {
         tenantId,

package/src/modules/staff/api/timesheets/time-entries/route.ts

@@ -5,6 +5,7 @@ import { resolveCrudRecordId, parseScopedCommandInput } from '@open-mercato/shar
 import { StaffTimeEntry } from '../../../data/entities'
 import { staffTimeEntryCreateSchema, staffTimeEntryUpdateSchema } from '../../../data/validators'
 import { buildTimeEntryListFilters, isParseableDateFilter } from '../../../lib/timesheets/timeEntryListFilters'
+import { staffTimeEntryCommandIds } from '../../../lib/crud'
 import { createStaffCrudOpenApi, createPagedListResponseSchema, defaultOkResponseSchema } from '../../openapi'
 
 const F = {
@@ -99,7 +100,7 @@ const crud = makeCrudRoute({
   },
   actions: {
     create: {
-      commandId: 'staff.timesheets.time_entries.create',
+      commandId: staffTimeEntryCommandIds.create,
       schema: rawBodySchema,
       mapInput: async ({ raw, ctx }) => {
         const { translate } = await resolveTranslations()
@@ -109,7 +110,7 @@ const crud = makeCrudRoute({
       status: 201,
     },
     update: {
-      commandId: 'staff.timesheets.time_entries.update',
+      commandId: staffTimeEntryCommandIds.update,
       schema: rawBodySchema,
       mapInput: async ({ raw, ctx }) => {
         const { translate } = await resolveTranslations()
@@ -118,7 +119,7 @@ const crud = makeCrudRoute({
       response: () => ({ ok: true }),
     },
     delete: {
-      commandId: 'staff.timesheets.time_entries.delete',
+      commandId: staffTimeEntryCommandIds.delete,
       schema: rawBodySchema,
       mapInput: async ({ parsed, ctx }) => {
         const { translate } = await resolveTranslations()

package/src/modules/staff/lib/crud.ts

@@ -36,6 +36,18 @@ export const staffTeamMemberActivityCrudEvents = buildCrudEvents<StaffTeamMember
 export const staffTeamMemberJobHistoryCrudEvents = buildCrudEvents<StaffTeamMemberJobHistory>('job_history')
 
 // Timesheets
+/**
+ * Command ids the time-entries CRUD route registers. Exported so the route and the
+ * cache-invalidation helper share one string: `makeCrudRoute` derives the CRUD cache
+ * resource tag from the create id, so a second copy of it drifting apart would leave
+ * custom write routes flushing a tag nothing is stored under (#4970).
+ */
+export const staffTimeEntryCommandIds = {
+  create: 'staff.timesheets.time_entries.create',
+  update: 'staff.timesheets.time_entries.update',
+  delete: 'staff.timesheets.time_entries.delete',
+} as const
+
 export const staffTimeEntryCrudEvents = buildCrudEvents<StaffTimeEntry>('timesheets.time_entry')
 export const staffTimeProjectCrudEvents = buildCrudEvents<StaffTimeProject>('timesheets.time_project')
 export const staffTimeProjectMemberCrudEvents = buildCrudEvents<StaffTimeProjectMember>('timesheets.time_project_member')

package/src/modules/staff/lib/timesheets/timeEntryCacheInvalidation.ts

@@ -0,0 +1,64 @@
+import type { AwilixContainer } from 'awilix'
+import {
+  canonicalizeResourceTag,
+  deriveResourceFromCommandId,
+  invalidateCrudCache,
+  type CrudCacheIdentifiers,
+} from '@open-mercato/shared/lib/crud/cache'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { staffTimeEntryCommandIds } from '../crud'
+
+const logger = createLogger('staff').child({ component: 'timesheets-cache' })
+
+/**
+ * The resource tag the CRUD list cache stores time-entry payloads under.
+ *
+ * `makeCrudRoute` derives it from the create action's command id (the route declares
+ * no `events` config), which singularizes the command's SECOND segment — so the tag
+ * is `staff.timesheet`, NOT the `staff.time_entry` the entity name suggests. Deriving
+ * it here through the same shared helpers keeps the flush tag equal to the store tag;
+ * a hand-typed literal is how a custom write route silently flushes nothing (#3143,
+ * #3711). The literal fallback only guards against a null derivation at runtime — the
+ * unit test pins the derived value so drift fails in CI instead of in production.
+ */
+export const staffTimeEntryCacheResource =
+  canonicalizeResourceTag(deriveResourceFromCommandId(staffTimeEntryCommandIds.create)) ?? 'staff.timesheet'
+
+/**
+ * Flush the cached time-entry collections and record entries after a committed write.
+ *
+ * Custom write routes that mutate `StaffTimeEntry` through the EntityManager bypass
+ * `makeCrudRoute`'s own POST/PUT/DELETE handlers and the command bus, so neither of
+ * the platform's two `invalidateCrudCache` call sites runs for them. Without this the
+ * opt-in CRUD list cache (`ENABLE_CRUD_API_CACHE`) keeps serving the pre-write payload
+ * and the weekly timesheet grid reloads without the rows it just saved (#4970).
+ *
+ * MUST be called after the transaction commits, never inside it. Because the write is
+ * already committed by then, a failing cache backend is logged rather than thrown — the
+ * command bus guards its own invalidation the same way. Surfacing it would turn a
+ * successful write into an error response and invite a duplicating client retry, while
+ * swallowing it costs at most one TTL of staleness.
+ */
+export async function invalidateStaffTimeEntryCache(
+  container: AwilixContainer,
+  identifiers: CrudCacheIdentifiers,
+  fallbackTenant: string | null,
+  reason: string,
+): Promise<void> {
+  try {
+    await invalidateCrudCache(
+      container,
+      staffTimeEntryCacheResource,
+      identifiers,
+      fallbackTenant,
+      reason,
+    )
+  } catch (err) {
+    logger.warn('Time-entry cache invalidation failed', {
+      resource: staffTimeEntryCacheResource,
+      recordId: identifiers.id ?? null,
+      reason,
+      err,
+    })
+  }
+}