cabloy 5.1.61 → 5.1.62

package/cabloy-docs/backend/dto-infer-generation.md

@@ -2,12 +2,37 @@
 
 This guide explains how DTO inference and generation work in Vona within the Cabloy monorepo.
 
+Use this page when your question is not only “what is a DTO?”, but also:
+
+- when should a DTO stay explicit?
+- when should a DTO be inferred?
+- when should I wrap an inferred shape in a named DTO class?
+- how do inferred DTO choices show up in generated metadata and downstream contract flow?
+
 ## Why DTO inference matters
 
-DTOs are essential for validation and OpenAPI metadata, but manually maintaining them becomes expensive and error-prone as models and relationships grow more complex.
+DTOs are essential for validation and OpenAPI metadata, but manually maintaining them becomes expensive and error-prone as models, filters, and relationships grow more complex.
 
 Vona addresses that by dynamically inferring and generating DTOs from model structure and query shape.
 
+That gives you a more useful spectrum than a simple “handwritten or not” decision:
+
+- fully explicit named DTO classes
+- inline inferred DTOs
+- named DTO classes that wrap inferred helper surfaces
+
+This is one of the most important practical distinctions in the backend contract loop.
+
+## This page’s role in the backend reading chain
+
+A practical split is:
+
+- [DTO Guide](/backend/dto-guide) explains DTOs as named contract artifacts
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain) shows how one real module is wired end-to-end
+- this page explains how DTO shapes are chosen, inferred, wrapped, and surfaced in generated metadata
+
+That means this page is the DTO-mechanics deep dive, not the full module specimen page.
+
 ## DTO tools
 
 Several DTO-oriented tools are available, including:
@@ -23,12 +48,46 @@ Several DTO-oriented tools are available, including:
 
 These tools let DTOs emerge from model-aware structure instead of always being hand-authored from scratch.
 
+## Three useful DTO shapes to distinguish
+
+### 1. Explicit named DTO classes
+
+Use this shape when the contract should be a stable named artifact with strong public identity.
+
+Typical reasons:
+
+- the contract is long-lived and reused broadly
+- the contract needs stronger customization
+- the contract should be easy to find and discuss by name
+
+### 2. Inline inferred DTOs
+
+Use this shape when the contract closely follows model or query truth and only one action needs it.
+
+Typical reasons:
+
+- one endpoint needs one inferred relation-aware shape
+- a separate named class would add little value
+- the contract is more about one query result than about a reusable domain artifact
+
+### 3. Named DTO classes that wrap inferred helpers
+
+This is the most practical middle ground in real Cabloy code.
+
+The class stays explicit and discoverable, but its shape is derived from model/entity/query truth through `$Dto.*` helpers.
+
+That means the contract can be:
+
+- readable by name
+- reusable by other code and docs
+- still close to model and query truth rather than manually duplicated
+
 ## When each inferred DTO shape is useful
 
 A practical mental model is:
 
 - use `$Dto.get` for one-item read contracts
-- use `$Dto.listAndCount` for paginated or list-plus-total contracts
+- use `$Dto.listAndCount` for list-plus-total contracts
 - use `$Dto.query` and `$Dto.queryPage` for query-input or query-result patterns
 - use `$Dto.create` and `$Dto.update` for write contracts derived from model structure
 - use `$Dto.aggregate` and `$Dto.group` for summary-oriented result shapes
@@ -43,13 +102,109 @@ A practical rule is:
 - prefer explicit DTO classes when the contract is long-lived, heavily customized, or needs a strong named public identity
 - wrap inferred DTOs into named DTO classes when reuse becomes more important than one-off convenience
 
