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

package/src/modules/staff/lib/timesheets-reports/reportApprovalPolicies.ts

@@ -0,0 +1,137 @@
+/**
+ * EP-41 — the report approval / lock policy provider.
+ *
+ * The policy layer sits ON TOP of the ACL check, it does not replace it. The
+ * close and unlock routes still require `staff.timesheets.lock` and
+ * `staff.timesheets.reports.unlock` respectively, unconditionally and before
+ * anything here runs; a policy can only add a reason to refuse. That is enforced
+ * structurally: `canClose` / `canUnlock` return a refusal or nothing, never a
+ * grant, so there is no shape in which a policy can open a door the ACL closed.
+ *
+ * The built-in `staff.time_tracking.report_approval.acl_only` refuses nothing,
+ * which is exactly the ACL-only gate the module shipped with.
+ */
+
+import { extensionPoints } from '@open-mercato/core/modules/staff/extension-points'
+import { createStrategyRegistry, BUILT_IN_STRATEGY_PRIORITY } from '../time-tracking/registries/registry'
+import { runStrategy } from '../time-tracking/registries/invoke'
+import { hasResolverScope, type ScopedResolverContext } from '../time-tracking/registries/scope'
+
+export type ReportApprovalContext = ScopedResolverContext & {
+  reportId: string
+  actorUserId: string | null
+  /** The features the ACL gate already resolved for the actor. */
+  actorFeatures: readonly string[]
+  status: string
+  reason?: string | null
+}
+
+export type ReportApprovalRefusal = {
+  /** Machine-readable, surfaced in the response body as `code`. */
+  code: string
+  /** i18n key the route translates; never a user-facing literal. */
+  messageKey: string
+}
+
+/** `null` — and `undefined` — mean "no objection", never "allowed". */
+export type ReportApprovalVerdict = ReportApprovalRefusal | null | undefined
+
+export type ReportApprovalPolicy = {
+  id: string
+  priority?: number
+  canClose?(ctx: ReportApprovalContext): ReportApprovalVerdict
+  canUnlock?(ctx: ReportApprovalContext): ReportApprovalVerdict
+  onClosed?(ctx: ReportApprovalContext): void | Promise<void>
+}
+
+export const REPORT_APPROVAL_POLICY_REGISTRY_ID = extensionPoints.hosts.reportApprovalPolicyRegistry.spotId
+
+export const BUILT_IN_REPORT_APPROVAL_POLICY_ID = 'staff.time_tracking.report_approval.acl_only'
+
+const registry = createStrategyRegistry<ReportApprovalPolicy>(REPORT_APPROVAL_POLICY_REGISTRY_ID)
+
+export function registerReportApprovalPolicy(policy: ReportApprovalPolicy): () => void {
+  return registry.register(policy)
+}
+
+export function listReportApprovalPolicies(): ReportApprovalPolicy[] {
+  return registry.list()
+}
+
+export function getReportApprovalPolicy(id: string | null | undefined): ReportApprovalPolicy | null {
+  return registry.get(id)
+}
+
+registry.registerBuiltIn({
+  id: BUILT_IN_REPORT_APPROVAL_POLICY_ID,
+  priority: BUILT_IN_STRATEGY_PRIORITY,
+})
+
+function applicablePolicies(ctx: ReportApprovalContext): ReportApprovalPolicy[] {
+  const scoped = hasResolverScope(ctx)
+  return registry
+    .list()
+    .filter((policy) => scoped || policy.id === BUILT_IN_REPORT_APPROVAL_POLICY_ID)
+}
+
+/**
+ * These two are the only registry call sites that do NOT fall back to the built-in
+ * when a policy throws, and the asymmetry is deliberate: they are gates, and the
+ * built-in grants (it declares no `canClose`/`canUnlock` at all, because the ACL
+ * check in the routes runs first and unconditionally). Falling back would turn a
+ * broken policy into permission. A thrower refuses instead, which is the same answer
+ * the policy would have given if it could not satisfy itself.
+ */
+function refusalOnFailure(): ReportApprovalRefusal {
+  return { code: 'approval_policy_unavailable', messageKey: 'staff.errors.forbidden' }
+}
+
+function evaluatePolicyVerdict(
+  ctx: ReportApprovalContext,
+  read: (policy: ReportApprovalPolicy) => ReportApprovalVerdict,
+): ReportApprovalRefusal | null {
+  for (const policy of applicablePolicies(ctx)) {
+    const verdict = runStrategy(
+      REPORT_APPROVAL_POLICY_REGISTRY_ID,
+      policy.id,
+      () => read(policy),
+      () => refusalOnFailure(),
+    )
+    if (verdict) return verdict
+  }
+  return null
+}
+
+/** The first refusal wins; every policy must agree before a close proceeds. */
+export function evaluateReportClosePolicies(ctx: ReportApprovalContext): ReportApprovalRefusal | null {
+  return evaluatePolicyVerdict(ctx, (policy) => policy.canClose?.(ctx))
+}
+
+export function evaluateReportUnlockPolicies(ctx: ReportApprovalContext): ReportApprovalRefusal | null {
+  return evaluatePolicyVerdict(ctx, (policy) => policy.canUnlock?.(ctx))
+}
+
+export type ReportApprovalNotificationFailure = {
+  policyId: string
+  error: unknown
+}
+
+/**
+ * Fired after a close has committed. A throwing hook cannot unwind a freeze that
+ * already happened, so failures are collected and handed back for the caller to
+ * log — the same trade the export route makes with its audit row.
+ */
+export async function notifyReportClosed(
+  ctx: ReportApprovalContext,
+): Promise<ReportApprovalNotificationFailure[]> {
+  const failures: ReportApprovalNotificationFailure[] = []
+  for (const policy of applicablePolicies(ctx)) {
+    if (!policy.onClosed) continue
+    try {
+      await policy.onClosed(ctx)
+    } catch (error) {
+      failures.push({ policyId: policy.id, error })
+    }
+  }
+  return failures
+}

