cabloy 5.1.60 → 5.1.62

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)

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

@@ -100,6 +100,9 @@ For the downstream bridge and consumption path, also see:
 A practical split is:
 
 - this page explains backend contract authoring and emission
+- [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen) explains one concrete emitted action thread
+- [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map) explains the shortest file-order path through the emission inputs
+- [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection) explains how to inspect the emitted output surfaces themselves
 - the fullstack page explains the bridge from emitted OpenAPI to generated frontend SDK
 - the frontend page explains how Zova consumes that contract in its own workflows
 

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

@@ -10,10 +10,10 @@ This is one of the main bridges between synchronous application code and distrib
 
 ## Create a queue
 
-Example: create a queue named `add` in module `demo-student`.
+Example: create a queue named `add` in module `training-student`.
 
 ```bash
-npm run vona :create:bean queue add -- --module=demo-student
+npm run vona :create:bean queue add -- --module=training-student
 ```
 
 ## Queue definition
@@ -197,7 +197,7 @@ Representative pattern:
 ```typescript
 config.onions = {
   queue: {
-    'demo-student:add': {
+    'training-student:add': {
       concurrency: false,
       transaction: false,
       options: {

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

@@ -10,10 +10,10 @@ Vona provides a Redlock-based distributed lock abstraction so that mutual exclus
 
 ## Create a redlock definition
 
-Example: create redlock metadata in module `demo-student`.
+Example: create redlock metadata in module `training-student`.
 
 ```bash
-npm run vona :create:bean meta redlock -- --module=demo-student
+npm run vona :create:bean meta redlock -- --module=training-student
 ```
 
 ## Lock resource types

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

@@ -10,10 +10,10 @@ This matters because recurring work is modeled with the same broader distributed
 
 ## Create a schedule
 
-Example: create a schedule named `log` in module `demo-student`.
+Example: create a schedule named `log` in module `training-student`.
 
 ```bash
-npm run vona :create:bean schedule log -- --module=demo-student
+npm run vona :create:bean schedule log -- --module=training-student
 ```
 
 ## Schedule definition

package/cabloy-docs/backend/scripts.md

@@ -114,3 +114,11 @@ When documenting or automating backend scripts:
 - prefer root scripts for normal contributor workflows
 - drop to `vona/package.json` only when you need backend-specific detail
 - verify commands against current scripts before publishing examples
+
+## Where to read next
+
+If your next question is not only how the monorepo runs backend workflows, but which source surfaces those workflows eventually enter, continue with:
+
+- [Backend CLI](/backend/cli)
+- [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)

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

@@ -41,6 +41,16 @@ async findOne(id) {
 
 This makes serialization an explicit request-path capability rather than an invisible response-side convention.
 
+Important operational rule:
+
+- for performance reasons, serialization is **not enabled by default**
+- `v.serializerTransform(...)`, `v.serializerExclude()`, `v.serializerReplace(...)`, `v.serializerGetter(...)`, and `v.serializerCustom(...)` only declare field-level transform metadata
+- those transforms do **not** run unless the target API explicitly enables serialization with `@Core.serializer()`
+
+A practical debugging rule is:
+
+- if a field-level serializer appears correct but the response still returns the raw value, first check whether the controller action uses `@Core.serializer()`
+
 ## Serializer transforms
 
 Vona supports custom serializer transforms through `@SerializerTransform(...)`.
@@ -48,7 +58,7 @@ Vona supports custom serializer transforms through `@SerializerTransform(...)`.
 Representative generation workflow:
 
 ```bash
-npm run vona :create:bean serializerTransform upper -- --module=demo-student
+npm run vona :create:bean serializerTransform upper -- --module=training-student
 ```
 
 Representative pattern:
@@ -78,7 +88,7 @@ Field-level serialization is attached through `@Api.field(...)` metadata helpers
 Representative pattern:
 
 ```typescript
-@Api.field(v.serializerTransform('demo-student:upper'))
+@Api.field(v.serializerTransform('training-student:upper'))
 name: string;
 ```
 

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

@@ -10,10 +10,10 @@ In practice, the service guide is also the most useful page for understanding ba
 
 ## Create a service
 
-Example: create a service named `student` in module `demo-student`.
+Example: create a service named `student` in module `training-student`.
 
 ```bash
