cabloy 5.1.113 → 5.1.114

package/.cabloy-version

@@ -1 +1 @@
-5.1.113
+5.1.114

package/.claude/skills/cabloy-backend-scaffold/references/follow-up-checklist.md

@@ -43,6 +43,10 @@ After generating or extending a backend thread, check which follow-up layers app
 - retain exact IDs or entities for every test-local persisted resource and delete them from `finally`
 - delete joins, children, derived records, and other dependents before their owners, in the same active tenant/instance scope
 - do not use unscoped, timestamp-, prefix-, or broad business-condition deletion when an exact test-owned identity is available
+- treat the application lifecycle as runner-owned; do not create or close the shared `app` in an individual test
+- give each scoped test or operation its own `app.bean.executor.mockCtx(...)` boundary
+- for a business race, give every contender a separate `mockCtx(...)`, launch the competing operations explicitly, wait for all branches to settle, and assert the combined durable state
+- gate lock- or isolation-sensitive contention tests on supporting database capabilities; runner scheduling is never race-condition evidence
 
 ## Module composition and dependency intent
 

package/.github/workflows/vona-test-mysql.yml

@@ -34,6 +34,18 @@ jobs:
           version: 11.5.2
       - name: init
         run: npm run init
+      - name: run Commerce lifecycle gate
+        run: >-
+          DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run vona :bin:test --
+          commerce-trade/test/stockBalance.test.ts
+          commerce-trade/test/stockReservation.test.ts
+          commerce-trade/test/stockAudit.test.ts
+          commerce-promotion/test/couponReservation.test.ts
+          commerce-payment/test/paymentAttempt.test.ts
+          commerce-trade/test/checkoutReservation.test.ts
+          commerce-trade/test/reservationExpiry.test.ts
+          --flavor=normal
+        working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run test
         working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run build -- --flavor=ci

package/.github/workflows/vona-test-pg.yml

@@ -36,10 +36,14 @@ jobs:
         run: npm run init
       - name: run Commerce stock contention gate
         run: >-
-          TEST_CONCURRENCY=false DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test --
+          DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test --
           commerce-trade/test/stockBalance.test.ts
           commerce-trade/test/stockReservation.test.ts
           commerce-trade/test/stockAudit.test.ts
+          commerce-promotion/test/couponReservation.test.ts
+          commerce-payment/test/paymentAttempt.test.ts
+          commerce-trade/test/checkoutReservation.test.ts
+          commerce-trade/test/reservationExpiry.test.ts
           --flavor=normal
         working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=pg npm run test

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 5.1.114
+
+### Features
+
+- Add retryable AOP infrastructure for Commerce transactions.
+- Add a foundational Commerce coupon lifecycle.
+- Add a foundational Commerce order snapshot capability.
+- Add `ctx.state.fetch` support.
+- Add checkout functionality.
+
+### Improvements
+
+- Decorate Commerce transaction retries.
+
 ## 5.1.113
 
 ### Features

package/CLAUDE.md

@@ -72,6 +72,10 @@ Before inventing a custom implementation path:
 - In Vona, a tenant corresponds to an instance. Ordinary resource-model CRUD is automatically scoped to the active instance; treat records absent from that scope as absent, and do not use raw cross-instance probes merely to choose between `403` and not-found behavior. Model future multi-merchant boundaries explicitly inside an instance.
 - Model cross-Model query-cache dependencies as one directed, acyclic `modelsClear` / `modelsClearedBy` graph, and verify source mutations refresh warmed dependent queries; read `.docs-internal/architecture/vona-cross-model-query-cache-dependencies.md` before designing a nontrivial graph.
 - For `@Api.field(...)` and related schemaLike composition, framework guards now preserve previously attached OpenAPI metadata across schema rebuilds, but structure-shaping schemaLike is still order-sensitive. Treat `v.object(...)`, `v.array(...)`, `v.optional()`, `v.nullable()`, `v.default(...)`, and preprocess/transform wrappers as structure-shaping; keep the final structure-defining schemaLike last and verify emitted schema/OpenAPI output after such edits.
