cabloy 5.1.50 → 5.1.52

package/cabloy-docs/frontend/mock-guide.md

@@ -0,0 +1,109 @@
+# Mock Guide
+
+## Why mock matters in Zova
+
+Zova provides an out-of-the-box mock mechanism so frontend development can continue even when a real backend integration path is incomplete or intentionally decoupled.
+
+That matters because page, API, and server-data workflows often need stable response shapes before the final backend contract is available.
+
+## Core mock model
+
+The Zova mock mechanism is based on `vite-plugin-fake-server` and is integrated into the frontend development workflow.
+
+A mock route is typically defined in a `.fake.ts` file inside the relevant module.
+
+## Mock file structure
+
+Representative example:
+
+```typescript
+import { defineFakeRoute } from 'vite-plugin-fake-server-turbo/client';
+
+export default defineFakeRoute([
+  {
+    url: '/home/layout/menu/select',
+    method: 'get',
+    response: () => {
+      return {
+        code: 0,
+        message: 'Success',
+        data: [],
+      };
+    },
+  },
+]);
+```
+
+Key points:
+
+- mock files use the `.fake.ts` extension
+- `defineFakeRoute(...)` provides the route definition shape
+- each mock route describes the request path, method, and response
+
+## Where mock files belong
+
+Mocks belong near the frontend module that consumes or defines the route shape.
+
+Representative example:
+
+- `src/suite/a-home/modules/home-layout/mock/menu.fake.ts`
+
+This keeps mock behavior close to the page, API, or business module that depends on it.
+
+## Relationship to frontend APIs and server data
+
+Mocking fits naturally with:
+
+- [API Guide](/frontend/api-guide)
+- [Server Data](/frontend/server-data)
+- [Page Guide](/frontend/page-guide)
+
+A common workflow is:
+
+1. define or update the frontend page or API contract
+2. provide a mock route with the expected response shape
+3. build page, component, or model behavior against that mock response
+4. later replace the mock-backed path with the real backend contract when ready
+
+## Configuration
+
+Mock behavior is configured through environment variables such as:
+
+- `MOCK_ENABLED`
+- `MOCK_LOGGER`
+- `MOCK_BASE_NAME`
+- `MOCK_BUILD`
+- `MOCK_BUILD_PORT`
+- `MOCK_BUILD_OUTPUT`
+- `MOCK_BUILD_CORS`
+
+These settings control whether mocks are enabled, whether a standalone fake server should be built, and how the mock server behaves.
+
+## Development and production behavior
+
+By default, production builds do not generate the fake server.
+
+If a standalone fake server should be generated during build, `MOCK_BUILD` must be enabled.
+
+That means mock support can be used in development only, or intentionally packaged for separate deployment when needed.
+
+## When to use mock
+
+Use mock when:
+
+- frontend page or API work needs stable response data before the backend is ready
+- you want to prototype UI behavior against an expected contract
+- you want repeatable local demo or development behavior without a live backend dependency
+
+Do not treat mock as the final source of truth for the contract when a real backend/OpenAPI path already exists.
+
+## Implementation checks for mock-versus-contract decisions
+
+When editing frontend integration paths, ask:
+
+1. is the real backend contract available yet?
+2. should this flow use a temporary mock route or a real `$api`/OpenAPI path?
+3. does the mock response shape match the intended page, API, or model contract?
+4. should mock be enabled only for development, or is a standalone fake server also needed?
+
+That helps AI keep frontend development moving without confusing temporary mock behavior with final backend truth.

package/cabloy-docs/frontend/model-architecture.md

