cabloy 5.1.59 → 5.1.61

package/cabloy-docs/frontend/model-resource-owner-pattern.md

@@ -0,0 +1,382 @@
+# Model Resource Owner Pattern
+
+This guide explains the resource-owner pattern built on top of Zova Model.
+
+It uses the current `rest-resource` model as the main source specimen:
+
+- `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts`
+
+Read [Model Architecture](/frontend/model-architecture) and [Model State Guide](/frontend/model-state-guide) first if you want the broader Model runtime and helper surface.
+
+If your next question is how to apply this pattern in your own module, continue with [Using `ModelResource` in Your Module](/frontend/model-resource-usage-guide).
+
+If your next question is how to review or constrain that pattern in a larger codebase, continue with [Resource Model Best Practices and Anti-Patterns](/frontend/model-resource-best-practices).
+
+If your next question is which common extension shapes to implement first, continue with [Resource Model Cookbook](/frontend/model-resource-cookbook).
+
+## Why this page exists
+
+Many examples of Zova Model start from a small feature model:
+
+- one list query
+- one item query
+- one or two mutations
+
+Those examples are useful, but they can accidentally make Model look smaller than it really is.
+
+The `rest-resource` specimen shows a larger pattern:
+
+> a model can become the stable owner of one whole resource domain boundary.
+
+That means the model is no longer only a query wrapper.
+
+It becomes the place that owns:
+
+- resource bootstrap
+- schema access
+- permissions access
+- form integration
+- query state
+- mutation state
+- cache invalidation policy
+
+This page explains that pattern explicitly.
+
+## What “resource owner” means in Zova
+
+In this context, a resource-owner model is a model bean that becomes the reusable frontend boundary for one backend resource.
+
+It is responsible for presenting one coherent surface to the rest of the UI.
+
+Instead of asking every page, table, form, and action to individually know:
+
+- how to resolve the resource API path
+- how to fetch list data
+- how to fetch row data
+- how to submit create/update/delete requests
+- how to obtain schema metadata
+- how to choose invalidation rules
+
+those decisions are centralized inside the model.
+
+A practical reading takeaway is:
+
+> the resource-owner model is the frontend resource facade.
+
+## The source specimen
+
+The main example is:
+
+- `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts`
+
+This class is generic:
+
+```typescript
+export class ModelResource<
+  Entity = any,
+  EntityCreate = Partial<Entity>,
+  EntityUpdate = Partial<Entity>,
+> extends BeanModelBase {}
+```
+
+That already tells you something important.
+
+This model is designed to be reused across many resource types rather than tied to one page.
+
+## Why `enableSelector` is essential
+
+The class is decorated like this:
+
+```typescript
+@Model<IModelOptionsResource>({
+  enableSelector: true,
+})
+```
+
+This matters because one generic `ModelResource` class needs to serve many different resources.
+
+The resource name is passed into initialization:
+
+```typescript
+protected async __init__(resource: string) {
+  await super.__init__(resource);
+  this.resource = resource;
+  ...
+}
+```
+
+That means the selector becomes the runtime identity for the concrete resource instance.
+
+So even when many consumers reuse the same generic class, each resource instance stays isolated.
+
+This is not only conceptual isolation.
+
+It also affects cache identity.
+
+Because Zova Model prefixes query keys by bean identity and selector, the effective cache keys are separated by resource.
+
+So logical keys such as:
+
+```typescript
+['select', '', hashkey(query)]
+['item', id, 'view']
+```
+
+can safely exist for many resources without colliding.
+
+## Bootstrap before normal state usage
+
+A small feature model often starts using queries immediately.
+
+`ModelResource` adds a bootstrap step first:
+
+```typescript
+protected async __init__(resource: string) {
+  ...
+  await this._bootstrap();
+}
+```
+
+And `_bootstrap()` uses:
+
+```typescript
+const queryBootstrap = await $QueryAutoLoad(() => this.$sdk.getBootstrap(this.resource));
+```
+
+Then it resolves:
+
+```typescript
+this.resourceApi = this.sys.util.parseResourceApi(this.resource, queryBootstrap.data.apiPath);
+```
+
+This is an important pattern.
+
+The model does not assume that the final operational API path is already known as a hardcoded constant.
+
+Instead, it loads resource metadata first, then turns that metadata into the stable runtime resource API boundary.
+
+That is one reason this model is better understood as infrastructure rather than only CRUD sugar.
+
+## The model owns resource metadata surfaces
+
+Inside `__init__`, the model exposes several computed resource-level surfaces:
+
+- `permissions`
+- `formProvider`
+- `schemaView`
+- `schemaCreate`
+- `schemaUpdate`
+- `schemaFilter`
+- `schemaRow`
+- `schemaPages`
+
+These are not random conveniences.
+
+They show that the model owns not only request state, but also the metadata that resource UIs need in order to render and behave correctly.
+
+For example:
+
+- permissions affect whether UI actions are available
+- schemas affect view/create/edit/filter rendering
+- form provider affects how forms are assembled
+
+This is exactly the kind of cross-cutting ownership that fits a resource-owner model.
+
+## Query ownership pattern
+
+The query side is organized around a reusable internal structure.
+
+### List/query state
+
+The model exposes list-style querying through:
+
+- `selectGeneral(actionPath?, query?)`
+- `select(query?)`
+
+These methods use `$useStateData(...)` and place query ownership inside the model.
+
+That means the page does not own the fetch details or cache-key policy.
+
+### Row-specific query state
+
+The model exposes item-style querying through:
+
+- `queryItem(...)`
+- `view(id)`
+
+Again, the page consumes a stable model API rather than building row fetch rules ad hoc.
+
+A practical reading takeaway is:
+
+> pages consume resource semantics; the model owns query semantics.
+
+## Mutation ownership pattern
+
+The mutation side follows the same idea.
+
+The model does not expose only one-off raw mutation calls.
+
+Instead, it builds a reusable mutation layer:
+
+- `create()`
+- `update(id)`
+- `delete(id)`
+- `mutationItem(...)`
+
+This gives the model one place to enforce mutation-key conventions and invalidation rules.
+
+That is an important architectural advantage.
+
+Without this model boundary, every page or dialog could invent slightly different invalidation behavior.
+
+## Cache-key design
+
+One of the best design lessons in this specimen is the cache-key structure.
+
+The class defines three related key helpers:
+
+```typescript
+protected keySelect(actionPath?: string, query?: ITableQuery) {
+  return ['select', actionPath ?? '', hashkey(query)] as const;
+}
+
+protected keyItemRoot(id: TableIdentity) {
+  return ['item', id] as const;
+}
+
+protected keyItem(id: TableIdentity, action: string) {
+  return ['item', id, action] as const;
+}
+```
+
+This separates resource state into three layers:
+
+- list/query scope
+- row root scope
+- row action scope
+
+That structure gives the model precise invalidation control.
+
+## Invalidation policy as model-owned policy
+
+The model also centralizes invalidation behavior.
+
+### Create
+
+`create()` invalidates:
+
+- `['select']`
+
+That makes sense because a new row affects list-level state first.
+
+### Update/Delete
+
+`mutationItem(...)` invalidates:
+
+- `['select']`
+- `keyItemRoot(id)`
+
+That means:
+
+- list views refresh when row mutations change aggregate list state
+- row-specific state refreshes when one row changes
+
+This is a very important design point.
+
+The model itself defines consistency rules for resource state.
+
+That keeps cache policy close to resource semantics rather than scattering it across UI code.
+
+## Form integration pattern
+
+`ModelResource` also owns form-facing behavior.
+
+Representative methods:
+
+- `getFormSchema(formMeta)`
+- `getFormApiSchemas(formMeta)`
+- `getFormMutationSubmit(formMeta, id?)`
+- `getFormData(formMeta, id?)`
+- `getQueryDataDefaultValue(schemaName?)`
+
+This is what makes the model a real resource facade instead of only a transport helper.
+
+The model translates resource semantics into form semantics.
+
+For example:
+
+- create form → use create schema and create mutation
+- update form → use update schema and update mutation
+- view form → use view schema and row data query
+
+This keeps form orchestration aligned with the same resource owner that already owns queries and mutations.
+
+## Relationship to `$fetch`, `$sdk`, and OpenAPI
+
+`ModelResource` also shows how multiple frontend data layers can be composed cleanly.
+
+Inside one model boundary it uses:
+
+- `$fetch` for direct REST request execution
+- `$sdk` for bootstrap, schema, permissions, and default-value helpers
+- model helpers for cached query/mutation state
+
+That composition matters.
+
+It shows that the server-data ladder is not a set of isolated choices.
+
+A higher-level model can combine those layers into one coherent business-facing API.
+
+## When to use this pattern
+
+Use a resource-owner model when:
+
+- many screens or widgets depend on the same backend resource
+- schema metadata, permissions, and CRUD behavior should stay aligned
+- form behavior should stay aligned with the same resource owner
+- cache invalidation rules should be centralized
+- you want one stable frontend boundary for resource-level business semantics
+
+This pattern is especially strong for admin-style, resource-driven UIs.
+
+## When not to use this pattern
+
+Do not reach for this pattern by default when:
+
+- the state is truly page-local and disposable
+- the feature only needs one tiny query with no reusable semantics
+- there is no meaningful resource-level schema/permission/form ownership
+- adding a generic resource facade would be heavier than the real business problem
+
+In those cases, a smaller feature model may be the better fit.
+
+## A useful comparison
+
+A compact comparison is:
+
+- `demo-todo` → minimal feature model pattern
+- `home-passport` → SSR-sensitive state ownership pattern
+- `rest-resource` → generic reusable resource-owner pattern
+
+Use these three together when reading how far Zova Model can scale.
+
+## Source-reading checklist
+
+When you read `ModelResource`, focus on these questions:
+
+1. where does the selector identity come from?
+2. where does `resourceApi` become available?
+3. which state belongs to list scope vs row scope?
+4. which invalidation rules belong to each mutation?
+5. which responsibilities are query-related and which are schema/form-related?
+6. what would become duplicated across pages if this model did not exist?
+
+Those questions will help you see the architectural pattern, not only the method list.
+
+## Final takeaway
+
+The most important insight is simple:
+
+> a Zova model can be more than a data hook wrapper. `ModelResource` can become the stable owner of one whole frontend resource boundary.
+
+In application code, prefer using that owner directly or adding a thin facade over it, rather than creating a competing second owner for the same resource.