-npm run vona :create:bean service student -- --module=demo-student
+npm run vona :create:bean service student -- --module=training-student
 ```
 
 ## Service definition
@@ -58,7 +58,7 @@ class ControllerStudent {
 import type { ServiceStudent } from '../service/student.ts';
 
 class ControllerStudent {
-  @Use('demo-student.service.student')
+  @Use('training-student.service.student')
   serviceStudent: ServiceStudent;
 }
 ```
@@ -84,7 +84,7 @@ class ControllerStudent {
 ```typescript
 class ControllerStudent {
   findOne() {
-    return this.$scope.demoStudent.service.student.findOne();
+    return this.$scope.trainingStudent.service.student.findOne();
   }
 }
 ```
@@ -103,19 +103,19 @@ Direct bean access patterns are also available.
 ### Global container access: `_getBean`
 
 ```typescript
-const serviceStudent = this.bean._getBean('demo-student.service.student');
+const serviceStudent = this.bean._getBean('training-student.service.student');
 ```
 
 ### Request-scoped access
 
 ```typescript
-const serviceStudent = this.ctx.bean._getBean('demo-student.service.student');
+const serviceStudent = this.ctx.bean._getBean('training-student.service.student');
 ```
 
 ### Fresh bean creation: `_newBean`
 
 ```typescript
-const serviceStudent = this.bean._newBean('demo-student.service.student');
+const serviceStudent = this.bean._newBean('training-student.service.student');
 ```
 
 A practical split is:
@@ -127,7 +127,7 @@ A practical split is:
 A practical “when to use which” rule is:
 
 - use `this.scope.service.student` when the dependency belongs to the current module and ordinary business code is enough
-- use `this.$scope.demoStudent.service.student` when the dependency clearly belongs to another module
+- use `this.$scope.trainingStudent.service.student` when the dependency clearly belongs to another module
 - use `this.bean._getBean(...)` when you need explicit app-container access by bean identifier
 - use `this.ctx.bean._getBean(...)` when the workflow should resolve through request-scoped access
 - use `this.bean._newBean(...)` when you need a fresh bean instance instead of the ordinary resolved one
@@ -138,7 +138,7 @@ Services are one bean scene inside the larger backend essentials model.
 
 That means service access should be understood together with:
 
-- bean identifiers such as `demo-student.service.student`
+- bean identifiers such as `training-student.service.student`
 - local module scope vs cross-module scope
 - other scope resource categories such as model and entity
 
@@ -166,3 +166,12 @@ A better default is:
 4. choose deliberately among local scope, cross-module scope, injection, and direct bean access
 
 That keeps backend access patterns aligned with Vona’s actual architecture instead of using one access style everywhere by habit.
+
+## Where to read next
+
+If your next question is how service orchestration hands off to the persistence and contract layers in one real module, continue with:
+
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)

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

@@ -42,10 +42,10 @@ This is one of the reasons backend startup belongs in the backend docs, not in t
 
 ## Create a startup bean
 
-Example: create a startup named `log` in module `demo-student`.
+Example: create a startup named `log` in module `training-student`.
 
 ```bash
-npm run vona :create:bean startup log -- --module=demo-student
+npm run vona :create:bean startup log -- --module=training-student
 ```
 
 Representative shape:
