cabloy 5.1.50 → 5.1.52

package/cabloy-docs/backend/introduction.md

@@ -0,0 +1,95 @@
+# Backend (Vona)
+
+This page is the backend hub for Cabloy users, contributors, and AI vibe coding workflows that need the backend side of the framework.
+
+Vona is the backend half of Cabloy’s one-framework-system fullstack architecture.
+
+## What Vona is responsible for
+
+- application startup and runtime composition
+- IOC and AOP infrastructure
+- controller, service, model, entity, DTO, and AOP workflows
+- authentication, captcha, user access, menus, events, logging, upload, mail, serialization, ORM, caching, startup, election, queues, workers, schedules, broadcast, redlock, and other backend infrastructure
+- OpenAPI output used by frontend SDK-related workflows
+
+## How to approach backend work
+
+For contributor and automation workflows in this repository, prefer this order:
+
+1. inspect the root `package.json` and `npm run vona` entrypoint
+2. inspect Vona CLI command families such as `create:*`, `init:*`, `tools:*`, and `bin:*`
+3. inspect the current module or suite layout before creating new files manually
+4. use public docs for user-facing guidance and `.docs-internal/` for maintainer rationale
+
+## Backend reading paths
+
+Use this page as the main backend hub, then choose the family that matches your task.
+
+### Architecture spine
+
+Start here when you need the core backend mental model first:
+
+- [Backend Foundation](/backend/foundation)
+- [Backend Essentials](/backend/backend-essentials)
+- [Backend CLI](/backend/cli)
+- [Service Guide](/backend/service-guide)
+- [Package Map](/reference/package-map)
+
+This gives the architectural vocabulary for concepts such as bean, scope, suite, module, package, and backend access patterns.
+
+### Contract and data family
+
+Use this path when the task is about the backend contract loop or ORM-backed backend data design:
+
+- [Controller Guide](/backend/controller-guide)
+- [Validation Guide](/backend/validation-guide)
+- [DTO Guide](/backend/dto-guide)
+- [Entity Guide](/backend/entity-guide)
+- [Model Guide](/backend/model-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [ORM Guide](/backend/orm-guide)
+
+### Runtime and distributed family
+
+Use this path when the task is about runtime shape, startup, instances, workers, or distributed execution:
+
+- [Runtime and Flavors](/backend/runtime-and-flavors)
+- [Config Guide](/backend/config-guide)
+- [Backend Startup Guide](/backend/startup-guide)
+- [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution)
+- [Worker Guide](/backend/worker-guide)
+- [Election Guide](/backend/election-guide)
+- [Queue Guide](/backend/queue-guide)
+- [Broadcast Guide](/backend/broadcast-guide)
+- [Schedule Guide](/backend/schedule-guide)
+- [Redlock Guide](/backend/redlock-guide)
+
+### Reference and support pages
+
+Use these when you need repo structure, scripts, or command context around the backend families:
+
+- [Backend Quickstart](/backend/quickstart)
+- [Backend Scripts](/backend/scripts)
+- [Package Map](/reference/package-map)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+
+## Edition impact
+
+Most Vona concepts are shared between Cabloy Basic and Cabloy Start.
+
+Differences usually appear when backend modules integrate with edition-specific frontend modules, assets, routes, or generated outputs. When that happens, explain the backend concept once and annotate the edition-specific integration points explicitly.
+
+## Suggested next runtime topics
+
+If your task is already inside the runtime and distributed family, read these guides together in roughly this order:
+
+- [Runtime and Flavors](/backend/runtime-and-flavors)
+- [Config Guide](/backend/config-guide)
+- [Backend Startup Guide](/backend/startup-guide)
+- [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution)
+- [Worker Guide](/backend/worker-guide)
+- [Election Guide](/backend/election-guide)
+- [Queue Guide](/backend/queue-guide)
+- [Broadcast Guide](/backend/broadcast-guide)
+- [Schedule Guide](/backend/schedule-guide)
+- [Redlock Guide](/backend/redlock-guide)

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

@@ -0,0 +1,276 @@
+# JWT Guide
+
+## Why JWT matters in Vona
+
+Vona treats JWT as a framework capability rather than a raw token-library wrapper.
+
+That matters because backend auth flows usually need more than one token type, more than one verification path, and more than one lifecycle strategy for access, refresh, OAuth, or temporary tokens.
+
+## Core JWT model
+
+The `a-jwt` module provides JWT capabilities on top of `jsonwebtoken`.
+
+The most important framework-level pieces are:
+
+- **JWT clients**
+- a shared **base** configuration
+- helper methods for paired token creation
+- temporary-token support
+- integration with the passport/auth flow
+
+## JWT configuration
+
+JWT behavior is configured under `config.modules['a-jwt']`.
+
+Representative pattern:
+
+```typescript
+config.modules = {
+  'a-jwt': {
+    tempAuthToken: {
+      signOptions: { expiresIn: 5 * 60 },
+    },
+    base: {
+      secret: undefined,
+      signOptions: { issuer: env.APP_NAME },
+      verifyOptions: { issuer: env.APP_NAME },
+    },
+    clients: {
+      access: {
+        signOptions: { expiresIn: 2 * 60 * 60 },
+      },
+      refresh: {
+        signOptions: { expiresIn: 7 * 24 * 60 * 60 },
+      },
+    },
+  },
+};
+```
+
+The main configuration layers are:
+
+- `tempAuthToken`
+- `base`
+- `clients`
+
+A useful ownership rule is:
+
+- `base` defines common signing and verification defaults
+- `clients` specialize token behavior by scenario
+- `tempAuthToken` shortens the lifecycle for query-oriented or temporary access flows
+
+## Built-in JWT clients
+
+Vona ships with built-in JWT clients including:
+
+- `access`
+- `refresh`
+- `oauth`
+- `oauthstate`
+- `code`
+
+This is one of the reasons JWT should be understood as part of the broader auth/passport architecture rather than as only one access token string.
+
+## Secret fallback model
+
+A client can provide its own `secret`.
+
+If a client secret is absent, Vona falls back to:
+
+1. the client-specific secret
+2. `base.secret`
+3. `config.server.keys[0]`
+
+That means JWT signing can stay centrally configured even when most clients share the same secret source.
+
+## Adding a new JWT client
+
+Projects can add additional JWT clients for custom scenarios.
+
+Representative type extension:
+
+```typescript
+declare module 'vona-module-a-jwt' {
+  export interface IJwtClientRecord {
+    test: never;
+  }
+}
+```
+
+In the VSCode workflow, the `recordjwtclient` snippet can generate the augmentation skeleton.
+
+Representative client config:
+
+```typescript
+config.modules = {
+  'a-jwt': {
+    clients: {
+      test: {
+        secret: 'xxxx',
+        signOptions: { expiresIn: 2 * 60 * 60 },
+      },
+    },
+  },
+};
+```
+
+## `bean.jwt`
+
+Vona exposes a global bean `bean.jwt` for working with JWT clients.
+
+Representative client retrieval:
+
+```typescript
+const jwtAccess = this.bean.jwt.get('access');
+const jwtRefresh = this.bean.jwt.get('refresh');
+const jwtTest = this.bean.jwt.get('test');
+```
+
+This lets business code stay explicit about which token lifecycle it is using.
+
+## Generate an access token directly
+
+Representative pattern:
+
+```typescript
+const jwtAccess = this.bean.jwt.get('access');
+const accessToken = await jwtAccess.sign({ userId: '1' });
+```
+
+This is useful when a flow needs one specific client rather than the paired access/refresh helper.
+
+## Generate paired JWT tokens
+
+Vona can generate `accessToken` and `refreshToken` together:
+
+```typescript
+const jwtTokens = await this.bean.jwt.create({ userId: '1' });
+```
+
+The returned shape is `IJwtToken`:
+
+```typescript
+export interface IJwtToken {
+  accessToken: string;
+  refreshToken: string;
+  expiresIn: number;
+}
+```
+
+That paired helper is the normal fit for sign-in flows.
+
+## Temporary auth tokens
+
+Some flows need an access token in a URL query or similarly constrained transport.
+
+For those cases, Vona supports shorter-lived temporary access tokens.
+
+### Method 1: temporary sign on the access client
+
+```typescript
+const jwtAccess = this.bean.jwt.get('access');
+const accessToken = await jwtAccess.sign({ userId: '1' }, { temp: true });
+```
+
+### Method 2: dedicated helper
+
+```typescript
+const accessToken = await this.bean.jwt.createTempAuthToken({ userId: '1' });
+```
+
+This is useful when a token should remain valid only briefly, for example for URL-bound handoff flows.
+
+## Verification
+
+JWT verification can happen directly through a client:
+
+```typescript
+const jwtAccess = this.bean.jwt.get('access');
+const accessToken = await jwtAccess.sign({ userId: '1' });
+const payload = await jwtAccess.verify(accessToken);
+```
+
+Direct verification is useful when the business flow really needs raw payload verification.
+
+In ordinary request-path auth flows, the more important layer is usually the passport guard, not manual verification.
+
+## Relationship to passport
+
+In most application flows, JWT is consumed through `bean.passport` rather than through raw token handling in every controller.
+
+Representative passport-facing capabilities include:
+
+- `signin(...)`
+- `signout()`
+- `checkAuthToken(...)`
+- `refreshAuthToken(...)`
+- `createTempAuthToken(...)`
+- `createAuthTokenFromOauthCode(...)`
+
+This is the key architectural point:
+
+- `bean.jwt` owns token creation and verification mechanics
+- `bean.passport` owns identity-bearing flows built on top of those mechanics
+
+For example, the out-of-the-box Passport controller in `home-user` uses:
+
+- `refreshAuthToken` for refresh-token exchange
+- `createPassportJwtFromOauthCode` for finishing OAuth login
+- `createTempAuthToken` for temporary URL-bound auth scenarios
+
+## Relationship to guards and request-path auth
+
+The built-in global passport guard uses JWT checking as part of request authentication.
+
+That means request-path authorization usually works like this:
+
+1. the guard checks whether an auth token should be verified
+2. `bean.passport.checkAuthToken()` verifies and deserializes token state
+3. the current passport is attached to request context
+4. later guards or business logic use current user / roles / passport state
+
+So JWT is a foundational mechanism, but request-path access control should still be understood through the passport and guard layers.
+
+Read this guide together with:
+
+- [Auth Guide](/backend/auth-guide)
+- [User Access Guide](/backend/user-access-guide)
+- [Controller AOP Guide](/backend/controller-aop-guide)
+
+## OAuth-specific JWT flows
+
+Vona also uses JWT-backed flows for OAuth-oriented state and code handling.
+
+Representative passport methods include:
+
+- `createOauthAuthToken(...)`
+- `createOauthCode(...)`
+- `createOauthCodeFromOauthAuthToken(...)`
+- `createAuthTokenFromOauthCode(...)`
+
+This is why JWT is not only about access/refresh tokens. It is also part of the framework’s OAuth handoff model.
+
+## When to use `bean.jwt` directly
+
+Use `bean.jwt` directly when:
+
+- the business flow needs a specific client instance
+- the flow needs direct sign/verify control
+- the token use case is infrastructural rather than ordinary login/logout controller behavior
+
+Use `bean.passport` when:
+
+- the flow is really about user sign-in/out
+- refresh-token behavior should reuse framework defaults
+- token handling should remain tied to current passport lifecycle behavior
+
+## Implementation checks for JWT-sensitive changes
+
+When editing JWT-sensitive backend behavior, ask:
+
+1. is this really a raw JWT concern, or should it stay at the passport/auth layer?
+2. does the flow need `access`, `refresh`, `oauth`, `code`, or a custom client?
+3. should this token be temporary rather than normal-lived?
+4. does the request path already rely on the passport guard instead of manual verification?
+
+That helps AI keep token handling aligned with Vona’s real auth architecture instead of scattering raw JWT logic through unrelated controllers and services.

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

@@ -0,0 +1,223 @@
+# Logger Guide
+
+## Why logging matters in Vona
+
+Vona provides a structured logging system so backend logs can stay typed, environment-aware, and operationally useful instead of becoming ad hoc console output.
+
+That matters because production systems need different log clients, different retention behavior, different levels, and different context metadata.
+
+## Core logger model
+
+Vona’s logging system is built around:
+
+- **clients**
+- **children**
+- **rotation**
+- **levels**
+
+The system is based on Winston, but the important point in Cabloy is the framework-level model rather than the raw logger library itself.
+
+## Log directory behavior
+
+By default, the log directory changes by runtime environment.
+
+Representative defaults are:
+
+- test/development → `{project path}/.app/logs`
+- production → `{home}/.vona/{project name}/logs`
+
+This can be configured through app config or environment variables such as `LOGGER_DIR`.
+
+## Logger configuration
+
+Logger behavior is configured through `config.logger`.
+
+Representative areas include:
+
+- `baseDir`
+- `rotate(...)`
+- `base`
+- `clients`
+
+This means log behavior is part of the app configuration model, not a hardcoded utility.
+
+## Rotation
+
+Vona supports rotating log files by configuration.
+
+Representative rotate options include:
+
+- `enable`
+- `filename`
+- `datePattern`
+- `maxSize`
+- `maxFiles`
+
+These can be configured through app config or environment variables.
+
+## Logger clients
+
+The system provides a built-in `default` client and supports adding additional clients for scenario-specific logging.
+
+For example, a project can add an `order` client to separate order-related logs.
+
+A client can define its own transports while still inheriting common logger behavior.
+
+Representative type extension and client configuration patterns include:
+
+```typescript
+declare module 'vona' {
+  export interface ILoggerClientRecord {
+    order: never;
+  }
+}
+```
+
+```typescript
+config.logger = {
+  clients: {
+    order(this: VonaApplication, clientInfo) {
+      const transports = [
+        this.bean.logger.makeTransportFile(clientInfo, 'order'),
+        this.bean.logger.makeTransportConsole(clientInfo),
+      ];
+      return { transports };
+    },
+  },
+};
+```
+
+In the VSCode workflow, the `recordloggerclient` snippet can generate the client-type augmentation skeleton.
+
+## Getting a logger client
+
+There are two common access styles.
+
+### Via bean logger
+
+```typescript
+const loggerDefault = this.bean.logger.default;
+const loggerOrder = this.bean.logger.get('order');
+```
+
+### Via shorthand helpers
+
+```typescript
+this.$logger.info('test');
+this.$loggerClient('order').info('test');
+```
+
+The shorthand helpers are especially useful because they automatically include the current bean identity in the log context.
+
+## Child loggers
+
+For the same client, Vona can create child loggers for scenario-level context.
+
+Representative pattern:
+
+```typescript
+this.$loggerChild('pay').info('$50');
+this.$loggerChild('pay', 'order').info('$50');
+```
+
+That keeps business-specific log context explicit without requiring a whole new logger client every time.
+
+As with clients, child names can also be formalized through interface merging so logger usage stays type-safe at the project level.
+
+## Log levels
+
+Vona uses standard npm/RFC5424-style levels such as:
+
+- `error`
+- `warn`
+- `info`
+- `http`
+- `verbose`
+- `debug`
+- `silly`
+
+These levels map directly to logger methods such as:
+
+```typescript
+this.$logger.error('test');
+this.$logger.warn('test');
+this.$logger.info('test');
+this.$logger.debug('test');
+```
+
+## Level control and transport behavior
+
+Logger level controls what gets written where.
+
+Representative patterns include:
+
+- file transport at the normal level threshold
+- a second file transport for a more verbose level such as `debug`
+- console transport behavior for operational visibility
+
+Representative transport patterns:
+
+```typescript
+this.bean.logger.makeTransportFile(clientInfo, 'order');
+this.bean.logger.makeTransportFile(clientInfo, 'order-debug', 'debug');
+this.bean.logger.makeTransportConsole(clientInfo);
+```
+
+Default level behavior can also be configured through environment variables such as:
+
+- `LOGGER_CLIENT_DEFAULT`
+- `LOGGER_CLIENT_ORDER`
+
+## Reading and changing levels at runtime
+
+Vona can inspect or change active logger levels while the system is running.
+
+Representative methods include:
+
+- `getFilterLevel()`
+- `setFilterLevel(...)`
+
+Representative patterns:
+
+```typescript
+const levelDefault = this.bean.logger.getFilterLevel();
+const levelOrder = this.bean.logger.getFilterLevel('order');
+
+this.bean.logger.setFilterLevel('debug');
+this.bean.logger.setFilterLevel(false);
+this.bean.logger.setFilterLevel(true);
+```
+
+When level changes are applied, Vona can propagate them across workers, which is especially useful for live diagnostics.
+
+## Delayed log messages
+
+When expensive log-message construction would be wasted at a disabled level, Vona supports delayed message generation through callbacks.
+
+Representative pattern:
+
+```typescript
+this.$logger.debug(() => {
+  return JSON.stringify(obj);
+});
+```
+
+That avoids unnecessary work when the current level would drop the message anyway.
+
+## Relationship to internal AOP and runtime behavior
+
+Logging is closely connected to:
+
+- [Internal AOP Guide](/backend/internal-aop-guide) through built-in AOP helpers such as `@Core.log(...)`
+- [Runtime and Flavors](/backend/runtime-and-flavors) because log location, level, and operational behavior often vary by environment
+
+## Implementation checks for backend logging changes
+
+When editing backend logging behavior, ask:
+
+1. does this belong in the default client, a dedicated client, or a child logger?
+2. should the behavior be implemented through normal logger usage or an AOP-style logging decorator?
+3. does the current runtime environment or flavor affect where or how logs should be written?
+4. should expensive log-message construction be delayed behind a callback?
+
+That helps AI keep logging aligned with Vona’s operational model instead of scattering raw console output through the codebase.