cabloy 5.1.119 → 5.1.121

package/.cabloy-version

@@ -1 +1 @@
-5.1.119
+5.1.121

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 5.1.121
+
+### Features
+
+- Support embedded layout blocks in forms.
+
+### Improvements
+
+- Update the student selection result item component.
+- Add commerce test coverage for shipment refund race conditions.
+
+## 5.1.120
+
+### Features
+
+- Update functionality.
+
 ## 5.1.119
 
 ### Improvements

package/cabloy-docs/.vitepress/config.mjs

@@ -243,6 +243,7 @@ export default defineConfig({
             { text: 'Error Guide', link: '/backend/error-guide' },
             { text: 'Event Guide', link: '/backend/event-guide' },
             { text: 'Logger Guide', link: '/backend/logger-guide' },
+            { text: 'Metrics Guide', link: '/backend/metrics-guide' },
             { text: 'Telemetry Guide', link: '/backend/telemetry-guide' },
             { text: 'Upload Guide', link: '/backend/upload-guide' },
             { text: 'Image Guide', link: '/backend/image-guide' },

package/cabloy-docs/frontend/form-layout-guide.md

@@ -13,8 +13,8 @@ Several APIs contain the word “layout,” but they own different concerns:
 
 | Surface                                        | Owns                                                                                                           | Does not own                                              |
 | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| `formLayout`                                   | Field placement, Grid/flow sections, groups, responsive spans, and tabs                                        | Field renderer selection, validation rules, submit policy |
-| `basic-form:blockFormLayout`                   | Resolving and rendering a structural `formLayout` tree in Cabloy Basic                                         | Page-entry or filter actions                              |
+| `formLayout`                                   | Field and renderable-block placement, Grid/flow sections, groups, responsive spans, and tabs                   | Field renderer selection, validation rules, submit policy |
+| `basic-form:blockFormLayout`                   | Resolving and rendering a structural `formLayout` tree in Cabloy Basic, including embedded renderable blocks   | Page-entry or filter action semantics                     |
 | `layout`, `formFieldLayout`, `FormFieldLayout` | One field's label and wrapper presentation: inline/block mode, icons, borders, header/footer, class, and style | Sections, Grid/flow placement, groups, or tabs            |
 
 For example, `formFieldLayout: { inline: false }` makes each field use a block-style wrapper. It does not create a grid. Pair it with `basic-form:blockFormLayout` when the fields also need structural placement.
@@ -63,7 +63,7 @@ Form Layout changes neither readonly behavior nor actions. Create, update, and v
 
 ### Filter form composition
 
-A filter uses the filter block as its host and keeps filter actions as an explicit sibling block:
+A filter uses the filter block as its host. Place Search/Reset inside the structural layout when they should participate in the same Grid or flow as filter fields:
 
 ```tsx
 ZovaRender.block('basic-page:blockFilter', {
@@ -72,16 +72,36 @@ ZovaRender.block('basic-page:blockFilter', {
     ZovaRender.block('basic-form:blockFormLayout', {
       formLayout: {
         children: [
-          /* structural nodes */
+          {
+            type: 'section',
+            layout: 'flow',
+            children: [
+              /* filter fields */
+              {
+                type: 'block',
+                block: ZovaRender.block('basic-page:blockFilterActions'),
+              },
+            ],
+          },
         ],
       },
     }),
-    ZovaRender.block('basic-page:blockFilterActions'),
   ],
 });
 ```
 
-A nonempty `blocks` list replaces `ZForm`'s automatic body and footer. Therefore a structured filter must explicitly include `basic-page:blockFilterActions`; it owns Search and Reset and keeps the filter's existing normalization and page-query handoff. See [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook#use-blocks-for-a-structural-filter-layout) for the filter ownership model.
+The renderable block node controls only structural placement. `basic-page:blockFilterActions` still owns Search/Reset and obtains the filter command surface from the inherited form scope, preserving normalization and page-query handoff. A nonempty `blocks` list replaces `ZForm`'s automatic body and footer.
+
+The legacy sibling composition remains supported when actions do not need to share a structural section:
+
+```tsx
+blocks: [
+  ZovaRender.block('basic-form:blockFormLayout', { formLayout }),
+  ZovaRender.block('basic-page:blockFilterActions'),
+];
+```
+
+Use either the embedded layout block or the legacy sibling action block, never both; otherwise Search and Reset are rendered twice. See [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook#use-blocks-for-a-structural-filter-layout) for the filter ownership model.
 
 ## Layout node grammar
 
@@ -90,28 +110,35 @@ A nonempty `blocks` list replaces `ZForm`'s automatic body and footer. Therefore
 ```text
 formLayout
 ├─ field
+├─ block
 ├─ section
-│  └─ field
+│  ├─ field
+│  └─ block
 ├─ group
 │  ├─ field
+│  ├─ block
 │  ├─ group
 │  └─ section
 └─ tabs
    └─ tab
       ├─ field
+      ├─ block
       ├─ group
       └─ section
 ```
 
-| Node      | Key properties                                             | Allowed children         | Use it for                                |
-| --------- | ---------------------------------------------------------- | ------------------------ | ----------------------------------------- |
-| `field`   | required `name`; optional `span`                           | none                     | Place one resolved schema field           |
-| `section` | optional `id`, `title`, `description`, `layout`, `columns` | fields only              | A Grid or wrapping flow field layout      |
-| `group`   | optional `id`, `title`, `description`                      | fields, groups, sections | A semantic, bordered fieldset-style group |
-| `tabs`    | optional `id`                                              | tabs only                | One tab container                         |
-| `tab`     | optional `id`; required `title`                            | fields, groups, sections | One tab panel                             |
+| Node      | Key properties                                             | Allowed children                 | Use it for                                  |
+| --------- | ---------------------------------------------------------- | -------------------------------- | ------------------------------------------- |
+| `field`   | required `name`; optional `span`                           | none                             | Place one resolved schema field             |
+| `block`   | required `block`; optional `span`                          | none                             | Place an existing renderable resource block |
+| `section` | optional `id`, `title`, `description`, `layout`, `columns` | fields and blocks                | A Grid or wrapping flow layout              |
+| `group`   | optional `id`, `title`, `description`                      | fields, blocks, groups, sections | A semantic, bordered fieldset-style group   |
+| `tabs`    | optional `id`                                              | tabs only                        | One tab container                           |
+| `tab`     | optional `id`; required `title`                            | fields, blocks, groups, sections | One tab panel                               |
+
+A section is a layout boundary. It uses the Grid strategy by default; set `layout: 'flow'` for compact, left-packed fields and blocks that wrap at their intrinsic widths. Use a group when the fields need a semantic or visual boundary, and place a section inside that group when it also needs Grid columns or flow placement. There is no separate `row` node: Grid and flow placement create rows automatically.
 
-A section is a layout boundary. It uses the Grid strategy by default; set `layout: 'flow'` for compact, left-packed fields that wrap at their intrinsic widths. Use a group when the fields need a semantic or visual boundary, and place a section inside that group when it also needs Grid columns or flow placement. There is no separate `row` node: Grid and flow placement create rows automatically.
+A `block` node is not a schema field and does not add a request, response, validation, or query value. It wraps an existing `ZovaRender.block(...)` descriptor and renders it with the current form JSX/CEL context. This lets a filter action block participate in a flow section without transferring filter-action behavior into Form Layout.
 
 Nested tabs are not part of the current contract. Likewise, a section cannot contain a group or another section.
 
@@ -286,24 +313,27 @@ ZovaRender.block('basic-page:blockFilter', {
               { type: 'field', name: 'name' },
               { type: 'field', name: 'level' },
               { type: 'field', name: 'createdAt' },
+              {
+                type: 'block',
+                block: ZovaRender.block('basic-page:blockFilterActions'),
+              },
             ],
           },
         ],
       },
     }),
