cabloy 5.1.101 → 5.1.103

package/cabloy-docs/frontend/use-state-data-best-practices.md

@@ -220,6 +220,60 @@ The better middle ground is:
 
 That is very different from rebuilding a second fetch lifecycle.
 
+### Choose the wait semantic: loaded versus fresh
+
+Waiting for an existing query can mean two different things:
+
+- **Loaded** means a value exists.
+  `$QueryEnsureLoaded(...)` waits only when `query.data === undefined`, so it can continue with an older cached value.
+- **Fresh** means the model's domain-specific validity rule accepts the value.
+  `$QueryGetFresh(...)` and `$QueryEnsureFresh(...)` receive an `isStale(query)` predicate, so the model decides whether loaded data is still safe to consume.
+
+| Need                                 | Helper                          | Missing or stale behavior                                                | Return shape                |
+| ------------------------------------ | ------------------------------- | ------------------------------------------------------------------------ | --------------------------- |
+| An interaction needs any loaded data | `await $QueryEnsureLoaded(...)` | Waits only while `query.data === undefined`                              | Query object or `undefined` |
+| Render may consume only fresh data   | `$QueryGetFresh(...)`           | Starts `query.suspense()` and returns no data for the current render     | `TData \| undefined`        |
+| An interaction requires fresh data   | `await $QueryEnsureFresh(...)`  | Waits for `query.suspense()` and throws a query error when refresh fails | `TData \| undefined`        |
+
+Loaded is an availability condition. Fresh is a validity condition defined by the model; it might use `dataUpdatedAt`, response expiry metadata, or another business rule. `a-model` accepts the predicate and does not prescribe that policy.
+
+For example, `ModelPassport` keeps the temporary-token query and its 30-second reuse rule in the model, while the generic helpers provide the consumption mechanics:
+
+```ts
+import { $QueryEnsureFresh, $QueryGetFresh, BeanModelBase, Model } from 'zova-module-a-model';
+
+@Model()
+export class ModelPassport extends BeanModelBase {
+  getFreshTempAuthToken(options: TempTokenOptions): string | undefined {
+    return $QueryGetFresh(
+      () => this.getTempAuthToken(options),
+      query => this._isTempAuthTokenExpired(query.data, query.dataUpdatedAt, options.staleTime),
+    );
+  }
+
+  async ensureFreshTempAuthToken(options: TempTokenOptions): Promise<string | undefined> {
+    return await $QueryEnsureFresh(
+      () => this.getTempAuthToken(options),
+      query => this._isTempAuthTokenExpired(query.data, query.dataUpdatedAt, options.staleTime),
+    );
+  }
+}
+```
+
+Use the non-blocking facade during render, where stale data should not build a protected URL:
+
+```ts
+const passportCode = this.$passport.getFreshTempAuthToken(options);
+```
+
+Use the awaited facade at an interaction boundary, where a download or preview must not continue with an expired token:
+
+```ts
+const passportCode = await this.$passport.ensureFreshTempAuthToken(options);
+```
+
+Both paths reuse the same model-owned query. When `$QueryGetFresh(...)` finds stale data, it starts `query.suspense()` and returns `undefined` for the current render; reactive query state provides the replacement value on a later render. `$QueryEnsureFresh(...)` instead waits for that refresh and propagates query errors to the interaction flow.
+
 ## Practical rule 7: derive render-time state once per render when possible
 
 Even when the query object is reused, a controller can still become noisy if it repeatedly derives the same values in several helper calls.

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

