cabloy 5.1.97 → 5.1.99

package/cabloy-docs/frontend/zova-vs-vue3-comparison.md

@@ -12,6 +12,7 @@ The goal is to explain two things clearly:
 Use this page together with:
 
 - [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers)
 - [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
 - [Zova Source Reading Map](/frontend/zova-source-reading-map)
 
@@ -40,16 +41,16 @@ The big difference is the **business-facing programming model**.
 
 ## Side-by-side comparison table
 
-| Dimension | Zova | Vue 3 default mental model |
-| --- | --- | --- |
-| Reactive host | controller or bean instance | local `ref` / `reactive` values inside `setup()` |
-| Derived state | `$computed()` often assigned to instance fields | `computed()` usually assigned to local variables |
-| Main wiring surface | `__init__` and bean lifecycle | `setup()` and composition hooks |
-| Route state access | page-controller surface such as `$route`, `$params`, `$query` | composables such as `useRoute()` |
-| Sharing model | IoC containers and bean scopes unify more sharing patterns | composables, props/emits, `provide/inject`, and store layers often coexist |
-| Render organization | controller-oriented; render can stay in controller or move to render beans | component-oriented; template/render/setup stay the obvious center |
-| Growth path | split into controller, render, style, service, model, or other beans | split into composables, child components, and store or helper layers |
-| Architectural emphasis | explicit object roles, scope ownership, and runtime-managed surfaces | flexible local composition with more developer-managed assembly |
+| Dimension              | Zova                                                                       | Vue 3 default mental model                                                 |
+| ---------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Reactive host          | controller or bean instance                                                | local `ref` / `reactive` values inside `setup()`                           |
+| Derived state          | `$computed()` often assigned to instance fields                            | `computed()` usually assigned to local variables                           |
+| Main wiring surface    | `__init__` and bean lifecycle                                              | `setup()` and composition hooks                                            |
+| Route state access     | page-controller surface such as `$route`, `$params`, `$query`              | composables such as `useRoute()`                                           |
+| Sharing model          | IoC containers and bean scopes unify more sharing patterns                 | composables, props/emits, `provide/inject`, and store layers often coexist |
+| Render organization    | controller-oriented; render can stay in controller or move to render beans | component-oriented; template/render/setup stay the obvious center          |
+| Growth path            | split into controller, render, style, service, model, or other beans       | split into composables, child components, and store or helper layers       |
+| Architectural emphasis | explicit object roles, scope ownership, and runtime-managed surfaces       | flexible local composition with more developer-managed assembly            |
 
 ## 1. Reactive host
 

package/cabloy-docs/fullstack/image-workflow.md

@@ -0,0 +1,403 @@
+# Fullstack Image Workflow
+
+This page explains the fullstack image workflow in Cabloy Basic with a practical, contract-chain path.
+
+In this page, **resolved relation field** means the DTO-side field such as `image` or `sceneImages` that carries `DtoImageView` data for frontend preview and display.
+
+It fills the gap between the layer-specific image guides:
+
+- [Backend Image Guide](/backend/image-guide)
+- [Frontend Image Guide](/frontend/image-guide)
+
+Use this page when the real question is not only backend image policy and not only frontend image rendering, but the bridge between the two.
+
+Use this page together with:
+
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- [Backend Image Guide](/backend/image-guide)
+- [Frontend Image Guide](/frontend/image-guide)
+- [Upload Guide](/backend/upload-guide)
+- [Serialization Guide](/backend/serialization-guide)
+- [Form Guide](/frontend/form-guide)
+- [Table Guide](/frontend/table-guide)
+
+> [!TIP]
+> **Image workflow docs path**
+>
+> - **[Fullstack Image Workflow](/fullstack/image-workflow)** — learn the cross-stack chain from backend image field contract and scene policy to frontend `basic-image` consumption
+> - **[Backend Image Guide](/backend/image-guide)** — learn image scenes, providers, serializer transforms, delivery policy, and backend lifecycle behavior
+> - **[Frontend Image Guide](/frontend/image-guide)** — learn `basic-image:formFieldImage`, `basic-image:image`, relation previews, and client-side image-field behavior
+>
+> Use this page when the question is about how one image field travels across the full stack rather than only one layer.
+
+## Why this page exists
+
+The repository now has a backend image guide and a frontend image guide.
+
+What contributors and AI workflows often still need is one continuous answer to this narrower question:
+
+> how does one image field travel from backend entity and DTO metadata to frontend form and table rendering?
+
+This page answers that question by treating image handling as one contract chain rather than as disconnected snippets.
+
+## The shortest correct mental model
+
+If you only remember one idea, remember this one:
+
+> backend code owns the image field contract, image scene policy, and DTO-side image view resolution, while frontend `basic-image` resources consume that resolved contract for upload, preview, and display.
+
+That means an image field usually has two connected surfaces:
+
+- a stored identity field such as `imageId` or `sceneImageIds`
+- a resolved relation field such as `image` or `sceneImages`
+
+The fullstack workflow works best when both surfaces are authored deliberately and kept aligned.
+
+## The fullstack chain in one view
+
+A practical image workflow usually looks like this:
+
+1. the backend entity stores image identity data such as `imageId` or `sceneImageIds`
+2. backend field metadata points to the frontend image resources with `ZovaRender.field(...)` and `ZovaRender.cell(...)`
+3. the backend image scene defines upload policy such as MIME type, size, and multiple-image rules
+4. the backend DTO resolves image IDs into `DtoImageView` or `DtoImageView[]` through `a-image:resolveView` or `a-image:resolveViews`
+5. the shared contract exposes both the stored ID field and the resolved relation field to frontend consumers
+6. frontend `basic-image:formFieldImage` binds the stored ID field while reusing the resolved relation field for preview cards and dialogs
+7. frontend `basic-image:image` uses the same resolved relation field to render thumbnails in list pages
+
+This is not only a forward chain and not only a reverse chain.
+
+Instead, it is one concrete business thread where backend contract truth, shared metadata, and frontend resource consumption cooperate.
+
+For the broader decision model, read [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
+## Specimen A: single image on Student
+
+The Student resource is the best single-image specimen because it shows the complete chain with the smallest number of moving parts.
+
+### Backend entity field
+
+The Student entity stores one image identity field and points to the built-in image resources:
+
+```typescript
+@Api.field(
+  v.title($locale('StudentImage')),
+  v.optional(),
+  ZovaRender.field('basic-image:formFieldImage', {
+    imageScene: 'training-student:studentImage',
+    relationName: 'image',
+    accept: ['image/png', 'image/jpeg', 'image/webp'],
+    maxSize: 2 * 1024 * 1024,
+    enableCrop: true,
+    cropAspectRatio: 1,
+    resize: {
+      width: 512,
+      height: 512,
+      fit: 'cover',
+      format: 'jpeg',
+      quality: 90,
+    },
+  }),
+  ZovaRender.cell('basic-image:image', { relationName: 'image' }),
+  v.tableIdentity(),
+)
+imageId?: TableIdentity;
+```
+
+This already defines two important truths:
+
+- the stored field is `imageId`
+- the frontend resource identities are `basic-image:formFieldImage` and `basic-image:image`
+
+### Backend image scene
+
+The Student image scene defines the upload policy:
+
+```typescript
+@ImageScene({
+  upload: {
+    maxSize: 2 * 1024 * 1024,
+    mimeTypes: ['image/png', 'image/jpeg', 'image/webp'],
+  },
+})
+export class ImageSceneStudentImage extends BeanBase {}
+```
+
+This means the backend owns the true upload policy even when the frontend also performs convenience validation.
+
+### DTO-side image resolution
+
+The Student DTO resolves the stored ID into a resolved relation field:
+
+```typescript
+@Api.field(
+  ZovaRender.visible(false),
+  v.optional(),
+  v.serializerTransform('a-image:resolveView', {
+    fieldName: 'imageId',
+    imageScene: 'training-student:studentImage',
+  }),
+  v.object(DtoImageView),
+)
+image?: DtoImageView;
+```
+
+This is the bridge that turns:
+
+- stored value: `imageId`
+- resolved preview data: `image?: DtoImageView`
+
+The same list-page branch is also visible in `DtoStudentSelectResItem`, where the row DTO resolves `image` for table usage.
+
+### Frontend consumption
+
+On the frontend side, the built-in resources consume that contract shape:
+
+- `basic-image:formFieldImage` binds the ID field and reuses the `image` resolved relation field for preview cards
+- `basic-image:image` uses the same resolved relation field to render thumbnails in tables
+
+This is the cleanest single-image chain in the repo.
+
+## Specimen B: multiple images on Record
+
+The Record resource shows the plural branch.
+
+### Backend entity field
+
+The Record entity stores an array of image IDs and points to the same built-in resources:
+
+```typescript
+@Api.field(
+  v.title($locale('ScenePhotos')),
+  v.optional(),
+  ZovaRender.field('basic-image:formFieldImage', {
+    imageScene: 'training-record:sceneImage',
+    multiple: true,
+    maxCount: 9,
+    relationName: 'sceneImages',
+    accept: ['image/png', 'image/jpeg', 'image/webp'],
+    maxSize: 2 * 1024 * 1024,
+    enableCrop: false,
+    resize: {
+      width: 1280,
+      height: 1280,
+      fit: 'contain',
+      format: 'jpeg',
+      quality: 90,
+    },
+  }),
+  ZovaRender.cell('basic-image:image', { relationName: 'sceneImages' }),
+  v.array(v.tableIdentity()),
+)
+sceneImageIds?: TableIdentity[];
+```
+
+### Backend image scene
+
+The matching scene enables multi-image upload policy:
+
+```typescript
+@ImageScene({
+  upload: {
+    maxSize: 2 * 1024 * 1024,
+    mimeTypes: ['image/png', 'image/jpeg', 'image/webp'],
+    multiple: true,
+  },
+})
+export class ImageSceneSceneImage extends BeanBase {}
+```
+
+### DTO-side image resolution
+
+The DTO resolves many IDs into many preview objects:
+
+```typescript
+@Api.field(
+  ZovaRender.visible(false),
+  v.optional(),
+  v.serializerTransform('a-image:resolveViews', {
+    fieldName: 'sceneImageIds',
+    imageScene: 'training-record:sceneImage',
+  }),
+  v.array(DtoImageView),
+)
+sceneImages?: DtoImageView[];
+```
+
+The same pattern also appears in `DtoRecordSelectResItem`, which makes the relation data available for list-page thumbnails.
+
+### Why this branch matters
+
+This branch proves that the same workflow scales from:
+
+- one ID -> one relation object
+- many IDs -> many relation objects
+
+without changing the overall contract-chain model.
+
+## Backend authoring responsibilities
+
+The backend owns the contract truth.
+
+For image workflows, that usually means:
+
+- the entity field defines the stored data shape
+- `ZovaRender.field(...)` chooses the form-side frontend resource identity
+- `ZovaRender.cell(...)` chooses the table-side frontend resource identity
+- the image scene bean defines upload policy
+- the DTO serializer transform resolves stored IDs into preview-ready image view objects
+
+A practical rule is:
+
+- when the business meaning of the image field changes, start by changing backend truth first
+
+For the backend-authoring details, read [Backend Image Guide](/backend/image-guide).
+
+## What crosses the contract boundary
+
+The most important thing that crosses the fullstack boundary is not only the raw image ID.
+
+What really crosses the boundary is the pairing of:
+
+- stored identity field
+- resolved preview field
+
+In the single-image branch, that pair is usually:
+
+- `imageId`
+- `image?: DtoImageView`
+
+In the multi-image branch, that pair is usually:
+
+- `sceneImageIds`
+- `sceneImages?: DtoImageView[]`
+
+This is why the DTO serializer step matters so much.
+
+It turns backend-owned identity data into frontend-friendly preview data without changing the persistence model.
+
+## Frontend consumption responsibilities
+
+The frontend does not redefine the image field contract.
+
+Instead, it consumes the contract through the built-in image resources.
+
+### `basic-image:formFieldImage`
+
+The form-side resource is responsible for:
+
+- selecting files
+- performing frontend validation
+- optionally cropping and resizing in the browser
+- requesting an upload token
+- uploading multipart data
+- binding the stored image ID field
+- synchronizing the resolved relation field for immediate UI refresh
+
+### `basic-image:image`
+
+The table-side resource is responsible for:
+
+- resolving relation-backed preview data first
+- falling back to URL-style values when needed
+- rendering thumbnails
+- opening the shared preview dialog
+
+### Why `relationName` matters
+
+The built-in frontend image resources work best when the resolved relation field is named predictably.
+
+Common pairings are:
+
+- `imageId` -> `image`
+- `sceneImageIds` -> `sceneImages`
+
+When your field names are nonstandard, set `relationName` explicitly so backend DTO resolution and frontend preview lookup stay aligned.
+
+For the frontend runtime details, read [Frontend Image Guide](/frontend/image-guide).
+
+## Single-image vs multi-image differences
+
+The contract chain stays the same, but three details change.
+
+### 1. Stored value shape
+
+- single image: scalar ID such as `imageId`
+- multiple images: ID array such as `sceneImageIds`
+
+### 2. DTO serializer transform
+
+- single image: `a-image:resolveView`
+- multiple images: `a-image:resolveViews`
+
+### 3. Relation preview shape
+
+- single image: one `DtoImageView`
+- multiple images: `DtoImageView[]`
+
+That is the main branching point the fullstack doc should make explicit.
+
+## Where this page sits in the contract loop
+
+This workflow is easiest to understand when you keep the contract-loop vocabulary precise.
+
+- backend field metadata and DTO/image-scene changes belong to backend contract truth
+- image DTO resolution is part of the backend-authored handoff
+- frontend `basic-image` resources are consumers of that truth
+- frontend-specific render behavior is not a reason to duplicate the backend contract
+
+That is why this page sits between:
+
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+
+It is a bridge page for one concrete business thread rather than a general direction guide.
+
+## Verification workflow
+
+When writing or changing image workflow docs, verify in this order.
+
+1. confirm the entity field still points to:
+   - `basic-image:formFieldImage`
+   - `basic-image:image`
+2. confirm the image scene still matches the specimen field
+3. confirm the DTO still uses:
+   - `a-image:resolveView` for single-image fields
+   - `a-image:resolveViews` for multi-image fields
+4. confirm the list-row DTOs still expose the same resolved relation fields for table usage
+5. confirm the frontend image resources still consume the same relation-name pattern
+6. confirm the page stays bridge-focused rather than duplicating the backend or frontend guides
+7. run the docs build and confirm the page appears under `Fullstack / Architecture & Integration`
+
+## Read together with
+
+Use the surrounding docs based on which layer now needs deeper attention.
+
+### Backend policy and authoring details
+
+- [Backend Image Guide](/backend/image-guide)
+- [Upload Guide](/backend/upload-guide)
+- [Serialization Guide](/backend/serialization-guide)
+- [Controller Guide](/backend/controller-guide)
+
+### Frontend runtime and rendering details
+
+- [Frontend Image Guide](/frontend/image-guide)
+- [Form Guide](/frontend/form-guide)
+- [Table Guide](/frontend/table-guide)
+- [TableCell Authoring Cookbook](/frontend/table-cell-cookbook)
+
+### Broader fullstack bridge and contract-loop decisions
+
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+
+A good final question is:
+
+- am I debugging one layer, or am I debugging the handoff between layers?
+
+If the answer is the handoff, this page is the right place to start.

package/cabloy-docs/fullstack/introduction.md

@@ -46,6 +46,7 @@ Use this path when the task is about how backend and frontend stay aligned insid
 - [Vona + Zova Integration](/fullstack/vona-zova-integration)
 - [Contract Loop Playbook](/fullstack/contract-loop-playbook)
 - [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- [Fullstack Image Workflow](/fullstack/image-workflow)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 - [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.97",
+  "version": "5.1.99",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/scripts/upgrade.ts

@@ -50,6 +50,7 @@ const OVERWRITE_DIRS: string[] = [
 const MERGE_DIRS: string[] = [
   // Claude project assets
   '.claude/commands',
+  '.claude/hooks',
   '.claude/skills',
   // Vona Claude project assets
   'vona/.claude/commands',
@@ -67,6 +68,7 @@ const BLACKLIST_DIRS: string[] = [
 const WHITELIST_FILES: string[] = [
   // root
   'CLAUDE.md',
+  '.claude/settings.json',
   'tsconfig.json',
   'tsconfig.base.json',
   'tsconfig.base.esm.json',

package/vona/package.original.json

@@ -30,7 +30,6 @@
     "build:docker": "npm run prerun && npm run vona :bin:build -- --flavor=docker",
     "start": "pnpm -C ./dist/normal install && node ./dist/normal/bootstrap.js",
     "start:one": "pnpm -C ./dist/normal install && cross-env SERVER_WORKERS=1 node ./dist/normal/bootstrap.js",
-    "start:docker": "pnpm -C ./dist/docker install && cross-env SERVER_WORKERS=1 node ./dist/docker/bootstrap.js",
     "prerun": "npm run vona :tools:deps",
     "format": "oxfmt --check",
     "format:fix": "oxfmt --write",

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

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

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "vona-core",
-  "version": "5.1.31",
+  "version": "5.1.32",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona",
   "keywords": [

package/vona/packages-vona/vona-core/src/lib/bean/beanBase.ts

@@ -1,29 +1,29 @@
 import type winston from 'winston';
 
 import type { ILoggerChildRecord, ILoggerClientRecord } from '../../types/interface/logger.ts';
-import type { IModuleLocaleText } from './resource/locale/type.ts';
+// import type { IModuleLocaleText } from './resource/locale/type.ts';
 import type { IBeanScopeContainer } from './scope/beanScopeContainer.ts';
 
 import { BeanBaseSimple, SymbolBeanInstanceKey, SymbolModuleBelong } from './beanBaseSimple.ts';
 
-const SymbolText = Symbol('SymbolText');
+// const SymbolText = Symbol('SymbolText');
 const SymbolLogger = Symbol('SymbolLogger');
 const SymbolLoggerChildren = Symbol('SymbolLoggerChildren');
 
 export class BeanBase extends BeanBaseSimple {
-  private [SymbolText]: IModuleLocaleText;
+  // private [SymbolText]: IModuleLocaleText;
   private [SymbolLogger]: Record<keyof ILoggerClientRecord, winston.Logger> = {} as any;
   private [SymbolLoggerChildren]: Record<
     keyof ILoggerClientRecord,
     Record<string, winston.Logger>
   > = {} as any;
 
-  protected get $text(): IModuleLocaleText {
-    if (!this[SymbolText]) {
-      this[SymbolText] = this.app.meta.locale.createLocaleText(this[SymbolModuleBelong]);
-    }
-    return this[SymbolText];
-  }
+  // protected get $text(): IModuleLocaleText {
+  //   if (!this[SymbolText]) {
+  //     this[SymbolText] = this.app.meta.locale.createLocaleText(this[SymbolModuleBelong]);
+  //   }
+  //   return this[SymbolText];
+  // }
 
   protected get $logger() {
     return this.$loggerClient('default');

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

@@ -1,6 +1,6 @@
 {
   "name": "vona-mock",
-  "version": "6.1.31",
+  "version": "6.1.32",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona mock",
   "keywords": [