+- `@Core.transaction(...)` defaults to `REQUIRED`: it starts a transaction only when none exists and otherwise joins the current datasource transaction without upgrading its isolation. Prefer it over manual `inTransaction` wrappers for atomic service methods; use `REQUIRES_NEW` only when an independently committed boundary is explicitly required.
+- For replay-safe transient failures, use `@Core.retryable(...)` with an explicit `errorCodes` allowlist. It retries the downstream AOP suffix, so place it closest to the method when it must wrap and retry a `@Core.transaction(...)` boundary; use `ownerOnly: true` for dual-role leaves that must not retry inside a caller-owned transaction; do not retry external side effects or infer retryability from isolation level.
+- Backend tests that use scoped Vona state must own an `app.bean.executor.mockCtx(...)` boundary; every intentionally competing operation must run in a separate `mockCtx(...)`.
+- Do not set `TEST_CONCURRENCY=false` for normal `npm run test` or CI runs: an unset value defaults to concurrent execution. For stateful `node:test` suites, declare `{ concurrency: false }` explicitly. Prove business contention by explicitly launching competing operations and asserting their combined durable outcome, never through runner parallelism or scheduling.
 - Unit tests must delete every test-owned persisted resource in `finally`, using precise owned identities and reverse dependency order.
 - Shared durable test or local-development fixtures must be created through the owning module's `meta.version.ts` `seed()` hook and treated as read-only by tests; the managed seed path starts from a newly recreated database rather than repeating against one database.
 

package/cabloy-docs/backend/internal-aop-guide.md

@@ -82,6 +82,7 @@ Representative examples include:
 
 - `a-logger:log`
 - `a-orm:transaction`
+- `a-retryable:retryable`
 - `a-caching:cachingGet`
 - `a-caching:cachingSet`
 - `a-caching:cachingDel`
@@ -92,9 +93,43 @@ These built-ins also expose shorthand decorators such as:
 ```typescript
 @Core.log({ level: 'info' })
 @Core.transaction({ isolationLevel: 'READ_COMMITTED', propagation: 'REQUIRED' })
+@Core.retryable({
+  retries: 1,
+  minTimeout: 0,
+  maxTimeout: 0,
+  errorCodes: ['40001'],
+})
 @Caching.get({ cacheName: 'module-name:xxx' })
 ```
 
+`@Core.retryable(...)` retries only errors whose string `code` is explicitly listed in `errorCodes`. It replays the downstream AOP suffix; to retry a complete transaction, place `@Core.retryable(...)` closest to the method so it runs outside the transaction decorator:
+
+```typescript
+@Core.transaction({ isolationLevel: 'SERIALIZABLE' })
+@Core.retryable({ retries: 1, minTimeout: 0, maxTimeout: 0, errorCodes: ['40001'] })
+async reserve() {
+  // transactional writes
+}
+```
+
+Use `ownerOnly: true` for a dual-role leaf method that may either own a transaction when called directly or join an aggregate transaction owned by its caller. It retries only when no current-datasource transaction existed when the method began; when nested, it executes once and lets the aggregate owner decide whether to replay the complete unit of work:
+
+```typescript
+@Core.transaction({ isolationLevel: 'SERIALIZABLE' })
+@Core.retryable({
+  retries: 1,
+  minTimeout: 0,
+  maxTimeout: 0,
+  errorCodes: ['40001'],
+  ownerOnly: true,
+})
+async reserveLeaf() {
+  // transactional writes
+}
+```
+
+Retried methods must be replay-safe: defer external side effects until commit, and do not use this helper to imply cross-datasource or independent `REQUIRES_NEW` retry semantics.
+
 For the broader logger-client, rotation, and level model behind `@Core.log(...)`, see [Logger Guide](/backend/logger-guide).
 
 ## Magic Method

package/cabloy-docs/backend/unit-testing.md

@@ -46,11 +46,18 @@ npm run test
 
 A typical Vona test flow includes:
 
-1. create a global `app` object
+1. create one shared global `app` object for the test run
 2. clean Redis data
 3. recreate the database
 4. execute migration code
 5. run the test files
