cabloy 5.1.98 → 5.1.99

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

@@ -0,0 +1,384 @@
+# `$useStateData` Best Practices
+
+This guide explains how to use `$useStateData(...)` well in Zova, especially when you are deciding whether a piece of async frontend data should behave like render-time state or interaction-time ad hoc fetch logic.
+
+Read [Model Architecture](/frontend/model-architecture) first if you want the broader role of Model.
+
+Read [Model State Guide](/frontend/model-state-guide) first if you want the larger helper-family overview.
+
+Use this page when your real design question is one of these:
+
+- should this async value live in a model query or stay inside one controller?
+- should the query be established during render or only during interaction?
+- should I use `enabled: false` or let the query participate in the normal lifecycle?
+- how should I think about `disableSuspenseOnInit: true`?
+- if I remove a manual `ensure...()` helper, can interaction still wait for query readiness when needed?
+
+## Why this page exists
+
+`$useStateData(...)` is easy to misuse if it is treated only as a request helper.
+
+The larger value is architectural:
+
+- model-owned async state gets one stable owner
+- query identity, persistence, restore, and refetch behavior stay in one place
+- render logic can consume a formal query state instead of rebuilding mini loading/cache systems in controllers
+
+The common failure mode is not that the code stops working immediately.
+
+The common failure mode is that the code keeps working while the state model becomes increasingly command-oriented, duplicated, and difficult to reason about.
+
+## The core mental model
+
+The best starting point is simple:
+
+> treat `$useStateData(...)` as a model-owned async state source, not only as a function that happens to fetch data.
+
+That changes several downstream decisions.
+
+If a value affects:
+
+- whether a button can be clicked
+- accepted file types
+- maximum upload size
+- whether a UI branch is shown
+- whether a flow can continue safely
+
+then that value is usually not just a click-time fetch result.
+It is part of the page's real interaction state.
+
+## Practical rule 1: prefer model ownership for reusable async state
+
+When a value has broader reuse, persistence, or lifecycle requirements, prefer model ownership.
+
+Typical good fits are:
+
+- upload policy by scene
+- resource bootstrap
+- schema metadata
+- permission/capability state
+- query-style domain state reused across pages or components
+
+Typical weak fits are:
+
+- a one-off page-local toggle
+- a tiny local interaction detail with no reuse value
+- temporary page-only state that does not benefit from caching or restore semantics
+
+### Review question
+
+Ask:
+
+> if another controller needed this same async value tomorrow, would I want the ownership and lifecycle policy to already exist in one model?
+
+If the answer is yes, that state usually belongs in a model.
+
+## Practical rule 2: if the value affects render or interaction rules, establish the query during render
+
+If a value determines runtime interaction conditions, prefer this shape:
+
+1. model exposes `getXxx(...)`
+2. controller/page establishes the query during render
+3. render consumes `data`, `pending`, and derived values
+4. interaction consumes that existing query state instead of inventing a second lifecycle
+
+### Why this is good
+
+This keeps the UI honest.
+
+The rendered UI can already know:
+
+- whether interaction should wait
+- which accept/multiple flags apply
+- which validation path should be used
+
+### Smell
+
+A controller renders as though the interaction is ready, but clicking the button is what really begins the important state lookup.
+
+That is a sign that a query-state concern may have been pushed too far into imperative interaction code.
+
+## Practical rule 3: `disableSuspenseOnInit: true` disables the init-time `query.suspense()` kick, not the query itself
+
+This point needs precise wording.
+
+Current model runtime shows that `$useStateData(...)` creates the query wrapper first, then, only on first creation, optionally calls `query.suspense()`:
+
+```ts
+if (!this[SymbolUseQueries][queryHash]) {
+  const useQuery = this.$useQuery(options, queryClient);
+  this[SymbolUseQueries][queryHash] = useQuery;
+  if (!options.meta?.disableSuspenseOnInit) {
+    useQuery.suspense();
+  }
+}
+```
+
+Two details matter:
+
+- the query is already created either way
+- the runtime does **not** use `await` there
+
+So `disableSuspenseOnInit: true` does **not** mean “block vs do not block render” in a strict synchronous sense.
+
+It more precisely means:
+
+- with default behavior, the first consumer of that query immediately kicks one init-time `query.suspense()` call
+- with `disableSuspenseOnInit: true`, that automatic init-time kick is skipped
+
+This option is often a good fit when you want:
+
+- query state to exist immediately
+- persistence/restore/refetch behavior to remain normal
+- no automatic init-time `query.suspense()` kick on first creation
+
+Representative pattern:
+
+```ts
+getUploadPolicy(imageScene?: string) {
+  if (!imageScene) return undefined;
+  return this.$useStateData({
+    queryKey: ['uploadPolicy', 'image', imageScene],
+    queryFn: async () => {
+      return this.scope.api.image.getUploadPolicy({ imageScene });
+    },
+    meta: {
+      disableSuspenseOnInit: true,
+    },
+  });
+}
+```
+
+### What it does not mean
+
+It does not mean:
+
+- no query should be created
+- no request should run
+- no persisted value should be restored
+- no refetch should happen later
+- interaction can never explicitly wait for query readiness
+
+That distinction matters a lot.
+
+## Practical rule 4: distinguish three different semantics
+
+A useful review habit is to keep these three behaviors separate.
+
+| Case                                                            | What happens                                                                       | What it does **not** mean                                                          | Best fit                                                                                                                         |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Default `$useStateData(...)`                                    | On first query creation, runtime immediately calls `query.suspense()` once         | It does **not** synchronously `await` readiness in that call site                  | Data where “first consumer should eagerly kick one refresh/update semantic” is a good default                                    |
+| `$useStateData(..., { meta: { disableSuspenseOnInit: true } })` | Query still exists, but the automatic init-time `query.suspense()` kick is skipped | It does **not** disable the query, persistence, restore, or later refetch behavior | Data that is relatively stable inside the current frontend process and does not need an automatic first-consumer kick every time |
+| `await query.suspense()`                                        | Current logic sequence explicitly waits until the query is ready                   | It is **not** merely a hint or passive kickoff                                     | Interaction or orchestration boundaries where later logic must not continue until the value is ready                             |
+
+Two practical consequences follow from this table:
+
+1. multiple synchronous `query.suspense()` calls can still deduplicate at the query runtime level
+2. only explicit `await query.suspense()` introduces a true sequencing guarantee for the current logic path
+
+## Practical rule 5: be cautious with `enabled: false` and `staleTime: Infinity`
+
+These options are useful, but they are easy to over-apply.
+
+### `enabled: false`
+
+Use it when the query should not exist yet because a real prerequisite is missing.
+
+Good examples:
+
+- required params are absent
+- the page is in a branch where the query truly does not apply
+- the query would be meaningless or invalid before some explicit condition
+
+Be cautious when the real motivation is only:
+
+- “I want to fetch later when the user clicks”
+
+That often means you are taking a state concern and turning it back into a command concern.
+
+### `staleTime: Infinity`
+
+Use it when the value is effectively static for the relevant session.
+
+Be cautious when the underlying backend configuration may change.
+
+If backend scene config can change, letting the query participate in normal freshness/refetch rules is usually healthier than freezing it forever.
+
+## Practical rule 6: removing a manual `ensure...()` helper does not mean interaction can never wait
+
+A common over-correction is:
+
+- first version: controller manually owns fetching through `ensure...()`
+- second version: remove `ensure...()` and assume interaction must never wait for anything
+
+The better middle ground is:
+
+- query lifecycle remains model-owned
+- query is established during render
+- interaction consumes the existing query
+- if an edge timing window appears, interaction may wait for the existing query to finish
+
+That is very different from rebuilding a second fetch lifecycle.
+
+## 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.
+
+A good cleanup pattern is to derive one local state object such as:
+
+- `acceptAttr`
+- `multiple`
+- `pending`
+
+and let input/button/render branches consume that shared result.
+
+### Why this helps
+
+It makes one render pass easier to understand:
+
+- what query-backed state is being consumed
+- which UI props come from that state
+- where the interaction gate really is
+
+### Smell
+
+The controller repeatedly:
+
+- grabs the same query
+- re-reads the same policy data
+- re-derives the same `multiple` or `accept` value in several places
+
+That is often a sign that local render-time derivation should be consolidated.
+
+## Practical rule 8: design query keys so the ownership boundary is obvious
+
+Prefer keys that make the domain explicit.
+
+For example:
+
+- `['uploadPolicy', 'image', imageScene]`
+- `['uploadPolicy', 'file', fileScene]`
+
+This is usually better than ambiguous cross-domain shapes such as:
+
+- `['uploadPolicy', scene]`
+
+### Why this matters
+
+Readable keys improve:
+
+- debugging
+- tracing cache behavior
+- future refactors when similar query families grow
+
+## Anti-pattern: command-first controller state
+
+A common anti-pattern looks like this:
+
+- model query is disabled by default
+- controller clicks trigger `ensure...()`
+- controller maintains the important timing logic itself
+- render does not fully know the interaction conditions yet
+
+### Why this is harmful
+
+- the model no longer owns the full lifecycle cleanly
+- restore/refetch semantics are weakened or bypassed
+- controller responsibilities grow too large
+- interaction rules become harder to inspect from the render path
+
+## Better pattern: model-owned query, render-owned derivation, interaction-owned orchestration
+
+A healthier split is:
+
+### Model owns
+
+- `queryKey`
+- `queryFn`
+- persistence/restore/refetch lifecycle
+- the stable meaning of the async state
+
+### Controller/page owns
+
+- how the query-backed state is rendered
+- derived props needed by the current UI
+- user interaction flow
+- edge-timing waits on the already-existing query when necessary
+
+This creates a much cleaner division of responsibilities.
+
+## Representative examples
+
+### Example A: resource entry pages usually prefer the default init-time kick
+
+A good counterexample to overusing `disableSuspenseOnInit: true` is the resource entry-page branch.
+
+Useful reading pages are:
+
+- [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+- [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+
+In that branch, the practical expectation is often:
+
+- opening a row page may show an already-known value first
+- but entering that page should still eagerly kick one update semantic for the item-level state
+- the page benefits from the default “first consumer kicks `query.suspense()` once” behavior
+
+This makes entry pages a good mental model for queries where the default init-time kick is healthy:
+
+- the query is a real page-state dependency
+- the first consumer should actively nudge freshness
+- you usually do not want every caller to remember to add that kickoff manually
+
+This is not about synchronous blocking.
+It is about preserving the default eager-init semantic when the first consumer of that page state appears.
+
+### Example B: upload policy prefers `disableSuspenseOnInit: true`
+
+Representative files in the Cabloy Basic frontend:
+
+- `zova/src/suite/cabloy-basic/modules/basic-image/src/model/image.ts`
+- `zova/src/suite/cabloy-basic/modules/basic-file/src/model/file.ts`
+- `zova/src/suite/cabloy-basic/modules/basic-image/src/component/formFieldImage/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-file/src/component/formFieldFile/controller.tsx`
+
+### What this example demonstrates
+
+- `getUploadPolicy(...)` stays in the model
+- the query is created as formal state instead of a one-off click helper
+- `disableSuspenseOnInit: true` skips the automatic init-time `query.suspense()` kick while preserving the query as formal state
+- render derives `acceptAttr`, `multiple`, and `pending`
+- interaction reuses that state
+- interaction may still `await query.suspense()` on the already-created query if an edge timing window requires it
+
+Why this is a good fit:
+
+- upload policy is a real query-backed state
+- it is relatively stable within the current frontend process
+- every first consumer does not need to auto-kick one eager init-time refresh semantic
+- the strict-ready moment is the interaction boundary, not every initial render consumer
+
+Taken together, Example A and Example B show the most important design contrast on this page:
+
+- entry-page item state is a good example of why the default init-time kick can be valuable
+- upload policy is a good example of why a stable state may still be a formal query while skipping that init-time kick
+
+## Checklist before you use `$useStateData(...)`
+
+Ask these questions:
+
+1. Is this value really a reusable async state source rather than a one-off action result?
+2. Will this value affect render or interaction conditions?
+3. Should another page or controller be able to consume the same lifecycle and cache policy later?
+4. Is `disableSuspenseOnInit: true` enough, instead of disabling the query entirely?
+5. Would `enabled: false` or `staleTime: Infinity` accidentally cut off useful restore/refetch behavior?
+6. If interaction needs a safety wait, can it wait on the existing query rather than reintroducing a manual `ensure...()` lifecycle?
+7. Can I derive the render-time state once and reuse it across the UI branch?
+
+## Final takeaway
+
+The most important usage insight is simple:
+
+> `$useStateData(...)` is strongest when it models async state that the UI can render from, persist, restore, and refresh naturally.
+
+When that mindset is clear, controllers become thinner, models become more authoritative, and query lifecycle decisions become easier to reason about.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.98",
+  "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/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.71",
+  "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": [

package/vona/pnpm-lock.yaml

@@ -1517,13 +1517,13 @@ importers:
   src/suite-vendor/a-file:
     dependencies:
       vona-module-a-file:
-        specifier: ^5.0.1
+        specifier: ^5.0.3
         version: link:modules/a-file
       vona-module-file-cloudflare:
-        specifier: ^5.0.1
+        specifier: ^5.0.3
         version: link:modules/file-cloudflare
       vona-module-file-native:
-        specifier: ^5.0.1
+        specifier: ^5.0.3
         version: link:modules/file-native
 
   src/suite-vendor/a-file/modules/a-file:
@@ -1625,7 +1625,7 @@ importers:
   src/suite-vendor/a-test:
     dependencies:
       vona-module-test-file:
-        specifier: ^5.0.1
+        specifier: ^5.0.3
         version: link:modules/test-file
 
   src/suite-vendor/a-test/modules/test-auth:

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

@@ -0,0 +1,22 @@
+import { BeanBase } from 'vona';
+import { FileScene } from 'vona-module-a-file';
+
+@FileScene({
+  upload: {
+    maxSize: 20 * 1024 * 1024,
+    mimeTypes: [
+      'application/pdf',
+      'application/msword',
+      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      'application/vnd.ms-excel',
+      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      'application/zip',
+      'application/x-zip-compressed',
+      'text/plain',
+    ],
+    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/meta.version.ts

@@ -18,6 +18,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate {
         table.decimal(entityRecord.averageScore, 8, 2).comment(entityRecord.$comment.averageScore);
         table.dateTime(entityRecord.trainingTime).comment(entityRecord.$comment.trainingTime);
         table.json(entityRecord.sceneImageIds).comment(entityRecord.$comment.sceneImageIds);
+        table.json(entityRecord.dossierFileIds).comment(entityRecord.$comment.dossierFileIds);
         table.string(entityRecord.description, 255).comment(entityRecord.$comment.description);
       });
     }

package/vona/src/suite/a-training/modules/training-record/src/config/locale/en-us.ts

@@ -9,6 +9,7 @@ export default {
   TrainingRecordName: 'Training Record Name',
   TrainingTime: 'Training Time',
   ScenePhotos: 'Scene Photos',
+  DossierFiles: 'Dossier Files',
   AddTrainingRecord: 'Add Student Training Record',
   EditTrainingRecord: 'Edit Student Training Record',
   ViewTrainingRecord: 'View Student Training Record',

package/vona/src/suite/a-training/modules/training-record/src/config/locale/zh-cn.ts

@@ -9,6 +9,7 @@ export default {
   TrainingRecordName: '培训记录名称',
   TrainingTime: '培训时间',
   ScenePhotos: '现场照片',
+  DossierFiles: '培训档案附件',
   AddTrainingRecord: '添加学生培训记录',
   EditTrainingRecord: '编辑学生培训记录',
   ViewTrainingRecord: '查看学生培训记录',

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

@@ -0,0 +1,47 @@
+import type { TableIdentity } from 'table-identity';
+import type { IDecoratorDtoOptions } from 'vona-module-a-web';
+
+import { Api, v } from 'vona-module-a-openapiutils';
+import { Dto } from 'vona-module-a-web';
+import z from 'zod';
+
+export interface IDtoOptionsRecordDossierFileView extends IDecoratorDtoOptions {}
+
+@Dto<IDtoOptionsRecordDossierFileView>()
+export class DtoRecordDossierFileView {
+  @Api.field(v.tableIdentity())
+  id: TableIdentity;
+
+  @Api.field(z.string())
+  provider: string;
+
+  @Api.field(z.string())
+  clientName: string;
+
+  @Api.field(v.optional(), z.string())
+  fileScene?: string;
+
+  @Api.field(v.optional())
+  filename?: string;
+
+  @Api.field(v.optional())
+  contentType?: string;
+
+  @Api.field(v.optional())
+  size?: number;
+
+  @Api.field(v.optional())
+  public?: boolean;
+
+  @Api.field(v.optional())
+  uploadedAt?: Date;
+
+  @Api.field(v.optional(), z.record(z.string(), z.unknown()))
+  meta?: Record<string, unknown>;
+
+  @Api.field(z.string())
+  downloadUrl: string;
+
+  @Api.field(v.default(true))
+  signed: boolean;
+}

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

@@ -7,7 +7,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 { DtoRecordDossierFileView } from './recordDossierFileView.ts';
 
 export interface IDtoOptionsRecordSelectResItem extends IDecoratorDtoOptions {}
 
@@ -37,6 +39,17 @@ export class DtoRecordSelectResItem extends $Dto.get(() => ModelRecord) {
   )
   sceneImages?: DtoImageView[];
 
+  @Api.field(
+    v.title($locale('DossierFiles')),
+    ZovaRender.visible(false),
+    v.optional(),
+    v.serializerTransform('a-serialization:custom', {
+      custom: resolveDossierFiles,
+    }),
+    v.array(DtoRecordDossierFileView),
+  )
+  dossierFiles?: DtoRecordDossierFileView[];
+
   @Api.field(
     v.title($locale('Operations')),
     ZovaRender.order(1, 'max'),

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

@@ -7,9 +7,11 @@ 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 {}
 
@@ -49,6 +51,17 @@ export class DtoRecordView extends $Dto.get(() => ModelRecord, {
   )
   sceneImages?: DtoImageView[];
 
+  @Api.field(
+    v.title($locale('DossierFiles')),
+    ZovaRender.visible(false),
+    v.optional(),
+    v.serializerTransform('a-serialization:custom', {
+      custom: resolveDossierFiles,
+    }),
+    v.array(DtoRecordDossierFileView),
+  )
+  dossierFiles?: DtoRecordDossierFileView[];
+
   @Api.field(ZovaRender.visible(false), v.optional(), v.array(DtoDetailRecordSubjectResItem))
   _trainingRecordSubjects?: DtoDetailRecordSubjectResItem[];
 }