@rytass/bpm-core-shared 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -8,6 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Releases are managed by [`nx release`](https://nx.dev/recipes/nx-release) with
 Conventional Commits — see `nx.json` for the release config.
 
+## 0.5.0 — 2026-07-06
+
+No source changes. Version aligned with `@rytass/bpm-core-client` and
+`@rytass/bpm-core-nestjs-module` 0.5.0 (fixed release group). The new
+`BPMMemberSearchPage` paged-search types added in that release live in
+`@rytass/bpm-core-nestjs-module`, not here.
+
+## 0.4.0 — 2026-07-02
+
+No source changes. Version aligned with `@rytass/bpm-core-client` and
+`@rytass/bpm-core-nestjs-module` 0.4.0 (fixed release group).
+
 ## 0.3.0 — 2026-06-06
 
 No source changes. Version aligned with `@rytass/bpm-core-client` and

package/eslint.config.mjs

@@ -0,0 +1,19 @@
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}'],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+];

package/jest.config.cts

@@ -0,0 +1,10 @@
+module.exports = {
+  displayName: 'shared',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/libs/shared',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-shared",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Shared TypeScript contracts for the Rytass BPM approval workflow stack (workflow, form, condition, identity, organization, status types).",
   "keywords": [
     "bpm",
@@ -94,6 +94,5 @@
   },
   "dependencies": {
     "tslib": "^2.3.0"
-  },
-  "type": "commonjs"
+  }
 }

package/project.json

@@ -0,0 +1,49 @@
+{
+  "name": "shared",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/shared/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/shared",
+        "main": "libs/shared/src/index.ts",
+        "tsConfig": "libs/shared/tsconfig.lib.json",
+        "assets": [
+          "libs/shared/*.md",
+          { "input": ".", "glob": "LICENSE", "output": "." }
+        ]
+      }
+    },
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsc --noEmit -p libs/shared/tsconfig.lib.json"
+      }
+    },
+    "pkg-quality": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "commands": [
+          "pnpm exec publint dist/libs/shared"
+        ],
+        "parallel": false
+      }
+    },
+    "pkg-quality-attw": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "pnpm exec attw --pack dist/libs/shared"
+      }
+    },
+    "prepublish-check": {
+      "executor": "nx:noop",
+      "dependsOn": ["typecheck", "lint", "build", "pkg-quality"]
+    }
+  }
+}

package/src/lib/condition.ts

@@ -0,0 +1,55 @@
+export type ConditionContextType =
+  | 'INITIATOR_POLICY'
+  | 'ENTRY_CONDITION'
+  | 'FLOW_CONDITION'
+  | 'APPROVER_RESOLVER'
+  | 'FORM_FIELD_CONDITION'
+  | 'DELEGATION_CONDITION';
+
+export interface SubjectContext {
+  readonly customFields: Readonly<Record<string, unknown>>;
+  readonly email: string;
+  readonly memberId: string;
+  readonly name: string;
+  readonly org: OrgContext;
+  readonly position: PositionContext;
+  readonly roles: readonly string[];
+}
+
+export interface OrgContext {
+  readonly code: string;
+  readonly costCenter?: string;
+  readonly id: string;
+  readonly location?: string;
+  readonly name: string;
+  readonly parentId: string | null;
+  readonly path: readonly string[];
+  readonly type: string;
+}
+
+export interface PositionContext {
+  readonly code: string;
+  readonly id: string;
+  readonly level: number;
+  readonly name: string;
+}
+
+export interface EnvContext {
+  readonly now: string;
+}
+
+export interface InstanceContext {
+  readonly id: string;
+  readonly startedAt: string;
+  readonly templateId: string;
+  readonly templateVersion: number;
+}
+
+export interface LastDecisionContext {
+  readonly action: 'approved' | 'rejected' | 'returned';
+  readonly comment: string;
+  readonly decidedAt: string;
+  readonly decidedBy: SubjectContext;
+  readonly nodeId: string;
+  readonly taskId: string;
+}