package/src/modules/staff/lib/timesheets-reports/reportConfigData.ts

@@ -0,0 +1,247 @@
+/**
+ * Client-side shapes for the report config screen (13) and the preview endpoint
+ * that feeds it. Kept out of the page component so the parsing is unit-testable
+ * without mounting React.
+ */
+
+export type ReportCandidateProject = {
+  id: string
+  name: string
+  hourlyRate: number | null
+  currencyCode: string | null
+}
+
+export type PreviewProjectRow = {
+  id: string
+  name: string
+  hourlyRate: number | null
+  currencyCode: string | null
+  entryCount: number
+  billableMinutes: number
+  nonbillableMinutes: number
+  amount: number | null
+}
+
+export type PreviewAlreadyReportedSource = {
+  reportId: string
+  reference: string | null
+  title: string | null
+  entryCount: number
+  minutes: number
+}
+
+export type PreviewLine = {
+  key: string
+  label: string
+  minutes: number
+  rate: number | null
+  amount: number
+  entryCount: number
+  hasOverride: boolean
+  children: PreviewLine[]
+}
+
+export type PreviewGroup = {
+  key: string
+  kind: 'project' | 'nonbillable'
+  label: string
+  rate: number | null
+  minutes: number
+  amount: number
+  entryCount: number
+  lines: PreviewLine[]
+}
+
+export type ReportPreview = {
+  currencyCode: string | null
+  grouping: 'project_task' | 'project_person' | 'project_day'
+  nonbillableMode: 'separate' | 'exclude'
+  includeAlreadyReported: boolean
+  showRates: boolean
+  projects: PreviewProjectRow[]
+  groups: PreviewGroup[]
+  totals: {
+    entryCount: number
+    billableMinutes: number
+    nonbillableMinutes: number
+    totalAmount: number | null
+  }
+  alreadyReportedCount: number
+  alreadyReportedMinutes: number
+  alreadyReportedIn: PreviewAlreadyReportedSource[]
+  rounding: { unitMinutes: number; direction: string }
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+}
+
+export function readNumber(value: unknown): number | null {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null
+  if (typeof value === 'string' && value.trim().length > 0) {
+    const parsed = Number.parseFloat(value)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+  return null
+}
+
+/** Maps a `/time-projects` list row onto the pick-list's candidate shape. */
+export function toCandidateProject(row: Record<string, unknown>): ReportCandidateProject | null {
+  const id = readString(row.id)
+  if (!id) return null
+  return {
+    id,
+    name: readString(row.name) ?? readString(row.code) ?? id,
+    hourlyRate: readNumber(row.hourly_rate ?? row.hourlyRate),
+    currencyCode: readString(row.currency_code ?? row.currencyCode),
+  }
+}
+
+function toLine(raw: unknown): PreviewLine | null {
+  if (!raw || typeof raw !== 'object') return null
+  const row = raw as Record<string, unknown>
+  const key = readString(row.key)
+  if (key === null) return null
+  return {
+    key,
+    label: readString(row.label) ?? key,
+    minutes: readNumber(row.minutes) ?? 0,
+    rate: readNumber(row.rate),
+    amount: readNumber(row.amount) ?? 0,
+    entryCount: readNumber(row.entryCount) ?? 0,
+    hasOverride: row.hasOverride === true,
+    children: Array.isArray(row.children)
+      ? row.children.map(toLine).filter((line): line is PreviewLine => line !== null)
+      : [],
+  }
+}
+
+/**
+ * Defensive because the preview response is money the screen renders verbatim:
+ * a shape surprise must yield an empty sheet, never a plausible-looking wrong
+ * number. Missing amounts read as `null` and are rendered as "—".
+ */
+export function parseReportPreview(payload: unknown): ReportPreview | null {
+  if (!payload || typeof payload !== 'object') return null
+  const row = payload as Record<string, unknown>
+  const totalsRaw = (row.totals ?? {}) as Record<string, unknown>
+  const roundingRaw = (row.rounding ?? {}) as Record<string, unknown>
+  const grouping = row.grouping
+  const nonbillableMode = row.nonbillableMode
+
+  return {
+    currencyCode: readString(row.currencyCode),
+    grouping:
+      grouping === 'project_person' || grouping === 'project_day' ? grouping : 'project_task',
+    nonbillableMode: nonbillableMode === 'exclude' ? 'exclude' : 'separate',
+    includeAlreadyReported: row.includeAlreadyReported === true,
+    showRates: row.showRates === true,
+    projects: Array.isArray(row.projects)
+      ? row.projects
+          .map((entry) => {
+            if (!entry || typeof entry !== 'object') return null
+            const project = entry as Record<string, unknown>
+            const id = readString(project.id)
+            if (!id) return null
+            return {
+              id,
+              name: readString(project.name) ?? id,
+              hourlyRate: readNumber(project.hourlyRate),
+              currencyCode: readString(project.currencyCode),
+              entryCount: readNumber(project.entryCount) ?? 0,
+              billableMinutes: readNumber(project.billableMinutes) ?? 0,
+              nonbillableMinutes: readNumber(project.nonbillableMinutes) ?? 0,
+              amount: readNumber(project.amount),
+            } satisfies PreviewProjectRow
+          })
+          .filter((project): project is PreviewProjectRow => project !== null)
+      : [],
+    groups: Array.isArray(row.groups)
+      ? row.groups
+          .map((entry) => {
+            if (!entry || typeof entry !== 'object') return null
+            const group = entry as Record<string, unknown>
+            const key = readString(group.key)
+            if (key === null) return null
+            return {
+              key,
+              kind: group.kind === 'nonbillable' ? 'nonbillable' : 'project',
+              label: readString(group.label) ?? key,
+              rate: readNumber(group.rate),
+              minutes: readNumber(group.minutes) ?? 0,
+              amount: readNumber(group.amount) ?? 0,
+              entryCount: readNumber(group.entryCount) ?? 0,
+              lines: Array.isArray(group.lines)
+                ? group.lines.map(toLine).filter((line): line is PreviewLine => line !== null)
+                : [],
+            } satisfies PreviewGroup
+          })
+          .filter((group): group is PreviewGroup => group !== null)
+      : [],
+    totals: {
+      entryCount: readNumber(totalsRaw.entryCount) ?? 0,
+      billableMinutes: readNumber(totalsRaw.billableMinutes) ?? 0,
+      nonbillableMinutes: readNumber(totalsRaw.nonbillableMinutes) ?? 0,
+      totalAmount: readNumber(totalsRaw.totalAmount),
+    },
+    alreadyReportedCount: readNumber(row.alreadyReportedCount) ?? 0,
+    alreadyReportedMinutes: readNumber(row.alreadyReportedMinutes) ?? 0,
+    alreadyReportedIn: Array.isArray(row.alreadyReportedIn)
+      ? row.alreadyReportedIn
+          .map((entry) => {
+            if (!entry || typeof entry !== 'object') return null
+            const source = entry as Record<string, unknown>
+            const reportId = readString(source.reportId)
+            if (!reportId) return null
+            return {
+              reportId,
+              reference: readString(source.reference),
+              title: readString(source.title),
+              entryCount: readNumber(source.entryCount) ?? 0,
+              minutes: readNumber(source.minutes) ?? 0,
+            } satisfies PreviewAlreadyReportedSource
+          })
+          .filter((source): source is PreviewAlreadyReportedSource => source !== null)
+      : [],
+    rounding: {
+      unitMinutes: readNumber(roundingRaw.unitMinutes) ?? 0,
+      direction: readString(roundingRaw.direction) ?? 'up',
+    },
+  }
+}
+
+export type CurrencyConflict = {
+  currencies: string[]
+  offenders: Array<{ id: string; name: string; currencyCode: string | null }>
+}
+
+/**
+ * Risk R2 surfaced rather than swallowed. The server refuses a mixed selection
+ * with `422 report_currency_conflict`; the screen has to be able to say WHICH
+ * projects disagree, or the user is left toggling checkboxes at random.
+ */
+export function readCurrencyConflict(error: unknown): CurrencyConflict | null {
+  const body = (error as { body?: unknown } | null)?.body ?? error
+  if (!body || typeof body !== 'object') return null
+  const row = body as Record<string, unknown>
+  if (row.code !== 'report_currency_conflict') return null
+  const currencies = Array.isArray(row.currencies)
+    ? row.currencies.filter((code): code is string => typeof code === 'string')
+    : []
+  const offenders = Array.isArray(row.offenders)
+    ? row.offenders
+        .map((entry) => {
+          if (!entry || typeof entry !== 'object') return null
+          const offender = entry as Record<string, unknown>
+          const id = readString(offender.id)
+          if (!id) return null
+          return {
+            id,
+            name: readString(offender.name) ?? id,
+            currencyCode: readString(offender.currencyCode),
+          }
+        })
+        .filter((offender): offender is CurrencyConflict['offenders'][number] => offender !== null)
+    : []
+  return { currencies, offenders }
+}

package/src/modules/staff/lib/timesheets-reports/reportConfigState.ts

@@ -0,0 +1,89 @@
+/**
+ * D-4 made executable: a period preset FILLS an editable From/To pair, and the
+ * moment either date is moved by hand the report's `period_kind` becomes
+ * `custom`.
+ *
+ * The mockup drew fixed Week / Month / Year buttons and §8 described the same,
+ * but consulting invoices rarely stop at a calendar boundary — the screen 13
+ * example is itself a 1 June – 19 July range. Rather than choosing between the
+ * two, the preset is a shortcut that seeds the dates and then gets out of the
+ * way. Keeping the preset highlighted after the user moved a date would be a
+ * lie about what is going to be reported, so it is dropped rather than kept.
+ */
+
+import { resolvePeriodRange, todayIso, type TimesheetDateRange } from '../time-tracking-ui/timesheetPeriod'
+
+export type ReportPeriodKind = 'week' | 'month' | 'year' | 'custom'
+
+export const REPORT_PERIOD_PRESETS: readonly Exclude<ReportPeriodKind, 'custom'>[] = ['week', 'month', 'year']
+
+export type ReportPeriodState = {
+  kind: ReportPeriodKind
+  from: string
+  to: string
+}
+
+export function isReportPeriodPreset(value: unknown): value is Exclude<ReportPeriodKind, 'custom'> {
+  return value === 'week' || value === 'month' || value === 'year'
+}
+
+export function presetRange(
+  kind: Exclude<ReportPeriodKind, 'custom'>,
+  anchorIso: string = todayIso(),
+): TimesheetDateRange {
+  return resolvePeriodRange(kind, anchorIso)
+}
+
+export function initialReportPeriod(anchorIso: string = todayIso()): ReportPeriodState {
+  const range = presetRange('month', anchorIso)
+  return { kind: 'month', from: range.from, to: range.to }
+}
+
+/** Applying a preset replaces both dates and restores the preset kind. */
+export function applyPreset(
+  state: ReportPeriodState,
+  kind: Exclude<ReportPeriodKind, 'custom'>,
+  anchorIso: string = todayIso(),
+): ReportPeriodState {
+  // Anchor on the range the user is already looking at so "Month" next to a
+  // June range means June, not whatever month it happens to be today.
+  const anchor = state.from || anchorIso
+  const range = presetRange(kind, anchor)
+  return { kind, from: range.from, to: range.to }
+}
+
+/**
+ * Moving a bound by hand. The kind drops to `custom` only when the date actually
+ * changed, so re-typing the same value does not silently relabel the period.
+ */
+export function applyBound(
+  state: ReportPeriodState,
+  bound: 'from' | 'to',
+  value: string,
+): ReportPeriodState {
+  const current = bound === 'from' ? state.from : state.to
+  if (value === current) return state
+  const next: ReportPeriodState = { ...state, [bound]: value } as ReportPeriodState
+  next.kind = 'custom'
+  return next
+}
+
+export function isValidReportPeriod(state: ReportPeriodState): boolean {
+  if (!state.from || !state.to) return false
+  return state.to >= state.from
+}
+
+/** The period spans more than one calendar month, which screen 13 calls out. */
+export function spansMultipleMonths(state: ReportPeriodState): boolean {
+  if (!state.from || !state.to) return false
+  return state.from.slice(0, 7) !== state.to.slice(0, 7)
+}
+
+export function defaultReportTitle(
+  customerName: string | null,
+  period: ReportPeriodState,
+  fallbackCustomer: string,
+): string {
+  const name = customerName && customerName.trim().length > 0 ? customerName.trim() : fallbackCustomer
+  return `${name} · ${period.from} – ${period.to}`
+}