cabloy 5.1.106 → 5.1.107

package/.cabloy-version

@@ -1 +1 @@
-5.1.106
+5.1.107

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 5.1.107
+
+### Features
+
+- Localize persisted home roles.
+- Define response contracts for resource mutations, including null responses.
+- Secure generated CRUD actions.
+
+### Improvements
+
+- Clarify built-in role configuration.
+
 ## 5.1.106
 
 ### Improvements

package/cabloy-docs/backend/backend-resource-module-contract-chain.md

@@ -143,6 +143,7 @@ Representative source facts from this file:
 - the class is decorated with `@Controller<IControllerOptionsStudent>('student')`
 - the class is also decorated with `@Resource()`
 - CRUD actions are declared with `@Web.post()`, `@Web.get()`, `@Web.get(':id')`, `@Web.patch(':id')`, and `@Web.delete(':id')`
+- the standard CRUD actions and the `summary` / `deleteForce` management actions explicitly use `@Passport.systemAdmin()`
 - request shapes use `@Arg.body(...)`, `@Arg.param(...)`, and `@Arg.filter(...)`
 - actions delegate to `this.scope.service.student`
 

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

@@ -99,6 +99,18 @@ Typical jobs include:
 
 These shorthands still map back to the generic aspect model.
 
+### Passport inheritance and action policy
+
+The global Passport guard is the baseline for controller actions: without a local Passport decorator, an action requires an authenticated and activated user. It is not public.
+
+Use a local Passport or domain guard when an action needs a policy beyond that baseline:
+
+- use `@Passport.public()` only when anonymous access is intentional
+- use `@Passport.systemAdmin()`, `@Passport.roleName(...)`, or a domain-specific guard when access needs additional restriction
+- leave an action without a local Passport guard when authenticated-and-activated access is intentionally sufficient
+
+The CRUD generator applies `@Passport.systemAdmin()` to each generated CRUD action rather than to the controller class. This keeps the administrative default explicit while allowing a future custom action to deliberately inherit the baseline or define its own policy.
+
 For the underlying auth, passport, and user-access model, see [Auth Guide](/backend/auth-guide) and [User Access Guide](/backend/user-access-guide).
 
 ## Interceptor

package/cabloy-docs/backend/controller-guide.md

@@ -148,11 +148,11 @@ Representative pattern:
 
 ```typescript
 @Web.patch('updateUser/:id')
-updateUser(
+async updateUser(
   @Arg.param('id') id: TableIdentity,
   @Arg.body(v.object(DtoUserUpdate)) user: DtoUserUpdate,
-) {
-  return this.scope.model.user.update(user, { where: { id } });
+): Promise<void> {
+  await this.scope.service.user.update(id, user);
 }
 ```
 
@@ -208,6 +208,48 @@ A practical rule is:
 - use return-type inference when the contract is obvious and simple
 - use explicit `@Api.body(...)` when the response shape needs more control or the inference boundary becomes unclear
 