-    ZovaRender.block('basic-page:blockFilterActions'),
   ],
 });
 ```
 
-Here `formFieldLayout.inline: true` controls how each field wrapper is presented. The flow section keeps those compact wrappers left-packed and wraps them when necessary. `basic-page:blockFilterActions` remains required because the custom blocks replace automatic filter body/footer content.
+Here `formFieldLayout.inline: true` controls how each field wrapper is presented. The flow section keeps fields and the action block left-packed and wraps them together when necessary. `basic-page:blockFilterActions` remains required because the custom blocks replace automatic filter body/footer content, but it is now placed through the structural layout rather than as a sibling block.
 
 ## Authoring checklist
 
 1. Start with DTO or resource metadata; do not hand-patch generated `.zova-rest` artifacts.
 2. Use `formLayout` when the requirement is field placement, Grid or flow structure, groups, or tabs.
 3. Use `layout`, `formFieldLayout`, `options`, or provider behaviors when the requirement is one field's wrapper or renderer.
-4. Keep entry actions in page-entry toolbar blocks and filter actions in `basic-page:blockFilterActions`.
+4. Keep entry actions in page-entry toolbar blocks. Keep filter action semantics in `basic-page:blockFilterActions`; place that block inside Form Layout only when actions must share structural Grid or flow placement with fields.
 5. Review field names against the scene-specific schema. Unlisted visible fields are appended; unknown and duplicate declarations are silently pruned from the rendered plan.
 6. Use the smallest layout that communicates the form structure; reserve tabs for genuinely separate field groups.
 

package/cabloy-docs/frontend/table-resource-crud-cookbook.md

@@ -180,7 +180,7 @@ A practical rule is:
 
 ### Use blocks for a structural filter layout
 
-A bare `basic-page:blockFilter` keeps the default schema field rendering and adds Search/Reset controls automatically. For a structured filter, compose the existing form layout block with the filter-specific action block:
+A bare `basic-page:blockFilter` keeps the default schema field rendering and adds Search/Reset controls automatically. For a structured filter whose actions should share the flow with filter fields, embed the existing action block in Form Layout:
 
 ```tsx
 ZovaRender.block('basic-page:blockFilter', {
@@ -196,17 +196,20 @@ ZovaRender.block('basic-page:blockFilter', {
               { type: 'field', name: 'name' },
               { type: 'field', name: 'level' },
               { type: 'field', name: 'createdAt' },
+              {
+                type: 'block',
+                block: ZovaRender.block('basic-page:blockFilterActions'),
+              },
             ],
           },
         ],
       },
     }),
-    ZovaRender.block('basic-page:blockFilterActions'),
   ],
 });
 ```
 
-`basic-form:blockFormLayout` only places schema fields. `basic-page:blockFilterActions` owns Search/Reset placement and invokes the filter command surface supplied through the form scope, so it preserves filter normalization and page-query behavior. A nonempty `blocks` list replaces the automatic body and footer; include the action block explicitly to make the filter operable.
+`basic-form:blockFormLayout` owns structural placement only. `basic-page:blockFilterActions` still owns Search/Reset behavior and invokes the filter command surface supplied through the inherited form scope, preserving filter normalization and page-query behavior. A nonempty `blocks` list replaces the automatic body and footer; include the action block explicitly to make the filter operable. The older sibling action-block composition remains supported, but do not combine it with an embedded action block.
 
 `ZForm.inline` is no longer a form API. Use `formFieldLayout.inline` for field-level compact layout, or use blocks plus `basic-form:blockFormLayout` for structural layout. The flow section above keeps compact filters left-packed and wrapping; use the default Grid section when fields need responsive columns and spans. Read [Form Layout Guide](/frontend/form-layout-guide) for the full node grammar, section layout rules, resolver behavior, tabs, and entry-form composition.
 

package/cabloy-docs/frontend/zova-form-source-reading-map.md

@@ -223,7 +223,7 @@ Use this path when you are asking questions like:
 Use this path when you are asking questions like:
 
 - where does `formLayout` come from in a resource DTO?
-- how are fields, sections, groups, and tabs normalized before rendering?
+- how are fields, embedded blocks, sections, groups, and tabs normalized before rendering?
 - why are omitted visible fields appended or duplicate fields removed?
 - where does Cabloy Basic render responsive grids and tab error badges?
 
@@ -240,15 +240,17 @@ Use this path when you are asking questions like:
 3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/resource/formLayout.ts`
 4. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/formLayout.ts`
 5. `zova/src/suite/cabloy-basic/modules/basic-form/src/component/blockFormLayout/controller.tsx`
-6. `vona/src/suite/a-training/modules/training-student/test/student.test.ts`
+6. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockFilterActions/controller.tsx`
+7. `vona/src/suite/a-training/modules/training-student/test/student.test.ts`
 
 ### What each file clarifies
 
 - the Student DTOs show the entry and filter block composition that supplies layout metadata
 - the OpenAPI type contract defines the legal node grammar and responsive values