-This is one of the most important distinctions in the backend contract loop.
+A practical reading takeaway is:
+
+> the best default is often not “handwritten DTO or no DTO.” It is “named DTO class backed by the right inferred helper.”
+
+## `training-student` as the decision specimen
+
+The current `training-student` module is a strong specimen because it shows several different DTO choices in one compact family.
+
+Relevant source files include:
+
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentCreate.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentUpdate.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentView.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectReq.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectRes.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+
+### Create and update DTOs
+
+Representative source facts:
+
+- `DtoStudentCreate` extends `$Dto.create(() => ModelStudent)`
+- `DtoStudentUpdate` extends `$Dto.update(() => ModelStudent)`
+
+These are good examples of **named DTO classes that wrap inference**.
+
+Why this is a good fit:
+
+- the contracts are operation-specific and worth naming
+- the underlying field truth already exists in the model/entity thread
+- rewriting all fields manually would add duplication without adding much clarity
+
+So the code gets both:
+
+- a stable named DTO artifact
+- inference-backed contract derivation
+
+### View DTO
+
+Representative source fact:
+
+- `DtoStudentView` extends `$Dto.get(() => ModelStudent)`
+
+This is the one-item read version of the same pattern.
+
+Again, the class keeps a named public identity, while the DTO shape stays close to model truth.
+
+### Query/filter DTO
+
+`DtoStudentSelectReq` is especially important because it shows that query contracts are often more than a simple list of optional fields.
+
+Representative source facts:
+
+- it extends `$Dto.queryPage(EntityStudent, ['name', 'level', 'createdAt'])`
+- it also adds `@Dto({ openapi: { filter: { table: 'trainingStudent' } }, fields: { ... } })`
+- `level` uses preprocess logic so string query input can be normalized before schema validation
+- `createdAt` uses `v.filterTransform('a-web:dateRange')`
+
+This makes it a strong specimen of a **query DTO that still wraps inference, but adds operation-specific shaping**.
+
+A practical reading takeaway is:
+
+- inference gives the structural baseline
+- explicit field metadata adds the operation-specific contract behavior
+
+### Row-item response DTO
+
+`DtoStudentSelectResItem` is useful for a different reason.
+
+Representative source fact:
+
+- it extends `$Dto.get(() => ModelStudent)`
+
+But it also adds response-facing metadata such as:
+
+- page block metadata
+- row-action metadata
+- table-cell-related render hints
+
+That means a named DTO can still wrap inference while carrying richer response-facing semantics that matter downstream.
+
+### List-and-count response DTO
+
+Representative source fact:
+
+- `DtoStudentSelectRes` extends `$Dto.listAndCount(DtoStudentSelectResItem)`
+
+This is the aggregate response wrapper for the list endpoint.
+
+So the list-response chain is not one DTO only. It is:
+
+1. one query/filter request DTO
+2. one row-item DTO
+3. one list-and-count wrapper DTO
+
+That is exactly the kind of shape where helper-level inference improves consistency more than manual duplication would.
 
 ## Main-details example
 
-A representative example uses an `Order -> Product` relation.
+A representative example for relation-aware inferred contracts uses an `Order -> Product` relation.
 
-The key lesson is that when the return shape is richer than a simple entity array, an inferred DTO can capture the actual result shape more accurately than a hand-waved entity annotation.
+The key lesson is that when the return shape is richer than a simple entity array, an inferred DTO can capture the real result shape more accurately than a hand-waved entity annotation.
 
 Representative pattern:
 
@@ -57,8 +212,6 @@ Representative pattern:
 @Api.body(v.array($Dto.get(() => ModelOrder, { include: { products: true } })))
 ```
 
-This shows the dynamic DTO layer participating directly in controller return contracts.
-
 Another useful inferred pattern is action-derived contract reuse:
 
 ```typescript
@@ -81,12 +234,6 @@ Examples include:
 
 That means DTO inference should often be considered together with relation design rather than only after the fact.
 
-A representative relation-aware response pattern is:
-
-```typescript
-@Api.body(v.array($Dto.get(() => ModelOrder, { include: { products: true } })))
-```
-
 A practical rule is:
 
 - keep inference inline when one action needs one contract shape only once
@@ -103,6 +250,30 @@ A practical rule is:
 
 For the query side of this topic, also see [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide).
 
