cabloy 5.1.49 → 5.1.51

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.

package/cabloy-docs/frontend/openapi-sdk-guide.md

@@ -0,0 +1,102 @@
+# OpenAPI SDK Guide
+
+This guide explains how the Zova OpenAPI SDK workflow fits into the Cabloy monorepo.
+
+## Why OpenAPI SDK matters
+
+Zova can generate frontend client SDKs from backend Swagger/OpenAPI metadata.
+
+This is one of the most important fullstack links in Cabloy, because it lets backend contracts drive frontend integration more directly and reduces redundant hand-written API code.
+
+## This page’s role in the contract loop
+
+A practical split is:
+
+- backend docs explain contract authoring and OpenAPI emission
+- the fullstack bridge doc explains how emitted OpenAPI becomes generated frontend SDKs
+- this page explains frontend configuration, generation, and usage choices after that contract reaches Zova
+
+For the bridge view, also see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
+For the broader frontend contract-consumption ladder, also see [Server Data](/frontend/server-data), [API Schema Guide](/frontend/api-schema-guide), and [SDK Guide](/frontend/sdk-guide).
+
+## Initialize OpenAPI config
+
+Example: initialize OpenAPI config for module `demo-student`.
+
+```bash
+npm run zova :openapi:config demo-student
+```
+
+## Module-level config
+
+Each module can control which backend operations belong to it.
+
+Representative idea:
+
+- configure matching rules in the module OpenAPI config
+- keep API ownership aligned with the module boundary
+
+This modular split matters because Cabloy does not treat the frontend as one flat API client surface.
+
+## Project-level config
+
+The project-level OpenAPI config defines where Swagger/OpenAPI metadata is downloaded from.
+
+Representative use case:
+
+- point the frontend project at the correct backend Swagger JSON source
+- then generate only the SDK slices needed by the current module
+
+## Generate the SDK
+
+Example: generate OpenAPI-based frontend services for module `demo-student`.
+
+```bash
+npm run zova :openapi:generate demo-student
+```
+
+## Build the rest-contract output
+
+For Cabloy Basic, representative contract-build commands include:
+
+```bash
+cd zova && npm run build:rest:cabloyBasicAdmin
+cd zova && npm run build:rest:cabloyBasicWeb
+```
+
+This matters because SDK generation and rest-contract build steps are related, but not identical.
+
+## Important convention
+
+One important rule is that a module should usually standardize on one API-service creation style.
+
+That means a module should generally choose between:
+
+- manually authored API services
+- OpenAPI-generated API services
+
+Mixing both styles carelessly inside one module makes the codebase harder to reason about.
+
+## Relationship to backend authoring
+
+This page is about frontend consumption and generation, not backend contract authoring.
+
+If the backend contract itself changes, first inspect or update the backend contract pages such as:
+
+- [Controller Guide](/backend/controller-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [DTO Guide](/backend/dto-guide)
+
+Then return to this page for the frontend regeneration step.
+
+## Implementation checks for SDK regeneration decisions
+
+When evaluating a request that depends on backend contracts, ask:
+
+1. is this module already using generated OpenAPI services?
+2. should the SDK be regenerated instead of hand-writing a new frontend service?
+3. is the real source of truth the backend OpenAPI metadata rather than the current frontend code?
+4. is the current task backend authoring, bridge regeneration, or frontend consumption?
+
+That helps keep frontend integration aligned with the backend contract.