-- the resolver reconciles metadata with visible schema fields, generated IDs, and diagnostics
-- the Basic block controller renders sections, groups, tabs, and field spans while delegating widgets to `$$form.renderField(...)`
-- the Student test verifies emitted metadata nesting, columns, spans, and optional IDs; it is not a browser rendering test
+- the resolver reconciles field metadata with visible schema fields, generated IDs, diagnostics, and preserved embedded blocks
+- the Basic block controller renders sections, groups, tabs, field spans, and embedded blocks while delegating fields to `$$form.renderField(...)`
+- `blockFilterActions` shows how a block rendered inside Form Layout reuses the inherited form CEL scope to invoke `$$filter`
+- the Student test verifies emitted metadata nesting, columns, spans, embedded action blocks, and optional IDs; it is not a browser rendering test
 
 ## 8. Resource-driven CRUD page integration
 

package/cabloy-docs/frontend/zova-form-under-the-hood.md

@@ -414,11 +414,14 @@ That means automatic schema-driven rendering is not happening magically in the w
 
 When `ZForm` receives a nonempty block list, the render bean delegates body rendering to those blocks instead of iterating schema fields directly. For Cabloy Basic structural forms, `basic-form:blockFormLayout` resolves `formLayout` against the form's current schema properties and calls `$$form.renderField(...)` for each surviving layout field.
 
+Form Layout also supports a leaf `block` node. It wraps an existing resource block descriptor and the Basic renderer invokes it with the inherited `IJsxRenderContextForm`, including the same JSX runtime and CEL scope. The node has no schema property or field value; for example, a filter can place `basic-page:blockFilterActions` inside a flow section while that action block continues to read `$$filter` from the filter-owned form scope.
+
 This keeps ownership separate:
 
 - the form controller owns schema properties, field state, validation, and field rendering
-- the shared form-layout resolver normalizes field placement metadata
-- the Basic layout block renders sections, groups, grids, and tabs
+- the shared form-layout resolver normalizes field placement metadata while preserving non-field block nodes
+- the Basic layout block renders sections, groups, grids, tabs, and embedded blocks
+- embedded blocks own their behavior; Form Layout owns only their placement
 - field-layout behaviors still own each field wrapper and its visible validation message
 
 Read [Form Layout Guide](/frontend/form-layout-guide) for the DTO authoring grammar, resolver behavior, and Basic-specific responsive/tab behavior.

package/e2e/specs/cabloy-basic/basic.spec.ts

