@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/lib/work-inbox/user-task-source.ts

@@ -0,0 +1,240 @@
+/**
+ * Work Inbox — the core `user_task` source.
+ *
+ * A read-model over the existing `user_tasks` rows (spec §6.3: "phase 1: a
+ * projection/read-model over existing `UserTask` … with no data migration").
+ * Nothing here writes; the inbox's mutations go through `taskHandler`.
+ *
+ * Rows are projected through the SAME `serializeUserTask` the task list route
+ * uses and carried on the wire under `details`, so a work-inbox row remains a
+ * strict superset of a task-list row.
+ */
+
+import type { EntityManager, FilterQuery } from '@mikro-orm/core'
+import { UserTask } from '../../data/entities'
+import { serializeUserTask, USER_TASK_INBOX_KIND } from '../../api/tasks/serialize'
+import {
+  WORK_INBOX_TERMINAL_STATUSES,
+  deriveWorkInboxOverdue,
+  normalizeWorkInboxPriority,
+} from './provider'
+import {
+  buildTaskVisibilityRequestConditions,
+  partitionTaskPage,
+} from '../task-visibility-request'
+import type {
+  WorkInboxAction,
+  WorkInboxEntityBinding,
+  WorkInboxQuery,
+  WorkInboxRow,
+  WorkInboxScope,
+  WorkInboxSourceContext,
+  WorkInboxSourceProvider,
+  WorkInboxSourceResult,
+} from './provider'
+
+export const WORKFLOWS_MODULE_ID = 'workflows'
+
+/**
+ * Declarative actions the inbox renders for a workflow task. `complete` points
+ * at the task detail page rather than an endpoint because completing needs the
+ * form; claim and unclaim are one-shot POSTs.
+ */
+export const USER_TASK_WORK_INBOX_ACTIONS: WorkInboxAction[] = [
+  {
+    id: 'claim',
+    labelKey: 'workflows.tasks.actions.claim',
+    endpoint: '/api/workflows/tasks/{id}/claim',
+    appliesTo: 'claimable',
+  },
+  {
+    id: 'unclaim',
+    labelKey: 'workflows.tasks.actions.unclaim',
+    endpoint: '/api/workflows/tasks/{id}/unclaim',
+    appliesTo: 'claimed-by-me',
+  },
+]
+
+type WorkInboxWhere = FilterQuery<UserTask>
+
+/**
+ * Per-source options a `UserTask`-serving provider passes through to the §6.4
+ * rule.
+ *
+ * `administrativeQueueFeature` is the source's own declaration, handed back by
+ * `listWorkInbox`. Core's `user_task` source declares none, so an unassigned row
+ * keeps falling back to `workflows.tasks.view_all` exactly as before; a
+ * specialized source (an administrative queue raised by another module) supplies
+ * its own, and the SQL filter and the predicate must be given the SAME value or
+ * a row is counted in `pagination.total` and then dropped from the page.
+ */
+export type UserTaskWorkInboxOptions = {
+  administrativeQueueFeature?: string | null
+}
+
+function asBindings(value: unknown): WorkInboxEntityBinding[] {
+  if (!Array.isArray(value)) return []
+  const bindings: WorkInboxEntityBinding[] = []
+  for (const item of value) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) continue
+    const record = item as Record<string, unknown>
+    const entityType = record.entityType
+    const entityId = record.entityId
+    if (typeof entityType !== 'string' || typeof entityId !== 'string') continue
+    const label = typeof record.label === 'string' ? record.label : null
+    bindings.push({ entityType, entityId, label })
+  }
+  return bindings
+}
+
+/**
+ * Translate a work-inbox query into the ORM filter.
+ *
+ * Exported and pure so the tenant/organization scoping and every filter can be
+ * asserted without a database. Independent predicates are pushed onto `$and`
+ * rather than merged into one object, because several of them (`myWork`,
+ * `entityTypes`) each need their own `$or` group and a single object can only
+ * carry one.
+ */
+export function buildUserTaskWorkInboxWhere(
+  query: WorkInboxQuery,
+  scope: WorkInboxScope,
+  options: UserTaskWorkInboxOptions = {},
+): WorkInboxWhere {
+  const conditions: Record<string, unknown>[] = []
+
+  if (query.statuses && query.statuses.length > 0) {
+    conditions.push({ status: { $in: query.statuses } })
+  }
+
+  if (query.overdueOnly) {
+    conditions.push({ dueDate: { $lt: query.now } })
+    conditions.push({ status: { $nin: [...WORK_INBOX_TERMINAL_STATUSES] } })
+  }
+
+  if (query.assignedTo) {
+    conditions.push({ assignedTo: query.assignedTo })
+  }
+
+  if (query.workflowInstanceId) {
+    conditions.push({ workflowInstanceId: query.workflowInstanceId })
+  }
+
+  if (query.priorities && query.priorities.length > 0) {
+    conditions.push({ priority: { $in: query.priorities } })
+  }
+
+  if (query.roles && query.roles.length > 0) {
+    conditions.push({ assignedToRoles: { $overlap: query.roles } })
+  }
+
+  if (query.entityTypes && query.entityTypes.length > 0) {
+    conditions.push({
+      $or: query.entityTypes.map((entityType) => ({
+        entityBindings: { $contains: [{ entityType }] },
+      })),
+    })
+  }
+
+  if (query.myWork) {
+    conditions.push({
+      $or: [
+        { assignedTo: scope.userId },
+        { claimedBy: scope.userId },
+        { assignedToRoles: { $overlap: scope.roles } },
+      ],
+    })
+  }
+
+  // §6.4. Pushed onto the SAME `$and` array as every other predicate, so the
+  // relationship clause, the entity gate and the caller's own filters compose
+  // rather than overwrite each other. Empty for an administrator, a superadmin,
+  // or a tenant that has flipped the opt-out — the rule then adds nothing and
+  // tenant/organization scoping below is still the floor.
+  conditions.push(
+    ...buildTaskVisibilityRequestConditions(scope.visibility, {
+      administrativeQueueFeature: options.administrativeQueueFeature ?? null,
+    }),
+  )
+
+  const where: Record<string, unknown> = { tenantId: scope.tenantId }
+  if (scope.organizationIds) {
+    where.organizationId = { $in: scope.organizationIds }
+  }
+  if (conditions.length > 0) {
+    where.$and = conditions
+  }
+
+  return where as WorkInboxWhere
+}
+
+export function toUserTaskWorkInboxRow(task: UserTask, now: Date): WorkInboxRow {
+  const details = serializeUserTask(task)
+  const bindings = asBindings(details.entityBindings)
+  return {
+    id: details.id,
+    kind: USER_TASK_INBOX_KIND,
+    moduleId: WORKFLOWS_MODULE_ID,
+    title: details.taskName,
+    description: details.description ?? null,
+    status: details.status,
+    priority: normalizeWorkInboxPriority(details.priority),
+    dueDate: details.dueDate ?? null,
+    overdue: deriveWorkInboxOverdue(details.dueDate ?? null, details.status, now),
+    createdAt: details.createdAt,
+    updatedAt: details.updatedAt,
+    assignedTo: details.assignedTo ?? null,
+    assignedToRoles: details.assignedToRoles ?? null,
+    claimedBy: details.claimedBy ?? null,
+    entityTypes: [...new Set(bindings.map((binding) => binding.entityType))],
+    entityBindings: bindings,
+    detailHref: `/backend/tasks/${details.id}`,
+    actions: USER_TASK_WORK_INBOX_ACTIONS,
+    details,
+  }
+}
+
+/**
+ * SQL orders by due date (Postgres puts NULLs last on ASC, which is what the
+ * inbox wants) and then by recency; the canonical priority → due → created
+ * ordering is applied by the merge service over the returned window, because
+ * `priority` is an authored label with no ordinal column to sort on. Phase 1 is
+ * a projection — a persisted sort key belongs with the `Task` entity, which
+ * resolved question #1 defers to the next cycle.
+ */
+async function listUserTaskWorkItems(
+  query: WorkInboxQuery,
+  context: WorkInboxSourceContext,
+): Promise<WorkInboxSourceResult> {
+  const em = context.resolve<EntityManager>('em')
+  const options: UserTaskWorkInboxOptions = {
+    administrativeQueueFeature: context.administrativeQueueFeature ?? null,
+  }
+  const where = buildUserTaskWorkInboxWhere(query, context.scope, options)
+
+  const [tasks, total] = await em.findAndCount(UserTask, where, {
+    orderBy: [{ dueDate: 'ASC' }, { createdAt: 'DESC' }],
+    limit: query.offset + query.limit,
+    offset: 0,
+  })
+
+  // The `WHERE` already IS the rule; running the predicate over the page keeps
+  // this source routed through the single decision point and makes a
+  // SQL/predicate divergence lose a row instead of leaking one. It is handed the
+  // SAME queue feature the filter was built with, for exactly that reason.
+  const { visible, entityHidden } = partitionTaskPage(context.scope.visibility, tasks, options)
+
+  return {
+    rows: visible.map((task) => toUserTaskWorkInboxRow(task, query.now)),
+    total,
+    ...(entityHidden.length > 0 ? { entityHidden } : {}),
+  }
+}
+
+export const userTaskWorkInboxSource: WorkInboxSourceProvider = {
+  kind: USER_TASK_INBOX_KIND,
+  moduleId: WORKFLOWS_MODULE_ID,
+  render: 'work-inbox:user_task:detail',
+  actions: USER_TASK_WORK_INBOX_ACTIONS,
+  list: listUserTaskWorkItems,
+}

