cabloy 5.1.60 → 5.1.62

package/cabloy-docs/frontend/model-resource-internals-deep-dive.md

@@ -0,0 +1,238 @@
+# ModelResource Internals Deep Dive
+
+This guide explains the internals of `ModelResource` in Zova through the current public Cabloy Basic source.
+
+Use this page when you want to understand:
+
+- how `ModelResource` bootstraps itself
+- how `resourceApi` is resolved
+- where permissions, schemas, and form-provider surfaces come from
+- how query, mutation, and form helpers are organized
+- how query-key prefixing and invalidation work
+- why `ModelResource` is the stable resource-owner boundary under both list and entry pages
+
+## Why this page exists
+
+This page is the third layer of a small source-reading chain around same-resource model facades:
+
+1. [Model Architecture](/frontend/model-architecture) for the broader role of Zova Model
+2. [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch) for the consumer-side handoff into the owner
+3. this page for the owner internals that make that handoff work
+
+Several existing docs already explain the meaning and usage of the resource owner well:
+
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern) explains the architecture and why the owner boundary exists
+- [Using `ModelResource` in Your Module](/frontend/model-resource-usage-guide) explains application-level usage patterns
+- [Resource Model Best Practices](/frontend/model-resource-best-practices) and [Resource Model Cookbook](/frontend/model-resource-cookbook) explain review and implementation guidance
+- [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood) explains the module/runtime bridge around the owner
+
+What those pages do not isolate directly is the one source-first path through `ModelResource` itself.
+
+That is the gap this page fills.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+1. `ModelResource` is a selector-backed owner keyed by `resource`
+2. bootstrap resolves the final `resourceApi`
+3. the owner exposes computed surfaces for permissions, schema, and form provider
+4. query helpers wrap the shared model/query runtime for select/view/item-style fetches
+5. mutation helpers wrap the shared model/query runtime for create/update/delete behavior
+6. form helpers let pages choose schema/data/mutation behavior from `formMeta`
+7. query keys and invalidation are centralized as part of the owner contract
+
+That means `ModelResource` is not only a fetch helper. It is the stable resource semantics boundary for the frontend.
+
+## Source-confirmed reading path
+
+When reading this topic, use this order:
+
+1. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/model/sdk.ts`
+3. `zova/packages-zova/zova-core/src/core/sys/util.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useQuery.ts`
+5. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.query.ts`
+6. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.persister.ts`
+7. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controller.tsx`
+8. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/entry/controller.tsx`
+
+That order moves from the owner core, to the OpenAPI model it relies on, to path/config helpers, to query/persister behavior, and finally to the clearest current consumers.
+
+## Initialization and bootstrap
+
+The owner core lives in:
+
+```text
+zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts
+```
+
+The first source-confirmed facts are:
+
+- `@Model({ enableSelector: true })`
+- `__init__(resource)` requires a concrete `resource`
+- bootstrap happens before downstream consumers use the owner surfaces
+
+This matters because `ModelResource` is not one global singleton.
+
+It is a selector-backed owner whose runtime identity is the current resource name.
+
+## `resourceApi` resolution
+
+The bootstrap path uses:
+
+- `this.$sdk.getBootstrap(this.resource)`
+- `this.sys.util.parseResourceApi(resource, api)`
+
+The path/config helper lives in:
+
+```text
+zova/packages-zova/zova-core/src/core/sys/util.ts
+```
+
+This confirms the owner flow:
+
+- bootstrap data may override the final API path
+- otherwise the resource name is translated into a default controller/action API path
+
+That is why `resourceApi` should be treated as an owner-level resolved surface, not as one hard-coded string duplicated across pages.
+
+## Metadata surfaces exposed by the owner
+
+Inside `ModelResource`, the owner computes and exposes:
+
+- `permissions`
+- `formProvider`
+- `schemaView`
+- `schemaCreate`
+- `schemaUpdate`
+- `schemaFilter`
+- `schemaRow`
+- `schemaPages`
+
+These surfaces are derived from:
+
+- the bootstrap/runtime resource context
+- the OpenAPI SDK/schema helpers
+
+This is the clearest source-confirmed reason why both list pages and entry pages reuse the same owner: schema, permission, and provider surfaces belong to one resource boundary.
+
+## Query helper layer
+
+The query helpers are organized around:
+
+- `selectGeneral(actionPath?, query?)`
+- `select(query?)`
+- `queryItem(...)`
+- `view(id)`
+
+`select(query?)` is only a thin wrapper over `selectGeneral(undefined, query)`.
+
+The important source-confirmed detail is that the select key includes a hash of the query object:
+
+- `['select', actionPath ?? '', hashkey(query)]`
+
+That means query identity is deliberate and owner-controlled.
+
+This is the owner-side boundary for list/query fetches, not the page shell.
+
+## Mutation helper layer
+
+The mutation helpers are organized around:
+
+- `create()`
+- `mutationItem(...)`
+- `update(id)`
+- `delete(id)`
+
+The most important source-confirmed behavior is:
+
+- select queries are invalidated after successful mutations
+- item-root queries are invalidated for the specific row identity
+
+That means mutation helpers do not only perform network requests. They also own the default resource-level invalidation policy.
+
+## Form helper layer
+
+The form-facing helpers are:
+
+- `getFormSchema(formMeta)`
+- `getFormApiSchemas(formMeta)`
+- `getFormMutationSubmit(formMeta, id?)`
+- `getFormData(formMeta, id?)`
+- `getQueryDataDefaultValue(schemaName?)`
+
+This is the clearest source-confirmed bridge from resource owner to entry-page form runtime.
+
+A practical reading rule is:
+
+- list pages mainly consume `schemaFilter`, `schemaRow`, and `select(...)`
+- entry pages mainly consume `formMeta`-driven form helpers
+
+## Query-key prefixing and invalidation behavior
+
+The shared model/query behavior lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useQuery.ts
+zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.query.ts
+zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.persister.ts
+```
+
+The important source-confirmed behavior is:
+
+- owner query keys are prefixed with bean full name
+- selector-backed models also prefix by selector
+- persister/query behavior therefore treats one resource owner as a distinct query namespace
+
+This is why `ModelResource` query identity is stable even when multiple resources or multiple selectors exist at once.
+
+## Current consumers that prove the contract
+
+The clearest current consumers are:
+
+- `rest-resource/src/page/resource/controller.tsx`
+- `rest-resource/src/page/entry/controller.tsx`
+
+These page shells prove that:
+
+- list pages consume the owner for top-level list/schema/runtime entry
+- entry pages consume the owner for form/provider/schema/runtime entry
+
+That is enough to verify that `ModelResource` is the shared owner beneath both branches.
+
+## What this guide does not re-explain
+
+This page does **not** fully re-explain:
+
+- why the resource owner pattern exists -> see [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- application-level facade and usage guidance -> see [Using `ModelResource` in Your Module](/frontend/model-resource-usage-guide)
+- the full list-page runtime -> see [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive)
+- the full entry-page runtime -> see [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+
+Its job is only to explain the owner internals and their current consumer contract.
+
+## Where to read next
+
+Use these next steps depending on your question:
+
+- if you want to step back to the broader model role, return to [Model Architecture](/frontend/model-architecture)
+- if you want to step back to the consumer-side handoff, return to [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch)
+- if you want the list-page runtime branch, read [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive)
+- if you want the entry-page runtime branch, read [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+- if you want the owner-pattern explanation, read [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- if you want application-level usage/facade rules, read [Using `ModelResource` in Your Module](/frontend/model-resource-usage-guide)
+
+## Final takeaway
+
+The most accurate way to read `ModelResource` is not as one generic CRUD helper.
+
+Read it as the selector-backed resource owner that:
+
+- bootstraps and resolves `resourceApi`
+- exposes schema, permission, and provider surfaces
+- owns query, mutation, and form helper boundaries
+- defines query-key and invalidation behavior
+- remains the stable resource semantics layer beneath both list pages and entry pages
+
+That is the source-confirmed role of `ModelResource` in the current Cabloy Basic frontend architecture.

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

@@ -0,0 +1,402 @@
+# 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 `ModelResource` itself works internally at the source level, continue with [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive).
+
+If your next question is how the generic lower-level model runtime works beneath `ModelResource`, continue with [Model Runtime Under the Hood](/frontend/a-model-under-the-hood).
+
+If your next question is how the whole `rest-resource` module works at runtime beyond the model itself, continue with [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood).
+
+If your next question is which files to read next for that runtime, continue with [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map).
+
+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).
+
+> [!TIP]
+> **Resource docs path**
+>
+> 1. **[Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)** — learn why `ModelResource` is a resource owner
+> 2. **[Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)** — learn how the module runtime pieces cooperate
+> 3. **[Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map)** — learn which files to read next
+> 4. **[Using `ModelResource` in Your Module](/frontend/model-resource-usage-guide)** — learn how to reuse the owner in application code
+> 5. **[Resource Model Best Practices](/frontend/model-resource-best-practices)** — learn the review guardrails
+> 6. **[Resource Model Cookbook](/frontend/model-resource-cookbook)** — learn the common implementation shapes
+>
+> **You are here:** step 1.
+> **Next recommended page:** [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood).
+
+## 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.