@@ -209,6 +209,8 @@ test(
     await expect(name).toBeVisible();
     await expect(level).toBeVisible();
     await expect(dates).toHaveCount(2);
+    await expect(search).toHaveCount(1);
+    await expect(reset).toHaveCount(1);
     await expect(search).toBeVisible();
     await expect(reset).toBeVisible();
 
@@ -223,6 +225,13 @@ test(
     for (const geometry of wideGeometry) {
       expect(geometry.field.right).toBeLessThanOrEqual(geometry.container.right + 1);
     }
+    const actionFlowMatchesFieldFlow = await search.evaluate(element => {
+      const actionFlow = element.parentElement?.parentElement?.parentElement;
+      const fieldFlow = element.closest('section')?.querySelector('label')
+        ?.parentElement?.parentElement;
+      return actionFlow === fieldFlow;
+    });
+    expect(actionFlowMatchesFieldFlow).toBeTruthy();
 
     await page.setViewportSize({ width: 700, height: 900 });
     const drawer = page.locator('.drawer').first();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.119",
+  "version": "5.1.121",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/vona/env/.env

@@ -38,7 +38,7 @@ LOGGER_ROTATE_MAXFILES = 7d
 TELEMETRY_ENABLED = false
 
 # metrics
-METRICS_ENABLED = true
+METRICS_ENABLED = false
 
 # build
 

package/vona/src/suite/a-commerce/modules/commerce-trade/src/service/order.ts

@@ -97,7 +97,11 @@ export type PaymentOutcomeFailureStage =
 
 type PaymentOutcomeStageCallback = (stage: PaymentOutcomeFailureStage) => void | Promise<void>;
 
-export type ShipmentFailureStage = 'afterShipmentInsert' | 'afterOrderState' | 'afterOrderAudit';
+export type ShipmentFailureStage =
+  | 'beforeOrderLock'
+  | 'afterShipmentInsert'
+  | 'afterOrderState'
+  | 'afterOrderAudit';
 
 type ShipmentStageCallback = (stage: ShipmentFailureStage) => void | Promise<void>;
 
@@ -678,6 +682,7 @@ export class ServiceOrder extends BeanBase {
     if (!carrier) this.app.throw(400, 'shipment carrier is required');
     if (!trackingNumber) this.app.throw(400, 'shipment trackingNumber is required');
 
+    await onStage?.('beforeOrderLock');
     const order = await this.scope.model.order.getByIdForUpdate(orderId);
     if (!order) this.app.throw(404, 'order not found');
     const existingShipment = await this.scope.model.shipment.get({ orderId: order.id });

package/vona/src/suite/a-commerce/modules/commerce-trade/test/shipmentRefundRace.test.ts

@@ -31,8 +31,8 @@ async function cleanup(fixture: IFixture) {
   }
 }
 
-async function createPaidOrder(suffix: string): Promise<IFixture> {
-  const fixture: IFixture = { customerName: `shipment-refund-${suffix}` };
+async function createPaidOrder(fixture: IFixture, suffix: string): Promise<void> {
+  fixture.customerName = `shipment-refund-${suffix}`;
   const customer = await app.bean.user.register({ name: fixture.customerName }, true);
   fixture.userId = customer.id as number;
   await app.bean.passport.signinMock(fixture.customerName as any);
@@ -61,7 +61,111 @@ async function createPaidOrder(suffix: string): Promise<IFixture> {
   } finally {
     await app.bean.passport.signout();
   }
-  return fixture;
+}
+
+async function runInMockCtx<TResult>(
+  customerName: string | undefined,
+  operation: () => Promise<TResult>,
+): Promise<TResult> {
+  return await app.bean.executor.mockCtx(async () => {
+    if (customerName === undefined) {
+      await app.bean.passport.signinMock();
+    } else {
+      await app.bean.passport.signinMock(customerName as any);
+    }
+    try {
+      return await operation();
+    } finally {
+      await app.bean.passport.signout();
+    }
+  });
+}
+
+async function withTimeout<TResult>(promise: Promise<TResult>, message: string): Promise<TResult> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => reject(new Error(message)), 5_000);
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+async function waitForHolderStage(
+  entered: Promise<void>,
+  holder: Promise<unknown>,
+  label: string,
+): Promise<void> {
+  return await withTimeout(
+    Promise.race([
+      entered,
+      holder.then(
+        () =>
+          Promise.reject(new Error(`${label} completed before reaching its lock-holding stage`)),
+        error => Promise.reject(error),
+      ),
+    ]),
+    `${label} did not reach its lock-holding stage`,
+  );
+}
+
+async function waitForPostgresWaiter(waiterPid: number, holderPid: number): Promise<void> {
+  const deadline = Date.now() + 5_000;
+  while (Date.now() < deadline) {
+    const result = await app.bean.database.current.connection.raw(
+      `
+        select wait_event_type
+          from pg_stat_activity
+         where pid = ?
+           and ? = any(pg_blocking_pids(pid))
+      `,
+      [waiterPid, holderPid],
+    );
+    if (result.rows[0]) {
+      assert.equal(result.rows[0].wait_event_type, 'Lock');
+      return;
+    }
+    await new Promise(resolve => setTimeout(resolve, 10));
+  }
+  assert.fail(`PostgreSQL backend ${waiterPid} was not blocked by backend ${holderPid}`);
+}
+
+async function assertPersistedRefundOutcome(
+  orderId: number,
+  expected: {
+    orderState: string;
+    refundState: string;
+    refundAttemptState: string;
+    orderAuditOperations: readonly string[];
+    refundAuditStates: readonly string[];
+  },
+): Promise<void> {
+  const trade = app.scope('commerce-trade');
+  const payment = app.scope('commerce-payment');
+  const order = await trade.model.order.getById(orderId);
+  const shipments = await trade.model.shipment.select({ where: { orderId } });
+  const requests = await payment.model.refundRequest.select({ where: { orderId } });
+  const attempts = await payment.model.refundAttempt.select({
+    where: { refundRequestId: requests[0]?.id },
+  });
+  const orderAudits = await trade.model.orderAudit.select({ where: { orderId } });
+  const refundAudits = await payment.model.refundAudit.select({ where: { orderId } });
+
+  assert.equal(order?.state, expected.orderState);
+  assert.equal(shipments.length, 0);
+  assert.equal(requests.length, 1);
+  assert.equal(requests[0]?.state, expected.refundState);
+  assert.equal(attempts.length, 1);
+  assert.equal(attempts[0]?.state, expected.refundAttemptState);
+  for (const operation of expected.orderAuditOperations) {
+    assert.equal(orderAudits.filter(item => item.operation === operation).length, 1);
+  }
+  assert.equal(orderAudits.filter(item => item.operation === 'shipped').length, 0);
+  assert.deepEqual(refundAudits.map(item => item.toRefundState).sort(), expected.refundAuditStates);
 }
 
 describe('shipmentRefundRace.test.ts', { concurrency: false, sequential: true }, () => {
@@ -83,31 +187,65 @@ describe('shipmentRefundRace.test.ts', { concurrency: false, sequential: true },
     const fixture: IFixture = {};
     try {
       await app.bean.executor.mockCtx(async () => {
-        Object.assign(fixture, await createPaidOrder(randomUUID().slice(0, 12)));
+        await createPaidOrder(fixture, randomUUID().slice(0, 12));
       });
-      const requestRefund = app.bean.executor.mockCtx(async () => {
-        await app.bean.passport.signinMock(fixture.customerName as any);
-        try {
-          return await app.scope('commerce-trade').service.order.requestRefund(fixture.orderId!, {
+      const requestEntered = Promise.withResolvers<void>();
+      const releaseRequest = Promise.withResolvers<void>();
+      let requestPid: number | undefined;
+      const requestRefund = runInMockCtx(fixture.customerName, async () => {
+        return await app.scope('commerce-trade').service.order.requestRefundForTest(
+          fixture.orderId!,
+          {
             reason: 'race request',
             idempotencyKey: 'shipment-refund-race-request-1',
-          });
-        } finally {
-          await app.bean.passport.signout();
-        }
+          },
+          async stage => {
+            if (stage !== 'afterRefundRequestOrderState') return;
+            const result = await app.bean.database.current.connection.raw(
+              'select pg_backend_pid() as pid',
+            );
+            requestPid = result.rows[0].pid;
+            requestEntered.resolve();
+            await releaseRequest.promise;
+          },
+        );
       });
-      const ship = app.bean.executor.mockCtx(async () => {
-        await app.bean.passport.signinMock();
-        try {
-          return await app.scope('commerce-trade').service.order.ship(fixture.orderId!, {
-            carrier: 'Cabloy Express',
-            trackingNumber: 'CAB-RFD-1',
-          });
-        } finally {
-          await app.bean.passport.signout();
-        }
-      });
-      await Promise.allSettled([requestRefund, ship]);
+      const shipmentReady = Promise.withResolvers<void>();
+      const releaseShipment = Promise.withResolvers<void>();
+      let shipmentPid: number | undefined;
+      let ship: Promise<unknown> | undefined;
+      try {
+        await waitForHolderStage(requestEntered.promise, requestRefund, 'refund request');
+        assert.notEqual(requestPid, undefined);
+        ship = runInMockCtx(undefined, async () => {
+          return await app.scope('commerce-trade').service.order.shipForTest(
+            fixture.orderId!,
+            {
+              carrier: 'Cabloy Express',
+              trackingNumber: 'CAB-RFD-1',
+            },
+            async stage => {
+              if (stage !== 'beforeOrderLock') return;
+              const result = await app.bean.database.current.connection.raw(
+                'select pg_backend_pid() as pid',
+              );
+              shipmentPid = result.rows[0].pid;
+              shipmentReady.resolve();
+              await releaseShipment.promise;
+            },
+          );
+        });
+        await waitForHolderStage(shipmentReady.promise, ship, 'shipment');
+        assert.notEqual(shipmentPid, undefined);
+        releaseShipment.resolve();
+        await app.bean.executor.mockCtx(async () => {
+          await waitForPostgresWaiter(shipmentPid!, requestPid!);
+        });
+      } finally {
+        releaseShipment.resolve();
+        releaseRequest.resolve();
+        await Promise.allSettled([requestRefund, ship].filter(Boolean));
+      }
       await app.bean.executor.mockCtx(async () => {
         const trade = app.scope('commerce-trade');
         const payment = app.scope('commerce-payment');
@@ -140,4 +278,219 @@ describe('shipmentRefundRace.test.ts', { concurrency: false, sequential: true },
       });
     }
   });
+
+  it('rejects shipment when refund approval contends for the locked refund-requested order', async t => {
+    if (process.env.DATABASE_DEFAULT_CLIENT !== 'pg') {
+      t.skip('requires PostgreSQL row-lock contention');
+      return;
+    }
+    const fixture: IFixture = {};
+    try {
+      await app.bean.executor.mockCtx(async () => {
+        await createPaidOrder(fixture, randomUUID().slice(0, 12));
+      });
+      await runInMockCtx(fixture.customerName, async () => {
+        await app.scope('commerce-trade').service.order.requestRefund(fixture.orderId!, {
+          reason: 'race approval request',
+          idempotencyKey: 'shipment-refund-race-approval-request-1',
+        });
+      });
+      const entered = Promise.withResolvers<void>();
+      const release = Promise.withResolvers<void>();
+      let holderPid: number | undefined;
+      const approveRefund = runInMockCtx(undefined, async () => {
+        return await app.scope('commerce-trade').service.order.reviewRefundForTest(
+          fixture.orderId!,
+          {
+            reason: 'race approval',
+            idempotencyKey: 'shipment-refund-race-approval-1',
+          },
+          'approved',
+          async stage => {
+            if (stage !== 'afterRefundReviewOrderState') return;
+            const result = await app.bean.database.current.connection.raw(
+              'select pg_backend_pid() as pid',
+            );
+            holderPid = result.rows[0].pid;
+            entered.resolve();
+            await release.promise;
+          },
+        );
+      });
+      const shipmentReady = Promise.withResolvers<void>();
+      const releaseShipment = Promise.withResolvers<void>();
+      let shipmentPid: number | undefined;
+      let ship: Promise<unknown> | undefined;
+      let results: PromiseSettledResult<unknown>[] | undefined;
+      try {
+        await waitForHolderStage(entered.promise, approveRefund, 'refund approval');
+        assert.notEqual(holderPid, undefined);
+        ship = runInMockCtx(undefined, async () => {
+          return await app.scope('commerce-trade').service.order.shipForTest(
+            fixture.orderId!,
+            {
+              carrier: 'Cabloy Express',
+              trackingNumber: 'CAB-RFD-APPROVAL-1',
+            },
+            async stage => {
+              if (stage !== 'beforeOrderLock') return;
+              const result = await app.bean.database.current.connection.raw(
+                'select pg_backend_pid() as pid',
+              );
+              shipmentPid = result.rows[0].pid;
+              shipmentReady.resolve();
+              await releaseShipment.promise;
+            },
+          );
+        });
+        await waitForHolderStage(shipmentReady.promise, ship, 'shipment');
+        assert.notEqual(shipmentPid, undefined);
+        releaseShipment.resolve();
+        await app.bean.executor.mockCtx(async () => {
+          await waitForPostgresWaiter(shipmentPid!, holderPid!);
+        });
+      } finally {
+        releaseShipment.resolve();
+        release.resolve();
+        results = await Promise.allSettled([approveRefund, ship].filter(Boolean));
+      }
+      const [approvalResult, shipmentResult] = results!;
+      const message = JSON.stringify(results);
+      assert.equal(approvalResult.status, 'fulfilled', message);
+      assert.equal(shipmentResult.status, 'rejected', message);
+      if (approvalResult.status !== 'fulfilled' || shipmentResult.status !== 'rejected') return;
+      assert.deepEqual(
+        [
+          approvalResult.value.orderState,
+          approvalResult.value.refundState,
+          approvalResult.value.refundAttemptState,
+        ],
+        ['refund_approved', 'approved', 'created'],
+      );
+      assert.equal(shipmentResult.reason?.code, 409);
+      await app.bean.executor.mockCtx(async () => {
+        await assertPersistedRefundOutcome(fixture.orderId!, {
+          orderState: 'refund_approved',
+          refundState: 'approved',
+          refundAttemptState: 'created',
+          orderAuditOperations: ['refund_requested', 'refund_approved'],
+          refundAuditStates: ['approved', 'requested'],
+        });
+      });
+    } finally {
+      await app.bean.executor.mockCtx(async () => {
+        await cleanup(fixture);
+      });
+    }
+  });
+
+  it('rejects shipment when successful refund execution contends for the locked approved order', async t => {
+    if (process.env.DATABASE_DEFAULT_CLIENT !== 'pg') {
+      t.skip('requires PostgreSQL row-lock contention');
+      return;
+    }
+    const fixture: IFixture = {};
+    try {
+      await app.bean.executor.mockCtx(async () => {
+        await createPaidOrder(fixture, randomUUID().slice(0, 12));
+      });
+      await runInMockCtx(fixture.customerName, async () => {
+        await app.scope('commerce-trade').service.order.requestRefund(fixture.orderId!, {
+          reason: 'race execution request',
+          idempotencyKey: 'shipment-refund-race-execution-request-1',
+        });
+      });
+      await runInMockCtx(undefined, async () => {
+        await app.scope('commerce-trade').service.order.approveRefund(fixture.orderId!, {
+          reason: 'race execution approval',
+          idempotencyKey: 'shipment-refund-race-execution-approval-1',
+        });
+      });
+      const entered = Promise.withResolvers<void>();
+      const release = Promise.withResolvers<void>();
+      let holderPid: number | undefined;
+      const executeRefund = runInMockCtx(undefined, async () => {
+        return await app.scope('commerce-trade').service.order.applyRefundOutcomeForTest(
+          fixture.orderId!,
+          {
+            outcome: 'succeeded',
+            idempotencyKey: 'shipment-refund-race-execution-outcome-1',
+          },
+          async stage => {
+            if (stage !== 'afterRefundOutcomeOrderState') return;
+            const result = await app.bean.database.current.connection.raw(
+              'select pg_backend_pid() as pid',
+            );
+            holderPid = result.rows[0].pid;
+            entered.resolve();
+            await release.promise;
+          },
+        );
+      });
+      const shipmentReady = Promise.withResolvers<void>();
+      const releaseShipment = Promise.withResolvers<void>();
+      let shipmentPid: number | undefined;
+      let ship: Promise<unknown> | undefined;
+      let results: PromiseSettledResult<unknown>[] | undefined;
+      try {
+        await waitForHolderStage(entered.promise, executeRefund, 'refund execution');
+        assert.notEqual(holderPid, undefined);
+        ship = runInMockCtx(undefined, async () => {
+          return await app.scope('commerce-trade').service.order.shipForTest(
+            fixture.orderId!,
+            {
+              carrier: 'Cabloy Express',
+              trackingNumber: 'CAB-RFD-EXECUTION-1',
+            },
+            async stage => {
+              if (stage !== 'beforeOrderLock') return;
+              const result = await app.bean.database.current.connection.raw(
+                'select pg_backend_pid() as pid',
+              );
+              shipmentPid = result.rows[0].pid;
+              shipmentReady.resolve();
+              await releaseShipment.promise;
+            },
+          );
+        });
+        await waitForHolderStage(shipmentReady.promise, ship, 'shipment');
+        assert.notEqual(shipmentPid, undefined);
+        releaseShipment.resolve();
+        await app.bean.executor.mockCtx(async () => {
+          await waitForPostgresWaiter(shipmentPid!, holderPid!);
+        });
+      } finally {
+        releaseShipment.resolve();
+        release.resolve();
+        results = await Promise.allSettled([executeRefund, ship].filter(Boolean));
+      }
+      const [refundResult, shipmentResult] = results!;
+      const message = JSON.stringify(results);
+      assert.equal(refundResult.status, 'fulfilled', message);
+      assert.equal(shipmentResult.status, 'rejected', message);
+      if (refundResult.status !== 'fulfilled' || shipmentResult.status !== 'rejected') return;
+      assert.deepEqual(
+        [
+          refundResult.value.orderState,
+          refundResult.value.refundState,
+          refundResult.value.refundAttemptState,
+        ],
+        ['refunded', 'refunded', 'succeeded'],
+      );
+      assert.equal(shipmentResult.reason?.code, 409);
+      await app.bean.executor.mockCtx(async () => {
+        await assertPersistedRefundOutcome(fixture.orderId!, {
+          orderState: 'refunded',
+          refundState: 'refunded',
+          refundAttemptState: 'succeeded',
+          orderAuditOperations: ['refund_requested', 'refund_approved', 'refunded'],
+          refundAuditStates: ['approved', 'refunded', 'requested'],
+        });
+      });
+    } finally {
+      await app.bean.executor.mockCtx(async () => {
+        await cleanup(fixture);
+      });
+    }
+  });
 });

package/vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx

@@ -28,12 +28,15 @@ export interface IDtoOptionsStudentSelectResItem extends IDecoratorDtoOptions {}
                       { type: 'field', name: 'name' },
                       { type: 'field', name: 'level' },
                       { type: 'field', name: 'createdAt' },
+                      {
+                        type: 'block',
+                        block: ZovaRender.block('basic-page:blockFilterActions'),
+                      } as any,
                     ],
                   },
                 ],
               },
             }),