package/src/modules/workflows/lib/workflow-command-enablement.ts

@@ -0,0 +1,188 @@
+/**
+ * Tier 2 of the UPDATE_ENTITY authorization model: which of the commands the
+ * CODE declares possible are SWITCHED ON for this tenant.
+ *
+ * ## The three gates, and why there are three
+ *
+ * `executeUpdateEntity` runs a command only when ALL of the following hold:
+ *
+ * 1. **Catalogue** — the command was declared through
+ *    `registerWorkflowSafeCommands`. Only the owning module can state that a
+ *    command is safe to run unattended and which ACL feature it needs, so that
+ *    fact stays in code and an administrator can never type an arbitrary id.
+ * 2. **Tenant enablement** — THIS module, decided here. A catalogue entry is a
+ *    CANDIDATE; a human ticks it before any workflow can reach it.
+ * 3. **Actor features** — the workflow's acting user holds the declared
+ *    `requiredFeatures`. Unchanged, and deliberately still last: enabling a
+ *    command for a tenant is not a grant of it to everybody in that tenant.
+ *
+ * Dropping any one of them collapses the model. In particular gate 2 without
+ * gate 1 would be "let an admin name any of the ~275 commands", which is the
+ * design the maintainer rejected.
+ *
+ * ## Why an absent setting is not "nothing enabled"
+ *
+ * Before this file existed, every catalogue entry was reachable. Exactly one
+ * command was ever in the catalogue (`sales.orders.update`), so "all-off by
+ * default" would break the shipped `sales.order-approval` workflow and its
+ * gallery template, while "all-on by default" would silently hand every tenant
+ * the ability to have workflows mutate products and customers the moment a new
+ * candidate is declared.
+ *
+ * So an absent setting resolves to the entries whose declaration carries
+ * `defaultEnabled: true` — the grandfather clause, reserved for commands that
+ * were ALREADY reachable before this gate existed. Everything declared from now
+ * on omits the flag and is therefore off until a human ticks it. A tenant with
+ * no stored row behaves byte-identically to how it behaved before.
+ *
+ * ## Purity
+ *
+ * Nothing here reads a database, a container or a clock. The impure read
+ * happens once per request in `lib/workflow-command-settings.ts` and the
+ * decision is these functions, in the same shape `lib/task-visibility.ts` and
+ * its `-request` companion use.
+ */
+
+import type { WorkflowSafeCommandDefinition } from './workflow-safe-commands'
+
+/**
+ * The tenant's stored answer, already read.
+ *
+ * `enabledCommandIds: null` means the tenant has never saved the setting — NOT
+ * that it saved an empty list. An empty array is a deliberate "nothing is
+ * enabled" and must not be confused with the grandfathered default, which is
+ * why this is a nullable list rather than a set with a sentinel.
+ */
+export type WorkflowCommandEnablementPolicy = {
+  enabledCommandIds: readonly string[] | null
+}
+
+/** The policy for a tenant with no stored row. */
+export const UNSET_WORKFLOW_COMMAND_POLICY: WorkflowCommandEnablementPolicy = {
+  enabledCommandIds: null,
+}
+
+/** One catalogue entry plus this tenant's answer for it. */
+export type WorkflowCommandAvailability = {
+  commandId: string
+  requiredFeatures: string[]
+  /** i18n key supplied by the owning module; absent means "render the id". */
+  labelKey: string | null
+  enabled: boolean
+  /**
+   * Whether the declaration carries the grandfather clause. Surfaced so the
+   * settings UI can explain why a row is ticked in a tenant that never saved.
+   */
+  defaultEnabled: boolean
+}
+
+function normalizeIds(values: readonly unknown[]): string[] {
+  const seen = new Set<string>()
+  for (const value of values) {
+    if (typeof value !== 'string') continue
+    const trimmed = value.trim()
+    if (trimmed.length > 0) seen.add(trimmed)
+  }
+  return [...seen]
+}
+
+/**
+ * Turn whatever is stored in `module_configs` into a policy.
+ *
+ * An absent, null or structurally wrong value all resolve to the UNSET policy,
+ * i.e. to the grandfathered set. That is the conservative direction: a broken
+ * row can never widen what a tenant may execute beyond what it could execute
+ * before the setting existed, and it can never silently disable a command that
+ * already works. Non-string members are dropped rather than failing the whole
+ * read — a single bad element must not reopen the grandfathered set.
+ */
+export function parseStoredEnabledCommandIds(value: unknown): readonly string[] | null {
+  if (!Array.isArray(value)) return null
+  return normalizeIds(value)
+}
+
+function findCatalogueEntry(
+  catalogue: readonly WorkflowSafeCommandDefinition[],
+  commandId: string,
+): WorkflowSafeCommandDefinition | null {
+  return catalogue.find((command) => command.commandId === commandId) ?? null
+}
+
+/**
+ * Gate 2 for one already-catalogued command.
+ *
+ * Takes the DEFINITION, not an id, so a caller cannot accidentally ask about a
+ * command that is not in the catalogue and get a `true` back — gate 1 is
+ * discharged by having the definition at all.
+ */
+export function isWorkflowCommandEnabled(
+  command: WorkflowSafeCommandDefinition,
+  policy: WorkflowCommandEnablementPolicy,
+): boolean {
+  if (policy.enabledCommandIds === null) return command.defaultEnabled === true
+  return policy.enabledCommandIds.includes(command.commandId)
+}
+
+/**
+ * Gates 1 and 2 together: the definition to execute, or `null`.
+ *
+ * The single answer the runtime asks for. A command absent from the catalogue
+ * and a command present but not ticked are both `null` here — they differ only
+ * in the message the caller reports, never in the outcome.
+ */
+export function resolveEnabledWorkflowCommand(
+  catalogue: readonly WorkflowSafeCommandDefinition[],
+  policy: WorkflowCommandEnablementPolicy,
+  commandId: string,
+): WorkflowSafeCommandDefinition | null {
+  const command = findCatalogueEntry(catalogue, commandId)
+  if (!command) return null
+  return isWorkflowCommandEnabled(command, policy) ? command : null
+}
+
+/** The whole catalogue with this tenant's answer attached, in catalogue order. */
+export function resolveWorkflowCommandCatalogue(
+  catalogue: readonly WorkflowSafeCommandDefinition[],
+  policy: WorkflowCommandEnablementPolicy,
+): WorkflowCommandAvailability[] {
+  return catalogue.map((command) => ({
+    commandId: command.commandId,
+    requiredFeatures: [...command.requiredFeatures],
+    labelKey: command.labelKey ?? null,
+    enabled: isWorkflowCommandEnabled(command, policy),
+    defaultEnabled: command.defaultEnabled === true,
+  }))
+}
+
+/**
+ * The ids a settings write must persist.
+ *
+ * Two rules, both about not losing a tenant's answer:
+ *
+ * - Submitted ids outside the catalogue are DROPPED, never stored. Gate 1 makes
+ *   them unexecutable anyway, so storing one would only manufacture a row that
+ *   looks like a grant and is not.
+ * - Stored ids outside the CURRENT catalogue are KEPT. A module can be absent
+ *   from a given process (an optional peer, a temporarily disabled module), and
+ *   a settings save from a UI that could not list its commands must not silently
+ *   untick them.
+ */
+export function mergeEnabledCommandIds(
+  submitted: readonly string[],
+  stored: readonly string[] | null,
+  catalogue: readonly WorkflowSafeCommandDefinition[],
+): string[] {
+  const catalogueIds = new Set(catalogue.map((command) => command.commandId))
+  const kept = normalizeIds(submitted).filter((commandId) => catalogueIds.has(commandId))
+  const retained = normalizeIds(stored ?? []).filter((commandId) => !catalogueIds.has(commandId))
+  return [...new Set([...kept, ...retained])]
+}
+
+/** Ids a settings write asked for that the catalogue does not declare. */
+export function findUncataloguedCommandIds(
+  submitted: readonly string[],
+  catalogue: readonly WorkflowSafeCommandDefinition[],
+): string[] {
+  const catalogueIds = new Set(catalogue.map((command) => command.commandId))
+  return normalizeIds(submitted).filter((commandId) => !catalogueIds.has(commandId))
+}