package/src/lib/form.ts

@@ -0,0 +1,77 @@
+export interface FormDefinitionSchema {
+  readonly fields: readonly FormFieldDefinition[];
+  readonly schemaVersion: 1;
+}
+
+export type FormFieldDefinition =
+  | TextFieldDefinition
+  | NumberFieldDefinition
+  | DateFieldDefinition
+  | SelectFieldDefinition
+  | BooleanFieldDefinition
+  | FileUploadFieldDefinition;
+
+interface BaseFormFieldDefinition<TType extends string> {
+  readonly defaultValue?: FormFieldValue;
+  readonly description?: string;
+  readonly fieldKey: string;
+  readonly label: string;
+  readonly placeholder?: string;
+  readonly readonlyWhen?: string;
+  readonly required: boolean;
+  readonly requiredWhen?: string;
+  readonly type: TType;
+  readonly visibleWhen?: string;
+}
+
+export type FormFieldValue =
+  | boolean
+  | number
+  | string
+  | readonly string[]
+  | null;
+
+export type TextFieldDefinition = BaseFormFieldDefinition<
+  'text' | 'textarea'
+> & {
+  readonly maxLength?: number;
+  readonly minLength?: number;
+};
+
+export type NumberFieldDefinition = BaseFormFieldDefinition<
+  'number' | 'money'
+> & {
+  readonly maximum?: number;
+  readonly minimum?: number;
+};
+
+export type DateFieldDefinition = BaseFormFieldDefinition<'date' | 'datetime'>;
+
+export type SelectFieldDefinition = BaseFormFieldDefinition<
+  'select' | 'radio' | 'checkbox'
+> & {
+  readonly options: readonly FormFieldOption[];
+};
+
+export interface FormFieldOption {
+  readonly label: string;
+  readonly value: string;
+}
+
+export type BooleanFieldDefinition = BaseFormFieldDefinition<'boolean'>;
+
+export type FileUploadFieldDefinition =
+  BaseFormFieldDefinition<'file_upload'> & {
+    readonly acceptedMimeTypes?: readonly string[];
+    readonly maxFiles?: number;
+  };
+
+export interface FormUiSchema {
+  readonly layout: readonly FormLayoutItem[];
+  readonly schemaVersion: 1;
+}
+
+export interface FormLayoutItem {
+  readonly fieldKey: string;
+  readonly width: 'FULL' | 'HALF' | 'THIRD';
+}

package/src/lib/identity.ts

@@ -0,0 +1,25 @@
+export interface MemberMetadata {
+  readonly memberId: string;
+  readonly name: string;
+  readonly email: string;
+  /**
+   * Opaque host-shaped JSON. BPM stores the object verbatim, serializes
+   * it back to GraphQL clients as `MemberProfile.customFieldsJson`, and
+   * never introspects keys — anything the host puts here flows through
+   * unchanged. Hosts using `createBPMMemberBaseResolverProvider` populate
+   * this field via the `options.readCustomFields?.(member)` hook;
+   * standalone `BPMMemberResolver` implementations return whatever shape
+   * the consumer UI needs. Use it as a side channel for picker labels,
+   * org context strings, avatar URLs, or any other host-specific
+   * metadata that should appear in member-display UIs.
+   */
+  readonly customFields: Readonly<Record<string, unknown>>;
+}
+
+export interface MemberMetadataCacheEntry {
+  readonly id: string;
+  readonly memberId: string;
+  readonly metadata: MemberMetadata;
+  readonly fetchedAt: string;
+  readonly expiresAt: string;
+}

package/src/lib/organization.ts

