@nocobase/flow-engine 3.0.0-alpha.7 → 3.0.0-alpha.9

package/src/__tests__/flowContext.test.ts

@@ -16,6 +16,7 @@ import { RunJSContextRegistry } from '../runjs-context/registry';
 import { setupRunJSContexts } from '../runjs-context/setup';
 import { createViewScopedEngine } from '../ViewScopedFlowEngine';
 import { DATA_SOURCE_DIRTY_EVENT } from '../views/viewEvents';
+import { serializeCtxDateExpressionConfig } from '../utils/dateVariable';
 
 describe('FlowContext properties and methods', () => {
   it('should return static property value', () => {
@@ -2068,10 +2069,16 @@ describe('getPropertyMetaTree with deep delegate meta', () => {
 describe('FlowContext resolveOnServer selective server resolution', () => {
   it('resolves ctx.date expressions on client context', async () => {
     const engine = new FlowEngine();
+    const formattedToday = serializeCtxDateExpressionConfig({
+      kind: 'preset',
+      preset: 'today',
+      format: 'YYYY/MM/DD',
+    });
     const out = await (engine.context as any).resolveJsonTemplate({
       today: '{{ ctx.date.preset.today }}',
       next12: '{{ ctx.date.relative.next.day.n12 }}',
       now: '{{ ctx.date.preset.now }}',
+      formattedToday,
     });
 
     expect(typeof out.today).toBe('string');
@@ -2080,6 +2087,7 @@ describe('FlowContext resolveOnServer selective server resolution', () => {
     expect(out.next12).toMatch(/^\d{4}-\d{2}-\d{2}$/);
     expect(typeof out.now).toBe('string');
     expect(out.now.length).toBeGreaterThan(0);
+    expect(out.formattedToday).toMatch(/^\d{4}\/\d{2}\/\d{2}$/);
   });
 
   it('does not call server by default (no resolveOnServer set)', async () => {

package/src/__tests__/objectVariable.test.ts

@@ -8,6 +8,7 @@
  */
 
 import { describe, expect, it, vi } from 'vitest';
+import { generateFlowModelRdFromToken } from '@nocobase/utils/client';
 import { FlowContext } from '../flowContext';
 import { FlowEngine } from '../flowEngine';
 import {
@@ -122,7 +123,10 @@ describe('objectVariable utilities', () => {
 
     // Provide API stub to intercept variables:resolve
     const calls: any[] = [];
+    const payload = Buffer.from(JSON.stringify({ userId: 1, signInTime: 'contract-owner-test' })).toString('base64url');
+    const token = `test.${payload}.sig`;
     (ctx as any).api = {
+      auth: { token },
       request: vi.fn(async ({ url, data, method }) => {
         calls.push({ url, data, method });
         const batch = (data?.values?.batch as any[]) || [];
@@ -146,13 +150,14 @@ describe('objectVariable utilities', () => {
     });
 
     const template = { x: '{{ ctx.obj.author.name }}' } as any;
-    await (ctx as any).resolveJsonTemplate(template);
+    await (ctx as any).resolveJsonTemplate(template, { contractModelUid: 'form-grid' });
 
     // Assert variables:resolve was called with proper flattened contextParams
     expect((ctx as any).api.request).toHaveBeenCalled();
     const call = calls.find((c) => c.url === 'variables:resolve');
     expect(call).toBeTruthy();
     const batch0 = call.data?.values?.batch?.[0];
+    expect(batch0?.contractRd).toBe(generateFlowModelRdFromToken('form-grid', token));
     expect(batch0?.contextParams).toBeTruthy();
     // Flattened key should be 'obj.author'
     const cp = batch0.contextParams as Record<string, any>;

package/src/__tests__/runjsFormSubmit.test.ts

@@ -0,0 +1,45 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { FlowContext, FlowRunJSContext } from '../flowContext';
+import { JSItemRunJSContext } from '../runjs-context/contexts/JSItemRunJSContext';
+
+describe('FlowRunJSContext form submission', () => {
+  it('uses the form block RunJS submit capability without changing the native form', () => {
+    const nativeSubmit = vi.fn();
+    const getFieldsValue = vi.fn(() => ({ name: 'Alice' }));
+    const form = { submit: nativeSubmit, getFieldsValue };
+    const submitFromRunJs = vi.fn();
+    const delegate = new FlowContext();
+    delegate.defineProperty('form', { value: form });
+    delegate.defineProperty('blockModel', { value: { submitFromRunJs } });
+
+    const ctx = new JSItemRunJSContext(delegate);
+
+    expect(ctx.form.getFieldsValue()).toEqual({ name: 'Alice' });
+    ctx.form.submit();
+    expect(submitFromRunJs).toHaveBeenCalledOnce();
+    expect(nativeSubmit).not.toHaveBeenCalled();
+    expect(form.submit).toBe(nativeSubmit);
+  });
+
+  it('keeps the native submit method when the block has no RunJS submit capability', () => {
+    const nativeSubmit = vi.fn();
+    const form = { submit: nativeSubmit };
+    const delegate = new FlowContext();
+    delegate.defineProperty('form', { value: form });
+    delegate.defineProperty('blockModel', { value: {} });
+
+    const ctx = new FlowRunJSContext(delegate);
+
+    ctx.form.submit();
+    expect(nativeSubmit).toHaveBeenCalledOnce();
+  });
+});

package/src/components/FlowContextSelector.tsx

@@ -311,6 +311,7 @@ const FlowContextSelectorComponent: React.FC<FlowContextSelectorProps> = ({
       const path = selectedValues.map(String);
       const pathString = path.join('.');
       const isLeaf = lastOption?.isLeaf;
+      const isSelectable = lastOption?.meta?.selectable !== false;
       const now = Date.now();
 
       // 使用自定义格式化函数或默认函数
@@ -325,6 +326,10 @@ const FlowContextSelectorComponent: React.FC<FlowContextSelectorProps> = ({
       }
 
       if (isLeaf) {
+        if (!isSelectable) {
+          setTempSelectedPath(path);
+          return;
+        }
         onChange?.(formattedValue, lastOption?.meta);
         // 选中叶子节点后，可清空内部临时路径（外部 value 将驱动级联）
         setTempSelectedPath([]);
@@ -333,7 +338,8 @@ const FlowContextSelectorComponent: React.FC<FlowContextSelectorProps> = ({
 
       // 非叶子节点：检查双击
       const lastSelected = lastSelectedRef.current;
-      const isDoubleClick = !onlyLeafSelectable && lastSelected?.path === pathString && now - lastSelected.time < 300;
+      const isDoubleClick =
+        isSelectable && !onlyLeafSelectable && lastSelected?.path === pathString && now - lastSelected.time < 300;
 
       if (isDoubleClick) {
         // 双击：选中非叶子节点

package/src/components/variables/__tests__/FlowContextSelector.test.tsx

@@ -864,4 +864,39 @@ describe('FlowContextSelector', () => {
     // It should only expand the node, not select it
     expect(onChange).not.toHaveBeenCalled();
   });
+
+  it('should expand but never select a node marked selectable=false', async () => {
+    const onChange = vi.fn();
+    const flowContext = createTestFlowContext();
+    const metaTree = [
+      {
+        name: 'date',
+        title: 'Date',
+        type: 'date',
+        paths: ['date'],
+        selectable: false,
+        children: [{ name: 'today', title: 'Today', type: 'date', paths: ['date', 'today'] }],
+      },
+    ];
+
+    render(
+      <TestFlowContextWrapper context={flowContext}>
+        <FlowContextSelector metaTree={metaTree} onChange={onChange} />
+      </TestFlowContextWrapper>,
+    );
+
+    fireEvent.click(screen.getByRole('button'));
+    await waitFor(() => expect(screen.getByText('Date')).toBeInTheDocument());
+
+    fireEvent.click(screen.getByText('Date'));
+    fireEvent.click(screen.getByText('Date'));
+    expect(onChange).not.toHaveBeenCalled();
+
+    await waitFor(() => expect(screen.getByText('Today')).toBeInTheDocument());
+    fireEvent.click(screen.getByText('Today'));
+    expect(onChange).toHaveBeenCalledWith(
+      '{{ ctx.date.today }}',
+      expect.objectContaining({ paths: ['date', 'today'] }),
+    );
+  });
 });

package/src/flowContext.ts

@@ -165,6 +165,10 @@ function inferSelectsFromUsage(paths: string[] = []): { generatedAppends?: strin
 
 type Getter<T = any> = (ctx: FlowContext) => T | Promise<T>;
 
+export type ResolveJsonTemplateOptions = {
+  contractModelUid?: string | number | null;
+};
+
 export type FlowContextDocRef = string | { url: string; title?: string };
 
 export type FlowDeprecationDoc =
@@ -221,6 +225,8 @@ export interface MetaTreeNode {
   // 变量禁用状态与原因（用于变量选择器 UI 展示）
   disabled?: boolean | (() => boolean);
   disabledReason?: string | (() => string | undefined);
+  // 允许节点仅用于展开子级，而不能作为变量值被选中
+  selectable?: boolean;
   children?: MetaTreeNode[] | (() => Promise<MetaTreeNode[]>);
 }
 
@@ -3044,7 +3050,7 @@ class BaseFlowEngineContext extends FlowContext {
    * @deprecated use `resolveJsonTemplate` instead
    */
   declare renderJson: (template: JSONValue) => Promise<any>;
-  declare resolveJsonTemplate: (template: JSONValue) => Promise<any>;
+  declare resolveJsonTemplate: (template: JSONValue, options?: ResolveJsonTemplateOptions) => Promise<any>;
   declare getVar: (path: string) => Promise<any>;
   declare request: (options: RequestOptions) => Promise<any>;
   declare runjs: (code: string, variables?: Record<string, any>, options?: JSRunnerOptions) => Promise<any>;
@@ -3227,7 +3233,11 @@ export class FlowEngineContext extends BaseFlowEngineContext {
     this.defineMethod('renderJson', function (template: any) {
       return this.resolveJsonTemplate(template);
     });
-    this.defineMethod('resolveJsonTemplate', async function (this: BaseFlowEngineContext, template: any) {
+    const resolveJsonTemplate = async function (
+      this: BaseFlowEngineContext,
+      template: any,
+      options?: ResolveJsonTemplateOptions,
+    ) {
       // 提取模板使用到的变量及其子路径
       const used = extractUsedVariablePaths(template);
       const usedVarNames = Object.keys(used || {});
@@ -3396,7 +3406,12 @@ export class FlowEngineContext extends BaseFlowEngineContext {
 
         if (this.api) {
           try {
+            const contractRd = buildFlowModelResolveDescriptor(
+              this as FlowRuntimeContext<FlowModel>,
+              options?.contractModelUid,
+            );
             serverResolved = await enqueueVariablesResolve(this as FlowRuntimeContext<FlowModel>, {
+              ...(contractRd ? { contractRd } : {}),
               rd: buildFlowModelResolveDescriptor(this as FlowRuntimeContext<FlowModel>, this.model?.uid),
               template,
               contextParams: autoContextParams || {},
@@ -3409,7 +3424,8 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       }
 
       return resolveExpressions(serverResolved, this);
-    });
+    };
+    this.defineMethod('resolveJsonTemplate', resolveJsonTemplate);
 
     // Helper: resolve a single ctx expression value via resolveJsonTemplate behavior.
     // Example: await ctx.getVar('ctx.record.id')
@@ -4595,6 +4611,10 @@ export class FlowRunJSContext extends FlowContext {
   constructor(delegate: FlowContext) {
     super();
     this.addDelegate(delegate);
+    const submit = delegate.blockModel?.submitFromRunJs?.bind(delegate.blockModel);
+    if (delegate.form && submit) {
+      this.defineProperty('form', { value: { ...delegate.form, submit } });
+    }
     this.defineProperty('React', { value: React });
     this.defineProperty('antd', { value: antd });
     this.defineProperty('dayjs', {

package/src/utils/__tests__/dateVariable.test.ts

@@ -12,9 +12,12 @@ import {
   decodeBase64Url,
   encodeBase64Url,
   isCompleteCtxDatePath,
+  isCtxDatePathPrefix,
   isCtxDateExpression,
   parseCtxDateExpression,
+  parseCtxDateExpressionConfig,
   resolveCtxDatePath,
+  serializeCtxDateExpressionConfig,
   serializeCtxDateValue,
 } from '../dateVariable';
 
@@ -54,13 +57,60 @@ describe('dateVariable utils', () => {
       number: 2,
     });
 
-    const singleExpr = serializeCtxDateValue('2026-02-12')!;
+    const singleExpr = serializeCtxDateValue('2026-02-12');
+    if (!singleExpr) throw new Error('Expected exact date expression');
     expect(parseCtxDateExpression(singleExpr)).toBe('2026-02-12');
 
-    const rangeExpr = serializeCtxDateValue(['2026-02-12', '2026-02-20'])!;
+    const rangeExpr = serializeCtxDateValue(['2026-02-12', '2026-02-20']);
+    if (!rangeExpr) throw new Error('Expected exact date range expression');
     expect(parseCtxDateExpression(rangeExpr)).toEqual(['2026-02-12', '2026-02-20']);
   });
 
+  it('serializes, parses and resolves formatted expressions', () => {
+    const expression = serializeCtxDateExpressionConfig({
+      kind: 'preset',
+      preset: 'today',
+      format: 'YYYY/MM/DD',
+    });
+    if (!expression) throw new Error('Expected formatted date expression');
+
+    expect(expression).toMatch(/^\{\{ ctx\.date\.format\.v[A-Za-z0-9_-]+\.preset\.today \}\}$/);
+    expect(parseCtxDateExpressionConfig(expression)).toEqual({
+      kind: 'preset',
+      preset: 'today',
+      format: 'YYYY/MM/DD',
+    });
+    // Keep the legacy parser contract for filter-form consumers.
+    expect(parseCtxDateExpression(expression)).toEqual({ type: 'today' });
+
+    const path = expression.replace('{{ ctx.', '').replace(' }}', '').split('.');
+    expect(resolveCtxDatePath(path)).toMatch(/^\d{4}\/\d{2}\/\d{2}$/);
+    expect(isCompleteCtxDatePath(path)).toBe(true);
+  });
+
+  it('preserves significant whitespace in a custom Format', () => {
+    const expression = serializeCtxDateExpressionConfig({
+      kind: 'preset',
+      preset: 'today',
+      format: 'YYYY-MM-DD ',
+    });
+    if (!expression) throw new Error('Expected formatted date expression');
+
+    expect(parseCtxDateExpressionConfig(expression)?.format).toBe('YYYY-MM-DD ');
+  });
+
+  it('formats exact ranges element by element', () => {
+    const expression = serializeCtxDateExpressionConfig({
+      kind: 'exact',
+      value: ['2026-02-12', '2026-02-20'],
+      format: 'YYYYMMDD',
+    });
+    if (!expression) throw new Error('Expected formatted date range expression');
+    const path = expression.replace('{{ ctx.', '').replace(' }}', '').split('.');
+
+    expect(resolveCtxDatePath(path)).toEqual(['20260212', '20260220']);
+  });
+
   it('resolves preset/relative/exact path', () => {
     expect(typeof resolveCtxDatePath(['date', 'preset', 'now'])).toBe('string');
 
@@ -72,11 +122,13 @@ describe('dateVariable utils', () => {
     expect(typeof rel).toBe('string');
     expect(rel).toMatch(/^\d{4}-\d{2}-\d{2}$/);
 
-    const singleExpr = serializeCtxDateValue('2026-02-12')!;
+    const singleExpr = serializeCtxDateValue('2026-02-12');
+    if (!singleExpr) throw new Error('Expected exact date expression');
     const token = singleExpr.replace('{{ ctx.date.exact.single.date.', '').replace(' }}', '');
     expect(resolveCtxDatePath(['date', 'exact', 'single', 'date', token])).toBe('2026-02-12');
 
-    const rangeExpr = serializeCtxDateValue(['2026-02-12', '2026-02-20'])!;
+    const rangeExpr = serializeCtxDateValue(['2026-02-12', '2026-02-20']);
+    if (!rangeExpr) throw new Error('Expected exact date range expression');
     const parts = rangeExpr.replace('{{ ctx.date.exact.range.date.', '').replace(' }}', '').split('.');
     expect(resolveCtxDatePath(['date', 'exact', 'range', 'date', parts[0], parts[1]])).toEqual([
       '2026-02-12',
@@ -90,6 +142,7 @@ describe('dateVariable utils', () => {
     expect(isCompleteCtxDatePath(['date', 'exact', 'single', 'date', 'vabc'])).toBe(true);
     expect(isCompleteCtxDatePath(['date', 'exact', 'range', 'date', 'vabc', 'vdef'])).toBe(true);
     expect(isCompleteCtxDatePath(['date', 'relative', 'next', 'day'])).toBe(false);
+    expect(isCtxDatePathPrefix(['date', 'format'])).toBe(true);
     expect(isCompleteCtxDatePath(['user', 'name'])).toBe(false);
   });
 

package/src/utils/dateVariable.ts

@@ -11,7 +11,7 @@ import dayjs from 'dayjs';
 
 const CTX_DATE_REGEX = /^\{\{\s*ctx\.date(?:\.(.+?))?\s*\}\}$/;
 
-const PRESET_KEYS = new Set([
+const PRESET_KEY_LIST = [
   'today',
   'now',
   'yesterday',
@@ -28,10 +28,28 @@ const PRESET_KEYS = new Set([
   'thisYear',
   'lastYear',
   'nextYear',
-]);
+] as const;
+
+export type CtxDatePreset = (typeof PRESET_KEY_LIST)[number];
+export type CtxDateRelativeDirection = 'next' | 'past';
+export type CtxDateRelativeUnit = 'day' | 'week' | 'month' | 'year';
+
+export type CtxDateExpressionConfig =
+  | { kind: 'exact'; value: string | [string, string]; format?: string }
+  | {
+      kind: 'relative';
+      direction: CtxDateRelativeDirection;
+      amount: number;
+      unit: CtxDateRelativeUnit;
+      format?: string;
+    }
+  | { kind: 'preset'; preset: CtxDatePreset; format?: string };
+
+const PRESET_KEYS = new Set<string>(PRESET_KEY_LIST);
 
 const RELATIVE_DIRECTIONS = new Set(['next', 'past']);
 const RELATIVE_UNITS = new Set(['day', 'week', 'month', 'year']);
+const MAX_DATE_FORMAT_LENGTH = 128;
 
 function parseCtxDateSegments(value: string): string[] | null {
   if (typeof value !== 'string') return null;
@@ -46,8 +64,7 @@ function parseCtxDateSegments(value: string): string[] | null {
     .filter(Boolean);
 }
 
-export function isCtxDatePathPrefix(pathSegments: string[]): boolean {
-  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+function isBaseCtxDatePathPrefix(segments: string[]): boolean {
   if (segments[0] !== 'date') return false;
   if (segments.length === 1) return true;
 
@@ -96,6 +113,36 @@ export function isCtxDatePathPrefix(pathSegments: string[]): boolean {
   return false;
 }
 
+function decodeFormatToken(token: string): string | undefined {
+  const raw = String(token || '');
+  if (!raw.startsWith('v')) return undefined;
+  const decoded = decodeBase64Url(raw.slice(1));
+  if (!decoded || decoded.length > MAX_DATE_FORMAT_LENGTH) return undefined;
+  return decoded;
+}
+
+function splitFormattedDateSegments(segments: string[]): { baseSegments: string[]; format?: string } | null {
+  if (segments[0] !== 'date') return null;
+  if (segments[1] !== 'format') return { baseSegments: segments };
+  if (segments.length < 4) return null;
+
+  const format = decodeFormatToken(segments[2]);
+  if (!format) return null;
+  return { baseSegments: ['date', ...segments.slice(3)], format };
+}
+
+export function isCtxDatePathPrefix(pathSegments: string[]): boolean {
+  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  if (segments[0] !== 'date') return false;
+  if (segments.length === 1) return true;
+  if (segments[1] !== 'format') return isBaseCtxDatePathPrefix(segments);
+  if (segments.length === 2) return true;
+  if (segments.length === 3) return typeof decodeFormatToken(segments[2]) === 'string';
+
+  const formatted = splitFormattedDateSegments(segments);
+  return formatted ? isBaseCtxDatePathPrefix(formatted.baseSegments) : false;
+}
+
 function withDatePrefix(pathSegments: string[]): string[] {
   if (pathSegments[0] === 'date') {
     return pathSegments;
@@ -210,27 +257,29 @@ export function isCtxDateExpression(value: unknown): value is string {
 export function isCompleteCtxDatePath(pathSegments: string[]): boolean {
   if (!isCtxDatePathPrefix(pathSegments)) return false;
   const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
-  if (segments[0] !== 'date') return false;
+  const formatted = splitFormattedDateSegments(segments);
+  if (!formatted) return false;
+  const baseSegments = formatted.baseSegments;
 
-  if (segments[1] === 'preset') {
-    return segments.length === 3 && PRESET_KEYS.has(segments[2]);
+  if (baseSegments[1] === 'preset') {
+    return baseSegments.length === 3 && PRESET_KEYS.has(baseSegments[2]);
   }
 
-  if (segments[1] === 'relative') {
-    if (segments.length !== 5) return false;
+  if (baseSegments[1] === 'relative') {
+    if (baseSegments.length !== 5) return false;
     return (
-      RELATIVE_DIRECTIONS.has(segments[2]) &&
-      RELATIVE_UNITS.has(segments[3]) &&
-      typeof parseNumberToken(segments[4]) === 'number'
+      RELATIVE_DIRECTIONS.has(baseSegments[2]) &&
+      RELATIVE_UNITS.has(baseSegments[3]) &&
+      typeof parseNumberToken(baseSegments[4]) === 'number'
     );
   }
 
-  if (segments[1] === 'exact' && segments[2] === 'single' && segments[3] === 'date') {
-    return segments.length === 5 && /^v.+/.test(segments[4]);
+  if (baseSegments[1] === 'exact' && baseSegments[2] === 'single' && baseSegments[3] === 'date') {
+    return baseSegments.length === 5 && /^v.+/.test(baseSegments[4]);
   }
 
-  if (segments[1] === 'exact' && segments[2] === 'range' && segments[3] === 'date') {
-    return segments.length === 6 && /^v.+/.test(segments[4]) && /^v.+/.test(segments[5]);
+  if (baseSegments[1] === 'exact' && baseSegments[2] === 'range' && baseSegments[3] === 'date') {
+    return baseSegments.length === 6 && /^v.+/.test(baseSegments[4]) && /^v.+/.test(baseSegments[5]);
   }
 
   return false;
@@ -238,7 +287,10 @@ export function isCompleteCtxDatePath(pathSegments: string[]): boolean {
 
 export function parseCtxDateExpression(value: unknown): any {
   if (!isCtxDateExpression(value)) return undefined;
-  const segments = withDatePrefix(parseCtxDateSegments(value as string) || []);
+  const rawSegments = withDatePrefix(parseCtxDateSegments(value as string) || []);
+  const formatted = splitFormattedDateSegments(rawSegments);
+  if (!formatted) return undefined;
+  const segments = formatted.baseSegments;
 
   if (segments[1] === 'preset' && segments.length === 3 && PRESET_KEYS.has(segments[2])) {
     return { type: segments[2] };
@@ -276,6 +328,66 @@ export function parseCtxDateExpression(value: unknown): any {
   return undefined;
 }
 
+export function parseCtxDateExpressionConfig(value: unknown): CtxDateExpressionConfig | undefined {
+  if (!isCtxDateExpression(value)) return undefined;
+  const segments = withDatePrefix(parseCtxDateSegments(value) || []);
+  const formatted = splitFormattedDateSegments(segments);
+  if (!formatted) return undefined;
+
+  const parsed = parseCtxDateExpression(value);
+  const formatConfig = formatted.format ? { format: formatted.format } : {};
+  if (typeof parsed === 'string') {
+    return { kind: 'exact', value: parsed, ...formatConfig };
+  }
+  if (Array.isArray(parsed) && parsed.length === 2 && typeof parsed[0] === 'string' && typeof parsed[1] === 'string') {
+    return { kind: 'exact', value: [parsed[0], parsed[1]], ...formatConfig };
+  }
+
+  if (!parsed || typeof parsed !== 'object') return undefined;
+  const typed = parsed as { type?: unknown; unit?: unknown; number?: unknown };
+  if (typed.type === 'past' || typed.type === 'next') {
+    if (typeof typed.unit !== 'string' || !RELATIVE_UNITS.has(typed.unit) || typeof typed.number !== 'number') {
+      return undefined;
+    }
+    return {
+      kind: 'relative',
+      direction: typed.type,
+      amount: typed.number,
+      unit: typed.unit as CtxDateRelativeUnit,
+      ...formatConfig,
+    };
+  }
+
+  if (typeof typed.type === 'string' && PRESET_KEYS.has(typed.type)) {
+    return { kind: 'preset', preset: typed.type as CtxDatePreset, ...formatConfig };
+  }
+  return undefined;
+}
+
+export function serializeCtxDateExpressionConfig(config: CtxDateExpressionConfig): string | undefined {
+  let legacyValue: unknown;
+
+  if (config.kind === 'preset') {
+    if (!PRESET_KEYS.has(config.preset)) return undefined;
+    legacyValue = { type: config.preset };
+  } else if (config.kind === 'relative') {
+    if (!RELATIVE_DIRECTIONS.has(config.direction) || !RELATIVE_UNITS.has(config.unit)) return undefined;
+    const amount = Math.floor(Number(config.amount));
+    if (!Number.isFinite(amount) || amount <= 0) return undefined;
+    legacyValue = { type: config.direction, unit: config.unit, number: amount };
+  } else {
+    legacyValue = config.value;
+  }
+
+  const expression = serializeCtxDateValue(legacyValue);
+  if (!expression || !config.format) return expression;
+
+  const format = String(config.format);
+  if (!format.trim() || format.length > MAX_DATE_FORMAT_LENGTH) return undefined;
+  const segments = withDatePrefix(parseCtxDateSegments(expression) || []);
+  return toCtxDateExpression(['date', 'format', `v${encodeBase64Url(format)}`, ...segments.slice(1)]);
+}
+
 export function serializeCtxDateValue(value: unknown): string | undefined {
   if (isCtxDateExpression(value)) {
     return String(value).trim();
@@ -327,8 +439,23 @@ export function serializeCtxDateValue(value: unknown): string | undefined {
   return undefined;
 }
 
+function formatResolvedDateValue(value: unknown, format: string): unknown {
+  const formatValue = (item: unknown) => {
+    if (typeof item !== 'string') return item;
+    const parsed = dayjs(item);
+    return parsed.isValid() ? parsed.format(format) : item;
+  };
+  return Array.isArray(value) ? value.map(formatValue) : formatValue(value);
+}
+
 export function resolveCtxDatePath(pathSegments: string[]): any {
-  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  const rawSegments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  const formatted = splitFormattedDateSegments(rawSegments);
+  if (!formatted) return undefined;
+  if (formatted.format) {
+    return formatResolvedDateValue(resolveCtxDatePath(formatted.baseSegments), formatted.format);
+  }
+  const segments = formatted.baseSegments;
   if (segments[0] !== 'date') return undefined;
 
   if (segments[1] === 'preset' && segments.length === 3) {

package/src/utils/index.ts

@@ -92,8 +92,14 @@ export {
   isCtxDatePathPrefix,
   isCtxDateExpression,
   parseCtxDateExpression,
+  parseCtxDateExpressionConfig,
   resolveCtxDatePath,
+  serializeCtxDateExpressionConfig,
   serializeCtxDateValue,
+  type CtxDateExpressionConfig,
+  type CtxDatePreset,
+  type CtxDateRelativeDirection,
+  type CtxDateRelativeUnit,
 } from './dateVariable';
 
 // RunJS value helpers

package/src/utils/params-resolvers.ts

@@ -79,6 +79,7 @@ export type JSONValue = string | { [key: string]: JSONValue } | JSONValue[];
 // =========================
 
 type BatchPayload = {
+  contractRd?: string;
   rd?: string;
   template: JSONValue;
   contextParams?: ServerContextParams | undefined;
@@ -172,6 +173,7 @@ export function enqueueVariablesResolve(ctx: FlowRuntimeContext, payload: BatchP
     try {
       const batch = items.map((it) => ({
         id: it.id,
+        contractRd: it.payload.contractRd,
         rd: it.payload.rd,
         template: it.payload.template,
         contextParams: it.payload.contextParams || {},