@@ -0,0 +1,87 @@
+# Model Architecture
+
+This guide explains the overall model architecture in Zova within the Cabloy monorepo.
+
+## Why Zova models matter
+
+Zova uses a unified `Model` mechanism to manage several kinds of data that other frontend stacks often split across unrelated tools.
+
+This is one of the most important architectural ideas in Zova.
+
+## Four kinds of global state
+
+The model architecture can be understood through four common data categories:
+
+- asynchronous data, usually from the server
+- local storage data
+- cookie data
+- in-memory data
+
+In Zova, these can all participate in one broader model-centered system instead of forcing developers to switch between unrelated mental models.
+
+## Relationship to TanStack Query
+
+One key point is explicit: the base of Zova Model is TanStack Query.
+
+That matters because Zova is not discarding the strengths of TanStack Query. It is building a more unified and framework-friendly usage model on top of it.
+
+## Key model capabilities
+
+Several important capabilities remain central in the unified docs:
+
+### 1. Support for async and sync data
+
+The model system is not limited to server data. It also extends the same broader mechanism to synchronous data categories.
+
+### 2. Automatic caching
+
+Remote data can be cached locally, while local-storage or cookie-backed data can be accessed through unified model patterns.
+
+### 3. Automatic update behavior
+
+The model system supports data freshness and update behavior instead of treating state as static snapshots.
+
+### 4. Reduced duplicate requests
+
+When multiple parts of the app need the same data, the framework avoids unnecessary repeated requests.
+
+### 5. Memory optimization
+
+Model-managed data does not need to occupy memory forever. Cache lifecycle and release behavior matter, especially for large long-running applications.
+
+### 6. Persistence
+
+Model-managed data can participate in persistence strategies so refreshes do not always mean starting from nothing.
+
+### 7. SSR support
+
+The model system helps smooth out SSR differences across data categories and makes hydration more natural.
+
+### 8. Namespace isolation
+
+Because data is managed through model beans, the bean identity itself helps provide namespace isolation and reduces collision risk.
+
+## Create a model bean
+
+Representative pattern:
+
+```typescript
+import { Model } from 'zova';
+import { BeanModelBase } from 'zova-module-a-model';
+
+@Model()
+export class ModelTodo extends BeanModelBase {}
+```
+
+## Practical implications for frontend state design
+
+When asked to add frontend state, do not immediately assume a generic Vue/Pinia-style answer.
+
+A better default is to ask:
+
+1. is this state already a good fit for a Zova model?
+2. is the data async or sync, and does that distinction matter to the model choice?
+3. does SSR or persistence make the model layer especially valuable here?
+4. is there already a model bean that should own this state instead of adding a new ad hoc state container?
+
+That keeps the code aligned with Zova’s actual architecture.

package/cabloy-docs/frontend/model-state-guide.md

@@ -0,0 +1,70 @@
+# Model State Guide
+
+This guide explains how model-based server-data state works in Zova within the Cabloy monorepo.
+
+## Why the model layer exists
+
+Zova uses model-based state management on top of API access so remote data can participate in a more unified caching and usage model.
+
+This improves runtime performance and developer experience by building on top of TanStack Query rather than exposing only raw request flows.
+
+## Create a model
+
+Example: create a model named `menu` in module `demo-student`.
+
+```bash
+npm run zova :create:bean model menu -- --module=demo-student
+```
+
+## Model definition
+
+Representative pattern:
+
+```typescript
+@Model()
+export class ModelMenu {
+  retrieveMenus() {
+    return this.$useStateData({
+      queryKey: ['retrieveMenus'],
+      queryFn: async () => {
+        return await this.$api.homeBaseMenu.retrieveMenus({
+          params: { publicPath: '' },
+        });
+      },
+    });
+  }
+}
+```
+
+This pattern is important because it shows that model logic is not just local state. It is also the place where cached remote data becomes a reusable abstraction.
+
+## Using a model
+
+Representative pattern:
+
+```typescript
+@Use()
+$$modelMenu: ModelMenu;
+
+protected render() {
+  const { data, error } = this.$$modelMenu.retrieveMenus();
+  if (error) return <div>{error.message}</div>;
+  return <div>{data}</div>;
+}
+```
+
+## Relationship to the server-data ladder
+
+In the new docs, think about the layers like this:
+
+- `$fetch` → direct request access
+- `$api` → business-oriented service methods
+- `Model` → cached, reusable, UI-friendly remote state
+
+That makes the model layer one of the most important bridges between backend contracts and frontend rendering.
+
+## Implementation checks for model-based state changes
+
+When you see repeated frontend data usage, caching concerns, or UI state that depends on remote data, ask whether the right abstraction is a model instead of a direct API call in the page.
+
+That usually leads to cleaner SSR behavior, cleaner reuse, and a more Cabloy-native structure.