-            ZovaRender.block('basic-page:blockFilterActions'),
           ],
         }),
         ZovaRender.block('basic-page:blockToolbarBulk', {

package/vona/src/suite/a-training/modules/training-student/test/student.test.ts

@@ -57,16 +57,23 @@ describe('student.test.ts', () => {
       assert.equal(filterBlock?.options?.formFieldLayout?.inline, true);
       assert.deepEqual(
         filterBlock?.options?.blocks?.map(item => item.render),
-        ['basic-form:blockFormLayout', 'basic-page:blockFilterActions'],
+        ['basic-form:blockFormLayout'],
       );
       const formLayout = filterBlock?.options?.blocks?.[0]?.options?.formLayout;
+      const filterLayoutChildren = formLayout?.children[0]?.children;
       assert.equal(formLayout?.children[0]?.layout, 'flow');
       assert.equal(formLayout?.children[0]?.columns, undefined);
+      assert.equal(filterLayoutChildren?.length, 4);
       assert.deepEqual(
-        formLayout?.children[0]?.children.map(item => item.name),
+        filterLayoutChildren?.map(item => item.type),
+        ['field', 'field', 'field', 'block'],
+      );
+      assert.deepEqual(
+        filterLayoutChildren?.slice(0, 3).map(item => item.name),
         ['name', 'level', 'createdAt'],
       );
-      assert.equal(formLayout?.children[0]?.children[2]?.span, undefined);
+      assert.equal(filterLayoutChildren?.[2]?.span, undefined);
+      assert.equal(filterLayoutChildren?.[3]?.block?.render, 'basic-page:blockFilterActions');
     });
   });
 

