cabloy 5.1.59 → 5.1.61

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

@@ -103,6 +103,24 @@ Representative examples include:
 - helpers such as `v.default`, `v.optional`, `v.array`
 - OpenAPI metadata such as `v.title`, `v.description`, `v.example`, `v.openapi`
 
+When mixing helper metadata and an explicit zod schema in `@Api.field(...)`, keep a small but important ordering rule:
+
+- `z.xxx(...)` returns the zod schema instance, so place it as the **last argument**
+- put helper metadata such as `v.xxx(...)` and `ZovaRender.xxx(...)` before the zod schema
+- otherwise helpers written after the zod schema may stop taking effect
+
+Representative pattern:
+
+```typescript
+@Api.field(
+  v.title($locale('Level')),
+  ZovaRender.order(3),
+  ZovaRender.field('basic-select:formFieldSelect', { items: levelItems }),
+  z.number().int().min(1).max(3),
+)
+level: number;
+```
+
 A practical rule is:
 
 - use inference for straightforward fields

package/cabloy-docs/backend/foundation.md

@@ -91,7 +91,7 @@ A practical rule is:
 | -------------------- | ------------------------------------------------------------------- | -------------------------------------------------------- |
 | Dependency injection | explicit wiring in the current class                                | `@Use('demo-student.service.student')`                   |
 | Dependency lookup    | ordinary module-oriented business code                              | `this.scope.service.student`                             |
-| Direct bean access   | container-aware control or request-scoped lookup                    | `this.bean._getBean(...)`, `this.ctx.bean._getBean(...)` |
+| 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(...)`                                |
 
 ## Dependency injection vs dependency lookup vs direct bean access
@@ -134,6 +134,12 @@ this.ctx.bean._getBean('demo-student.service.student');
 this.bean._newBean('demo-student.service.student');
 ```
 
+A practical distinction is:
+
+- `this.bean._getBean(...)` uses app-level container access
+- `this.ctx.bean._getBean(...)` uses request-scoped container access
+- `this.bean._newBean(...)` creates a fresh bean instance instead of reusing the ordinary resolved one
+
 The important conceptual split is:
 
 - injection wires a dependency into the current class
@@ -146,7 +152,7 @@ Legacy Vona essentials docs made bean identity more explicit, and that identity
 
 The most important terms are:
 
-- **bean identifier**: a dotted identity such as `{moduleName}.{sceneName}.{beanName}`
+- **bean identifier**: for most scene-based beans, a dotted identity such as `{moduleName}.{sceneName}.{beanName}`
 - **onion name**: a colon-based framework name such as `{moduleName}:{beanName}`
 - **bean scene**: the operational family a bean belongs to, such as service, model, startup, queue, or broadcast
 
@@ -159,12 +165,31 @@ This matters because naming is not cosmetic. It affects:
 
 A practical naming rule is:
 
-- bean identifier uses the fully qualified `module.scene.bean` form such as `demo-student.service.student`
+- 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`
 - 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
+
+If you need to create a **new backend bean scene** rather than only adding another bean to an existing scene, see [Backend Bean Scene Authoring](/backend/bean-scene-authoring).
 
 For deciding whether backend base classes belong in `src/lib`, `src/service`, or the global bean shorthand surface, also see [Class Placement Rule](/ai/class-placement-rule).
 
+## Module-local helper functions
+
+When you extract reusable helper functions for one backend module, initialize the module `src/lib` directory and place those helpers there.
+
+A practical rule is:
+
+- keep shared pure helpers in `src/lib`
+- export them from `src/lib/index.ts` when multiple module files should reuse them
+- avoid leaving reusable helper logic duplicated or buried inside `entity`, `dto`, `service`, or `controller` files
+- if the logic needs bean lifecycle, injection, selector lookup, or other container-managed behavior, do not treat it as a plain helper; re-evaluate `src/service` or another bean scene instead
+
+This complements the class placement rule:
+
+- `src/lib` is the normal home for pure reusable helper logic
+- `src/service` or other bean scenes remain the fit for container-managed runtime behavior
+
 ## BeanBase built-ins
 
 A large part of the backend essentials model is that ordinary backend beans already inherit a useful working surface from `BeanBase`.

package/cabloy-docs/backend/introduction.md

@@ -60,7 +60,12 @@ Use this path when the task is about runtime shape, startup, instances, workers,
 - [Worker Guide](/backend/worker-guide)
 - [Election Guide](/backend/election-guide)
 - [Queue Guide](/backend/queue-guide)
+- [Status Guide](/backend/status-guide)
 - [Broadcast Guide](/backend/broadcast-guide)
+- [Web Socket Guide](/backend/websocket-guide)
+- [Web Socket Usage Guide](/backend/websocket-usage-guide)
+- [Web Socket Protocol Guide](/backend/websocket-protocol-guide)
+- [Web Socket Call Flow](/backend/websocket-call-flow)
 - [Schedule Guide](/backend/schedule-guide)
 - [Redlock Guide](/backend/redlock-guide)
 
@@ -90,6 +95,11 @@ If your task is already inside the runtime and distributed family, read these gu
 - [Worker Guide](/backend/worker-guide)
 - [Election Guide](/backend/election-guide)
 - [Queue Guide](/backend/queue-guide)
+- [Status Guide](/backend/status-guide)
 - [Broadcast Guide](/backend/broadcast-guide)
+- [Web Socket Guide](/backend/websocket-guide)
+- [Web Socket Usage Guide](/backend/websocket-usage-guide)
+- [Web Socket Protocol Guide](/backend/websocket-protocol-guide)
+- [Web Socket Call Flow](/backend/websocket-call-flow)
 - [Schedule Guide](/backend/schedule-guide)
 - [Redlock Guide](/backend/redlock-guide)

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(...)`.

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

@@ -144,6 +144,8 @@ That means service access should be understood together with:
 
 For deciding whether a backend base class should stay a helper, move into service-scene, or remain part of the global bean shorthand surface, also see [Class Placement Rule](/ai/class-placement-rule).
 
+For reusable module-local helper functions, prefer the module `src/lib` directory. If the logic needs container-managed runtime behavior rather than plain helper placement, re-evaluate whether it belongs in service-scene instead. For the fuller rule, also see [Backend Foundation](/backend/foundation).
+
 Read this guide together with:
 
 - [Backend Foundation](/backend/foundation)

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=demo-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:
+
+- `demo-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.