+6. close the shared application after the test run
+
+The runner owns this application lifecycle. Test files import the shared app from `vona-mock` and must not create or close it themselves:
+
+```typescript
+import { app } from 'vona-mock';
+```
 
 This is one of the most important distinctions from ordinary app flow: test execution rebuilds and verifies the framework lifecycle, not only the target function.
 
@@ -72,6 +79,33 @@ Representative command:
 cd vona && npm run cov
 ```
 
+## Runner concurrency
+
+The Vona runner uses Node's built-in test runner with one shared application and process isolation disabled. `TEST_CONCURRENCY` controls runner scheduling:
+
+- `true` uses the available CPU count;
+- `false` forces serial execution;
+- a positive integer sets an explicit concurrency limit.
+
+```bash
+TEST_CONCURRENCY=false npm run test
+TEST_CONCURRENCY=4 npm run test
+```
+
+Cabloy Basic requests concurrency by default with `TEST_CONCURRENCY=true`. When the active database dialect does not advertise the required concurrency capability, the runner falls back to serial execution. The default SQLite path therefore runs serially.
+
+Runner concurrency schedules ordinary tests; it does not prove a business-level race condition. Tests must not rely on scheduling, timing, or execution order for correctness.
+
+A suite can also make sibling-test scheduling explicit:
+
+```typescript
+describe('resource.test.ts', { concurrency: false }, () => {
+  // sibling tests in this suite are serialized
+});
+```
+
+This setting controls test scheduling only. It is not a substitute for explicitly creating competing business operations.
+
 ## Mock request context
 
 One of the most important Vona testing patterns is simulating a request context.
@@ -84,6 +118,10 @@ await app.bean.executor.mockCtx(async () => {
 });
 ```
 
+Treat one `mockCtx(...)` callback as one simulated request boundary. Keep `app.ctx`, authentication, current database selection, and context-dependent service, model, or action work inside that callback, and always await it. Do not retain request-context state after the callback returns.
+
+`mockCtx(...)` isolates request-local context. It does not isolate committed persisted records, app-global state, external caches, or shared durable fixtures. For independent concurrent requests, create one `mockCtx(...)` for each branch; parallel work started inside a single `mockCtx(...)` shares that request context.
+
 Locale-sensitive variants and additional request-context helpers are also available.
 
 ## Persisted fixture lifecycle