+## How DTOs surface in generated metadata
+
+When you change or add DTOs, do not think only about the local DTO file.
+
+The current `training-student` module also makes DTOs visible through generated metadata in:
+
+- `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+
+The DTO-facing part of that generated registry includes:
+
+- exports of the DTO classes themselves
+- `IDtoRecord` registrations for DTO onion names
+- a broader generated surface that keeps DTO availability aligned with controller, API path, and resource registrations
+
+A practical reading takeaway is:
+
+> DTO classes are not only local TypeScript artifacts. They become part of the generated contract registry that the rest of the backend thread can reason about.
+
+This is also why DTO changes should be thought about together with:
+
+- OpenAPI emission
+- downstream frontend generation
+- broader contract-loop verification
+
 ## Relationship to CRUD generation
 
 Inferred DTOs are not separate from the CRUD workflow. They sit on the same contract loop.
@@ -111,34 +282,39 @@ A useful split is:
 
 - CRUD generation gives you the initial backend thread
 - explicit DTOs give you stable named operation contracts
-- inferred DTOs let the contract stay close to model and query truth when a separate handwritten class would add little value
+- inferred DTO helpers let the contract stay close to model and query truth when another handwritten class would add little value
 
 This helps keep the generated thread productive instead of forcing redundant DTO maintenance everywhere.
 
-## Encapsulating inferred DTOs
-
-Inferred DTO logic can also be wrapped inside an explicit DTO class for reuse.
+## Relationship to OpenAPI and frontend generation
 
-That is useful because it gives teams a spectrum of options:
-
-- use inference directly for one endpoint
-- wrap the inferred DTO into a named reusable class when the contract is important elsewhere too
+DTO inference and generation are not isolated authoring tricks. They are part of a broader backend contract workflow.
 
-## Relationship to generation and metadata refresh
+When model, relation, DTO, or controller contracts change, remember to consider the downstream path too:
 
-DTO inference and generation are not isolated authoring tricks. They are part of a broader backend contract workflow.
+- backend OpenAPI output
+- frontend SDK generation
+- frontend schema-driven helpers
 
-When model, relation, or controller contracts change, remember to consider the downstream metadata and generated-contract path as well.
+For the bridge step that carries this backend-authored contract across the stack, continue with [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
 
-Read this guide together with:
+## Read this guide together with
 
 - [DTO Guide](/backend/dto-guide)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
 - [Relations Guide](/backend/relations-guide)
 - [ORM Select Guide](/backend/orm-select-guide)
 - [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide)
 - [OpenAPI Guide](/backend/openapi-guide)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 
+## Where to read next
+
+- If you want one concrete module specimen first, continue with [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain).
+- If your next question is about broader DTO design choices, continue with [DTO Guide](/backend/dto-guide).
+- If your next question is about emitted backend contract output, continue with [OpenAPI Guide](/backend/openapi-guide).
+- If your next question is about how backend-authored DTO and OpenAPI truth becomes generated frontend contract material, continue with [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
 ## Implementation checks for DTO inference and generation changes
 
 When evaluating a return shape or input contract that closely follows model structure, ask:

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

@@ -26,10 +26,10 @@ That makes election a coordination primitive, not just a boolean lock.
 
 ## Create `meta.election`
 
-Example: create `meta.election` in module `demo-student`.
+Example: create `meta.election` in module `training-student`.
 
 ```bash
-npm run vona :create:bean meta election -- --module=demo-student
+npm run vona :create:bean meta election -- --module=training-student
 ```
 
 Representative definition:

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

@@ -10,10 +10,10 @@ That makes entity design one of the main places where database structure and API
 
 ## Create an entity
 
-Example: create an entity named `student` in module `demo-student`.
+Example: create an entity named `student` in module `training-student`.
 
 ```bash
-npm run vona :create:bean entity student -- --module=demo-student
+npm run vona :create:bean entity student -- --module=training-student
 ```
 
 ## Entity definition
@@ -21,7 +21,7 @@ npm run vona :create:bean entity student -- --module=demo-student
 Representative pattern:
 
 ```typescript
-@Entity<IEntityOptionsStudent>('demoStudent')
+@Entity<IEntityOptionsStudent>('trainingStudent')
 export class EntityStudent extends EntityBase {}
 ```
 
@@ -166,3 +166,12 @@ When creating or updates entities:
 3. keep validation, OpenAPI, serializer, and entity structure aligned
 4. remember that entities feed DTO, model, and OpenAPI workflows downstream
 5. keep identity and base-field assumptions consistent with the actual backend contract loop
+
+## Where to read next
+
+If your next question is how entity field metadata becomes named transport contracts and emitted backend contract metadata, continue with:
+
+- [DTO Guide](/backend/dto-guide)
+- [Validation Guide](/backend/validation-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)

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

@@ -13,10 +13,10 @@ That matters because backend contracts often need errors that are:
 
 ## Initialize the error skeleton
 
-Example: initialize error resources for module `demo-student`.
+Example: initialize error resources for module `training-student`.
 
 ```bash