package/src/modules/workflows/lib/workflow-command-settings.ts

@@ -0,0 +1,124 @@
+/**
+ * The impure half of the UPDATE_ENTITY tenant enablement gate.
+ *
+ * Shape copied from `lib/task-permission-settings.ts`: one tenant-scoped
+ * `module_configs` row under the `workflows` module id, read through
+ * `ModuleConfigService` (scoped row → global row → not found), decided by the
+ * PURE functions in `lib/workflow-command-enablement.ts`.
+ *
+ * ## Caching
+ *
+ * There is NO cache here, deliberately. `ModuleConfigService.getValue` already
+ * caches through the platform `CacheStrategy` — tenant-keyed, 60s TTL, tagged
+ * `module-config:module:workflows` — and `setValue` writes the new value
+ * through that same key, so the settings page's own save is visible
+ * immediately. A second cache in this module would need its own invalidation
+ * hook on every write path and could disagree with the settings page about what
+ * is enabled, which is the failure mode this gate exists to prevent. On the
+ * `UPDATE_ENTITY` hot path this costs one cache read per activity execution and,
+ * at most, one indexed single-row `SELECT` per tenant per minute.
+ *
+ * ## Failure direction
+ *
+ * A read that cannot happen — no container, no service, an unparseable row —
+ * resolves to the UNSET policy, i.e. the grandfathered set. That is the only
+ * answer that neither grants a capability the tenant never ticked nor breaks a
+ * workflow that already ran. It is never "everything enabled".
+ *
+ * `tenantId` MUST come from the authenticated context or from the workflow
+ * instance, never from request input.
+ */
+
+import {
+  parseStoredEnabledCommandIds,
+  UNSET_WORKFLOW_COMMAND_POLICY,
+  type WorkflowCommandEnablementPolicy,
+} from './workflow-command-enablement'
+
+/** `module_configs.module_id`, shared with the task-permission setting. */
+export const WORKFLOWS_COMMAND_CONFIG_MODULE = 'workflows'
+
+/** `module_configs.name`. Well within `moduleConfigKeySchema`'s 128 chars. */
+export const UPDATE_ENTITY_ENABLED_COMMANDS_KEY = 'update_entity_enabled_commands'
+
+/** The `ModuleConfigService` slice this needs, so tests need no container. */
+export type WorkflowCommandConfigService = {
+  getValue: (
+    moduleId: string,
+    name: string,
+    options?: { defaultValue?: unknown; scope?: { tenantId?: string | null } },
+  ) => Promise<unknown>
+  setValue: (
+    moduleId: string,
+    name: string,
+    value: unknown,
+    scope?: { tenantId?: string | null },
+  ) => Promise<unknown>
+}
+
+/** The container slice the runtime helper below reaches for. */
+export type WorkflowCommandSettingsContainer = { resolve: <T>(name: string) => T }
+
+export async function readEnabledWorkflowCommandIds(
+  moduleConfigService: WorkflowCommandConfigService | null | undefined,
+  tenantId: string | null,
+): Promise<readonly string[] | null> {
+  if (!moduleConfigService) return null
+  try {
+    const value = await moduleConfigService.getValue(
+      WORKFLOWS_COMMAND_CONFIG_MODULE,
+      UPDATE_ENTITY_ENABLED_COMMANDS_KEY,
+      { scope: { tenantId } },
+    )
+    return parseStoredEnabledCommandIds(value)
+  } catch {
+    return null
+  }
+}
+
+/** The `policy` argument every decision function takes. */
+export async function resolveWorkflowCommandEnablementPolicy(
+  moduleConfigService: WorkflowCommandConfigService | null | undefined,
+  tenantId: string | null,
+): Promise<WorkflowCommandEnablementPolicy> {
+  const enabledCommandIds = await readEnabledWorkflowCommandIds(moduleConfigService, tenantId)
+  return enabledCommandIds === null ? UNSET_WORKFLOW_COMMAND_POLICY : { enabledCommandIds }
+}
+
+export async function writeEnabledWorkflowCommandIds(
+  moduleConfigService: WorkflowCommandConfigService,
+  tenantId: string,
+  commandIds: readonly string[],
+): Promise<void> {
+  await moduleConfigService.setValue(
+    WORKFLOWS_COMMAND_CONFIG_MODULE,
+    UPDATE_ENTITY_ENABLED_COMMANDS_KEY,
+    [...commandIds],
+    { tenantId },
+  )
+}
+
+/**
+ * Resolve the config service from a container without letting its absence fail
+ * the caller. An absent service reads as the UNSET policy — see the header.
+ */
+export function resolveWorkflowCommandConfigService(
+  container: WorkflowCommandSettingsContainer,
+): WorkflowCommandConfigService | null {
+  try {
+    return container.resolve<WorkflowCommandConfigService>('moduleConfigService') ?? null
+  } catch {
+    return null
+  }
+}
+
+/** The policy for one workflow run, resolved from its own container + tenant. */
+export async function resolveWorkflowCommandPolicyForContainer(
+  container: WorkflowCommandSettingsContainer,
+  tenantId: string | null,
+): Promise<WorkflowCommandEnablementPolicy> {
+  return resolveWorkflowCommandEnablementPolicy(
+    resolveWorkflowCommandConfigService(container),
+    tenantId,
+  )
+}