cabloy 5.1.49 → 5.1.51

package/cabloy-docs/backend/foundation.md

@@ -0,0 +1,281 @@
+# Backend Foundation
+
+This guide explains the core architectural role of Vona in the Cabloy monorepo.
+
+## What Vona is in Cabloy
+
+Vona is the backend half of the Cabloy fullstack architecture.
+
+It is designed for building `SSR`, `SPA`, `Web`, and `Admin` experiences in one broader system while keeping frontend and backend concerns separated enough to evolve independently.
+
+## Fullstack mechanism
+
+The core fullstack pattern remains the same:
+
+- Zova provides the frontend framework
+- Vona provides the backend framework
+- the backend and frontend cooperate through generated artifacts, runtime integration, and shared conventions
+
+Important integration channels include:
+
+- backend-generated Swagger/OpenAPI metadata for frontend SDK generation
+- frontend-generated route, icon, and component types that can feed backend-side usage and tooling
+- shared monorepo scripts that make both sides visible to humans and AI systems
+
+## Why Vona matters for backend and fullstack development
+
+Vona combines backend productivity, DTO generation, CRUD-oriented workflows, multi-tenancy, and broad infrastructure support. In the monorepo docs, the key point is this:
+
+Vona is not only a backend framework. Its conventions already encode a large amount of fullstack knowledge that contributors and automation should reuse instead of re-deriving manually.
+
+That is why the docs, skills, and rules in this repo prefer:
+
+- `npm run vona`
+- CLI-driven generation
+- source-truth route and module inspection
+- verification against current scripts and code
+
+## High-value backend capabilities
+
+The most important enduring Vona capabilities include:
+
+- modular architecture for suites and modules
+- IOC container and dependency lookup
+- AOP support across controller, internal, and external aspects
+- a structured request-path model for middleware, guards, interceptors, pipes, and filters
+- DTO inference and generation
+- CRUD-oriented workflows
+- multi-tenancy
+- authentication, captcha, and user-access infrastructure
+- multi-database and multi-datasource support
+- transaction support
+- caching, including two-layer cache
+- playground support for quick verification
+
+## The backend essentials model
+
+The backend essentials model is built around three connected ideas:
+
+- IoC containers and bean identity
+- scope as the module resource facade
+- suite / module / package boundaries as architectural units
+
+For the broader backend hub, also see [Backend (Vona)](/backend/introduction). For the compact essentials-family hub, also see [Backend Essentials](/backend/backend-essentials).
+
+## IoC containers and bean access
+
+Vona uses framework-managed beans instead of expecting ordinary code to construct everything manually.
+
+A useful distinction is:
+
+- the **app container** owns global backend beans
+- the **ctx container** owns request-scoped access
+- **new-bean creation** allows fresh bean instances when a workflow really needs them
+
+That means backend code can choose among:
+
+- dependency injection
+- dependency lookup
+- direct bean access
+- explicit new-bean creation
+
+A practical rule is:
+
+- prefer dependency lookup for concise business code
+- use injection when the surrounding code already follows that pattern
+- use direct bean access when you truly need container-level control
+
+## Access-style comparison
+
+| Access style         | Best for                                                            | Representative shape                                     |
+| -------------------- | ------------------------------------------------------------------- | -------------------------------------------------------- |
+| Dependency injection | explicit wiring in the current class                                | `@Use('demo-student.service.student')`                   |
+| Dependency lookup    | ordinary module-oriented business code                              | `this.scope.service.student`                             |
+| Direct bean access   | container-aware control or request-scoped lookup                    | `this.bean._getBean(...)`, `this.ctx.bean._getBean(...)` |
+| Fresh bean creation  | workflows that should not reuse the ordinary resolved bean instance | `this.bean._newBean(...)`                                |
+
+## Dependency injection vs dependency lookup vs direct bean access
+
+These three access styles solve related but different problems.
+
+### Dependency injection
+
+Dependency injection is explicit and type-friendly.
+
+Representative pattern:
+
+```typescript
+class ControllerStudent {
+  @Use('demo-student.service.student')
+  serviceStudent: ServiceStudent;
+}
+```
+
+### Dependency lookup
+
+Dependency lookup is often the most concise default.
+
+Representative patterns:
+
+```typescript
+this.scope.service.student.findOne();
+this.$scope.demoStudent.service.student.findOne();
+```
+
+### Direct bean access
+
+Direct bean access exposes the container layer more explicitly.
+
+Representative patterns:
+
+```typescript
+this.bean._getBean('demo-student.service.student');
+this.ctx.bean._getBean('demo-student.service.student');
+this.bean._newBean('demo-student.service.student');
+```
+
+The important conceptual split is:
+
+- injection wires a dependency into the current class
+- lookup navigates the module resource facade
+- direct bean access reaches the container more explicitly
+
+## Bean identifier, onion name, and bean scenes
+
+Legacy Vona essentials docs made bean identity more explicit, and that identity layer is still useful.
+
+The most important terms are:
+
+- **bean identifier**: a dotted identity such as `{moduleName}.{sceneName}.{beanName}`
+- **onion name**: a colon-based framework name such as `{moduleName}:{beanName}`
+- **bean scene**: the operational family a bean belongs to, such as service, model, startup, queue, or broadcast
+
+This matters because naming is not cosmetic. It affects:
+
+- injection by identifier
+- config override paths
+- inspect tooling
+- CLI-created bean organization
+
+A practical naming rule is:
+
+- bean identifier uses the fully qualified `module.scene.bean` form such as `demo-student.service.student`
+- onion name uses the shorter `module:bean` form such as `demo-student:student`
+- bean scene is the middle grouping layer that turns one module into operational families like `service`, `model`, `entity`, `dto`, or `startup`
+
+For deciding whether backend base classes belong in `src/lib`, `src/service`, or the global bean shorthand surface, also see [Class Placement Rule](/ai/class-placement-rule).
+
+## BeanBase built-ins
+
+A large part of the backend essentials model is that ordinary backend beans already inherit a useful working surface from `BeanBase`.
+
+Representative built-ins include:
+
+- `app`
+- `ctx`
+- `bean`
+- `scope`
+- `$scope`
+- `$logger`
+- `$loggerChild(...)`
+- locale-oriented helpers such as `$text`
+
+This matters because backend code usually should not reassemble those access points manually. The framework already places them on the base bean surface.
+
+## Bean lifecycle vocabulary
+
+Backend bean behavior also includes lifecycle concepts.
+
+Representative lifecycle hooks include:
+
+- `__init__`
+- `__dispose__`
+
+That lifecycle vocabulary matters because some backend capabilities are more than static helpers. They may need initialization, teardown, or startup-scoped behavior.
+
+## Scope as the module resource facade
+
+The most practical backend access model is scope.
+
+Scope groups a module’s resources behind one structured facade, including areas such as:
+
+- service
+- model
+- entity
+- config
+- constant
+- locale
+- error
+
+The key distinction is:
+
+- `this.scope` means local module resources
+- `this.$scope.<module>` means cross-module resources
+- `app.scope(...)` means explicit app-level scope lookup outside the local class shorthand
+
+This is one of the reasons Vona backend code can stay concise without flattening everything into arbitrary imports.
+
+## Suite / module / package boundaries
+
+Vona architecture is not only about classes and beans. It is also about structural boundaries.
+
+The core units are:
+
+- **suite**
+- **module**
+- **package**
+
+These units matter because they shape:
+
+- generation targets from the CLI
+- naming and identifiers
+- dependency declarations
+- resource access patterns
+- documentation and ownership boundaries
+
+That is why backend modularization should be treated as architecture, not just folder layout.
+
+For the current monorepo shape, also see [Package Map](/reference/package-map).
+
+## Relationship to Cabloy Basic and Cabloy Start
+
+Most of these backend concepts are shared across both editions.
+
+The differences usually appear at the integration boundary, for example:
+
+- which frontend modules consume the backend output
+- which Zova flavors are paired with the backend
+- which edition-specific assets or routes are present
+
+So the rule is:
+
+- explain the backend capability once
+- annotate edition-specific integration points only where they actually diverge
+
+## Suggested next pages
+
+Use these groups to move from the architecture-first model into the deeper backend families.
+
+### Essentials and workflow entry pages
+
+- [Backend (Vona)](/backend/introduction)
+- [Backend Essentials](/backend/backend-essentials)
+- [Backend CLI](/backend/cli)
+- [Backend Scripts](/backend/scripts)
+- [Service Guide](/backend/service-guide)
+
+### Contract and data leaves
+
+- [Controller Guide](/backend/controller-guide)
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [DTO Guide](/backend/dto-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+
+### Runtime and distributed leaves
+
+- [Runtime and Flavors](/backend/runtime-and-flavors)
+- [Config Guide](/backend/config-guide)
+- [Backend Startup Guide](/backend/startup-guide)
+- [Worker Guide](/backend/worker-guide)
+- [Queue Guide](/backend/queue-guide)

package/cabloy-docs/backend/i18n-guide.md

@@ -0,0 +1,211 @@
+# I18n Guide
+
+## Why i18n matters in Vona
+
+Vona treats locale and timezone handling as framework-level backend capabilities rather than ad hoc request helpers.
+
+That matters because backend contracts, entity metadata, user-facing messages, and request-context behavior all need consistent localization rules.
+
+## The two main i18n dimensions
+
+In the backend docs, i18n is best understood through two related dimensions:
+
+- **locale** for language resources and localized metadata
+- **timezone** for request-context time interpretation
+
+## Module locale resources
+
+Each module can provide its own locale resources.
+
+Representative initialization workflow:
+
+```bash
+npm run vona :init:locale demo-student
+```
+
+Representative files include:
+
+- `src/module/demo-student/src/config/locale/en-us.ts`
+- `src/module/demo-student/src/config/locale/zh-cn.ts`
+
+This makes localization part of the module model rather than a single global string table.
+
+## Accessing locale resources
+
+Backend code can access locale resources through the module scope.
+
+### Current-module access
+
+```typescript
+const message1 = this.scope.locale.StudentName();
+const message2 = this.scope.locale.StudentName.locale('en-us');
+const message3 = this.scope.locale.StudentName.locale('zh-cn');
+```
+
+### Cross-module access
+
+```typescript
+const message1 = this.$scope.demoStudent.locale.StudentName();
+const message2 = this.$scope.demoStudent.locale.StudentName.locale('en-us');
+const message3 = this.$scope.demoStudent.locale.StudentName.locale('zh-cn');
+```
+
+## Project-level override
+
+Project-level locale resources can override module-level resources.
+
+Representative override files include:
+
+- `src/backend/config/locale/en-us.ts`
+- `src/backend/config/locale/zh-cn.ts`
+
+That means modules can provide defaults while the project still controls final wording when needed.
+
+A useful ownership rule is:
+
+- module locale files define reusable defaults close to the module
+- project locale files adjust wording for the current application
+- request context decides which locale is active for the current call
+
+## Current locale in request context
+
+The current locale is available on the request context.
+
+### Get current locale
+
+```typescript
+const locale = this.ctx.locale;
+```
+
+### Set current locale
+
+```typescript
+this.ctx.locale = 'en-us';
+```
+
+### Get default locale
+
+```typescript
+const localeDefault = this.$scope.locale.config.locale.defaultLocale;
+```
+
+## Locale configuration and resolution order
+
+The `a-locale` module exposes locale settings such as:
+
+- `defaultLocale`
+- `queryField`
+- `headerField`
+- `cookieField`
+
+The current locale is resolved in this order:
+
+- query field
+- header field
+- cookie field
+- user locale
+- `Accept-Language`
+- default locale
+
+This is important because locale is not guessed from only one source.
+
+## Adding a new language
+
+Vona ships with default locales such as `en-us` and `zh-cn`, and additional languages can be added through interface merging and new locale files.
+
+That means locale support is extensible at the type level as well as the resource-file level.
+
+Representative type extension:
+
+```typescript
+declare module 'vona' {
+  export interface ILocaleRecord {
+    'zh-tw': never;
+  }
+}
+```
+
+In the VSCode workflow, the `recordlocale` snippet can generate the augmentation skeleton.
+
+## Plural support
+
+Locale resources can express plural-aware strings through naming conventions such as:
+
+- `TestApples_`
+- `TestApples_0`
+- `TestApples_1`
+
+Multiple-parameter variants are also supported through ordinal-aware suffix conventions.
+
+This makes plural handling part of the localization model instead of forcing each project to invent its own formatting layer.
+
+## Timezone support
+
+Vona also tracks timezone in the request context.
+
+### Get current timezone
+
+```typescript
+const tz = this.ctx.tz;
+```
+
+### Set current timezone
+
+```typescript
+this.ctx.tz = 'America/New_York';
+```
+
+A representative use case is parsing request-driven date filters with the current timezone instead of assuming server-local time:
+
+```typescript
+const dateStart = DateTime.fromISO(dateStartStr, { zone: this.ctx.tz });
+```
+
+The `a-locale` module exposes timezone settings such as:
+
+- `defaultTz`
+- `queryField`
+- `headerField`
+- `cookieField`
+
+The current timezone is resolved in this order:
+
+- query field
+- header field
+- cookie field
+- user timezone
+- default timezone
+- system timezone fallback
+
+## OpenAPI and entity metadata localization
+
+One of the most important backend i18n capabilities is that entity and OpenAPI-facing metadata can be localized.
+
+Representative helpers include:
+
+- `$localeScope(...)`
+- module-local `$locale(...)`
+
+That allows fields such as `title`, `description`, or other metadata to stay machine-readable while still producing localized developer-facing output.
+
+## Relationship to other backend guides
+
+Read this guide together with:
+
+- [Entity Guide](/backend/entity-guide)
+- [Error Guide](/backend/error-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [User Access Guide](/backend/user-access-guide)
+
+These guides show how i18n affects entity metadata, API contracts, and user-scoped request behavior.
+
+## Implementation checks for backend localization changes
+
+When editing backend localization-sensitive behavior, ask:
+
+1. does this text belong in module locale resources instead of inline strings?
+2. should the value respect current locale, current timezone, or both?
+3. does the change affect OpenAPI or entity metadata localization?
+4. should the project override module defaults instead of editing shared resources directly?
+
+That helps AI keep backend localization aligned with Vona’s real request-context and metadata model.

package/cabloy-docs/backend/internal-aop-guide.md

@@ -0,0 +1,181 @@
+# Internal AOP Guide
+
+## Why internal AOP matters
+
+Internal AOP is how Vona adds behavior inside a class without forcing the developer to duplicate the same logic across many methods.
+
+This is especially useful for:
+
+- transactions
+- logging
+- caching
+- scope-based lookup
+- dynamic property and method behavior
+
+## Two internal AOP mechanisms
+
+Vona provides two main internal mechanisms:
+
+- **AOP Method**
+- **Magic Method**
+
+## AOP Method
+
+AOP Method extends class methods through decorators.
+
+It can be used on controller methods, service methods, and other class methods that should participate in reusable around-execution behavior.
+
+Representative CLI generation pattern:
+
+```bash
+npm run vona :create:bean aopMethod log -- --module=demo-student
+```
+
+That generator-backed workflow matters because AOP Method beans participate in the same onion metadata system as other Vona extension points.
+
+### Representative custom AOP Method
+
+```typescript
+@AopMethod<IAopMethodOptionsLog>()
+class AopMethodLog {
+  async execute(_options, _args, next) {
+    const timeBegin = Date.now();
+    const res = await next();
+    const timeEnd = Date.now();
+    console.log('time:', timeEnd - timeBegin);
+    return res;
+  }
+}
+```
+
+### Representative usage
+
+```typescript
+@Aspect.aopMethod('demo-student:log')
+```
+
+### Parameter model
+
+AOP Method supports:
+
+- typed options
+- default values
+- per-usage overrides
+- app-config overrides
+- enable/disable
+- `mode` and `flavor`
+- ordering through `dependencies` and `dependents`
+
+A representative precedence model is:
+
+- usage-site override
+- then `config.onions.aopMethod`
+- then decorator default values
+
+That makes AOP Method practical for both framework-wide defaults and one-off method specialization.
+
+## Built-in internal AOP helpers
+
+Several built-in AOP Method helpers already exist.
+
+Representative examples include:
+
+- `a-logger:log`
+- `a-orm:transaction`
+- `a-caching:cachingGet`
+- `a-caching:cachingSet`
+- `a-caching:cachingDel`
+- `a-caching:cachingClear`
+
+These built-ins also expose shorthand decorators such as:
+
+```typescript
+@Core.log({ level: 'info' })
+@Core.transaction({ isolationLevel: 'READ_COMMITTED', propagation: 'REQUIRED' })
+@Caching.get({ cacheName: 'module-name:xxx' })
+```
+
+For the broader logger-client, rotation, and level model behind `@Core.log(...)`, see [Logger Guide](/backend/logger-guide).
+
+## Magic Method
+
+Magic Method provides dynamic behavior through conventional method names such as:
+
+- `__get__`
+- `__set__`
+- `__method__`
+- `__init__`
+- `__dispose__`
+
+A useful ownership rule is that Magic Method is about changing how the class itself exposes properties, lookup, or lifecycle behavior, while AOP Method is about wrapping a named method call with reusable around-execution logic.
+
+### Why this matters
+
+Magic Method is one of the reasons Vona can keep dependency lookup and scope-driven APIs concise.
+
+A representative example is module scope lookup:
+
+```typescript
+this.scope.model.student.selectAndCount(params);
+```
+
+Instead of requiring verbose injection or manual bean lookup, Vona can resolve the target dynamically through magic-method conventions.
+
+### CRUD-oriented example
+
+Magic Method can also simplify ORM usage:
+
+```typescript
+this.scope.model.student.getById(id);
+```
+
+This reads more naturally than always spelling out lower-level query objects manually.
+
+### Custom `__get__` and `__set__`
+
+Any class can define custom dynamic property behavior:
+
+```typescript
+protected __get__(prop: string) {
+  return this._colors[prop];
+}
+
+protected __set__(prop: string, value: any): boolean {
+  if (this._colors[prop] === undefined) return false;
+  this._colors[prop] = value;
+  return true;
+}
+```
+
+Type merging can then expose those dynamic properties more safely.
+
+That is the key discipline when using Magic Method: keep the runtime shortcut and the type surface aligned, so dynamic behavior still reads like a deliberate framework abstraction rather than an untyped trick.
+
+## Choosing between AOP Method and Magic Method
+
+Use this rule of thumb:
+
+- use **AOP Method** when the goal is to decorate or wrap a class method
+- use **Magic Method** when the goal is dynamic property, lookup, lifecycle, or generic method behavior
+
+## Relationship to other backend guides
+
+Internal AOP connects directly to:
+
+- [Service Guide](/backend/service-guide)
+- [Model Guide](/backend/model-guide)
+- [Transaction Guide](/backend/transaction-guide)
+- [Cache Guide](/backend/cache-guide)
+
+These guides often show the business-facing results of internal AOP, while this page explains the underlying extension model.
+
+## Questions for internal AOP changes
+
+When editing backend classes, ask:
+
+1. is there already an AOP Method or shorthand for this behavior?
+2. is a magic-method pattern already part of the framework abstraction here?
+3. should scope lookup or dynamic method behavior be preserved instead of rewritten into a heavier pattern?
+4. does the change interact with caching, transactions, logging, or lifecycle hooks?
+
+That helps AI preserve Vona’s internal extension model instead of replacing it with generic patterns.