+## Resource mutation response contract
+
+Standard resource `update` and `delete` actions are command-style actions. Their public contract is successful completion, not an implicit persistence-model payload.
+
+Representative pattern:
+
+```typescript
+import { z } from 'zod';
+
+@Web.patch(':id')
+@Api.body(z.null())
+@Passport.systemAdmin()
+async update(
+  @Arg.param('id', v.tableIdentity()) id: TableIdentity,
+  @Arg.body() student: DtoStudentUpdate,
+): Promise<void> {
+  await this.scope.service.student.update(id, student);
+}
+```
+
+Use `await` without `return` at the controller boundary. A service or model may still return mutation data for internal orchestration, but that data is not automatically a stable public representation of the resource.
+
+`Promise<void>` expresses the controller's command semantics, while `@Api.body(z.null())` explicitly supplies the response schema that runtime reflection cannot recover from `Promise<void>`. It makes the existing no-payload response visible to emitted OpenAPI and generated SDK consumers.
+
+For a standard JSON action, Vona maps this no-result controller completion to its normal HTTP `200` success wrapper:
+
+```typescript
+{
+  code: 0,
+  message: 'success',
+  data: null,
+}
+```
+
+This is Vona's default resource-mutation convention. It does not use HTTP `204 No Content`, so consumers can keep one uniform success-envelope protocol.
+
+### When a mutation should return data
+
+Return data only when it is an intentional consumer-facing contract, such as an updated response DTO, a version token, or a job handle. Declare that shape explicitly with `@Api.body(...)`; add `@Core.serializer()` when the response depends on serializer transforms, exclusions, getters, or replacements. Do not forward raw ORM or service mutation results merely because the delegated method returns a value.
+
+`create` and read actions commonly expose an identity or DTO and therefore use their own explicit response contracts. For generated resource defaults, see [CRUD Workflow](/backend/crud-workflow#generated-mutation-response-default). For action-level verification, see [Unit Testing](/backend/unit-testing#testing-controllers-through-actions). When a declared response shape changes, follow the [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) contract loop.
+
 ## Response wrapper behavior
 
 By default, Vona wraps the response body in a standard wrapper object.

package/cabloy-docs/backend/crud-workflow.md

@@ -43,6 +43,20 @@ The generator creates a connected set of files, typically including:
 
 This is exactly why this generator should be the default starting point. It gives a consistent starting shape across the backend thread.
 
+### Generated authorization default
+
+The standard generated CRUD actions (`create`, `select`, `view`, `update`, and `delete`) each use `@Passport.systemAdmin()`. This is an explicit administrative whitelist for the generated Admin resource API, matching the generated SSR menu's `systemAdmin` visibility policy.
+
+The guard is attached to individual actions rather than the controller class. When you add a custom action later, no local Passport guard intentionally means the global authenticated-and-activated baseline applies; it does not mean the action is public. Use `@Passport.public()` to intentionally allow anonymous access, or add a role/domain guard when an action needs stronger restriction.
+
+SSR menu roles control navigation disclosure only. They never authorize a controller action, API, or resource; keep the action guard as the server-side authorization boundary. See [Controller AOP Guide](/backend/controller-aop-guide) and [Menu Guide](/backend/menu-guide).
+
+### Generated mutation response default
+
+Generated resource `update` and `delete` actions are command-style actions. Their controllers use `Promise<void>`, await the service call without forwarding its result, and declare `@Api.body(z.null())` so OpenAPI and generated SDKs describe the normal HTTP `200` success wrapper accurately as `data: null`.
+
+This controller-facing default does not require the service or model mutation method to return `void`. Those lower layers may retain mutation data for internal orchestration. See [Controller Guide](/backend/controller-guide#resource-mutation-response-contract) when a mutation deliberately needs a consumer-facing response payload.
+
 A practical generated-output checklist usually includes:
 
 - controller

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

@@ -121,13 +121,19 @@ A practical rule is:
 A representative contract-verification pattern is:
 
 ```typescript
-await app.bean.executor.performAction('patch', '/test/rest/product/:id', {
+const updateRes = await app.bean.executor.performAction('patch', '/test/rest/product/:id', {
   params: { id: productId },
   body: dataUpdate,
 });
+assert.equal(updateRes, null);
+
+const deleteRes = await app.bean.executor.performAction('delete', '/test/rest/product/:id', {
+  params: { id: productId },
+});
+assert.equal(deleteRes, null);
 ```
 
-This is a good default because the same test can exercise params, body, route wiring, validation, and response behavior together.
+For standard resource command mutations, these assertions verify the controller-facing no-payload runtime contract. Follow them with a query/read-back assertion to verify the persisted update or deletion. When the API is generated for frontend consumers, add a focused OpenAPI structural assertion that its wrapped response schema declares `data: null`; this verifies SDK-contract fidelity separately from responder behavior. The same test then exercises params, body, route wiring, validation, response behavior, and persistence effects together.
 
 ## Authentication simulation
 

package/cabloy-docs/fullstack/openapi-to-sdk.md

@@ -68,6 +68,7 @@ For the deeper frontend perspective, see:
 If you want the shortest accurate mental model, use this forward chain:
 
 1. backend controller signatures define request and response entry surfaces
+   - command-style mutations that complete with Vona's wrapped `data: null` must declare `@Api.body(z.null())`; `Promise<void>` alone cannot preserve that generic type through runtime reflection
 2. backend DTO and entity fields shape named and shared contract structure
 3. validation rules and `v` helpers refine the machine-readable contract
 4. Vona emits OpenAPI output from those backend declarations

package/cabloy-docs/fullstack/tutorial-2-first-crud.md

@@ -95,6 +95,9 @@ As you inspect the generated files, pay attention to the division of responsibil
 
 This is the backend contract thread that later tutorials will extend with `level`, `mobile`, render metadata, OpenAPI output, and row actions.
 
+> [!NOTE]
+> The generated Admin CRUD actions explicitly require the `systemAdmin` role. If this resource should serve another audience, adjust the relevant controller action guards as well as any SSR menu visibility; changing the menu alone does not authorize an API.
+
 ## Verification
 
 1. make sure the local dev workflow is running:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.106",
+  "version": "5.1.107",
   "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.129",
+  "version": "1.1.130",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/cli/templates/tools/crud/boilerplate/src/bean/ssrMenu.{{resourceName}}.ts_

@@ -20,6 +20,7 @@ export interface ISsrMenuOptions<%=argv.resourceNameCapitalize%> extends IDecora
         },
       },
       group: '<%=argv.ssrSiteGroupName%>',