@@ -111,6 +149,37 @@ try {
 
 Treat shared `seed()` records as read-only. If a scenario needs to change a record, create a separate test-local fixture instead and clean it up. See [Migration and Changes](/backend/migration-and-changes#seed-test-environment-baseline-data) for the durable seed lifecycle.
 
+Application shutdown is runner-owned; authentication and fixture cleanup are test-owned. Do not call `app.close()` from a test. Keep `signout()` and exact-identity deletion in `finally` inside an appropriate request context.
+
+## Testing concurrent behavior explicitly
+
+A concurrency test creates competing business operations inside one test; it does not depend on the runner to happen to schedule tests at the same time.
+
+```typescript
+const attempt = async () => {
+  return await app.bean.executor.mockCtx(async () => {
+    await app.bean.passport.signinMock();
+    try {
+      return await reserve(resourceId);
+    } finally {
+      await app.bean.passport.signout();
+    }
+  });
+};
+
+const results = await Promise.allSettled([attempt(), attempt()]);
+```
+
+Use this sequence:
+
+1. create a dedicated test-local fixture in an appropriate `mockCtx(...)`;
+2. give every contender its own `mockCtx(...)` and authentication lifecycle;
+3. launch the contenders explicitly and wait for all of them to settle;
+4. use a fresh `mockCtx(...)` to assert both individual outcomes and the combined durable invariant;
+5. clean up exact owned fixtures only after every branch has settled, in the appropriate tenant/instance context.
+
+For example, a one-winner reservation test should verify not only the fulfilled and rejected operations but also the final balance, surviving reservation, and audit records. If the invariant depends on row locks, transaction isolation, or another database-specific capability, skip the test on unsupported dialects rather than weakening its assertions. See [stockReservation.test.ts](../../vona/src/suite/a-commerce/modules/commerce-trade/test/stockReservation.test.ts) for this pattern.
+
 ## Working with module scope in tests
 
 Representative pattern:
@@ -218,6 +287,8 @@ Read this guide together with:
 - [CRUD Workflow](/backend/crud-workflow)
 - [Migration and Changes](/backend/migration-and-changes)
 - [Controller Guide](/backend/controller-guide)
+- [Transaction Guide](/backend/transaction-guide)
+- [Redlock Guide](/backend/redlock-guide)
 
 A practical split is:
 

package/package.json

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

package/vona/packages-cli/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.131",
+  "version": "1.1.132",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli-set-api",
-  "version": "1.1.129",
+  "version": "1.1.130",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

package/vona/packages-cli/cli-set-api/toolsIsolate/test.ts

@@ -7,6 +7,7 @@ import { globby } from 'globby';
 import { createWriteStream } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
 import { run } from 'node:test';
 import { lcov, spec } from 'node:test/reporters';
 import { fileURLToPath } from 'node:url';
@@ -104,19 +105,25 @@ async function testRun(projectPath: string, coverage: boolean, patterns: string[
         }
       });
     const summaryPromise = waitForTestSummary(testStream);
-    if (coverage) {
-      const reporterDir = path.join(projectPath, 'coverage');
-      fse.ensureDirSync(reporterDir);
-      const reporterLcov = createWriteStream(path.join(reporterDir, 'lcov.info'));
-      testStream.compose(lcov).pipe(reporterLcov);
-    } else {
-      testStream.compose(spec).pipe(process.stdout);
-    }
+    const reporterPromise = coverage
+      ? (() => {
+          const reporterDir = path.join(projectPath, 'coverage');
+          fse.ensureDirSync(reporterDir);
+          const reporterLcov = createWriteStream(path.join(reporterDir, 'lcov.info'));
+          return pipeline(testStream.compose(lcov), reporterLcov);
+        })()
+      : pipeline(testStream.compose(spec), process.stdout, { end: false });
 
-    const summarySuccess = await summaryPromise;
+    const [summarySuccess, [, reporterError]] = await Promise.all([
+      summaryPromise,
+      catchError(() => reporterPromise),
+    ]);
     if (!summarySuccess) {
       throw new Error('node:test reported failed tests');
     }
+    if (reporterError) {
+      throw reporterError;
+    }
   } catch (error) {
     testError = error;
   } finally {
@@ -143,13 +150,19 @@ function waitForTestSummary(testStream: ReturnType<typeof run>) {
 
 async function prepareConcurrency(app: VonaApplication) {
   // check
+  const configured = process.env.TEST_CONCURRENCY;
   let concurrency = 1;
-  if (process.env.TEST_CONCURRENCY === 'true') {
-    concurrency = os.cpus().length;
-  } else if (process.env.TEST_CONCURRENCY === 'false') {
+  if (configured === 'false') {
     concurrency = 1;
+  } else if (configured === undefined || configured === 'true') {
+    concurrency = Math.max(1, os.cpus().length);
   } else {
-    concurrency = Number.parseInt(process.env.TEST_CONCURRENCY!);
+    concurrency = Number.parseInt(configured, 10);
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+      throw new Error(
+        `TEST_CONCURRENCY must be true, false, or a positive integer; received ${configured}`,
+      );
+    }
   }
   if (concurrency === 1) return concurrency;
   // check again

package/vona/packages-utils/compose/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabloy/compose",
-  "version": "2.1.8",
+  "version": "2.1.9",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "cabloy compose",
   "keywords": [

package/vona/packages-utils/compose/src/index.ts

@@ -10,32 +10,40 @@ function __adapterDefault(_context, chain) {
   };
 }
 
+export type TypeComposeNext = ((context?: any) => any) & {
+  replay: (context?: any) => any;
+};
+
 export function compose(chains?: any[], adapter?: TypeComposeAdapter) {
   if (!adapter) adapter = __adapterDefault;
   if (!chains) chains = [];
   return function (context, next?) {
-    // last called middleware #
-    let index = -1;
-    return dispatch(0, context);
-    function dispatch(i, context) {
-      if (i <= index) throw new Error('next() called multiple times');
-      index = i;
+    return dispatch(0, context, { index: -1 });
+
+    function dispatch(i, context, state: { index: number }) {
+      if (i <= state.index) throw new Error('next() called multiple times');
+      state.index = i;
       let receiver;
       let fn;
       const chain = chains![i];
       if (chain) {
         const obj = adapter!(context, chain);
-        if (!obj) return dispatch(i + 1, context);
+        if (!obj) return dispatch(i + 1, context, state);
         receiver = obj.receiver;
         fn = obj.fn;
         if (!fn) throw new Error('fn is not defined');
       }
       if (i === chains!.length) fn = next;
       if (!fn) return context;
-      return fn.call(receiver, context, (...args) => {
-        context = args.length === 0 ? context : args[0];
-        return dispatch(i + 1, context);
-      });
+      const nextPatched = ((...args) => {
+        const nextContext = args.length === 0 ? context : args[0];
+        return dispatch(i + 1, nextContext, state);
+      }) as TypeComposeNext;
+      nextPatched.replay = (...args) => {
+        const nextContext = args.length === 0 ? context : args[0];
+        return dispatch(i + 1, nextContext, { index: i });
+      };
+      return fn.call(receiver, context, nextPatched);
     }
   };
 }

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.78",
+  "version": "5.1.79",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [

package/vona/packages-vona/vona-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-core",
-  "version": "5.1.32",
+  "version": "5.1.33",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona",
   "keywords": [

package/vona/packages-vona/vona-core/src/lib/bean/beanContainer.ts

@@ -614,7 +614,7 @@ export class BeanContainer {
             throw new Error(`get property accessor not exists: ${aopMethod.onionName}`);
           return beanInstance.get(
             aopMethod.options,
-            _patchAopNext([receiver, _], next),
+            _patchAopMethodNext([receiver, _], next),
             receiver,
             prop,
           );
@@ -627,7 +627,7 @@ export class BeanContainer {
           return beanInstance.set(
             aopMethod.options,
             value,
-            _patchAopNext([receiver, value], next),
+            _patchAopMethodNext([receiver, value], next),
             receiver,
             prop,
           );
@@ -640,7 +640,7 @@ export class BeanContainer {
           return beanInstance.execute(
             aopMethod.options,
             args,
-            _patchAopNext([receiver, args], next),
+            _patchAopMethodNext([receiver, args], next),
             receiver,
             prop,
           );
@@ -673,6 +673,18 @@ function _patchAopNext([receiver, context], next) {
   };
 }
 
+function _patchAopMethodNext([receiver, context], next) {
+  const nextPatched = (...args) => {
+    context = args.length === 0 ? context : args[0];
+    return next([receiver, context]);
+  };
+  nextPatched.replay = (...args) => {
+    const nextContext = args.length === 0 ? context : args[0];
+    return next.replay([receiver, nextContext]);
+  };
+  return nextPatched;
+}
+
 function __checkAopOfDescriptorInfo(descriptorInfo) {
   if (!descriptorInfo) return true;
   return !descriptorInfo.dynamic && !descriptorInfo.ofBeanBase;

package/vona/packages-vona/vona-mock/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-mock",
-  "version": "6.1.32",
+  "version": "6.1.33",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona mock",
   "keywords": [

package/vona/pnpm-lock.yaml

@@ -253,6 +253,9 @@ importers:
       vona-module-a-redlock:
         specifier: workspace:^
         version: link:src/suite-vendor/a-vona/modules/a-redlock
+      vona-module-a-retryable:
+        specifier: workspace:^
+        version: link:src/suite-vendor/a-vona/modules/a-retryable
       vona-module-a-runtime:
         specifier: workspace:^
         version: link:src/suite-vendor/a-vona/modules/a-runtime
@@ -1991,6 +1994,9 @@ importers:
       vona-module-a-redlock:
         specifier: workspace:^
         version: link:modules/a-redlock
+      vona-module-a-retryable:
+        specifier: workspace:^
+        version: link:modules/a-retryable
       vona-module-a-runtime:
         specifier: workspace:^
         version: link:modules/a-runtime
@@ -2618,6 +2624,15 @@ importers:
         specifier: ^6.1.3
         version: 6.1.3
 
+  src/suite-vendor/a-vona/modules/a-retryable:
+    devDependencies:
+      clean-package:
+        specifier: ^2.2.0
+        version: 2.2.0
+      rimraf:
+        specifier: ^6.1.3
+        version: 6.1.3
+
   src/suite-vendor/a-vona/modules/a-runtime:
     devDependencies:
       clean-package:

package/vona/src/suite/a-commerce/modules/commerce-catalog/src/.metadata/index.ts

@@ -377,6 +377,7 @@ export * from '../dto/productSelectRes.tsx';
 export * from '../dto/productSelectResItem.tsx';
 export * from '../dto/productUpdate.tsx';
 export * from '../dto/productView.tsx';
+export * from '../dto/skuAttribute.tsx';
 export * from '../dto/skuCreate.tsx';
 export * from '../dto/skuSelectReq.tsx';
 export * from '../dto/skuSelectRes.tsx';
@@ -399,6 +400,7 @@ import type { IDtoOptionsProductSelectRes } from '../dto/productSelectRes.tsx';
 import type { IDtoOptionsProductSelectResItem } from '../dto/productSelectResItem.tsx';
 import type { IDtoOptionsProductUpdate } from '../dto/productUpdate.tsx';
 import type { IDtoOptionsProductView } from '../dto/productView.tsx';
+import type { IDtoOptionsSkuAttribute } from '../dto/skuAttribute.tsx';
 import type { IDtoOptionsSkuCreate } from '../dto/skuCreate.tsx';
 import type { IDtoOptionsSkuSelectReq } from '../dto/skuSelectReq.tsx';
 import type { IDtoOptionsSkuSelectRes } from '../dto/skuSelectRes.tsx';
@@ -425,6 +427,7 @@ declare module 'vona-module-a-web' {
 'commerce-catalog:productSelectResItem': IDtoOptionsProductSelectResItem;
 'commerce-catalog:productUpdate': IDtoOptionsProductUpdate;
 'commerce-catalog:productView': IDtoOptionsProductView;
+'commerce-catalog:skuAttribute': IDtoOptionsSkuAttribute;
 'commerce-catalog:skuCreate': IDtoOptionsSkuCreate;
 'commerce-catalog:skuSelectReq': IDtoOptionsSkuSelectReq;
 'commerce-catalog:skuSelectRes': IDtoOptionsSkuSelectRes;
@@ -456,6 +459,7 @@ import type { DtoProductSelectRes } from '../dto/productSelectRes.tsx';
 import type { DtoProductSelectResItem } from '../dto/productSelectResItem.tsx';
 import type { DtoProductUpdate } from '../dto/productUpdate.tsx';
 import type { DtoProductView } from '../dto/productView.tsx';
+import type { DtoSkuAttribute } from '../dto/skuAttribute.tsx';
 import type { DtoSkuCreate } from '../dto/skuCreate.tsx';
 import type { DtoSkuSelectReq } from '../dto/skuSelectReq.tsx';
 import type { DtoSkuSelectRes } from '../dto/skuSelectRes.tsx';
@@ -528,6 +532,10 @@ declare module 'vona-module-commerce-catalog' {
       fields?: TypeEntityOptionsFields<DtoProductView, IDtoOptionsProductView[TypeSymbolKeyFieldsMore]>;
     }
 
+    export interface IDtoOptionsSkuAttribute {
+      fields?: TypeEntityOptionsFields<DtoSkuAttribute, IDtoOptionsSkuAttribute[TypeSymbolKeyFieldsMore]>;
+    }
+
     export interface IDtoOptionsSkuCreate {
       fields?: TypeEntityOptionsFields<DtoSkuCreate, IDtoOptionsSkuCreate[TypeSymbolKeyFieldsMore]>;
     }

package/vona/src/suite/a-commerce/modules/commerce-catalog/src/bean/meta.version.ts

@@ -42,6 +42,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate {
         table.tableIdentity(entitySku.productId).comment(entitySku.$comment.productId);
         table.string(entitySku.code, 100).comment(entitySku.$comment.code);
         table.integer(entitySku.priceCents).comment(entitySku.$comment.priceCents);
+        table.json(entitySku.attributes).comment(entitySku.$comment.attributes);
         table.string(entitySku.lifecycle, 20).comment(entitySku.$comment.lifecycle);
         table.index([entitySku.productId], `idx_${entitySku.$table}_productId`);
         table.index([entitySku.lifecycle], `idx_${entitySku.$table}_lifecycle`);

package/vona/src/suite/a-commerce/modules/commerce-catalog/src/config/locale/en-us.ts

@@ -10,6 +10,9 @@ export default {
   ProductTitle: 'Product title',
   Published: 'Published',
   Sku: 'SKU',
+  SkuAttributeName: 'SKU attribute name',
+  SkuAttributeValue: 'SKU attribute value',
+  SkuAttributes: 'SKU attributes',
   SkuCode: 'SKU code',
   SkuLifecycle: 'SKU lifecycle',
   SkuLifecycleActive: 'Active',

package/vona/src/suite/a-commerce/modules/commerce-catalog/src/config/locale/zh-cn.ts

@@ -10,6 +10,9 @@ export default {
   ProductTitle: '商品标题',
   Published: '已发布',
   Sku: 'SKU',
+  SkuAttributeName: 'SKU 属性名',
+  SkuAttributeValue: 'SKU 属性值',
+  SkuAttributes: 'SKU 属性',
   SkuCode: 'SKU 编码',
   SkuLifecycle: 'SKU 生命周期',
   SkuLifecycleActive: '已启用',

package/vona/src/suite/a-commerce/modules/commerce-catalog/src/dto/skuAttribute.tsx

@@ -0,0 +1,17 @@
+import type { IDecoratorDtoOptions } from 'vona-module-a-web';
+
+import { Api, v } from 'vona-module-a-openapiutils';
+import { Dto } from 'vona-module-a-web';
+
+import { $locale } from '../.metadata/locales.ts';
+
+export interface IDtoOptionsSkuAttribute extends IDecoratorDtoOptions {}
+
+@Dto<IDtoOptionsSkuAttribute>()
+export class DtoSkuAttribute {
+  @Api.field(v.title($locale('SkuAttributeName')), v.required(), v.min(1), v.max(100))
+  name: string;
+
+  @Api.field(v.title($locale('SkuAttributeValue')), v.required(), v.min(1), v.max(255))
+  value: string;
+}

package/vona/src/suite/a-commerce/modules/commerce-catalog/src/entity/sku.tsx

@@ -7,6 +7,7 @@ import z from 'zod';
 import { ZovaRender } from 'zova-rest-cabloy-basic-admin';
 
 import { $locale } from '../.metadata/locales.ts';
+import { DtoSkuAttribute } from '../dto/skuAttribute.tsx';
 
 export const skuLifecycleItems = [
   { value: 'draft', title: $locale('SkuLifecycleDraft') },
@@ -56,10 +57,18 @@ export class EntitySku extends EntityBase {
   )
   priceCents: number;
 
+  @Api.field(
+    v.title($locale('SkuAttributes')),
+    v.default([]),
+    v.array(v.object(DtoSkuAttribute)),
+    ZovaRender.order(4),
+  )
+  attributes: DtoSkuAttribute[];
+
   @Api.field(
     v.title($locale('SkuLifecycle')),
     v.default('draft'),
-    ZovaRender.order(4),
+    ZovaRender.order(5),
     z.enum(['draft', 'active', 'inactive', 'archived']),
   )
   lifecycle: 'draft' | 'active' | 'inactive' | 'archived';

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

@@ -448,7 +448,7 @@ describe('catalog.test.ts', () => {
     let foreignCatalog!: Awaited<ReturnType<typeof createCatalog>>;
     await app.bean.executor.mockCtx(
       async () => {
-        foreignCatalog = await createCatalog(`__catalog-relation-foreign-${suffix}__`, 'active');
+        foreignCatalog = await createCatalog(`crf-${suffix}`, 'active');
       },
       { instanceName: 'shareTest' as any },
     );