cabloy 5.1.134 → 5.1.136

package/vona/src/suite/a-commerce/modules/commerce-payment/src/bean/payScene.commerceOrder.ts

@@ -3,36 +3,42 @@ import type {
   IPaymentOutcomeEvent,
   IRefundOutcomeEvent,
 } from 'vona-module-a-pay';
+import type { IPayProviderPaypalClientOptions } from 'vona-module-pay-paypal';
+import type { IPayProviderStripeClientOptions } from 'vona-module-pay-stripe';
 
 import { BeanBase } from 'vona';
 import { PayScene } from 'vona-module-a-pay';
+import 'vona-module-a-ssr';
 
 @PayScene({
   providers: [
     { key: 'mock', providerName: 'pay-mock:mock', clientName: 'default' },
     { key: 'paypal', providerName: 'pay-paypal:paypal', clientName: 'default' },
+    { key: 'stripe', providerName: 'pay-stripe:stripe', clientName: 'default' },
   ],
   isProviderAvailable: (_ctx, input) => {
     if (input.candidate.key === 'mock') return true;
-    if (input.candidate.key !== 'paypal') return false;
     const { clientOptions } = _ctx.bean.payProvider.resolveByName(
       input.candidate.providerName,
       input.candidate.clientName,
     );
-    const options = clientOptions as {
-      secretCredential?: { clientId?: string; clientSecret?: string };
-      webhookId?: string;
-      merchantReference?: string;
-    };
     const server = _ctx.app.config.server.serve;
-    return !!(
-      options.secretCredential?.clientId &&
-      options.secretCredential.clientSecret &&
-      options.webhookId &&
-      options.merchantReference &&
-      server.protocol &&
-      server.host
-    );
+    const hasPublicServer = !!(server.protocol && server.host);
+    if (input.candidate.key === 'paypal') {
+      const options = clientOptions as IPayProviderPaypalClientOptions;
+      return !!(
+        options.secretCredential?.clientId &&
+        options.secretCredential.clientSecret &&
+        options.webhookId &&
+        options.merchantReference &&
+        hasPublicServer
+      );
+    }
+    if (input.candidate.key === 'stripe') {
+      const options = clientOptions as IPayProviderStripeClientOptions;
+      return !!(options.secretCredential && options.secretWebhook && hasPublicServer);
+    }
+    return false;
   },
   resolveProvider: (_ctx, input) => {
     const mock = input.providers.find(item => item.key === 'mock');
@@ -51,7 +57,18 @@ export class PaySceneCommerceOrder extends BeanBase {
   async getPaymentCallbackPath(session: EntityPaymentSession): Promise<string> {
     const attempt = await this.scope.model.paymentAttempt.get({ paymentSessionId: session.id });
     if (!attempt) this.app.throw(404, 'commerce payment attempt not found');
-    return `/commerce/payment/${session.id}/${attempt.orderId}`;
+    const pagePath = this.bean.ssr.getPagePath(
+      'commerce-siteweb:commerce',
+      '/commerce/trade/payment/:paymentSessionId/:orderId',
+      {
+        params: {
+          paymentSessionId: session.id,
+          orderId: attempt.orderId,
+        },
+      },
+    );
+    if (!pagePath) this.app.throw(500, 'commerce SSR Site is unavailable');
+    return pagePath;
   }
 
   async onPaymentOutcome(event: IPaymentOutcomeEvent): Promise<void> {

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

@@ -42,8 +42,14 @@ describe('paymentAttempt.test.ts', { concurrency: false }, () => {
         paymentSessionId = created.paymentSessionId as number;
         assert.equal(created.state, 'created');
         const session = await app.scope('a-pay').model.paymentSession.getById(paymentSessionId);
-        assert.equal(session?.payScene, 'commerce-payment:commerceOrder');
-        assert.equal(session?.providerName, 'pay-mock:mock');
+        assert.ok(session);
+        assert.equal(session.payScene, 'commerce-payment:commerceOrder');
+        assert.equal(session.providerName, 'pay-mock:mock');
+        const payScene = app.bean.payScene.get('commerce-payment:commerceOrder');
+        assert.equal(
+          await payScene.getPaymentCallbackPath(session),
+          `/commerce/commerce/trade/payment/${paymentSessionId}/${created.orderId}`,
+        );
         assert.equal(session?.clientName, 'default');
         assert.equal(session?.environment, 'sandbox');
         assert.match(

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

@@ -51,8 +51,11 @@ declare module 'vona-module-commerce-siteweb' {
           } 
 }
 /** ssrMenu: end */
+/** locale: begin */
+import { locales } from './locales.ts';
+/** locale: end */
 /** scope: begin */
-import { BeanScopeBase, type BeanScopeUtil } from 'vona';
+import { BeanScopeBase, type BeanScopeUtil, type TypeModuleLocales, type TypeLocaleBase } from 'vona';
 import { Scope } from 'vona-module-a-bean';
 
 @Scope()
@@ -60,6 +63,7 @@ export class ScopeModuleCommerceSiteweb extends BeanScopeBase {}
 
 export interface ScopeModuleCommerceSiteweb {
   util: BeanScopeUtil;
+locale: TypeModuleLocales<(typeof locales)[TypeLocaleBase]>;
 }
 
 import 'vona';
@@ -74,7 +78,9 @@ declare module 'vona' {
   
   
 
-  
+  export interface IBeanScopeLocale {
+    'commerce-siteweb': (typeof locales)[TypeLocaleBase];
+  }
 
   
 }

package/vona/src/suite/a-commerce/modules/commerce-siteweb/src/.metadata/locales.ts

@@ -0,0 +1,18 @@
+import type { TypeLocaleBase } from 'vona';
+
+import { $makeLocaleMagic } from 'vona';
+
+import locale_en_us from '../config/locale/en-us.ts';
+import locale_zh_cn from '../config/locale/zh-cn.ts';
+
+export const locales = {
+  'en-us': locale_en_us,
+  'zh-cn': locale_zh_cn,
+};
+
+export function $locale<K extends keyof (typeof locales)[TypeLocaleBase]>(
+  key: K,
+  ...args: any[]
+): any {
+  return $makeLocaleMagic(`commerce-siteweb::${key}`, ...args);
+}

package/vona/src/suite/a-commerce/modules/commerce-siteweb/src/bean/ssrMenu.home.ts

@@ -6,11 +6,13 @@ import { SsrMenu } from 'vona-module-a-ssr';
 
 import type { ISsrSiteOptionsCommerce } from './ssrSite.commerce.ts';
 
+import { $locale } from '../.metadata/locales.ts';
+
 export interface ISsrMenuOptionsHome extends IDecoratorSsrMenuOptions<ISsrSiteOptionsCommerce> {}
 
 @SsrMenu<ISsrMenuOptionsHome>({
   item: {
-    title: 'Commerce',
+    title: $locale('Commerce'),
     order: $order(1),
     icon: undefined,
     link: '/:locale' as never,

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

@@ -0,0 +1,3 @@
+export default {
+  Commerce: 'Commerce',
+};

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

@@ -0,0 +1,3 @@
+export default {
+  Commerce: '商城',
+};

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

@@ -1 +1,2 @@
+export * from './.metadata/locales.ts';
 export * from './.metadata/index.ts';

package/vona/src/suite/a-commerce/modules/commerce-trade/src/controller/checkout.ts

@@ -11,6 +11,17 @@ import { DtoCheckoutResult } from '../dto/checkoutResult.tsx';
 
 export interface IControllerOptionsCheckout extends IDecoratorControllerOptions {}
 
+function getPaymentMethodLabel(key: string): string {
+  switch (key) {
+    case 'paypal':
+      return 'PayPal';
+    case 'stripe':
+      return 'Stripe';
+    default:
+      return 'Mock payment';
+  }
+}
+
 @Controller<IControllerOptionsCheckout>('checkout')
 export class ControllerCheckout extends BeanBase {
   @Web.get('payment-methods')
@@ -22,8 +33,8 @@ export class ControllerCheckout extends BeanBase {
       );
     const items = candidates.map(candidate => ({
       key: candidate.key,
-      label: candidate.key === 'paypal' ? 'PayPal' : 'Mock payment',
-      interaction: candidate.key === 'paypal' ? ('redirect' as const) : ('embedded' as const),
+      label: getPaymentMethodLabel(candidate.key),
+      interaction: candidate.key === 'mock' ? ('embedded' as const) : ('redirect' as const),
     }));
     const defaultKey = items.find(item => item.key === 'mock')?.key ?? items[0]!.key;
     return { items, defaultKey };

package/vona/src/suite/a-commerce/modules/commerce-trade/src/lib/providerReference.ts

@@ -0,0 +1,18 @@
+import { createHash } from 'vona';
+
+const hashEncoding = 'base64url';
+
+export function compactProviderReference(
+  purpose: string,
+  source: string,
+  maxLength: number,
+): string {
+  if (source.length <= maxLength) return source;
+
+  const digest = createHash(`${purpose}\0${source}`, hashEncoding, 'sha256');
+  const reference = `${purpose}:${digest}`;
+  if (reference.length > maxLength) {
+    throw new RangeError('provider reference maximum length is too small');
+  }
+  return reference;
+}

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

@@ -38,8 +38,12 @@ import type { EntityShipment } from '../entity/shipment.tsx';
 import type { ModelOrder } from '../model/order.ts';
 
 import { orderSummaryColumns } from '../lib/order.ts';
+import { compactProviderReference } from '../lib/providerReference.ts';
 
 const maxOrderCents = 2_147_483_647;
+const maxProviderReferenceLength = 100;
+const couponCorrelationSuffix = ':coupon';
+const lateCaptureRefundSuffix = ':refund';
 const customerVisibleOrderStates: EntityOrder['state'][] = [
   'awaiting_payment',
   'paid',
@@ -396,7 +400,16 @@ export class ServiceOrder extends BeanBase {
     if (order.state !== 'awaiting_payment' || lockedAttempt.state !== 'created') {
       this.app.throw(409, 'payment attempt is no longer available');
     }
-    const correlationId = `${order.correlationId}:provider:${event.eventId}`;
+    const idempotencyKey = compactProviderReference(
+      'payment-event',
+      event.eventId,
+      maxProviderReferenceLength,
+    );
+    const correlationId = compactProviderReference(
+      'payment-correlation',
+      `${order.correlationId}:provider:${event.eventId}`,
+      maxProviderReferenceLength - couponCorrelationSuffix.length,
+    );
     const orderState = event.state === 'succeeded' ? 'paid' : 'cancelled';
     const reason = `provider payment ${event.state}`;
     await this.scope.model.order.updateById(order.id, { state: orderState });
@@ -423,7 +436,7 @@ export class ServiceOrder extends BeanBase {
       outcome: event.state,
       fromAttemptState: 'created',
       toOrderState: orderState,
-      idempotencyKey: event.eventId.slice(0, 100),
+      idempotencyKey,
       correlationId,
       reason,
       processedAt: new Date(),
@@ -464,9 +477,14 @@ export class ServiceOrder extends BeanBase {
     ) {
       this.app.throw(409, 'provider event conflicts with the commerce refund attempt');
     }
+    const idempotencyKey = compactProviderReference(
+      'refund-event',
+      event.eventId,
+      maxProviderReferenceLength,
+    );
     const existingAudit = await this.$scope.commercePayment.model.refundAudit.get({
       refundAttemptId: lockedAttempt.id,
-      idempotencyKey: event.eventId.slice(0, 100),
+      idempotencyKey,
     });
     if (existingAudit) return this._refundResult(order, request, lockedAttempt);
     if (
@@ -482,7 +500,11 @@ export class ServiceOrder extends BeanBase {
     const attemptState = isSucceeded ? 'succeeded' : 'failed';
     const refundState = isSucceeded ? 'refunded' : 'failed';
     const orderState = isSucceeded ? 'refunded' : 'paid';
-    const correlationId = `${order.correlationId}:provider-refund:${event.eventId}`;
+    const correlationId = compactProviderReference(
+      'refund-correlation',
+      `${order.correlationId}:provider-refund:${event.eventId}`,
+      maxProviderReferenceLength,
+    );
     const reason = `provider refund ${event.state}`;
     await this.$scope.commercePayment.model.refundAttempt.updateById(lockedAttempt.id, {
       state: attemptState,
@@ -509,7 +531,7 @@ export class ServiceOrder extends BeanBase {
       order,
       toRefundState: refundState,
       attemptState,
-      idempotencyKey: event.eventId.slice(0, 100),
+      idempotencyKey,
       correlationId,
       reason,
     });
@@ -1447,7 +1469,16 @@ export class ServiceOrder extends BeanBase {
     await this.$scope.commercePayment.model.paymentAttempt.updateById(attempt.id, {
       providerCaptureId: event.providerCaptureId,
     });
-    const correlationId = `${order.correlationId}:late-capture:${event.eventId}`;
+    const idempotencyKey = compactProviderReference(
+      'payment-event',
+      event.eventId,
+      maxProviderReferenceLength,
+    );
+    const correlationId = compactProviderReference(
+      'late-capture-correlation',
+      `${order.correlationId}:late-capture:${event.eventId}`,
+      maxProviderReferenceLength - lateCaptureRefundSuffix.length,
+    );
     const existingAudit = await this.$scope.commercePayment.model.paymentAudit.get({
       paymentAttemptId: attempt.id,
       providerEventId: event.eventId,
@@ -1462,7 +1493,7 @@ export class ServiceOrder extends BeanBase {
       outcome: 'succeeded',
       fromAttemptState: attempt.state,
       toOrderState: 'expired',
-      idempotencyKey: event.eventId.slice(0, 100),
+      idempotencyKey,
       correlationId,
       reason: 'late provider capture requires automatic compensation',
       processedAt: new Date(),
@@ -1474,7 +1505,11 @@ export class ServiceOrder extends BeanBase {
       businessReference: `late-capture:${attempt.id}`,
       amountMinor: event.amountMinor,
       currency: event.currency,
-      idempotencyKey: `${correlationId}:refund`,
+      idempotencyKey: compactProviderReference(
+        'late-capture-refund',
+        `${order.correlationId}:late-capture:${event.eventId}${lateCaptureRefundSuffix}`,
+        maxProviderReferenceLength,
+      ),
       correlationId,
     });
     return this._paymentOutcomeResult(order, attempt);

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

@@ -28,9 +28,28 @@ async function cleanup(fixture: IFixture) {
   const member = app.scope('commerce-member');
   const pay = app.scope('a-pay');
   if (fixture.paymentSessionId !== undefined) {
+    const refundOperations = await pay.model.refundOperation.select({
+      where: { paymentSessionId: fixture.paymentSessionId },
+    });
+    for (const refundOperation of refundOperations) {
+      const providerOperation = await pay.model.providerOperation.get({
+        refundOperationId: refundOperation.id,
+        kind: 'refund',
+      });
+      if (providerOperation) {
+        await pay.model.providerOperationRecoveryAudit.delete({
+          providerOperationId: providerOperation.id,
+        });
+      }
+      await pay.model.outboxEvent.delete({ refundOperationId: refundOperation.id });
+      await pay.model.webhookInbox.delete({ refundOperationId: refundOperation.id });
+      await pay.model.providerOperation.delete({ refundOperationId: refundOperation.id });
+      await pay.model.refundOperation.delete({ id: refundOperation.id });
+    }
     await pay.model.outboxEvent.delete({ paymentSessionId: fixture.paymentSessionId });
     await pay.model.paymentAudit.delete({ paymentSessionId: fixture.paymentSessionId });
     await pay.model.webhookInbox.delete({ paymentSessionId: fixture.paymentSessionId });
+    await pay.model.providerOperation.delete({ paymentSessionId: fixture.paymentSessionId });
   }
   if (fixture.paymentAttemptId !== undefined)
     await payment.model.paymentAudit.delete({ paymentAttemptId: fixture.paymentAttemptId });
@@ -307,6 +326,61 @@ describe('paymentOutcome.test.ts', { concurrency: false, sequential: true }, ()
     });
   });
 
+  it('keeps long provider event references distinct and replays the same event once', async () => {
+    const sharedPrefix = 'provider-event-'.padEnd(100, 'x');
+    const firstEventId = `${sharedPrefix}A`;
+    const secondEventId = `${sharedPrefix}B`;
+    const fixtures: IFixture[] = [];
+    try {
+      for (const [index, eventId] of [firstEventId, secondEventId].entries()) {
+        await app.bean.executor.mockCtx(async () => {
+          const fixture = await createCheckoutFixture(randomUUID().slice(0, 12));
+          fixtures.push(fixture);
+          await app.bean.passport.signout();
+          const event = {
+            eventId,
+            paymentSessionId: fixture.paymentSessionId!,
+            businessReference: String(fixture.paymentAttemptId),
+            providerName: 'pay-mock:mock',
+            state: 'succeeded' as const,
+            providerCaptureId: `capture-${index}`,
+            amountMinor: 799,
+            currency: 'USD',
+          };
+          const order = app.scope('commerce-trade').service.order;
+          await order.settlePaymentFromProvider(event);
+          await order.settlePaymentFromProvider(event);
+          const [audit] = await app.scope('commerce-payment').model.paymentAudit.select({
+            where: { paymentAttemptId: fixture.paymentAttemptId },
+          });
+          assert.equal(audit?.providerEventId, eventId);
+          assert.ok(audit?.idempotencyKey.length <= 100);
+          assert.ok(audit?.correlationId.length <= 100);
+        });
+      }
+      await app.bean.executor.mockCtx(async () => {
+        const audits = await Promise.all(
+          fixtures.map(async fixture => {
+            return (
+              await app.scope('commerce-payment').model.paymentAudit.select({
+                where: { paymentAttemptId: fixture.paymentAttemptId },
+              })
+            )[0];
+          }),
+        );
+        assert.equal(audits.filter(Boolean).length, 2);
+        assert.notEqual(audits[0]?.idempotencyKey, audits[1]?.idempotencyKey);
+        assert.notEqual(audits[0]?.correlationId, audits[1]?.correlationId);
+      });
+    } finally {
+      for (const fixture of fixtures.reverse()) {
+        await app.bean.executor.mockCtx(async () => {
+          await cleanup(fixture);
+        });
+      }
+    }
+  });
+
   it('settles a provider event without customer Passport authority', async () => {
     await app.bean.executor.mockCtx(async () => {
       const fixture: IFixture = {};

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

@@ -0,0 +1,33 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import { compactProviderReference } from '../src/lib/providerReference.ts';
+
+describe('providerReference.test.ts', () => {
+  it('keeps fitting values and compacts long values with a domain-separated digest', () => {
+    const maxLength = 100;
+    const sharedPrefix = 'provider-event-'.padEnd(100, 'x');
+    const first = `${sharedPrefix}A`;
+    const second = `${sharedPrefix}B`;
+
+    assert.equal(compactProviderReference('payment-event', 'event-1', maxLength), 'event-1');
+    assert.equal(
+      compactProviderReference('payment-event', 'x'.repeat(maxLength), maxLength),
+      'x'.repeat(maxLength),
+    );
+
+    const reference = compactProviderReference('payment-event', first, maxLength);
+    assert.equal(reference.length, 'payment-event:'.length + 43);
+    assert.equal(reference, compactProviderReference('payment-event', first, maxLength));
+    assert.notEqual(reference, compactProviderReference('payment-event', second, maxLength));
+    assert.notEqual(reference, compactProviderReference('refund-event', first, maxLength));
+    assert.match(reference, /^payment-event:[\w-]{43}$/);
+  });
+
+  it('rejects a maximum length that cannot hold its compact reference', () => {
+    assert.throws(
+      () => compactProviderReference('payment-event', 'x'.repeat(101), 10),
+      /maximum length is too small/,
+    );
+  });
+});

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

@@ -384,6 +384,79 @@ describe('refundLifecycle.test.ts', { concurrency: false, sequential: true }, ()
     });
   });
 
+  it('keeps long provider refund event references distinct and replays the same event once', async () => {
+    const sharedPrefix = 'provider-refund-event-'.padEnd(100, 'x');
+    const eventIds = [`${sharedPrefix}A`, `${sharedPrefix}B`];
+    const fixtures: IFixture[] = [];
+    try {
+      for (const [index, eventId] of eventIds.entries()) {
+        await app.bean.executor.mockCtx(async () => {
+          const fixture = await createPaidOrder(randomUUID().slice(0, 12));
+          fixtures.push(fixture);
+          const order = app.scope('commerce-trade').service.order;
+          await order.requestRefund(fixture.orderId!, {
+            reason: 'long provider event',
+            idempotencyKey: `long-event-request-${index}`,
+          });
+          await app.bean.passport.signout();
+          await app.bean.passport.signinMock();
+          const approved = await order.approveRefund(fixture.orderId!, {
+            reason: 'long provider event approved',
+            idempotencyKey: `long-event-approve-${index}`,
+          });
+          const executed = await order.executeRefund(fixture.orderId!);
+          const event = {
+            eventId,
+            paymentSessionId: fixture.paymentSessionId!,
+            refundOperationId: executed.refundOperationId!,
+            businessReference: String(executed.refundAttemptId),
+            providerName: 'pay-mock:mock',
+            state: 'failed' as const,
+            providerRefundId: `provider-refund-${index}`,
+            amountMinor: 799,
+            currency: 'USD',
+          };
+          const first = await order.settleRefundFromProvider(event);
+          const replay = await order.settleRefundFromProvider(event);
+          assert.deepEqual(replay, first);
+          assert.deepEqual(
+            [first.orderState, first.refundState, first.refundAttemptState],
+            ['paid', 'failed', 'failed'],
+          );
+          const audits = await app.scope('commerce-payment').model.refundAudit.select({
+            where: { refundRequestId: approved.refundRequestId },
+          });
+          const [audit] = audits.filter(item => item.toRefundState === 'failed');
+          assert.equal(audit?.idempotencyKey.length <= 100, true);
+          assert.equal(audit?.correlationId.length <= 100, true);
+        });
+      }
+      await app.bean.executor.mockCtx(async () => {
+        const failedAudits = await Promise.all(
+          fixtures.map(async fixture => {
+            const request = await app.scope('commerce-payment').model.refundRequest.get({
+              orderId: fixture.orderId,
+            });
+            return (
+              await app.scope('commerce-payment').model.refundAudit.select({
+                where: { refundRequestId: request?.id },
+              })
+            ).find(item => item.toRefundState === 'failed');
+          }),
+        );
+        assert.notEqual(failedAudits[0]?.idempotencyKey, failedAudits[1]?.idempotencyKey);
+        assert.notEqual(failedAudits[0]?.correlationId, failedAudits[1]?.correlationId);
+      });
+    } finally {
+      for (const fixture of fixtures.reverse()) {
+        await app.bean.executor.mockCtx(async () => {
+          await app.bean.passport.signout();
+          await cleanup(fixture);
+        });
+      }
+    }
+  });
+
   it('settles an executed mock-provider refund through the durable outbox', async () => {
     await app.bean.executor.mockCtx(async () => {
       const fixture: IFixture = {};

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

@@ -362,6 +362,7 @@ describe('reservationExpiry.test.ts', { concurrency: false, sequential: true },
           .execute();
         const audits = await app.scope('commerce-trade').model.orderAudit.select({
           where: { orderId: defaultFixture!.orderId! },
+          orders: [['id', 'asc']],
         });
         assert.deepEqual(
           audits.map(audit => audit.operation),
@@ -412,6 +413,7 @@ describe('reservationExpiry.test.ts', { concurrency: false, sequential: true },
             .execute();
           const audits = await app.scope('commerce-trade').model.orderAudit.select({
             where: { orderId: shareFixture!.orderId! },
+            orders: [['id', 'asc']],
           });
           assert.deepEqual(
             audits.map(audit => audit.operation),

package/vona/src/suite/a-home/modules/home-user/src/.metadata/index.ts

@@ -152,7 +152,17 @@ declare module 'vona-module-home-user' {
       [SymbolKeyEntityMeta]: EntityRoleMeta;
       [SymbolKeyModelOptions]: IModelOptionsRole;
       get<T extends IModelGetOptions<EntityRole,ModelRole>>(where: TypeModelWhere<EntityRole>, options?: T): Promise<TypeModelRelationResult<EntityRole, ModelRole, T> | undefined>;
+      /**
+       * Retrieves one matching primary row with a pessimistic FOR UPDATE lock.
+       * Requires an active transaction. The lock is released when that transaction completes.
+       * Entity and query caches are bypassed.
+       */
       getForUpdate<T extends IModelGetOptions<EntityRole,ModelRole>>(where: TypeModelWhere<EntityRole>, options?: T): Promise<TypeModelRelationResult<EntityRole, ModelRole, T> | undefined>;
+      /**
+       * Retrieves a primary row by ID with the same pessimistic FOR UPDATE lock semantics.
+       * Requires an active transaction. The lock is released when that transaction completes.
+       * Entity and query caches are bypassed.
+       */
       getByIdForUpdate<T extends IModelGetOptions<EntityRole,ModelRole>>(id: TableIdentity, options?: T): Promise<TypeModelRelationResult<EntityRole, ModelRole, T> | undefined>;
       mget<T extends IModelGetOptions<EntityRole,ModelRole>>(ids: TableIdentity[], options?: T): Promise<TypeModelRelationResult<EntityRole, ModelRole, T>[]>;
       selectAndCount<T extends IModelSelectParams<EntityRole,ModelRole,ModelJoins>, ModelJoins extends TypeModelsClassLikeGeneral | undefined = undefined>(params?: T, options?: IModelMethodOptions, modelJoins?: ModelJoins): Promise<TypeModelSelectAndCount<EntityRole, ModelRole, T>>;
@@ -183,7 +193,17 @@ export interface ModelRoleUser {
       [SymbolKeyEntityMeta]: EntityRoleUserMeta;
       [SymbolKeyModelOptions]: IModelOptionsRoleUser;
       get<T extends IModelGetOptions<EntityRoleUser,ModelRoleUser>>(where: TypeModelWhere<EntityRoleUser>, options?: T): Promise<TypeModelRelationResult<EntityRoleUser, ModelRoleUser, T> | undefined>;
+      /**
+       * Retrieves one matching primary row with a pessimistic FOR UPDATE lock.
+       * Requires an active transaction. The lock is released when that transaction completes.
+       * Entity and query caches are bypassed.
+       */
       getForUpdate<T extends IModelGetOptions<EntityRoleUser,ModelRoleUser>>(where: TypeModelWhere<EntityRoleUser>, options?: T): Promise<TypeModelRelationResult<EntityRoleUser, ModelRoleUser, T> | undefined>;
+      /**
+       * Retrieves a primary row by ID with the same pessimistic FOR UPDATE lock semantics.
+       * Requires an active transaction. The lock is released when that transaction completes.
+       * Entity and query caches are bypassed.
+       */
       getByIdForUpdate<T extends IModelGetOptions<EntityRoleUser,ModelRoleUser>>(id: TableIdentity, options?: T): Promise<TypeModelRelationResult<EntityRoleUser, ModelRoleUser, T> | undefined>;
       mget<T extends IModelGetOptions<EntityRoleUser,ModelRoleUser>>(ids: TableIdentity[], options?: T): Promise<TypeModelRelationResult<EntityRoleUser, ModelRoleUser, T>[]>;
       selectAndCount<T extends IModelSelectParams<EntityRoleUser,ModelRoleUser,ModelJoins>, ModelJoins extends TypeModelsClassLikeGeneral | undefined = undefined>(params?: T, options?: IModelMethodOptions, modelJoins?: ModelJoins): Promise<TypeModelSelectAndCount<EntityRoleUser, ModelRoleUser, T>>;
@@ -210,7 +230,17 @@ export interface ModelUser {
       [SymbolKeyEntityMeta]: EntityUserMeta;
       [SymbolKeyModelOptions]: IModelOptionsUser;
       get<T extends IModelGetOptions<EntityUser,ModelUser>>(where: TypeModelWhere<EntityUser>, options?: T): Promise<TypeModelRelationResult<EntityUser, ModelUser, T> | undefined>;
+      /**
+       * Retrieves one matching primary row with a pessimistic FOR UPDATE lock.
+       * Requires an active transaction. The lock is released when that transaction completes.
+       * Entity and query caches are bypassed.
+       */
       getForUpdate<T extends IModelGetOptions<EntityUser,ModelUser>>(where: TypeModelWhere<EntityUser>, options?: T): Promise<TypeModelRelationResult<EntityUser, ModelUser, T> | undefined>;
+      /**
+       * Retrieves a primary row by ID with the same pessimistic FOR UPDATE lock semantics.
+       * Requires an active transaction. The lock is released when that transaction completes.
+       * Entity and query caches are bypassed.
+       */
       getByIdForUpdate<T extends IModelGetOptions<EntityUser,ModelUser>>(id: TableIdentity, options?: T): Promise<TypeModelRelationResult<EntityUser, ModelUser, T> | undefined>;
       mget<T extends IModelGetOptions<EntityUser,ModelUser>>(ids: TableIdentity[], options?: T): Promise<TypeModelRelationResult<EntityUser, ModelUser, T>[]>;
       selectAndCount<T extends IModelSelectParams<EntityUser,ModelUser,ModelJoins>, ModelJoins extends TypeModelsClassLikeGeneral | undefined = undefined>(params?: T, options?: IModelMethodOptions, modelJoins?: ModelJoins): Promise<TypeModelSelectAndCount<EntityUser, ModelUser, T>>;

package/vona/src/suite/a-home/modules/home-user/src/bean/meta.version.ts

@@ -19,7 +19,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate, IMetaVe
         table.basicFields();
         table.string(entityRole.name, 255).comment(entityRole.$comment.name);
         table.string(entityRole.title, 255).comment(entityRole.$comment.title);
-        table.json(entityRole.locales).comment(entityRole.$comment.locales);
+        table.json(entityRole.titleLocales).comment(entityRole.$comment.titleLocales);
         table.json(entityRole.siteIds).comment(entityRole.$comment.siteIds);
       });
       // homeUser
@@ -35,6 +35,11 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate, IMetaVe
           .boolean(entityUser.activated)
           .defaultTo(entityUser.$default.activated)
           .comment(entityUser.$comment.activated);
+        table
+          .string(entityUser.accountStatus, 255)
+          .notNullable()
+          .defaultTo(entityUser.$default.accountStatus)
+          .comment(entityUser.$comment.accountStatus);
         table.string(entityUser.locale, 255).comment(entityUser.$comment.locale);
         table.string(entityUser.tz, 255).comment(entityUser.$comment.tz);
       });
@@ -55,7 +60,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate, IMetaVe
         await this.scope.model.role.insert({
           name,
           title: role.title,
-          locales: role.locales ?? {},
+          titleLocales: role.titleLocales ?? {},
           siteIds: role.siteIds,
         });
       }

package/vona/src/suite/a-home/modules/home-user/src/config/locale/en-us.ts

@@ -11,7 +11,10 @@ export default {
   UserAvatar: 'Avatar',
   UserEmail: 'Email',
   UserMobile: 'Mobile',
-  UserActivated: 'Activated',
+  UserActivated: 'Identity Activated',
+  UserAccountStatus: 'Account Status',
+  UserAccountStatusActive: 'Active',
+  UserAccountStatusDisabled: 'Disabled',
   UserLocale: 'Language',
   UserTz: 'Timezone',
   UsernameExists: 'Username Exists',