-npm run vona :init:error demo-student
+npm run vona :init:error training-student
 ```
 
 This gives the module the standard files for defining error codes and their language resources.
@@ -66,7 +66,7 @@ Cross-module error access uses the cross-module scope surface.
 Representative pattern:
 
 ```typescript
-this.$scope.demoStudent.error.ErrorTest.throw();
+this.$scope.trainingStudent.error.ErrorTest.throw();
 ```
 
 A practical distinction is:

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

@@ -29,7 +29,7 @@ An event is defined as a typed bean.
 Representative generation workflow:
 
 ```bash
-npm run vona :create:bean event echo -- --module=demo-student
+npm run vona :create:bean event echo -- --module=training-student
 ```
 
 Representative pattern:
@@ -79,13 +79,13 @@ Event listeners attach through `@EventListener({ match: ... })`.
 Representative generation workflow:
 
 ```bash
-npm run vona :create:bean eventListener echo -- --module=demo-student
+npm run vona :create:bean eventListener echo -- --module=training-student
 ```
 
 Representative pattern:
 
 ```typescript
-@EventListener({ match: 'demo-student:echo' })
+@EventListener({ match: 'training-student:echo' })
 export class EventListenerEcho implements IEventExecute<TypeEventData, TypeEventResult> {
   execute(data: TypeEventData, next: NextEventSync<TypeEventData, TypeEventResult>) {
     const dataNew = `${data}!`;
@@ -135,7 +135,7 @@ Vona can inspect the effective event-listener list for a named event.
 Representative pattern:
 
 ```typescript
-this.bean.onion.eventListener.inspectEventListener('demo-student:echo');
+this.bean.onion.eventListener.inspectEventListener('training-student:echo');
 ```
 
 This is useful for debugging event composition and verifying which listeners are active.

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

@@ -13,13 +13,13 @@ External AOP uses `@Aop({ match: ... })` to associate an aspect class with one o
 Representative CLI generation pattern:
 
 ```bash
-npm run vona :create:bean aop log -- --module=demo-student
+npm run vona :create:bean aop log -- --module=training-student
 ```
 
 Representative shape:
 
 ```typescript
-@Aop({ match: 'demo-student.service.test' })
+@Aop({ match: 'training-student.service.test' })
 export class AopLog extends BeanAopBase {}
 ```
 

package/cabloy-docs/backend/field-indexes.md

@@ -15,7 +15,7 @@ Vona uses a bean named `meta.index` to configure a module’s field indexes.
 Create it with:
 
 ```bash
-npm run vona :create:bean meta index -- --module=demo-student
+npm run vona :create:bean meta index -- --module=training-student
 ```
 
 Representative shell:
@@ -32,7 +32,7 @@ Representative pattern:
 ```typescript
 @Meta({
   indexes: {
-    demoStudent: 'name',
+    trainingStudent: 'name',
   },
 })
 class MetaIndex {}
@@ -52,7 +52,7 @@ import { $tableColumns } from 'vona-module-a-ormutils';
 
 @Meta({
   indexes: {
-    ...$tableColumns('demoStudent', 'name'),
+    ...$tableColumns('trainingStudent', 'name'),
   },
 })
 class MetaIndex {}
@@ -77,3 +77,9 @@ Also ask:
 3. is the typed style a better fit than raw string declarations?
 
 That leads to backend changes that are more production-aware and more aligned with Vona’s module metadata model.
+
+## Where to read next
+
+- If you want the broader persistence-side source-reading chooser, continue with [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap).
+- If you are deciding how indexed fields relate to backend persistence truth, continue with [Entity Guide](/backend/entity-guide).
+- If the index question is part of a persisted-schema change, continue with [Migration and Changes](/backend/migration-and-changes).

package/cabloy-docs/backend/foundation.md

@@ -89,7 +89,7 @@ A practical rule is:
 
 | Access style         | Best for                                                            | Representative shape                                     |
 | -------------------- | ------------------------------------------------------------------- | -------------------------------------------------------- |
-| Dependency injection | explicit wiring in the current class                                | `@Use('demo-student.service.student')`                   |
+| Dependency injection | explicit wiring in the current class                                | `@Use('training-student.service.student')`               |
 | Dependency lookup    | ordinary module-oriented business code                              | `this.scope.service.student`                             |
 | Direct bean access   | container-aware control through the app container or request scope  | `this.bean._getBean(...)`, `this.ctx.bean._getBean(...)` |
 | Fresh bean creation  | workflows that should not reuse the ordinary resolved bean instance | `this.bean._newBean(...)`                                |
@@ -106,7 +106,7 @@ Representative pattern:
 
 ```typescript
 class ControllerStudent {
-  @Use('demo-student.service.student')
+  @Use('training-student.service.student')
   serviceStudent: ServiceStudent;
 }
 ```
@@ -119,7 +119,7 @@ Representative patterns:
 
 ```typescript
 this.scope.service.student.findOne();
-this.$scope.demoStudent.service.student.findOne();
+this.$scope.trainingStudent.service.student.findOne();
 ```
 
 ### Direct bean access
@@ -129,9 +129,9 @@ Direct bean access exposes the container layer more explicitly.
 Representative patterns:
 
 ```typescript
-this.bean._getBean('demo-student.service.student');
-this.ctx.bean._getBean('demo-student.service.student');
-this.bean._newBean('demo-student.service.student');
+this.bean._getBean('training-student.service.student');
+this.ctx.bean._getBean('training-student.service.student');
+this.bean._newBean('training-student.service.student');
 ```
 
 A practical distinction is:
@@ -165,8 +165,8 @@ This matters because naming is not cosmetic. It affects:
 
 A practical naming rule is:
 
-- most scene-based beans use the fully qualified `module.scene.bean` form such as `demo-student.service.student`
-- onion name uses the shorter `module:bean` form such as `demo-student:student`
+- most scene-based beans use the fully qualified `module.scene.bean` form such as `training-student.service.student`
+- onion name uses the shorter `module:bean` form such as `training-student:student`
 - bean scene is the middle grouping layer that turns one module into operational families like `service`, `model`, `entity`, `dto`, or `startup`
 - the built-in global `bean` scene is an intentional exception and uses the plain bean name in the global shorthand surface
 

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

@@ -20,13 +20,13 @@ Each module can provide its own locale resources.
 Representative initialization workflow:
 
 ```bash
-npm run vona :init:locale demo-student
+npm run vona :init:locale training-student
 ```
 
 Representative files include:
 
-- `src/module/demo-student/src/config/locale/en-us.ts`
-- `src/module/demo-student/src/config/locale/zh-cn.ts`
+- `src/suite/a-training/modules/training-student/src/config/locale/en-us.ts`
+- `src/suite/a-training/modules/training-student/src/config/locale/zh-cn.ts`
 
 This makes localization part of the module model rather than a single global string table.
 
@@ -45,9 +45,9 @@ const message3 = this.scope.locale.StudentName.locale('zh-cn');
 ### Cross-module access
 
 ```typescript
-const message1 = this.$scope.demoStudent.locale.StudentName();
-const message2 = this.$scope.demoStudent.locale.StudentName.locale('en-us');
-const message3 = this.$scope.demoStudent.locale.StudentName.locale('zh-cn');
+const message1 = this.$scope.trainingStudent.locale.StudentName();
+const message2 = this.$scope.trainingStudent.locale.StudentName.locale('en-us');
+const message3 = this.$scope.trainingStudent.locale.StudentName.locale('zh-cn');
 ```
 
 ## Project-level override

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

@@ -28,7 +28,7 @@ It can be used on controller methods, service methods, and other class methods t
 Representative CLI generation pattern:
 
 ```bash
-npm run vona :create:bean aopMethod log -- --module=demo-student
+npm run vona :create:bean aopMethod log -- --module=training-student
 ```
 
 That generator-backed workflow matters because AOP Method beans participate in the same onion metadata system as other Vona extension points.
@@ -51,7 +51,7 @@ class AopMethodLog {
 ### Representative usage
 
 ```typescript
-@Aspect.aopMethod('demo-student:log')
+@Aspect.aopMethod('training-student:log')
 ```
 
 ### Parameter model

package/cabloy-docs/backend/introduction.md

@@ -37,6 +37,19 @@ Start here when you need the core backend mental model first:
 
 This gives the architectural vocabulary for concepts such as bean, scope, suite, module, package, and backend access patterns.
 
+### Source-reading entry
+
+Use these pages when the task is no longer only conceptual and you want the shortest path into current backend source:
+
+- [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)
+
+A practical split is:
+
+- stay on Introduction / Foundation / CLI when you still need the backend mental model
+- move to the roadmap when you need help choosing the right backend reading cluster
+- move to the source reading map when you already know the topic and want the shortest file-order path
+
 ### Contract and data family
 
 Use this path when the task is about the backend contract loop or ORM-backed backend data design:

package/cabloy-docs/backend/migration-and-changes.md

@@ -35,7 +35,7 @@ Representative pattern:
 
 ```json
 {
-  "name": "vona-module-demo-student",
+  "name": "vona-module-training-student",
   "vonaModule": {
     "fileVersion": 1
   }
@@ -55,7 +55,7 @@ Vona uses a bean named `meta.version` to organize migration code for a module.
 Create it with:
 
 ```bash
-npm run vona :create:bean meta version -- --module=demo-student
+npm run vona :create:bean meta version -- --module=training-student
 ```
 
 Representative shell:
@@ -96,7 +96,7 @@ Representative pattern:
 export class MetaVersion extends BeanBase implements IMetaVersionUpdate {
   async update(options: IMetaVersionUpdateOptions) {
     if (options.version === 1) {
-      await this.bean.model.createTable('demoStudent', table => {
+      await this.bean.model.createTable('trainingStudent', table => {
         table.basicFields();
         table.string('name', 50);
         table.string('description', 255);

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

@@ -17,10 +17,10 @@ That means model design affects not only SQL behavior, but also CRUD defaults, D
 
 ## Create a model
 
-Example: create a model named `student` in module `demo-student`.
+Example: create a model named `student` in module `training-student`.
 
 ```bash
-npm run vona :create:bean model student -- --module=demo-student
+npm run vona :create:bean model student -- --module=training-student
 ```
 
 ## Model definition
@@ -56,7 +56,7 @@ class ServiceStudent {
 ```typescript
 class ServiceStudent {
   async findAll(): Promise<EntityStudent[]> {
-    return await this.$scope.demoStudent.model.student.select();
+    return await this.$scope.trainingStudent.model.student.select();
   }
 }
 ```
@@ -66,7 +66,7 @@ class ServiceStudent {
 ```typescript
 class ServiceStudent {
   async findAll(): Promise<EntityStudent[]> {
-    return await this.bean._getBean('demo-student.model.student').select();
+    return await this.bean._getBean('training-student.model.student').select();
   }
 }
 ```
@@ -121,7 +121,7 @@ Representative patterns:
 ```typescript
 this.scope.model.student.builder().where('name', 'tom').orderBy('name');
 this.scope.model.student.builderSelect().where('name', 'tom').orderBy('name');
-this.scope.model.student.query('select * from demoStudent');
+this.scope.model.student.query('select * from trainingStudent');
 ```
 
 A practical rule is:
@@ -155,7 +155,7 @@ Representative pattern:
 ```typescript
 config.onions = {
   model: {
-    'demo-student:student': {
+    'training-student:student': {
       disableDeleted: true,
       disableInstance: true,
       client: 'mysql',
@@ -279,3 +279,13 @@ When creating backend persistence logic:
 4. choose deliberately among local scope, cross-module scope, and direct bean access
 5. remember that datasource, cache, and model options can change the behavior of the backend contract loop
 6. drop to raw SQL or lower-level query builder logic only when the higher-level model surface is insufficient
+
+## Where to read next
+
+If your next question is how model persistence behavior fits into one complete backend contract thread, continue with:
+
+- [Entity Guide](/backend/entity-guide)
+- [DTO Guide](/backend/dto-guide)
+- [CRUD Workflow](/backend/crud-workflow)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)