package/zova/packages-zova/zova/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova",
-  "version": "5.1.141",
+  "version": "5.1.142",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A vue3 framework with ioc",
   "keywords": [
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "zova-core": "^5.1.79",
-    "zova-suite-a-zova": "^5.1.140"
+    "zova-suite-a-zova": "^5.1.141"
   },
   "devDependencies": {
     "clean-package": "^2.2.0",

package/zova/src/suite/cabloy-basic/modules/basic-form/src/component/blockFormLayout/controller.tsx

@@ -2,7 +2,9 @@ import type { IComponentOptions } from 'zova';
 import type {
   IJsxRenderContextForm,
   IResolvedFormLayout,
+  IResolvedFormLayoutBlock,
   IResolvedFormLayoutField,
+  IResolvedFormLayoutLeaf,
   IResolvedFormLayoutGroup,
   IResolvedFormLayoutNode,
   IResolvedFormLayoutSection,
@@ -78,6 +80,8 @@ export class ControllerBlockFormLayout extends BeanControllerBase {
     switch (node.type) {
       case 'field':
         return this._renderField(node);
+      case 'block':
+        return this._renderBlock(node);
       case 'group':
         return this._renderGroup(node);
       case 'section':
@@ -87,11 +91,28 @@ export class ControllerBlockFormLayout extends BeanControllerBase {
     }
   }
 
-  private _renderField(node: IResolvedFormLayoutField, sectionLayout?: 'grid' | 'flow') {
-    const { $$form } = this.$$renderContext;
+  private _renderLeaf(node: IResolvedFormLayoutLeaf, sectionLayout?: 'grid' | 'flow') {
     const className =
       sectionLayout === 'flow' ? 'min-w-0 max-w-full' : this._gridClasses('col-span', node.span);
-    return <div class={className}>{$$form.renderField(node.name)}</div>;
+    return <div class={className}>{this._renderLeafContent(node)}</div>;
+  }
+
+  private _renderLeafContent(node: IResolvedFormLayoutLeaf) {
+    if (node.type === 'field') return this.$$renderContext.$$form.renderField(node.name);
+    return this._renderBlockContent(node);
+  }
+
+  private _renderField(node: IResolvedFormLayoutField) {
+    return this._renderLeaf(node);
+  }
+
+  private _renderBlock(node: IResolvedFormLayoutBlock) {
+    return this._renderLeaf(node);
+  }
+
+  private _renderBlockContent(node: IResolvedFormLayoutBlock) {
+    const { $celScope, $jsx } = this.$$renderContext;
+    return $jsx.render(node.block.render!, node.block.options, $celScope, this.$$renderContext);
   }
 
   private _renderGroup(node: IResolvedFormLayoutGroup) {
@@ -114,7 +135,7 @@ export class ControllerBlockFormLayout extends BeanControllerBase {
       <section>
         {!!node.title && <h3 class="mb-1 text-lg font-semibold">{node.title}</h3>}
         {!!node.description && <p class="mb-4 text-sm text-base-content/70">{node.description}</p>}
-        <div class={className}>{node.children.map(child => this._renderField(child, layout))}</div>
+        <div class={className}>{node.children.map(child => this._renderLeaf(child, layout))}</div>
       </section>
     );
   }

package/zova/src/suite-vendor/a-zova/modules/a-form/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-form",
-  "version": "5.1.45",
+  "version": "5.1.46",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx

@@ -411,6 +411,7 @@ export class ControllerForm<
     if (node.type === 'field') {
       return this.formState.fieldMeta[node.name]?.errors?.length ? 1 : 0;
     }
+    if (node.type === 'block') return 0;
     return node.children.reduce((count, child) => {
       return count + this._getFormLayoutErrorFieldCount(child);
     }, 0);

package/zova/src/suite-vendor/a-zova/modules/a-form/src/lib/formLayout.ts

@@ -1,6 +1,7 @@
 import type {
   IFormLayout,
   IFormLayoutField,
+  IFormLayoutLeaf,
   IFormLayoutNode,
   IFormLayoutTab,
   IFormLayoutTabs,
@@ -11,6 +12,7 @@ import type {
   IFormLayoutDiagnostic,
   IResolvedFormLayout,
   IResolvedFormLayoutField,
+  IResolvedFormLayoutLeaf,
   IResolvedFormLayoutGroup,
   IResolvedFormLayoutNode,
   IResolvedFormLayoutSection,
@@ -68,6 +70,9 @@ function resolveNode(
   if (node.type === 'field') {
     return resolveField(node, tabPath, propertyNames, fieldNames, diagnostics, fieldTabPaths);
   }
+  if (node.type === 'block') {
+    return node;
+  }
   if (node.type === 'tabs') {
     return resolveTabs(
       node,
@@ -84,9 +89,9 @@ function resolveNode(
   if (node.type === 'section') {
     const children = node.children
       .map(item =>
-        resolveField(item, tabPath, propertyNames, fieldNames, diagnostics, fieldTabPaths),
+        resolveLeaf(item, tabPath, propertyNames, fieldNames, diagnostics, fieldTabPaths),
       )
-      .filter(Boolean) as IResolvedFormLayoutField[];
+      .filter(Boolean) as IResolvedFormLayoutLeaf[];
     return children.length ? { ...node, id, children } : undefined;
   }
   const children = node.children
@@ -103,11 +108,23 @@ function resolveNode(
       ),
     )
     .filter(Boolean) as Array<
-    IResolvedFormLayoutField | IResolvedFormLayoutGroup | IResolvedFormLayoutSection
+    IResolvedFormLayoutLeaf | IResolvedFormLayoutGroup | IResolvedFormLayoutSection
   >;
   return children.length ? { ...node, id, children } : undefined;
 }
 
+function resolveLeaf(
+  node: IFormLayoutLeaf,
+  tabPath: IResolvedFormLayout['fieldTabPaths'][string],
+  propertyNames: Set<string>,
+  fieldNames: Set<string>,
+  diagnostics: IFormLayoutDiagnostic[],
+  fieldTabPaths: IResolvedFormLayout['fieldTabPaths'],
+): IResolvedFormLayoutLeaf | undefined {
+  if (node.type === 'block') return node;
+  return resolveField(node, tabPath, propertyNames, fieldNames, diagnostics, fieldTabPaths);
+}
+
 function resolveTabs(
   node: IFormLayoutTabs,
   indexPath: number[],
@@ -163,7 +180,7 @@ function resolveTab(
       ),
     )
     .filter(Boolean) as Array<
-    IResolvedFormLayoutField | IResolvedFormLayoutGroup | IResolvedFormLayoutSection
+    IResolvedFormLayoutLeaf | IResolvedFormLayoutGroup | IResolvedFormLayoutSection
   >;
   return children.length ? { ...node, id, children } : undefined;
 }

package/zova/src/suite-vendor/a-zova/modules/a-form/src/types/formLayout.ts

@@ -1,5 +1,6 @@
 import type {
   IFormLayoutResponsiveColumns,
+  IResourceRenderBlockOptionsBlock,
   TypeFormLayoutSectionLayout,
 } from 'zova-module-a-openapi';
 
@@ -15,12 +16,20 @@ export interface IResolvedFormLayoutField {
   span?: IFormLayoutResponsiveColumns;
 }
 
+export interface IResolvedFormLayoutBlock {
+  type: 'block';
+  block: IResourceRenderBlockOptionsBlock;
+  span?: IFormLayoutResponsiveColumns;
+}
+
+export type IResolvedFormLayoutLeaf = IResolvedFormLayoutField | IResolvedFormLayoutBlock;
+
 export interface IResolvedFormLayoutGroup {
   type: 'group';
   id: string;
   title?: string;
   description?: string;
-  children: Array<IResolvedFormLayoutField | IResolvedFormLayoutGroup | IResolvedFormLayoutSection>;
+  children: Array<IResolvedFormLayoutLeaf | IResolvedFormLayoutGroup | IResolvedFormLayoutSection>;
 }
 
 export interface IResolvedFormLayoutSection {
@@ -30,7 +39,7 @@ export interface IResolvedFormLayoutSection {
   description?: string;
   layout?: TypeFormLayoutSectionLayout;
   columns?: IFormLayoutResponsiveColumns;
-  children: IResolvedFormLayoutField[];
+  children: IResolvedFormLayoutLeaf[];
 }
 
 export interface IResolvedFormLayoutTabs {
@@ -43,7 +52,7 @@ export interface IResolvedFormLayoutTab {
   type: 'tab';
   id: string;
   title: string;
-  children: Array<IResolvedFormLayoutField | IResolvedFormLayoutGroup | IResolvedFormLayoutSection>;
+  children: Array<IResolvedFormLayoutLeaf | IResolvedFormLayoutGroup | IResolvedFormLayoutSection>;
 }
 
 export interface IResolvedFormLayoutTabRef {
@@ -52,7 +61,7 @@ export interface IResolvedFormLayoutTabRef {
 }
 
 export type IResolvedFormLayoutNode =
-  | IResolvedFormLayoutField
+  | IResolvedFormLayoutLeaf
   | IResolvedFormLayoutGroup
   | IResolvedFormLayoutSection
   | IResolvedFormLayoutTabs;

package/zova/src/suite-vendor/a-zova/modules/a-openapi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-openapi",
-  "version": "5.1.46",
+  "version": "5.1.47",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/resource/formLayout.ts

@@ -1,3 +1,5 @@
+import type { IResourceRenderBlockOptionsBlock } from './block.js';
+
 export interface IFormLayout {
   children: IFormLayoutNode[];
 }
@@ -18,12 +20,20 @@ export interface IFormLayoutField {
   span?: IFormLayoutResponsiveColumns;
 }
 
+export interface IFormLayoutBlock {
+  type: 'block';
+  block: IResourceRenderBlockOptionsBlock;
+  span?: IFormLayoutResponsiveColumns;
+}
+
+export type IFormLayoutLeaf = IFormLayoutField | IFormLayoutBlock;
+
 export interface IFormLayoutGroup {
   type: 'group';
   id?: string;
   title?: string;
   description?: string;
-  children: Array<IFormLayoutField | IFormLayoutGroup | IFormLayoutSection>;
+  children: Array<IFormLayoutLeaf | IFormLayoutGroup | IFormLayoutSection>;
 }
 
 export interface IFormLayoutSection {
@@ -33,7 +43,7 @@ export interface IFormLayoutSection {
   description?: string;
   layout?: TypeFormLayoutSectionLayout;
   columns?: IFormLayoutResponsiveColumns;
-  children: IFormLayoutField[];
+  children: IFormLayoutLeaf[];
 }
 
 export interface IFormLayoutTabs {
@@ -46,11 +56,11 @@ export interface IFormLayoutTab {
   type: 'tab';
   id?: string;
   title: string;
-  children: Array<IFormLayoutField | IFormLayoutGroup | IFormLayoutSection>;
+  children: Array<IFormLayoutLeaf | IFormLayoutGroup | IFormLayoutSection>;
 }
 
 export type IFormLayoutNode =
-  | IFormLayoutField
+  | IFormLayoutLeaf
   | IFormLayoutGroup
   | IFormLayoutSection
   | IFormLayoutTabs;

package/zova/src/suite-vendor/a-zova/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-suite-a-zova",
-  "version": "5.1.140",
+  "version": "5.1.141",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "zova",
   "license": "MIT",
@@ -16,13 +16,13 @@
     "zova-module-a-boundary": "^5.1.21",
     "zova-module-a-command": "^5.1.33",
     "zova-module-a-fetch": "^5.1.24",
-    "zova-module-a-form": "^5.1.45",
+    "zova-module-a-form": "^5.1.46",
     "zova-module-a-icon": "^5.1.26",
     "zova-module-a-interceptor": "^5.1.29",
     "zova-module-a-logger": "^5.1.26",
     "zova-module-a-meta": "^5.1.21",
     "zova-module-a-model": "^5.1.33",
-    "zova-module-a-openapi": "^5.1.46",
+    "zova-module-a-openapi": "^5.1.47",
     "zova-module-a-router": "^5.1.31",
     "zova-module-a-routerstack": "^5.1.26",
     "zova-module-a-routertabs": "^5.1.33",