@@ -0,0 +1,135 @@
+# Fullstack File Workflow
+
+This page follows a Cabloy Basic file field from Vona contract truth to Zova interaction. It is the forward contract loop for `a-file` and `basic-file`.
+
+> Read this with [Backend File Guide](/backend/file-guide), [Frontend File Guide](/frontend/file-guide), and [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
+## One business field, two consumer surfaces
+
+A file-backed business field persists IDs, while a DTO relation carries completed-file presentation data. The training-record module is the reference pattern:
+
+```ts
+// Vona scene: one trusted business capability
+@FileScene({
+  public: false,
+  upload: {
+    maxSize: 20 * 1024 * 1024,
+    mimeTypes: ['application/pdf', 'application/zip', 'text/plain'],
+    extensions: ['.pdf', '.zip', '.txt'],
+    multiple: true,
+  },
+})
+export class FileSceneDossierFile extends BeanBase {}
+
+// Entity: persist only IDs and attach Zova resource renderers
+@Api.field(
+  ZovaRender.field('basic-file:formFieldFile', {
+    fileScene: 'training-record:dossierFile',
+    relationName: 'dossierFiles',
+    maxCount: 3,
+  }),
+  ZovaRender.cell('basic-file:file', { relationName: 'dossierFiles' }),
+  v.array(v.tableIdentity()),
+)
+dossierFileIds?: TableIdentity[];
+
+// Consumer DTO: resolve completed display/delivery data
+@Api.field(
+  v.optional(),
+  v.serializerTransform('a-file:resolveViews', {
+    fieldName: 'dossierFileIds',
+    fileScene: 'training-record:dossierFile',
+  }),
+  v.array(DtoFileView),
+)
+dossierFiles?: DtoFileView[];
+```
+
+Keep the persisted field, resolved relation, `relationName`, and scene name aligned. `DtoFileView` is a consumer projection; it does not replace ID persistence. The serializer verifies the optional scene while resolving IDs, preventing a relation from silently consuming a file from another business capability.
+
+## Three ingestion paths and readiness
+
+### 1. Ordinary local upload
+
+```text
+Zova field
+→ authenticated POST /file/upload(fileScene, file)
+→ Vona validates received multipart file and resolves scene/provider
+→ provider storage
+→ ready action response
+→ ID field and relation update
+```
+
+The backend owns validation and storage. The response is ready immediately after backend storage; this is the portable Native-compatible path and needs no file upload token.
+
+### 2. Remote HTTPS URL import
+
+```text
+authorized server/API consumer
+→ POST /file/upload-url
+→ provider capability check
+→ secure HTTPS remote-fetch boundary
+→ provider storage
+→ ready action response
+```
+
+Remote import is not built into the browser field. It is a server/provider operation: the selected provider validates remote URL safety and actual content before storage. Native does not support this path; Cloudflare R2 does. A browser must not implement its own unrestricted remote fetch.
+
+### 3. Third-party direct upload
+
+```text
+policy.directUpload
+→ POST /file/direct-upload
+→ Cabloy draft + raw-body provider target
+→ browser transfers raw File without Cabloy credentials
+→ POST /file/direct-upload/finalize
+→ provider metadata verification + ready state
+→ ID field and relation update
+```
+
+A direct target is draft-only, not a completed file. Finalization is the only promotion to `ready`; drafts cannot resolve views, be downloaded, or enter business IDs/relations. The frontend uses returned method/headers for raw file transfer and stores only the finalized response.
+
+## Forward contract loop
+
+When a File contract changes, work from backend truth toward generated consumers:
+
+1. define or update the Vona `@FileScene`, persisted ID field, controller/DTO policy, and `a-file:resolveView(s)` relation;
+2. regenerate Vona metadata and inspect the emitted Swagger/OpenAPI contract;
+3. regenerate the filtered `basic-file` OpenAPI consumer;
+4. keep hand-authored Zova behavior in `ModelFile`, `ControllerFormFieldFile`, and `TableCellFile` thin and policy-driven;
+5. build the affected Admin and Web flavors, then run `npm run deps:vona` for the reverse dependency handoff.
+
+Generated contract outputs include:
+
+```text
+zova/.../basic-file/src/api/file.ts
+zova/.../basic-file/src/apiSchema/file.ts
+zova/.../basic-file/src/api/openapi/types.ts
+zova/.../basic-file/src/api/openapi/schemas.ts
+```
+
+Do not hand-edit these generated files. `ModelFile`, the form-field controller, the table cell, and Vona render metadata are hand-authored extension points.
+
+## Cross-layer invariants
+
+| Layer             | Owns                                                                                                     | Must not own                                                       |
+| ----------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Vona `a-file`     | scene policy, provider/client selection, actual validation, lifecycle, storage, visibility, and delivery | browser-controlled provider or storage choices                     |
+| DTO serializer    | safe `DtoFileView` projection and scene matching                                                         | persistence replacement or storage metadata disclosure             |
+| Zova `basic-file` | picker UX, local UX checks, policy-driven transport, ID/relation synchronization                         | provider selection, storage URL construction, or draft persistence |
+| Provider transfer | raw body transfer for a direct target                                                                    | Cabloy session credential forwarding                               |
+
+The frontend reads `downloadUrl` from a resolved view; it never constructs delivery URLs from IDs, buckets, or object keys. Upload-policy capability is semantic (`directUpload`), so frontend code never branches on provider identity.
+
+## Verification checklist
+
+For a File contract or workflow change, verify:
+
+1. the scene policy and persisted ID field match the intended business capability;
+2. create/view/list DTO schemas expose the matching `DtoFileView` relation and serializer transform;
+3. Swagger/OpenAPI contains the expected policy, multipart, direct-finalize, and URL-import actions;
+4. regenerated `basic-file` API/schema output is used rather than hand-patched;
+5. Native reports no direct/URL-import capability while the configured Cloudflare R2 scene advertises direct upload only when creation and finalization are both available;
+6. a draft cannot resolve a view or download URL, and the form updates only after finalization;
+7. private/public delivery still uses resolved URLs without leaking provider/storage data;
+8. run the affected Admin and Web builds and then `npm run deps:vona` after a generated frontend handoff.

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

@@ -291,11 +291,20 @@ 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
+- selecting the policy-supported ordinary or direct upload transport
+- binding the finalized stored image ID field
+- synchronizing the relation preview only after upload completion
 - synchronizing the resolved relation field for immediate UI refresh
 
+### Upload transport selection
+
+The form field waits for the backend image-scene upload policy and selects one of two server-authorized paths:
+
+- ordinary scenes submit authenticated multipart `imageScene` and `image` data to Cabloy;
+- direct-capable scenes create a direct-upload session, send the image to the returned provider URL without Cabloy credentials, and finalize using the returned Cabloy image ID.
+
+The browser does not branch on provider identity. In both paths, it updates the stored ID field and resolved relation preview only after it has a completed image response; a direct-upload draft is never used as the form value.
+
 ### `basic-image:image`
 
 The table-side resource is responsible for:

package/package.json

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

package/scripts/upgrade.ts

@@ -47,6 +47,14 @@ const OVERWRITE_DIRS: string[] = [
   'zova/scripts',
 ];
 
+const OVERWRITE_DIRS_CABLOY_BASIC: string[] = [
+  'vona/src/suite/cabloy-basic',
+  'vona/src/suite/a-training',
+  'zova/src/suite/cabloy-basic',
+  'zova/src/suite/a-training',
+  'zova/src/suite/a-devui',
+];
+
 const MERGE_DIRS: string[] = [
   // Claude project assets
   '.claude/commands',
@@ -242,8 +250,12 @@ async function downloadAndExtract(tarballUrl: string): Promise<void> {
 // --- Step 3: Selective overwrite ---
 
 function selectiveOverwrite(dryRun?: boolean): void {
+  const overwriteDirs = existsSync(resolve(ROOT_DIR, '__CABLOY_BASIC__'))
+    ? [...OVERWRITE_DIRS, ...OVERWRITE_DIRS_CABLOY_BASIC]
+    : OVERWRITE_DIRS;
+
   // Overwrite directories
-  for (const dir of OVERWRITE_DIRS) {
+  for (const dir of overwriteDirs) {
     const src = resolve(TEMP_DIR, dir);
     const dest = resolve(ROOT_DIR, dir);
     if (!existsSync(src)) continue;
@@ -316,13 +328,12 @@ function runInitTestData(dryRun: boolean): void {
 // --- Step 6: Cleanup ---
 
 function cleanup(dryRun?: boolean): void {
-  if (dryRun) {
-    log('  [dry-run] Remove temp dir: node_modules/.cabloy-upgrade/');
-    return;
-  }
   if (existsSync(TEMP_DIR)) {
     rmSync(TEMP_DIR, { recursive: true, force: true });
   }
+  if (dryRun) {
+    log('  [dry-run] Removed temp dir: node_modules/.cabloy-upgrade/');
+  }
 }
 
 // --- Main ---
@@ -350,15 +361,20 @@ async function main(): Promise<void> {
   if (currentVersion) {
     const comparison = compareVersions(currentVersion, latestPackageInfo.version);
     if (comparison === 0) {
-      log(`Cabloy is already up to date (current: ${currentVersion}). Skipping upgrade.`);
-      return;
-    }
-    if (comparison > 0) {
+      if (!dryRun) {
+        log(`Cabloy is already up to date (current: ${currentVersion}). Skipping upgrade.`);
+        return;
+      }
+      log(
+        `Cabloy is already up to date (current: ${currentVersion}). Continuing dry-run to show overwrite plan.\n`,
+      );
+    } else if (comparison > 0) {
       throw new Error(
         `Project Cabloy version ${currentVersion} is newer than npm latest ${latestPackageInfo.version}. Aborting upgrade.`,
       );
+    } else {
+      log(`Upgrading Cabloy from ${currentVersion} to ${latestPackageInfo.version}...\n`);
     }
-    log(`Upgrading Cabloy from ${currentVersion} to ${latestPackageInfo.version}...\n`);
   } else {
     log(`Upgrading Cabloy to ${latestPackageInfo.version}...\n`);
   }

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

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.72",
+  "version": "5.1.73",
   "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-training/modules/training-record/src/.metadata/index.ts

@@ -388,20 +388,46 @@ declare module 'vona-module-training-record' {
           } 
 }
 /** ssrMenu: end */
+/** fileScene: begin */
+export * from '../bean/fileScene.dossierFile.ts';
+
+import { type IDecoratorFileSceneOptions } from 'vona-module-a-file';
+declare module 'vona-module-a-file' {
+
+    export interface IFileSceneRecord {
+      'training-record:dossierFile': IDecoratorFileSceneOptions;
+    }
+
+
+}
+declare module 'vona-module-training-record' {
+
+        export interface FileSceneDossierFile {
+          /** @internal */
+          get scope(): ScopeModuleTrainingRecord;
+        }
+
+          export interface FileSceneDossierFile {
+            get $beanFullName(): 'training-record.fileScene.dossierFile';
+            get $onionName(): 'training-record:dossierFile';
+            get $onionOptions(): IDecoratorFileSceneOptions;
+          }
+}
+/** fileScene: end */
 /** imageScene: begin */
 export * from '../bean/imageScene.sceneImage.ts';
 
 import { type IDecoratorImageSceneOptions } from 'vona-module-a-image';
 declare module 'vona-module-a-image' {
-  
+
     export interface IImageSceneRecord {
       'training-record:sceneImage': IDecoratorImageSceneOptions;
     }
 
-  
+
 }
 declare module 'vona-module-training-record' {
-  
+
         export interface ImageSceneSceneImage {
           /** @internal */
           get scope(): ScopeModuleTrainingRecord;
@@ -411,7 +437,7 @@ declare module 'vona-module-training-record' {
             get $beanFullName(): 'training-record.imageScene.sceneImage';
             get $onionName(): 'training-record:sceneImage';
             get $onionOptions(): IDecoratorImageSceneOptions;
-          } 
+          }
 }
 /** imageScene: end */
 /** locale: begin */

package/vona/src/suite/a-training/modules/training-record/src/bean/fileScene.dossierFile.ts

@@ -2,6 +2,7 @@ import { BeanBase } from 'vona';
 import { FileScene } from 'vona-module-a-file';
 
 @FileScene({
+  public: false,
   upload: {
     maxSize: 20 * 1024 * 1024,
     mimeTypes: [
@@ -16,7 +17,6 @@ import { FileScene } from 'vona-module-a-file';
     ],
     extensions: ['.pdf', '.doc', '.docx', '.xls', '.xlsx', '.zip', '.txt'],
     multiple: true,
-    public: false,
   },
 })
 export class FileSceneDossierFile extends BeanBase {}

package/vona/src/suite/a-training/modules/training-record/src/bean/imageScene.sceneImage.ts

@@ -2,6 +2,7 @@ import { BeanBase } from 'vona';
 import { ImageScene } from 'vona-module-a-image';
 
 @ImageScene({
+  public: false,
   upload: {
     maxSize: 2 * 1024 * 1024,
     mimeTypes: ['image/png', 'image/jpeg', 'image/webp'],

package/vona/src/suite/a-training/modules/training-record/src/dto/recordSelectResItem.tsx

@@ -1,5 +1,6 @@
 import type { IDecoratorDtoOptions } from 'vona-module-a-web';
 
+import { DtoFileView } from 'vona-module-a-file';
 import { DtoImageView } from 'vona-module-a-image';
 import { Api, v } from 'vona-module-a-openapiutils';
 import { $Dto } from 'vona-module-a-orm';
@@ -7,9 +8,7 @@ import { Dto } from 'vona-module-a-web';
 import { ZovaRender } from 'zova-rest-cabloy-basic-admin';
 
 import { $locale } from '../.metadata/locales.ts';
-import { resolveDossierFiles } from '../lib/resolveDossierFiles.ts';
 import { ModelRecord } from '../model/record.ts';
-import { DtoRecordDossierFileView } from './recordDossierFileView.ts';
 
 export interface IDtoOptionsRecordSelectResItem extends IDecoratorDtoOptions {}
 
@@ -34,6 +33,7 @@ export class DtoRecordSelectResItem extends $Dto.get(() => ModelRecord) {
     v.serializerTransform('a-image:resolveViews', {
       fieldName: 'sceneImageIds',
       imageScene: 'training-record:sceneImage',
+      deliveryOptions: { audience: true },
     }),
     v.array(DtoImageView),
   )
@@ -43,12 +43,14 @@ export class DtoRecordSelectResItem extends $Dto.get(() => ModelRecord) {
     v.title($locale('DossierFiles')),
     ZovaRender.visible(false),
     v.optional(),
-    v.serializerTransform('a-serialization:custom', {
-      custom: resolveDossierFiles,
+    v.serializerTransform('a-file:resolveViews', {
+      fieldName: 'dossierFileIds',
+      fileScene: 'training-record:dossierFile',
+      deliveryOptions: { audience: true },
     }),
-    v.array(DtoRecordDossierFileView),
+    v.array(DtoFileView),
   )
-  dossierFiles?: DtoRecordDossierFileView[];
+  dossierFiles?: DtoFileView[];
 
   @Api.field(
     v.title($locale('Operations')),

package/vona/src/suite/a-training/modules/training-record/src/dto/recordView.tsx

@@ -1,5 +1,6 @@
 import type { IDecoratorDtoOptions } from 'vona-module-a-web';
 
+import { DtoFileView } from 'vona-module-a-file';
 import { DtoImageView } from 'vona-module-a-image';
 import { $makeMetadata, Api, v } from 'vona-module-a-openapiutils';
 import { $Dto } from 'vona-module-a-orm';
@@ -7,11 +8,9 @@ import { Dto } from 'vona-module-a-web';
 import { ZovaRender } from 'zova-rest-cabloy-basic-admin';
 
 import { $locale } from '../.metadata/locales.ts';
-import { resolveDossierFiles } from '../lib/resolveDossierFiles.ts';
 import { ModelRecord } from '../model/record.ts';
 import { DtoDetailRecordSubjectResItem } from './detailRecordSubjectResItem.tsx';
 import { DtoDetailRecordSubjectView } from './detailRecordSubjectView.tsx';
-import { DtoRecordDossierFileView } from './recordDossierFileView.ts';
 
 export interface IDtoOptionsRecordView extends IDecoratorDtoOptions {}
 
@@ -46,6 +45,7 @@ export class DtoRecordView extends $Dto.get(() => ModelRecord, {
     v.serializerTransform('a-image:resolveViews', {
       fieldName: 'sceneImageIds',
       imageScene: 'training-record:sceneImage',
+      deliveryOptions: { audience: true },
     }),
     v.array(DtoImageView),
   )
@@ -55,12 +55,14 @@ export class DtoRecordView extends $Dto.get(() => ModelRecord, {
     v.title($locale('DossierFiles')),
     ZovaRender.visible(false),
     v.optional(),
-    v.serializerTransform('a-serialization:custom', {
-      custom: resolveDossierFiles,
+    v.serializerTransform('a-file:resolveViews', {
+      fieldName: 'dossierFileIds',
+      fileScene: 'training-record:dossierFile',
+      deliveryOptions: { audience: true },
     }),
-    v.array(DtoRecordDossierFileView),
+    v.array(DtoFileView),
   )
-  dossierFiles?: DtoRecordDossierFileView[];
+  dossierFiles?: DtoFileView[];
 
   @Api.field(ZovaRender.visible(false), v.optional(), v.array(DtoDetailRecordSubjectResItem))
   _trainingRecordSubjects?: DtoDetailRecordSubjectResItem[];

package/vona/src/suite/a-training/modules/training-record/src/index.ts

@@ -1,6 +1,5 @@
 export * from './bean/fileScene.dossierFile.ts';
 export * from './bean/imageScene.sceneImage.ts';
-export * from './dto/recordDossierFileView.ts';
 export * from './lib/index.ts';
 export * from './.metadata/locales.ts';
 export * from './.metadata/index.ts';

package/vona/src/suite/a-training/modules/training-record/src/lib/index.ts

@@ -1,3 +1,2 @@
 export * from './onEffectForAverageScore.tsx';
 export * from './onEffectForTrainingRecordSubjects.tsx';
-export * from './resolveDossierFiles.ts';

package/vona/src/suite/a-training/modules/training-record/test/record.test.ts

@@ -43,10 +43,6 @@ describe('record.test.ts', () => {
             filename: 'attendance.txt',
             contentType: 'text/plain',
             public: false,
-            meta: {
-              category: 'attendanceSheet',
-              source: 'upload',
-            },
           },
           {
             clientName: 'default',
@@ -96,18 +92,24 @@ describe('record.test.ts', () => {
         assert.equal(String(record.studentId), String(studentId));
         assert.equal(record.subjectCount, recordData.subjectCount);
         assert.equal(record.totalScore, recordData.totalScore);
-        assert.equal(record.averageScore, recordData.averageScore);
+        assert.equal(Number(record.averageScore), recordData.averageScore);
         assert.equal(new Date(record.trainingTime).toISOString(), trainingTime.toISOString());
         assert.equal(record.dossierFileIds?.length, 1);
         assert.equal(record.dossierFiles?.length, 1);
         assert.equal(String(recordDossierFile?.id), String(dossierFileAttendance.id));
         assert.equal(recordDossierFile?.filename, 'attendance.txt');
         assert.equal(recordDossierFile?.signed, true);
-        assert.equal(recordDossierFile?.meta?.category, 'attendanceSheet');
+        assert.equal('meta' in (recordDossierFile ?? {}), false);
+        assert.equal('fileScene' in (recordDossierFile ?? {}), false);
         assert.equal(record.trainingRecordSubjects?.length, 1);
         assert.equal(recordSubject?.name, '__Math__');
         assert.equal(recordSubject?.score, 95);
-        const downloadResponse = await fetch(recordDossierFile.downloadUrl);
+        const passportCode = await app.bean.passport.createTempAuthToken({
+          path: '/api/file/download',
+        });
+        const downloadUrl = new URL(recordDossierFile.downloadUrl);
+        downloadUrl.searchParams.set('x-vona-passport-code', passportCode);
+        const downloadResponse = await fetch(downloadUrl);
         assert.equal(downloadResponse.ok, true);
         assert.equal(await downloadResponse.text(), dossierTextAttendance.toString());
 
@@ -129,10 +131,6 @@ describe('record.test.ts', () => {
             filename: 'assessment.txt',
             contentType: 'text/plain',
             public: false,
-            meta: {
-              category: 'assessmentReport',
-              source: 'upload',
-            },
           },
           {
             clientName: 'default',
@@ -174,7 +172,7 @@ describe('record.test.ts', () => {
         assert.equal(record.name, dataUpdate.name);
         assert.equal(record.subjectCount, dataUpdate.subjectCount);
         assert.equal(record.totalScore, dataUpdate.totalScore);
-        assert.equal(record.averageScore, dataUpdate.averageScore);
+        assert.equal(Number(record.averageScore), dataUpdate.averageScore);
         assert.equal(new Date(record.trainingTime).toISOString(), trainingTimeUpdate.toISOString());
         assert.equal(record.dossierFileIds?.length, 2);
         assert.equal(record.dossierFiles?.length, 2);

package/vona/src/suite/a-training/modules/training-student/src/bean/imageScene.studentImage.ts

@@ -2,6 +2,7 @@ import { BeanBase } from 'vona';
 import { ImageScene } from 'vona-module-a-image';
 
 @ImageScene({
+  public: true,
   upload: {
     maxSize: 2 * 1024 * 1024,
     mimeTypes: ['image/png', 'image/jpeg', 'image/webp'],

package/vona/src/suite/a-training/modules/training-student/src/dto/detailRecordBase.tsx

@@ -1,16 +1,12 @@
 import type { IDecoratorDtoOptions } from 'vona-module-a-web';
 
 import { $Class } from 'vona';
+import { DtoFileView } from 'vona-module-a-file';
 import { DtoImageView } from 'vona-module-a-image';
 import { $makeMetadata, Api, v } from 'vona-module-a-openapiutils';
 import { $Dto } from 'vona-module-a-orm';
 import { Dto } from 'vona-module-a-web';
-import {
-  DtoRecordDossierFileView,
-  ModelRecord,
-  onEffectForTrainingRecordSubjects,
-  resolveDossierFiles,
-} from 'vona-module-training-record';
+import { ModelRecord, onEffectForTrainingRecordSubjects } from 'vona-module-training-record';
 import { ZovaRender } from 'zova-rest-cabloy-basic-admin';
 
 import { $locale } from '../.metadata/locales.ts';
@@ -50,6 +46,7 @@ export class DtoDetailRecordBase extends $Dto.get(() => ModelRecord, {
     v.serializerTransform('a-image:resolveViews', {
       fieldName: 'sceneImageIds',
       imageScene: 'training-record:sceneImage',
+      deliveryOptions: { audience: true },
     }),
     v.array($Class.partial(DtoImageView)),
   )
@@ -59,10 +56,12 @@ export class DtoDetailRecordBase extends $Dto.get(() => ModelRecord, {
     v.title($locale('DossierFiles')),
     ZovaRender.visible(false),
     v.optional(),
-    v.serializerTransform('a-serialization:custom', {
-      custom: resolveDossierFiles,
+    v.serializerTransform('a-file:resolveViews', {
+      fieldName: 'dossierFileIds',
+      fileScene: 'training-record:dossierFile',
+      deliveryOptions: { audience: true },
     }),
-    v.array($Class.partial(DtoRecordDossierFileView)),
+    v.array($Class.partial(DtoFileView)),
   )
-  dossierFiles?: Partial<DtoRecordDossierFileView>[];
+  dossierFiles?: Partial<DtoFileView>[];
 }

package/vona/src/suite/a-training/modules/training-student/test/student.test.ts

@@ -87,7 +87,7 @@ describe('student.test.ts', () => {
       assert.equal(record?.name, '__Record__');
       assert.equal(record?.subjectCount, 1);
       assert.equal(record?.totalScore, 88);
-      assert.equal(record?.averageScore, 88);
+      assert.equal(Number(record?.averageScore), 88);
       assert.equal(new Date(record?.trainingTime).toISOString(), trainingTime.toISOString());
       assert.equal(record?.trainingRecordSubjects?.length, 1);
       assert.equal(recordSubject?.name, '__Math__');
@@ -141,7 +141,7 @@ describe('student.test.ts', () => {
       assert.equal(updatedRecord?.name, '__RecordNew__');
       assert.equal(updatedRecord?.subjectCount, 2);
       assert.equal(updatedRecord?.totalScore, 183);
-      assert.equal(updatedRecord?.averageScore, 91.5);
+      assert.equal(Number(updatedRecord?.averageScore), 91.5);
       assert.equal(
         new Date(updatedRecord?.trainingTime).toISOString(),
         trainingTimeUpdate.toISOString(),

package/vona/src/suite-vendor/a-file/modules/a-file/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-a-file",
-  "version": "5.0.4",
+  "version": "5.0.5",
   "description": "",
   "keywords": [
     "Vona Module"
@@ -9,7 +9,8 @@
   "files": [
     "assets",
     "dist",
-    "src"
+    "src",
+    "cli"
   ],
   "type": "module",
   "exports": {