@@ -102,7 +102,7 @@ Representative pattern:
 ```typescript
 config.onions = {
   startup: {
-    'demo-student:log': {
+    'training-student:log': {
       after: false,
       debounce: true,
       instance: false,
@@ -148,7 +148,7 @@ App config can disable a startup explicitly:
 ```typescript
 config.onions = {
   startup: {
-    'demo-student:log': {
+    'training-student:log': {
       enable: false,
     },
   },
@@ -200,7 +200,7 @@ Module monkey files can also receive module-oriented hook callbacks, and the app
 Representative CLI workflow:
 
 ```bash
-npm run vona :init:monkey demo-student
+npm run vona :init:monkey training-student
 ```
 
 ### Startup beans

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

@@ -0,0 +1,271 @@
+# Status Guide
+
+This guide explains how Status works in Vona within the Cabloy monorepo.
+
+## Why Status matters
+
+Some backend modules need a very small amount of durable module-local state without introducing a full business resource.
+
+Typical examples include:
+
+- feature toggles owned by one module
+- small structured status payloads
+- module-local runtime flags that should survive process restart
+- lightweight persisted settings that do not justify a dedicated CRUD surface
+
+Vona provides Status for exactly that shape.
+
+A practical mental model is:
+
+- Status is a persisted key/value store
+- keys are scoped by the owning module
+- values are stored as JSON
+- the main public API is a typed `get` / `set` surface
+
+## Create `meta.status`
+
+Create a status bean in your module with the shared Vona CLI entrypoint:
+
+```bash
+npm run vona :create:bean meta status -- --module=training-student
+```
+
+This follows the same `:create:bean` workflow used by other backend bean scenes and metadata beans.
+
+The generated shape is representative of:
+
+```typescript
+import { Meta } from 'vona-module-a-meta';
+import { BeanStatusBase } from 'vona-module-a-status';
+
+export interface IStatusRecord {}
+
+@Meta()
+export class MetaStatus extends BeanStatusBase<IStatusRecord> {}
+```
+
+The important point is that your module defines its own typed status record while reusing the shared persistence and locking behavior from `BeanStatusBase`.
+
+## Define a typed status record
+
+Status is most useful when the record shape is explicit.
+
+Representative pattern:
+
+```typescript
+interface IStatusUser {
+  name: string;
+  age: number;
+}
+
+export interface IStatusRecord {
+  enable: boolean;
+  user: IStatusUser;
+}
+
+@Meta()
+export class MetaStatus extends BeanStatusBase<IStatusRecord> {}
+```
+
+This gives a practical typed contract:
+
+- `get('enable')` returns `boolean | undefined`
+- `set('enable', true)` requires a boolean
+- `get('user')` returns the typed user object or `undefined`
+
+So Status is flexible at storage time because the value is JSON, but strongly typed at authoring time because the bean is generic.
+
+## Use `scope.status`
+
+After defining `meta.status` in a module, the generated scope exposes it as `scope.status` inside that module.
+
+Representative usage:
+
+```typescript
+let value = await this.scope.status.get('enable');
+await this.scope.status.set('enable', true);
+value = await this.scope.status.get('enable');
+
+let user = await this.scope.status.get('user');
+await this.scope.status.set('user', { name: 'zhennann', age: 18 });
+user = await this.scope.status.get('user');
+```
+
+A practical behavior summary is:
+
+- `get(...)` returns `undefined` when the key has not been written yet
+- `set(...)` creates the key on first write
+- later `set(...)` updates the existing value
+
+## What is actually stored
+
+The current source stores Status data in table `aStatus`.
+
+The logical identity of a record is:
+
+- `module`
+- `name`
+
+The stored payload is:
+
+- `value` as JSON
+
+So a practical storage reading is:
+
+| Field    | Meaning                               |
+| -------- | ------------------------------------- |
+| `module` | the owning backend module             |
+| `name`   | the status key inside that module     |
+| `value`  | the persisted JSON value for that key |
+
+The current migration creates the table with the framework basic fields plus:
+
+- `module`
+- `name`
+- `value`
+
+This means Status is designed as a small module-scoped persistence surface rather than a general-purpose relational model.
+
+## Module-local scoping
+
+One of the most important design points is that Status is scoped by the **consumer module**, not only by the key name.
+
+That means two different modules can both use a key such as `enable` without colliding with each other.
+
+A practical reading is:
+
+- `training-student + enable` is one status record
+- `demo-course + enable` is a different status record
+
+This makes Status a natural fit for module-local state.
+
+## First-write concurrency behavior
+
+The current implementation protects first-write creation with Redlock.
+
+A practical flow is:
+
+1. attempt to read the current `(module, name)` record
+2. if the record exists, update it
+3. if the record does not exist, enter a `lockIsolate(...)` critical section
+4. re-check the record with a forced fresh read
+5. insert only if it is still missing
+
+This is important in distributed or multi-worker deployments because two workers might otherwise try to create the same logical key at the same time.
+
+The design intention is:
+
+- ordinary reads stay simple
+- first-write races are serialized
+- the locked re-check avoids stale read behavior during creation
+
+For the broader locking model, also see [Redlock Guide](/backend/redlock-guide).
+
+## Relationship to cache and ORM
+
+Status is built on top of the Vona ORM model layer.
+
+That matters because Status is not a separate storage engine. It participates in the same broader backend persistence model as other ORM-backed data.
+
+A practical reading is:
+
+- Status persistence is implemented through an ORM model
+- reads can benefit from the framework data-access stack
+- write behavior still follows the framework mutation path
+
+For surrounding concepts, also see:
+
+- [ORM Guide](/backend/orm-guide)
+- [Cache Guide](/backend/cache-guide)
+- [Migration and Changes](/backend/migration-and-changes)
+
+## Relationship to migration
+
+The built-in `a-status` module currently creates its own storage table through `meta.version` with `fileVersion: 1`.
+
+For ordinary consumers of Status, the usual workflow is simple:
+
+- depend on the shared Status module
+- create your own `meta.status`
+- define your typed record
+- use `scope.status` from your module
+
+You do **not** create a separate status table per consuming module.
+
+If your own module later outgrows Status and needs a richer schema, that usually means moving to dedicated entity/model resources and managing your own `meta.version` changes directly.
+
+## What Status is good for
+
+Status is a strong fit when the data is:
+
+- small in size
+- keyed by a fixed or slowly changing set of names
+- naturally owned by one module
+- read or updated by key rather than queried as a collection
+
+Typical good fits include:
+
+- module enable flags
+- one module-owned progress marker
+- compact structured settings
+- one-off durable state snapshots
+
+## What Status is not for
+
+Status is usually the wrong abstraction when you need:
+
+- a large collection of rows
+- rich filtering or search
+- relational structure
+- a public CRUD API
+- list, delete, or pagination behavior
+- field-level validation and indexing as a first-class domain concern
+
+A practical boundary is:
+
+- use Status for a small number of durable module-local keys
+- use entity/model/controller resources when the data becomes a real business resource
+
+## Current implementation notes
+
+From the current source, some boundaries are worth knowing:
+
+- the public base API is intentionally small: `get` and `set`
+- there is no built-in delete or list convenience API
+- values are stored as JSON
+- first-write concurrency is protected by Redlock
+- the current table creation is lightweight and does not define a separate Status-specific CRUD surface
+
+These details make Status easy to use, but they also mean you should not stretch it into a substitute for a richer domain model.
+
+## Recommended workflow
+
+A practical Status workflow is:
+
+1. create `meta.status` with the Vona CLI
+2. define a small typed `IStatusRecord`
+3. read and write through `this.scope.status`
+4. keep payloads compact and module-owned
+5. move to dedicated entity/model resources if the data stops looking like key/value state
+
+## Related guides
+
+Read this guide together with:
+
+- [Backend CLI](/backend/cli)
+- [Migration and Changes](/backend/migration-and-changes)
+- [ORM Guide](/backend/orm-guide)
+- [Cache Guide](/backend/cache-guide)
+- [Redlock Guide](/backend/redlock-guide)
+
+## Implementation checks for Status changes
+
+When adding or revising module-local durable state, ask:
+
+1. is this really a small module-owned key/value need?
+2. should the state live in `meta.status` instead of a dedicated entity/model resource?
+3. is the status record shape explicit and typed?
+4. will the payload remain compact and stable over time?
+5. do later requirements such as list, delete, filtering, or indexing mean the design should graduate to a richer persistence model?
+
+That keeps Status aligned with its intended role in Vona.

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

@@ -33,7 +33,7 @@ This is why Vona testing should not be reduced to isolated helper-unit testing o
 Example:
 
 ```bash
-npm run vona :create:test student -- --module=demo-student
+npm run vona :create:test student -- --module=training-student
 ```
 
 ## Execute tests
@@ -91,7 +91,7 @@ Locale-sensitive variants and additional request-context helpers are also availa
 Representative pattern:
 
 ```typescript
-const scopeStudent = app.scope('demo-student');
+const scopeStudent = app.scope('training-student');
 ```
 
 This lets tests exercise:
@@ -108,7 +108,7 @@ through the same scoped abstractions used in application code.
 Representative pattern:
 
 ```typescript
-await app.bean.executor.performAction('get', '/demo/student');
+await app.bean.executor.performAction('get', '/training/student');
 ```
 
 This is especially useful because it exercises the controller path more realistically than only unit-testing isolated helper functions.