package/cabloy-docs/frontend/model-resource-usage-guide.md

@@ -0,0 +1,318 @@
+# Using `ModelResource` in Your Module
+
+This guide explains the two recommended ways to use `ModelResource` in application code.
+
+It is the practical follow-up to [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern).
+
+For review guardrails and design checks after applying the pattern, continue with [Resource Model Best Practices and Anti-Patterns](/frontend/model-resource-best-practices).
+
+For implementation templates covering common extension scenarios, continue with [Resource Model Cookbook](/frontend/model-resource-cookbook).
+
+Use this page when the main question is not only “what does `ModelResource` do?”, but also:
+
+- when should I use it directly?
+- when should I add a thin business facade?
+- which responsibilities should remain in the existing resource-owner?
+- where should custom business logic live?
+
+## Why this page exists
+
+After reading the `rest-resource` source, the next practical step is usually application.
+
+A frontend developer often needs one of these outcomes:
+
+1. use `ModelResource` directly
+2. add a thin business facade over the existing resource-owner
+
+This page explains those two choices.
+
+## The base specimen
+
+The base resource-owner model is:
+
+- `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts`
+
+Representative consumers that use it through selector-based lookup include:
+
+- `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx`
+
+Those consumers are important because they show that UI blocks can depend on the resource-owner contract without needing to know the low-level resource logic.
+
+## The first decision: use directly or add a thin facade?
+
+A practical decision rule is:
+
+### Use `ModelResource` directly when
+
+- the resource is close to standard CRUD
+- default `select` / `view` / `create` / `update` / `delete` behavior is already enough
+- form schema and permission ownership can follow the generic resource path
+- generic blocks can consume the resource-owner surface as-is
+- you mainly want the existing resource-owner facade without extra business semantics
+
+### Add a thin facade over the existing resource-owner when
+
+- the resource cache owner already exists through `rest-resource`
+- the business module needs a semantic frontend surface such as `summary(...)`, `selectArchived(...)`, or `deleteForce(...)`
+- you want to follow Cabloy’s bidirectional contract loop **forward chain**
+- the right frontend move is to reuse the existing resource-owner instead of creating a competing cache owner
+
+In that case, a thin business model facade is often better than creating a second resource-level state owner.
+
+The key point is that the business model does **not** become the cache owner itself.
+
+Instead, it delegates row/list/mutation ownership to the existing `ModelResource` instance.
+
+## The key architectural rule
+
+The goal is usually **not** to create another resource-owner surface for the same resource.
+
+The goal is to keep one stable owner boundary and add business-specific semantics on top of it only when needed.
+
+A good mental model is:
+
+- `ModelResource` owns the generic resource contract
+- your business-facing model owns semantic convenience methods only when the UI needs them
+
+## Pattern 1: use `ModelResource` directly
+
+This is the cleanest option when the generic resource owner already matches the real business shape.
+
+Typical signs:
+
+- the resource mostly needs standard CRUD
+- generic pages or forms already work well
+- no extra semantic query or mutation surface is needed yet
+- the team benefits more from uniformity than from additional business naming
+
+In this mode, the best abstraction is often no extra abstraction.
+
+## Pattern 2: add a thin business facade over the existing resource-owner
+
+This is the right option when business semantics appear, but ownership should stay centralized in the existing resource-owner.
+
+A representative shape is:
+
+```typescript
+const StudentResource = 'demo-student:student';
+
+@Model()
+export class ModelStudent extends BeanModelBase {
+  @Use({ beanFullName: 'rest-resource.model.resource' })
+  protected get $$modelResource(): ModelResource {
+    return usePrepareArg(StudentResource, true);
+  }
+
+  summary(id: TableIdentity) {
+    return this.$$modelResource.queryItem({
+      id,
+      action: 'summary',
+      queryFn: async () => {
+        const res = await this.scope.api.demoStudent.summary({ params: { id } });
+        return res ?? null;
+      },
+      meta: {
+        disableSuspenseOnInit: true,
+      },
+    });
+  }
+
+  deleteForce(id: TableIdentity) {
+    return this.$$modelResource.mutationItem<void, void>({
+      id,
+      action: 'deleteForce',
+      mutationFn: async () => {
+        await this.scope.api.demoStudent.deleteForce({ params: { id } });
+      },
+    });
+  }
+}
+```
+
+What this pattern preserves:
+
+- one cache owner
+- one selector-based resource identity model
+- one list/item invalidation policy
+- one resource-level state boundary
+
+What this pattern adds:
+
+- semantic business-facing methods
+- better UI readability
+- a cleaner place for forward-chain frontend follow-up
+
+## What should remain owned by `ModelResource`
+
+In both usage modes, these parts should remain conceptually owned by the existing resource-owner pattern:
+
+- resource bootstrap
+- `resourceApi` resolution
+- select/view/create/update/delete conventions
+- form schema resolution
+- permission/schema/form-provider surfaces
+- generic list/item invalidation structure
+
+That does not mean you can never customize behavior.
+
+It means the customization should still reuse the same owner boundary instead of competing with it.
+
+## The safest extension points
+
+The safest extension points are usually **new business-facing methods** that delegate to the existing resource-owner helper surfaces.
+
+Typical examples:
+
+- additional item queries through `queryItem(...)`
+- additional list queries through `selectGeneral(...)`
+- business actions through `mutationItem(...)`
+- resource-specific computed helpers
+- schema or permission convenience helpers
+
+This keeps the generic resource contract intact while adding local business semantics.
+
+## Pattern 3: add a row-level custom query through the facade
+
+Use this when the resource has a domain-specific query that is not just `select` or `view`.
+
+Representative shape:
+
+```typescript
+summary(id: TableIdentity) {
+  return this.$$modelResource.queryItem({
+    id,
+    action: 'summary',
+    queryFn: async () => {
+      const res = await this.scope.api.demoStudent.summary({ params: { id } });
+      return res ?? null;
+    },
+  });
+}
+```
+
+Why this is a good pattern:
+
+- it reuses `queryItem(...)`
+- it stays under the existing resource-owner cache-key structure
+- it keeps row-level query ownership centralized
+
+## Pattern 4: add a list-level query variant through the facade
+
+Use this when the resource needs a second list-style endpoint beyond the default `select(query)`.
+
+Representative shape:
+
+```typescript
+selectArchived(query?: ITableQuery) {
+  return this.$$modelResource.selectGeneral('archived', query);
+}
+```
+
+Why this is a good pattern:
+
+- it reuses `selectGeneral(...)`
+- it stays under the existing resource-owner list-key structure
+- it keeps list-level semantics inside the same resource boundary
+
+## Pattern 5: add a custom mutation through the facade
+
+Use this when the resource needs business actions beyond create/update/delete.
+
+Representative shape:
+
+```typescript
+deleteForce(id: TableIdentity) {
+  return this.$$modelResource.mutationItem<void, void>({
+    id,
+    action: 'deleteForce',
+    mutationFn: async () => {
+      await this.scope.api.demoStudent.deleteForce({ params: { id } });
+    },
+  });
+}
+```
+
+Why this is a good pattern:
+
+- it reuses `mutationItem(...)`
+- it inherits centralized invalidation behavior
+- it keeps mutation ownership under the same resource owner
+
+## Where custom business logic should live
+
+A practical placement rule is:
+
+### Put it in the thin business facade when
+
+- it is resource semantics
+- it affects query or mutation ownership through the existing resource-owner
+- it affects resource-level invalidation expectations
+- multiple pages or blocks should reuse it
+- it gives the UI a clearer business-facing surface
+
+### Keep it out of the business facade when
+
+- it is only local page presentation logic
+- it is one-off UI formatting with no resource ownership meaning
+- it is unrelated to the resource boundary
+
+## A good layering pattern
+
+A clean layering often looks like this:
+
+- `ModelResource` → generic resource-owner runtime
+- `ModelStudent` / `ModelArticle` / `ModelOrder` → thin business facade over the existing owner
+- page/component controllers → consume the model and focus on page flow
+
+That layering keeps the model architecture expressive without turning every page into a mini resource framework.
+
+## Common mistakes to avoid
+
+For the broader review-oriented version of these mistakes, see [Resource Model Best Practices and Anti-Patterns](/frontend/model-resource-best-practices).
+
+The usage mistakes to remember here are:
+
+### Mistake 1: creating a competing cache owner
+
+If the business model starts owning the same list/item resource state independently, the architecture loses its single resource-owner boundary.
+
+### Mistake 2: bypassing the model with ad hoc `$fetch` in pages
+
+If a page keeps calling the same resource endpoints directly while a resource-owner model already exists, the ownership boundary becomes inconsistent.
+
+### Mistake 3: adding wrapper classes with no semantic value
+
+If a business model does not add real business-facing semantics, the wrapper may create extra maintenance without improving clarity.
+
+## A practical evolution path
+
+A healthy evolution path often looks like this:
+
+1. start with direct `ModelResource` usage
+2. let generic pages/forms consume it directly
+3. add a thin business facade only when real business semantics appear
+4. keep generic page and form blocks consuming the stable resource-owner surface
+5. keep frontend follow-up thin during forward-chain contract evolution
+
+This path keeps the abstraction proportional to the real problem and reduces mental overhead.
+
+## Source-reading checklist for application
+
+When deciding how to apply `ModelResource`, ask:
+
+1. is the generic resource-owner already enough?
+2. does the UI need semantic business-facing methods?
+3. can the new behavior delegate to `queryItem`, `selectGeneral`, or `mutationItem`?
+4. which invalidation rules should remain centralized?
+5. which generic consumers should continue to work unchanged?
+
+If you can answer those clearly, your application of the pattern is usually on the right track.
+
+## Final takeaway
+
+The most important practical insight is simple:
+
+> use `ModelResource` directly when the generic owner already fits; add a thin facade only when the UI needs clearer business semantics.
+
+That approach keeps the programming model more uniform and reduces mental burden.