package/cabloy-docs/frontend/module-scope.md

@@ -0,0 +1,168 @@
+# Module Scope
+
+## Why module scope matters in Zova
+
+Zova uses module scope as the unified resource facade for frontend modules.
+
+That matters because business code needs a consistent way to access module resources such as config, locale, errors, APIs, and related metadata without scattering unrelated access patterns through every page or component.
+
+## What scope is
+
+A `Scope` instance is the module-facing object that exposes the resources of a module in one place.
+
+This is one of the main reasons Zova can keep dependency lookup concise while still preserving strong structure.
+
+## `this.scope`
+
+All beans inherit from `BeanBase`, so the current module scope is directly available through:
+
+```typescript
+this.scope;
+```
+
+This gives the current bean a natural way to access the resources of its own module.
+
+## Main scope resource categories
+
+Representative scope members include:
+
+- `config`
+- `constant`
+- `locale`
+- `error`
+- `api`
+- `apiSchema`
+
+These categories make module resources discoverable and consistently organized.
+
+## Initialize scope-backed resources
+
+Representative CLI entrypoints include:
+
+```bash
+npm run zova :init:config demo-student
+npm run zova :init:constant demo-student
+npm run zova :init:locale demo-student
+npm run zova :init:error demo-student
+npm run zova :create:bean api test -- --module=demo-student
+```
+
+This matters because scope is not just a read surface. It is the organized destination for resources generated or initialized through the standard Zova workflow.
+
+## `config`
+
+Module config belongs in the scope model so business logic can read feature-specific configuration in a structured way.
+
+Representative access pattern:
+
+```typescript
+console.log(this.scope.config.title);
+```
+
+Projects can also override module-level config through project-level frontend config, which makes scope a bridge between reusable module defaults and app-specific customization.
+
+## `constant`
+
+Module constants can live in scope so feature-level constant values remain namespaced and easy to access.
+
+Representative access pattern:
+
+```typescript
+console.log(this.scope.constant.gender.male);
+console.log(this.scope.constant.gender.female);
+```
+
+## `locale`
+
+Module locale resources are exposed through scope so frontend code can retrieve localized text in a module-aware way.
+
+Representative access patterns:
+
+```typescript
+const message1 = this.scope.locale.HelloWorld();
+const message2 = this.scope.locale.HelloWorld.locale('en-us');
+```
+
+Project-level locale resources can override module-level locale values, which is one of the key reasons scope stays useful even when the final app wants customized wording.
+
+## `error`
+
+Module-specific errors are exposed through scope so business code can throw namespaced error definitions without inventing ad hoc exception patterns.
+
+Representative access pattern:
+
+```typescript
+this.scope.error.ErrorTest.throw();
+```
+
+## `api`
+
+Backend API calls can be wrapped as module `api` resources and accessed through scope.
+
+This is one of the most practical scope categories because it keeps request logic close to the module boundary instead of scattering raw request paths through page code.
+
+Representative access pattern:
+
+```typescript
+const res = await this.scope.api.test.echo();
+```
+
+## `apiSchema`
+
+Schema-oriented API metadata can also be exposed through scope when higher-level frontend behavior depends on API metadata directly.
+
+## Cross-module scope access
+
+Zova also supports cross-module scope access through `@UseScope()`.
+
+Representative pattern:
+
+```typescript
+@UseScope()
+$$scopeDemoStudent: ScopeModuleDemoStudent;
+```
+
+A common follow-up access pattern is:
+
+```typescript
+const res = await this.$$scopeDemoStudent.api.test.echo();
+console.log(this.$$scopeDemoStudent.locale.HelloWorld());
+```
+
+This allows one module to consume another module’s scoped resources explicitly without flattening everything into one shared global namespace.
+
+Compiler support also lets `@UseScope()` participate in async module loading behavior, which fits naturally with Zova’s module-level bundle boundaries.
+
+## Why this matters for architecture
+
+Module scope is a key bridge between:
+
+- modularization
+- IoC and bean lookup
+- API access
+- locale and error handling
+- project-level override behavior
+
+That makes scope one of the most important frontend concepts to understand before extending a larger Zova application.
+
+## Relationship to other frontend guides
+
+Read this together with:
+
+- [IoC and Beans](/frontend/ioc-and-beans)
+- [Modules and Suites](/frontend/modules-and-suites)
+- [API Guide](/frontend/api-guide)
+- [Server Data](/frontend/server-data)
+
+These guides explain how scope fits into bean architecture, module boundaries, and data-access design.
+
+## Implementation checks for module-scope changes
+
+When editing Zova frontend code, ask:
+
+1. should this resource be accessed through `this.scope` instead of a direct ad hoc import?
+2. does the logic belong to the current module or another module’s scope?
+3. should cross-module access use `@UseScope()`?
+4. is this concern best modeled as config, constant, locale, error, api, or apiSchema?
+
+That helps AI keep frontend resource access aligned with Zova’s intended module architecture.