+      roles: ['systemAdmin'],
     },
   },
   site: ['<%=argv.ssrSiteOnionName%>'],

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudBasic/boilerplate/src/controller/{{resourceName}}.ts_

@@ -4,6 +4,8 @@ import type { IDecoratorControllerOptions } from 'vona-module-a-web';
 
 import { BeanBase } from 'vona';
 import { Api, Resource, v } from 'vona-module-a-openapiutils';
+import { z } from 'zod';
+import { Passport } from 'vona-module-a-user';
 import { Arg, Controller, Web } from 'vona-module-a-web';
 
 import type { Model<%=argv.resourceNameCapitalize%> } from '../model/<%=argv.resourceName%>.ts';
@@ -21,29 +23,36 @@ export interface IControllerOptions<%=argv.resourceNameCapitalize%> extends IDec
 export class Controller<%=argv.resourceNameCapitalize%> extends BeanBase {
   @Web.post()
   @Api.body(v.tableIdentity())
+  @Passport.systemAdmin()
   async create(@Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Create): Promise<TableIdentity> {
     return (await this.scope.service.<%=argv.resourceName%>.create(<%=argv.resourceName%>)).id;
   }
 
   @Web.get()
   @Api.body(Dto<%=argv.resourceNameCapitalize%>SelectRes)
+  @Passport.systemAdmin()
   async select(@Arg.filter(Dto<%=argv.resourceNameCapitalize%>SelectReq) params: IQueryParams<Model<%=argv.resourceNameCapitalize%>>): Promise<Dto<%=argv.resourceNameCapitalize%>SelectRes> {
     return await this.scope.service.<%=argv.resourceName%>.select(params);
   }
 
   @Web.get(':id')
   @Api.body(v.optional(), v.object(Dto<%=argv.resourceNameCapitalize%>View))
+  @Passport.systemAdmin()
   async view(@Arg.param('id', v.tableIdentity()) id: TableIdentity): Promise<Dto<%=argv.resourceNameCapitalize%>View | undefined> {
     return await this.scope.service.<%=argv.resourceName%>.view(id);
   }
 
   @Web.patch(':id')
-  async update(@Arg.param('id', v.tableIdentity()) id: TableIdentity, @Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Update) {
-    return await this.scope.service.<%=argv.resourceName%>.update(id, <%=argv.resourceName%>);
+  @Api.body(z.null())
+  @Passport.systemAdmin()
+  async update(@Arg.param('id', v.tableIdentity()) id: TableIdentity, @Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Update): Promise<void> {
+    await this.scope.service.<%=argv.resourceName%>.update(id, <%=argv.resourceName%>);
   }
 
   @Web.delete(':id')
-  async delete(@Arg.param('id', v.tableIdentity()) id: TableIdentity) {
-    return await this.scope.service.<%=argv.resourceName%>.delete(id);
+  @Api.body(z.null())
+  @Passport.systemAdmin()
+  async delete(@Arg.param('id', v.tableIdentity()) id: TableIdentity): Promise<void> {
+    await this.scope.service.<%=argv.resourceName%>.delete(id);
   }
 }

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudBasic/boilerplate/test/{{resourceName}}.test.ts_

@@ -15,7 +15,24 @@ describe('<%=argv.resourceName%>.test.ts', () => {
         name: '__TomNew__',
         description: 'This is a test',
       };
-      // login
+      // role-less authenticated users cannot access generated admin actions
+      await app.bean.passport.signinMock();
+      try {
+        app.bean.passport.current!.roles = [];
+        const actions = ['create', 'select', 'view', 'update', 'delete'];
+        const permissions = await Promise.all(
+          actions.map(action =>
+            app.bean.permission.retrievePermissionAction(
+              '<%=argv.moduleInfo.relativeName%>:<%=argv.resourceName%>',
+              action,
+            ),
+          ),
+        );
+        assert.deepEqual(permissions, actions.map(() => false));
+      } finally {
+        await app.bean.passport.signout();
+      }
+      // login as system admin
       await app.bean.passport.signinMock();
       // create
       const <%=argv.resourceName%>Id = await app.bean.executor.performAction('post', '<%=argv.moduleActionPathRaw%>', { body: data });
@@ -24,15 +41,17 @@ describe('<%=argv.resourceName%>.test.ts', () => {
       const selectRes: Dto<%=argv.resourceNameCapitalize%>SelectRes = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>');
       assert.equal(selectRes.list.findIndex(item => item.name === data.name) > -1, true);
       // update
-      await app.bean.executor.performAction('patch', '<%=argv.moduleActionPathRaw%>/:id', {
+      const updateRes = await app.bean.executor.performAction('patch', '<%=argv.moduleActionPathRaw%>/:id', {
         params: { id: <%=argv.resourceName%>Id },
         body: dataUpdate,
       });
+      assert.equal(updateRes, null);
       // findOne
       let <%=argv.resourceName%>: Entity<%=argv.resourceNameCapitalize%> = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>Id } });
       assert.equal(<%=argv.resourceName%>.name, dataUpdate.name);
       // delete
-      await app.bean.executor.performAction('delete', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
+      const deleteRes = await app.bean.executor.performAction('delete', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
+      assert.equal(deleteRes, null);
       // findOne
       <%=argv.resourceName%> = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
       assert.equal(<%=argv.resourceName%>, undefined);

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudStart/boilerplate/src/controller/{{resourceName}}.ts_

@@ -4,6 +4,8 @@ import type { IDecoratorControllerOptions } from 'vona-module-a-web';
 
 import { BeanBase } from 'vona';
 import { Api, Resource, v } from 'vona-module-a-openapiutils';
+import { z } from 'zod';
+import { Passport } from 'vona-module-a-user';
 import { Arg, Controller, Web } from 'vona-module-a-web';
 
 import type { Model<%=argv.resourceNameCapitalize%> } from '../model/<%=argv.resourceName%>.ts';
@@ -21,29 +23,36 @@ export interface IControllerOptions<%=argv.resourceNameCapitalize%> extends IDec
 export class Controller<%=argv.resourceNameCapitalize%> extends BeanBase {
   @Web.post()
   @Api.body(v.tableIdentity())
+  @Passport.systemAdmin()
   async create(@Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Create): Promise<TableIdentity> {
     return (await this.scope.service.<%=argv.resourceName%>.create(<%=argv.resourceName%>)).id;
   }
 
   @Web.get()
   @Api.body(Dto<%=argv.resourceNameCapitalize%>SelectRes)
+  @Passport.systemAdmin()
   async select(@Arg.filter(Dto<%=argv.resourceNameCapitalize%>SelectReq) params: IQueryParams<Model<%=argv.resourceNameCapitalize%>>): Promise<Dto<%=argv.resourceNameCapitalize%>SelectRes> {
     return await this.scope.service.<%=argv.resourceName%>.select(params);
   }
 
   @Web.get(':id')
   @Api.body(v.optional(), v.object(Dto<%=argv.resourceNameCapitalize%>View))
+  @Passport.systemAdmin()
   async view(@Arg.param('id', v.tableIdentity()) id: TableIdentity): Promise<Dto<%=argv.resourceNameCapitalize%>View | undefined> {
     return await this.scope.service.<%=argv.resourceName%>.view(id);
   }
 
   @Web.patch(':id')
-  async update(@Arg.param('id', v.tableIdentity()) id: TableIdentity, @Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Update) {
-    return await this.scope.service.<%=argv.resourceName%>.update(id, <%=argv.resourceName%>);
+  @Api.body(z.null())
+  @Passport.systemAdmin()
+  async update(@Arg.param('id', v.tableIdentity()) id: TableIdentity, @Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Update): Promise<void> {
+    await this.scope.service.<%=argv.resourceName%>.update(id, <%=argv.resourceName%>);
   }
 
   @Web.delete(':id')
-  async delete(@Arg.param('id', v.tableIdentity()) id: TableIdentity) {
-    return await this.scope.service.<%=argv.resourceName%>.delete(id);
+  @Api.body(z.null())
+  @Passport.systemAdmin()
+  async delete(@Arg.param('id', v.tableIdentity()) id: TableIdentity): Promise<void> {
+    await this.scope.service.<%=argv.resourceName%>.delete(id);
   }
 }

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudStart/boilerplate/test/{{resourceName}}.test.ts_

@@ -15,7 +15,24 @@ describe('<%=argv.resourceName%>.test.ts', () => {
         name: '__TomNew__',
         description: 'This is a test',
       };
-      // login
+      // role-less authenticated users cannot access generated admin actions
+      await app.bean.passport.signinMock();
+      try {
+        app.bean.passport.current!.roles = [];
+        const actions = ['create', 'select', 'view', 'update', 'delete'];
+        const permissions = await Promise.all(
+          actions.map(action =>
+            app.bean.permission.retrievePermissionAction(
+              '<%=argv.moduleInfo.relativeName%>:<%=argv.resourceName%>',
+              action,
+            ),
+          ),
+        );
+        assert.deepEqual(permissions, actions.map(() => false));
+      } finally {
+        await app.bean.passport.signout();
+      }
+      // login as system admin
       await app.bean.passport.signinMock();
       // create
       const <%=argv.resourceName%>Id = await app.bean.executor.performAction('post', '<%=argv.moduleActionPathRaw%>', { body: data });
@@ -24,15 +41,17 @@ describe('<%=argv.resourceName%>.test.ts', () => {
       const selectRes: Dto<%=argv.resourceNameCapitalize%>SelectRes = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>');
       assert.equal(selectRes.list.findIndex(item => item.name === data.name) > -1, true);
       // update
-      await app.bean.executor.performAction('patch', '<%=argv.moduleActionPathRaw%>/:id', {
+      const updateRes = await app.bean.executor.performAction('patch', '<%=argv.moduleActionPathRaw%>/:id', {
         params: { id: <%=argv.resourceName%>Id },
         body: dataUpdate,
       });
+      assert.equal(updateRes, null);
       // findOne
       let <%=argv.resourceName%>: Entity<%=argv.resourceNameCapitalize%> = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>Id } });
       assert.equal(<%=argv.resourceName%>.name, dataUpdate.name);
       // delete
-      await app.bean.executor.performAction('delete', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
+      const deleteRes = await app.bean.executor.performAction('delete', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
+      assert.equal(deleteRes, null);
       // findOne
       <%=argv.resourceName%> = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
       assert.equal(<%=argv.resourceName%>, undefined);

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

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

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

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

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

@@ -144,7 +144,7 @@ import { SymbolKeyEntity, SymbolKeyEntityMeta, SymbolKeyModelOptions } from 'von
 declare module 'vona-module-home-user' {
   export interface IModelOptionsUser {
         relations: {
-          roles: IModelRelationBelongsToMany<ModelRoleUser, ModelRole, false, undefined,undefined,undefined,undefined>;
+          roles: IModelRelationBelongsToMany<'home-user:roleUser', 'home-user:role', false, undefined,undefined,undefined,undefined>;
         };
       }
   export interface ModelRole {
@@ -511,8 +511,8 @@ export interface IApiPathPostRecord{
         '/home/user/passport/logout': undefined;
 '/home/user/passport/register': undefined;
 '/home/user/passport/login': undefined;
-'/home/user/passport/createPassportJwtFromOauthCode': undefined;
 '/home/user/passport/refreshAuthToken': undefined;
+'/home/user/passport/createPassportJwtFromOauthCode': undefined;
 '/home/user/passport/createTempAuthToken': undefined;
     }
 

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

@@ -18,6 +18,8 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate, IMetaVe
         table.comment(entityRole.$comment.$table);
         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.siteIds).comment(entityRole.$comment.siteIds);
       });
       // homeUser
@@ -49,14 +51,14 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate, IMetaVe
   async init(options: IMetaVersionInitOptions) {
     if (options.version === 1) {
       // roles
-      await this.scope.model.role.insert({
-        name: 'registeredUser',
-        siteIds: ['web'],
-      });
-      await this.scope.model.role.insert({
-        name: 'systemAdmin',
-        siteIds: ['web', 'admin'],
-      });
+      for (const [name, role] of Object.entries(this.scope.config.builtinRoles)) {
+        await this.scope.model.role.insert({
+          name,
+          title: role.title,
+          locales: role.locales ?? {},
+          siteIds: role.siteIds,
+        });
+      }
       // user: admin
       if (!this.scope.config.disableUserAdmin) {
         await this.bean.auth.authenticate('auth-simple:simple', {

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

@@ -1,5 +1,10 @@
 import type { VonaApplication } from 'vona';
 
+import { builtinRoles } from './roles.ts';
+
+export { builtinRoles } from './roles.ts';
+export type { IRoleConfig } from './roles.ts';
+
 export function config(_app: VonaApplication) {
   return {
     passwordDefault: {
@@ -7,5 +12,6 @@ export function config(_app: VonaApplication) {
     },
     disableBootstrapSystemAdmin: false,
     disableUserAdmin: false,
+    builtinRoles,
   };
 }

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

@@ -4,6 +4,8 @@ export default {
   PasswordResetEmailExpired: 'This password reset link has expired',
   Role: 'Role',
   RoleName: 'Role Name',
+  RoleTitle: 'Role Title',
+  RoleLocales: 'Role Locales',
   User: 'User',
   UserName: 'User Name',
   UserAvatar: 'Avatar',

package/vona/src/suite/a-home/modules/home-user/src/config/locale/zh-cn.ts

@@ -4,6 +4,8 @@ export default {
   PasswordResetEmailExpired: '重置密码链接已经过期',
   Role: '角色',
   RoleName: '角色名',
+  RoleTitle: '角色标题',
+  RoleLocales: '角色本地化文本',
   User: '用户',
   UserName: '用户名',
   UserAvatar: '头像',

package/vona/src/suite/a-home/modules/home-user/src/config/roles.ts

@@ -0,0 +1,24 @@
+import type { ILocaleRecord } from 'vona';
+
+export interface IRoleConfig {
+  title: string;
+  locales?: Partial<Record<keyof ILocaleRecord, string>>;
+  siteIds: string[];
+}
+
+export const builtinRoles: Record<string, IRoleConfig> = {
+  registeredUser: {
+    title: 'Registered User',
+    locales: {
+      'zh-cn': '注册用户',
+    },
+    siteIds: ['web'],
+  },
+  systemAdmin: {
+    title: 'System Administrator',
+    locales: {
+      'zh-cn': '系统管理员',
+    },
+    siteIds: ['web', 'admin'],
+  },
+};

package/vona/src/suite/a-home/modules/home-user/src/entity/role.ts

@@ -1,3 +1,4 @@
+import type { ILocaleRecord } from 'vona';
 import type { IDecoratorEntityOptions } from 'vona-module-a-orm';
 import type { IRole } from 'vona-module-a-user';
 
@@ -14,6 +15,12 @@ export class EntityRole extends EntityBase implements IRole {
   @Api.field(v.title($locale('RoleName')))
   name: string;
 
+  @Api.field(v.title($locale('RoleTitle')))
+  title: string;
+
+  @Api.field(v.title($locale('RoleLocales')), v.optional(), z.record(z.string(), z.string()))
+  locales?: Partial<Record<keyof ILocaleRecord, string>>;
+
   @Api.field(v.array(z.string()))
   siteIds: string[];
 }

package/vona/src/suite/a-home/modules/home-user/test/role.test.ts

@@ -0,0 +1,45 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { app } from 'vona-mock';
+
+describe('role.test.ts', () => {
+  it('action:roleSeedAndPassport', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const scope = app.scope('home-user');
+      const roleRegisteredUser = await scope.model.role.getByName('registeredUser');
+      assert.equal(roleRegisteredUser?.title, 'Registered User');
+      assert.deepEqual(roleRegisteredUser?.locales, { 'zh-cn': '注册用户' });
+      assert.deepEqual(roleRegisteredUser?.siteIds, ['web']);
+
+      const roleSystemAdmin = await scope.model.role.getByName('systemAdmin');
+      assert.equal(roleSystemAdmin?.title, 'System Administrator');
+      assert.deepEqual(roleSystemAdmin?.locales, { 'zh-cn': '系统管理员' });
+      assert.deepEqual(roleSystemAdmin?.siteIds, ['web', 'admin']);
+
+      await app.bean.passport.signinMock();
+      const passport = await app.bean.executor.performAction('get', '/home/user/passport/current');
+      assert.deepEqual(
+        passport.roles.map(role => ({
+          name: role.name,
+          title: role.title,
+          locales: role.locales,
+          siteIds: role.siteIds,
+        })),
+        [
+          {
+            name: 'registeredUser',
+            title: 'Registered User',
+            locales: { 'zh-cn': '注册用户' },
+            siteIds: ['web'],
+          },
+          {
+            name: 'systemAdmin',
+            title: 'System Administrator',
+            locales: { 'zh-cn': '系统管理员' },
+            siteIds: ['web', 'admin'],
+          },
+        ],
+      );
+    });
+  });
+});