@@ -0,0 +1,52 @@
+/**
+ * Org-unit type — matches the BPM GraphQL `OrgUnitType` enum SDL names
+ * (UPPERCASE). The server stores the value lower-cased internally
+ * (`'company'` etc. in the database row), but every read and write
+ * across the GraphQL wire and the REST surface uses the UPPERCASE form.
+ *
+ * Consumers of `@rytass/bpm-core-client/organization` must pass these
+ * UPPERCASE literals to `createOrgUnit` / `updateOrgUnit` (and the
+ * `readOrganizationDashboard` `orgUnitType` filter), and will receive
+ * UPPERCASE values back on `OrgUnitRecord.type`.
+ */
+export type OrgUnitType = 'COMPANY' | 'DIVISION' | 'DEPARTMENT' | 'TEAM';
+
+export type ManagerResolutionScopeType = 'MEMBER' | 'ORG_UNIT' | 'POSITION';
+
+export interface OrgUnit {
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly code: string;
+  readonly name: string;
+  readonly type: OrgUnitType;
+  readonly path: string;
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+export interface Position {
+  readonly id: string;
+  readonly code: string;
+  readonly name: string;
+  readonly level: number;
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+export interface Membership {
+  readonly id: string;
+  readonly memberId: string;
+  readonly orgUnitId: string;
+  readonly positionId: string | null;
+  readonly isPrimary: boolean;
+  readonly effectiveFrom: string;
+  readonly effectiveTo: string | null;
+}
+
+export interface ManagerResolution {
+  readonly id: string;
+  readonly scopeType: ManagerResolutionScopeType;
+  readonly scopeId: string;
+  readonly managerMemberId: string;
+  readonly priority: number;
+  readonly effectiveFrom: string;
+  readonly effectiveTo: string | null;
+}

package/src/lib/shared.spec.ts

@@ -0,0 +1,13 @@
+import { WorkflowDefinition } from './workflow';
+
+describe('shared', () => {
+  it('exports workflow definition types', () => {
+    const workflow: WorkflowDefinition = {
+      edges: [],
+      meta: { schemaVersion: 1 },
+      nodes: [],
+    };
+
+    expect(workflow.meta.schemaVersion).toBe(1);
+  });
+});

package/src/lib/status.ts

@@ -0,0 +1,29 @@
+export type VersionStatus = 'DRAFT' | 'PUBLISHED' | 'ARCHIVED';
+
+export type ApprovalInstanceState =
+  | 'DRAFT'
+  | 'RUNNING'
+  | 'APPROVED'
+  | 'REJECTED'
+  | 'RETURNED'
+  | 'CANCELLED'
+  | 'EXPIRED';
+
+export type WorkflowTokenStatus = 'ACTIVE' | 'WAITING' | 'CONSUMED';
+
+export type TaskStatus =
+  | 'PENDING'
+  | 'IN_PROGRESS'
+  | 'COMPLETED'
+  | 'TRANSFERRED'
+  | 'CANCELLED';
+
+export type TaskDecisionAction =
+  | 'APPROVED'
+  | 'REJECTED'
+  | 'RETURNED'
+  | 'TRANSFERRED';
+
+export type DelegationRuleStatus = 'ACTIVE' | 'REVOKED' | 'EXPIRED';
+
+export type DelegationScopeType = 'ALL' | 'TEMPLATE_LIST' | 'CONDITION_BASED';

package/src/lib/workflow-command.spec.ts

@@ -0,0 +1,278 @@
+import {
+  readFallbackWorkflowDefinition,
+  readWorkflowDefinitionIssue,
+} from './workflow-graph';
+import { WorkflowDefinition } from './workflow';
+import {
+  WorkflowCommandOptions,
+  WorkflowDesignerState,
+  applyWorkflowCommand,
+  applyWorkflowMacroCommand,
+} from './workflow-command';
+
+function deterministicEdgeIds(): WorkflowCommandOptions {
+  let counter = 0;
+
+  return {
+    createEdgeId: (source, target): string =>
+      `edge_${source}_${target}_${(counter += 1)}`,
+  };
+}
+
+function initialState(): WorkflowDesignerState {
+  return {
+    definition: readFallbackWorkflowDefinition(),
+    editingEdgeId: null,
+    formDefinitionVersionId: null,
+    formSchema: null,
+    initiatorPolicyCel: null,
+    selectedEdgeIds: [],
+    selectedNodeId: 'start',
+  };
+}
+
+describe('applyWorkflowCommand', () => {
+  it('adds a user task between start and end, flagging layout', () => {
+    const result = applyWorkflowCommand(
+      initialState(),
+      { nodeType: 'userTask', type: 'addNode' },
+      deterministicEdgeIds(),
+    );
+
+    expect(result.changed).toBe(true);
+    expect(result.effects.layout).toBe(true);
+    expect(
+      result.state.definition.nodes.some((node) => node.type === 'userTask'),
+    ).toBe(true);
+    // start -> userTask -> end
+    expect(result.state.definition.edges).toHaveLength(2);
+  });
+
+  it('only node inserts and autoLayout request a relayout', () => {
+    const base = applyWorkflowCommand(
+      initialState(),
+      { nodeType: 'userTask', type: 'addNode' },
+      deterministicEdgeIds(),
+    );
+
+    // addNode positions the new node -> relayout.
+    expect(base.effects.layout).toBe(true);
+
+    // Connecting already-positioned nodes preserves manual layout.
+    expect(
+      applyWorkflowCommand(base.state, {
+        source: 'start',
+        target: 'end',
+        type: 'connectEdge',
+      }).effects.layout,
+    ).toBe(false);
+
+    // autoLayout is the explicit tidy step.
+    expect(
+      applyWorkflowCommand(base.state, { type: 'autoLayout' }).effects.layout,
+    ).toBe(true);
+  });
+
+  it('rejects an invalid connection (end node cannot be a source)', () => {
+    const result = applyWorkflowCommand(initialState(), {
+      source: 'end',
+      target: 'start',
+      type: 'connectEdge',
+    });
+
+    expect(result.changed).toBe(false);
+    expect(result.error).toContain('無法連線');
+  });
+
+  it('refuses to delete the start node', () => {
+    const result = applyWorkflowCommand(initialState(), {
+      nodeId: 'start',
+      type: 'deleteNode',
+    });
+
+    expect(result.changed).toBe(false);
+    expect(result.error).toContain('無法刪除');
+  });
+
+  it('sets a user task approver and resets the decision policy to SINGLE', () => {
+    const withNode = applyWorkflowCommand(
+      initialState(),
+      { nodeType: 'userTask', type: 'addNode' },
+      deterministicEdgeIds(),
+    ).state;
+    const nodeId = withNode.definition.nodes.find(
+      (node) => node.type === 'userTask',
+    )?.id;
+
+    const result = applyWorkflowCommand(withNode, {
+      approverResolver: { positionId: 'pos-1', type: 'POSITION' },
+      nodeId: nodeId ?? '',
+      type: 'setUserTaskApprover',
+    });
+    const updated = result.state.definition.nodes.find(
+      (node) => node.id === nodeId,
+    );
+
+    expect(updated?.type).toBe('userTask');
+
+    if (updated?.type === 'userTask') {
+      expect(updated.data.approverResolver).toEqual({
+        positionId: 'pos-1',
+        type: 'POSITION',
+      });
+      expect(updated.data.decisionPolicy).toEqual({ type: 'SINGLE' });
+    }
+  });
+
+  it('reports a validation issue for an unconfigured DIRECT approver', () => {
+    const withNode = applyWorkflowCommand(
+      initialState(),
+      { nodeType: 'userTask', type: 'addNode' },
+      deterministicEdgeIds(),
+    ).state;
+    const nodeId =
+      withNode.definition.nodes.find((node) => node.type === 'userTask')?.id ??
+      '';
+
+    const result = applyWorkflowCommand(withNode, {
+      approverResolver: { memberIds: [], type: 'DIRECT' },
+      nodeId,
+      type: 'setUserTaskApprover',
+    });
+
+    expect(result.issue).toBe('簽核節點需要指定簽核會員。');
+  });
+
+  it('compiles an edge condition against the bound form schema', () => {
+    // Build: start -> gateway -> end, then condition the gateway output.
+    const base = applyWorkflowCommand(
+      {
+        ...initialState(),
+        formSchema: {
+          fields: [
+            {
+              fieldKey: 'amount',
+              label: '金額',
+              required: true,
+              type: 'money',
+            },
+          ],
+          schemaVersion: 1,
+        },
+      },
+      { nodeType: 'exclusiveGateway', type: 'addNode' },
+      deterministicEdgeIds(),
+    ).state;
+    const gatewayOutEdge = base.definition.edges.find((edge) =>
+      base.definition.nodes.some(
+        (node) =>
+          node.id === edge.source && node.type === 'exclusiveGateway',
+      ),
+    );
+
+    const result = applyWorkflowCommand(base, {
+      edgeId: gatewayOutEdge?.id ?? '',
+      fieldKey: 'amount',
+      operator: 'GREATER_THAN',
+      type: 'setEdgeCondition',
+      value: '1000',
+    });
+    const updatedEdge = result.state.definition.edges.find(
+      (edge) => edge.id === gatewayOutEdge?.id,
+    );
+
+    expect(updatedEdge?.data.condition).toBe('form.amount > 1000');
+    expect(updatedEdge?.data.isDefault).toBe(false);
+  });
+});
+
+describe('applyWorkflowMacroCommand', () => {
+  it('insertApprovalStep adds a user task and sets its approver in one call', () => {
+    const result = applyWorkflowMacroCommand(
+      initialState(),
+      {
+        approverResolver: { memberIds: ['m-1'], type: 'DIRECT' },
+        label: '部門簽核',
+        type: 'insertApprovalStep',
+      },
+      deterministicEdgeIds(),
+    );
+    const userTask = result.state.definition.nodes.find(
+      (node) => node.type === 'userTask',
+    );
+
+    expect(result.changed).toBe(true);
+    expect(userTask?.data.label).toBe('部門簽核');
+
+    if (userTask?.type === 'userTask') {
+      expect(userTask.data.approverResolver).toEqual({
+        memberIds: ['m-1'],
+        type: 'DIRECT',
+      });
+    }
+  });
+});
+
+describe('readWorkflowDefinitionIssue — exclusive gateway default path', () => {
+  function gatewayDefinition(
+    edges: WorkflowDefinition['edges'],
+  ): WorkflowDefinition {
+    return {
+      edges,
+      meta: { schemaVersion: 1 },
+      nodes: [
+        { data: { label: '開始' }, id: 'start', position: { x: 0, y: 0 }, type: 'startEvent' },
+        {
+          data: { direction: 'split', label: '分流', triggerMode: 'AND' },
+          id: 'gw',
+          position: { x: 0, y: 0 },
+          type: 'exclusiveGateway',
+        },
+        {
+          data: { endState: 'APPROVED', label: '完成', triggerMode: 'AND' },
+          id: 'end',
+          position: { x: 0, y: 0 },
+          type: 'endEvent',
+        },
+      ],
+    };
+  }
+
+  it('flags a gateway whose outputs all have conditions but no "其他情況" default', () => {
+    const issue = readWorkflowDefinitionIssue(
+      gatewayDefinition([
+        { data: {}, id: 'e0', source: 'start', target: 'gw' },
+        {
+          data: { condition: 'form.amount > 100000', label: '金額>10萬' },
+          id: 'e1',
+          source: 'gw',
+          target: 'end',
+        },
+      ]),
+    );
+
+    expect(issue).toContain('其他情況');
+  });
+
+  it('passes once one output edge is the default path', () => {
+    const issue = readWorkflowDefinitionIssue(
+      gatewayDefinition([
+        { data: {}, id: 'e0', source: 'start', target: 'gw' },
+        {
+          data: { condition: 'form.amount > 100000', label: '金額>10萬' },
+          id: 'e1',
+          source: 'gw',
+          target: 'end',
+        },
+        {
+          data: { isDefault: true, label: '其他情況' },
+          id: 'e2',
+          source: 'gw',
+          target: 'end',
+        },
+      ]),
+    );
+
+    expect(issue).toBeNull();
+  });
+});