package/cabloy-docs/frontend/modules-and-suites.md

@@ -0,0 +1,179 @@
+# Modules and Suites
+
+## Why modularization matters in Zova
+
+Zova organizes frontend code into modules and suites so business code can scale without collapsing into one large undifferentiated app surface.
+
+That matters for:
+
+- business decoupling
+- reuse of feature units
+- clear bundle boundaries
+- team-level work decomposition
+- namespace isolation
+
+## Module as the core business unit
+
+In Zova, a module groups related pages, components, config, locale, API resources, and other frontend assets into one coherent feature boundary.
+
+A module is not just a folder. It is a unit of architecture, naming, and bundling.
+
+## Why modules help
+
+Representative benefits include:
+
+- clearer business boundaries
+- easier reuse across systems
+- reduced naming conflicts through namespace isolation
+- more natural async bundle boundaries during build
+
+## Module naming convention
+
+Zova modules follow a naming model such as:
+
+```text
+FullName: zova-module-{providerId}-{moduleName}
+ShortName: {providerId}-{moduleName}
+```
+
+This naming system is important because it supports both architectural clarity and bean/scope identity across module boundaries.
+
+## Suite as a multi-module boundary
+
+A suite groups several related modules into a larger business scenario.
+
+Representative examples might correspond to areas such as:
+
+- e-commerce
+- CRM
+- supply chain
+- shared application foundations
+
+A suite is therefore not merely a package wrapper. It is a business-level composition boundary.
+
+## Suite naming convention
+
+Suites follow a similar naming model:
+
+```text
+FullName: zova-suite-{providerId}-{suiteName}
+ShortName: {providerId}-{suiteName}
+```
+
+## Create modules and suites
+
+Representative CLI entrypoints are:
+
+```bash
+npm run zova :create:module moduleName -- [--suite=]
+npm run zova :create:suite suiteName
+```
+
+That matters because the CLI already knows the intended source-tree conventions and should be preferred over ad hoc manual scaffolding.
+
+## Directory structure
+
+The project directory structure expresses this modular architecture directly.
+
+Representative areas include:
+
+- `src/module`
+- `src/module-vendor`
+- `src/suite`
+- `src/suite-vendor`
+
+This makes frontend architecture visible in the source tree rather than hiding it behind build-only conventions.
+
+### Representative source tree
+
+```text
+project
+├── env
+├── src
+│  ├── front
+│  │  └── config
+│  ├── module
+│  ├── module-vendor
+│  ├── suite
+│  │  ├── a-demo
+│  │  └── a-home
+│  │     └── modules
+│  │        ├── home-base
+│  │        ├── home-icon
+│  │        ├── home-indexadmin
+│  │        └── home-layoutadmin
+│  └── suite-vendor
+```
+
+A practical convention from the legacy guidance is that `a-demo` can host demo or disposable exploratory code, while suites such as `a-home` act as the normal starting point for real application growth.
+
+## Module and suite boundaries in practice
+
+A practical mental model is:
+
+- use a **module** for a coherent feature unit
+- use a **suite** when several modules belong to one larger business scenario
+- use the source tree as a reflection of real architecture, not only file storage
+
+## Relationship to frontend build behavior
+
+A module is also a natural async bundle boundary.
+
+That means modularization is not only about code organization. It also affects how frontend output is built, loaded, and maintained.
+
+### Package-level module metadata
+
+A module package can also declare metadata in `package.json` through `zovaModule`, for example to describe inter-module dependencies or bundle behavior.
+
+Representative patterns include:
+
+```json
+{
+  "name": "zova-module-demo-student",
+  "zovaModule": {
+    "dependencies": {
+      "a-zova": "5.0.0"
+    }
+  }
+}
+```
+
+```json
+{
+  "name": "zova-module-a-model",
+  "zovaModule": {
+    "bundle": {
+      "vendors": [
+        {
+          "match": ["@tanstack/query-core", "@tanstack/vue-query"],
+          "output": "tanstack-query"
+        }
+      ]
+    }
+  }
+}
+```
+
+This reinforces that modules are not merely folders. They are explicit package, dependency, and bundle boundaries.
+
+## Relationship to other frontend guides
+
+Read this together with:
+
+- [IoC and Beans](/frontend/ioc-and-beans)
+- [Module Scope](/frontend/module-scope)
+- [Frontend Scripts](/frontend/scripts)
+- [Reference Package Map](/reference/package-map)
+
+These guides explain how modules connect to bean identity, scope-based resources, and monorepo layout.
+
+## Implementation checks for module and suite changes
+
+When editing or creates frontend code, ask:
+
+1. does this belong in an existing module or a new one?
+2. is this really one feature unit, or should it become part of a suite?
+3. does the naming follow Zova’s module/suite conventions?
+4. will the chosen placement preserve the intended architectural and bundle boundaries?
+
+That helps AI keep frontend growth aligned with Zova’s modular system instead of falling back to generic folder expansion.

package/cabloy-docs/frontend/navigation-guards-guide.md

@@ -0,0 +1,68 @@
+# Navigation Guards Guide
+
+This guide explains how navigation guards work in Zova within the Cabloy monorepo.
+
+## Why navigation guards matter
+
+Navigation guards are one of the main places where routing behavior becomes application policy.
+
+Typical uses include:
+
+- checking authentication state
+- redirecting unauthenticated users to login
+- enforcing route-level behavior from route metadata
+
+## Home-base guard entrypoint
+
+The `home-base` module provides a router-guard service hook where custom logic can be added.
+
+Representative shape:
+
+```typescript
+class ServiceRouterGuards {
+  protected onRouterGuards(router: BeanRouter) {
+    router.beforeEach(async to => {
+      if (
+        !this.sys.config.ssr.ignoreCookieOnServer &&
+        to.meta.requiresAuth !== false &&
+        !this.$passport.isAuthenticated
+      ) {
+        const [_res, err] = await catchError(() => {
+          return this.$passport.ensurePassport();
+        });
+        if (err) {
+          this.$errorHandler(err, 'onRouterGuards');
+          return false;
+        }
+        if (!this.$passport.isAuthenticated) {
+          this.app.$gotoLogin(to.fullPath);
+          return false;
+        }
+      }
+    });
+  }
+}
+```
+
+## Why route meta matters here
+
+The example makes a key architectural point: navigation guards are tightly coupled to route metadata such as `requiresAuth`.
+
+That means route configuration and guard behavior should be read together, not as separate concerns.
+
+## SSR-sensitive detail
+
+The example also references SSR-related configuration such as cookie handling on the server side.
+
+So guards are not purely a client-side router concern. In Cabloy/Zova, they can also intersect with SSR behavior.
+
+## Implementation checks for navigation-guard changes
+
+When changing auth-sensitive routing behavior, ask:
+
+1. does the route meta need to change?
+2. does the guard logic need to change?
+3. does SSR cookie or server-side behavior affect the guard decision path?
+4. should redirects happen at the routing-policy layer rather than being hardcoded into page logic?
+
+That produces cleaner and more framework-native navigation behavior.