cabloy 5.1.49 → 5.1.51

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

@@ -0,0 +1,189 @@
+# Mail Guide
+
+## Why mail matters in Vona
+
+Vona treats email delivery as a framework capability rather than a one-off SMTP utility call.
+
+That matters because email sending often needs queue-backed execution, multiple clients, environment-specific configuration, and integration with user-access or other business workflows.
+
+## Core mail model
+
+The `a-mail` module provides email delivery on top of Nodemailer.
+
+The most important framework-level pieces are:
+
+- one or more **mail clients**
+- a **default client**
+- queue-backed sending
+- configuration through app config or environment variables
+
+## Mail clients
+
+Mail clients are configured under the `a-mail` module config.
+
+Representative configuration areas include:
+
+- `defaultClient`
+- `clients`
+
+A client usually defines:
+
+- `transport`
+- `defaults`
+
+### Transport
+
+Transport settings describe how mail is actually delivered, for example:
+
+- `service`
+- `host`
+- `port`
+- `secure`
+- `auth.user`
+- `auth.pass`
+
+### Defaults
+
+Defaults provide common message values such as `from`.
+
+## Built-in test service
+
+Vona provides a built-in `test` mail service so email flows can be exercised during development without requiring a real mail server.
+
+This is important because it makes email behavior easier to verify early instead of deferring all mail testing to production-like infrastructure.
+
+## Configuration through app config and env
+
+Mail configuration can be provided through:
+
+- app config under `config.modules['a-mail']`
+- environment variables such as `MAIL_DEFAULT_CLIENT` and related transport/default fields
+
+That means operational mail behavior can remain configurable without rewriting application logic.
+
+## Adding a new mail client
+
+Projects can add additional clients for different email responsibilities, such as a dedicated `order` client.
+
+This is useful when different workflows need different senders, transports, or message defaults.
+
+Representative type extension:
+
+```typescript
+declare module 'vona-module-a-mail' {
+  export interface IMailClientRecord {
+    order: never;
+  }
+}
+```
+
+In the VSCode workflow, the `recordmailclient` snippet can generate the augmentation skeleton.
+
+A representative config expansion is:
+
+```typescript
+config.modules = {
+  'a-mail': {
+    defaultClient: 'system',
+    clients: {
+      system: {
+        transport: { service: 'test' },
+        defaults: { from: 'no.reply@cabloy.com' },
+      },
+      order: {
+        transport: { service: 'test' },
+        defaults: { from: 'order@cabloy.com' },
+      },
+    },
+  },
+};
+```
+
+## `bean.mail`
+
+Vona exposes a global bean `bean.mail` for sending emails.
+
+Representative pattern:
+
+```typescript
+const mail: IMailOptions = {
+  to: 'someone@cabloy.com',
+  subject: 'this is a test mail',
+  text: 'message body!',
+};
+await this.bean.mail.send(mail);
+```
+
+A specific client can also be selected explicitly:
+
+```typescript
+await this.bean.mail.send(mail, 'order');
+```
+
+## Queue-backed delivery
+
+Vona sends mail through a built-in queue.
+
+This is one of the most important architectural points of the mail system, because email delivery is naturally asynchronous and should not be tightly coupled to the immediate request path.
+
+Queue behavior can be tuned through queue config, for example worker concurrency.
+
+Representative config pattern:
+
+```typescript
+config.onions = {
+  queue: {
+    'a-mail:mail': {
+      options: {
+        worker: {
+          concurrency: 10,
+        },
+      },
+    },
+  },
+};
+```
+
+A useful ownership rule is:
+
+- request or business logic decides _that_ a mail should be sent
+- `bean.mail` decides which client to use
+- the queue owns _when_ the actual delivery work runs
+
+## Relationship to user-access and event workflows
+
+Mail is commonly part of broader backend lifecycle behavior such as:
+
+- account registration follow-up
+- activation or confirmation mail
+- notification workflows after business events
+
+Read this guide together with:
+
+- [User Access Guide](/backend/user-access-guide)
+- [Event Guide](/backend/event-guide)
+
+Those guides explain the flows where mail often becomes a downstream effect rather than the initiating business action.
+
+In the current repo, the `a-mailconfirm` flow is a representative example: user-access events can trigger mail-confirm behavior, and that bean ultimately delegates delivery through `bean.mail.send(...)` instead of embedding transport details directly into the user workflow.
+
+## When to use a dedicated mail client
+
+Use a dedicated client when:
+
+- a workflow needs a different sender identity
+- a workflow needs a different transport
+- a workflow needs separate operational handling from the default client
+
+Use the default client when the mail path belongs to the general system mail flow.
+
+## Implementation checks for backend mail changes
+
+When editing backend mail behavior, ask:
+
+1. should this email be sent through the default client or a dedicated client?
+2. does the flow belong in the immediate request path or in a queue-backed asynchronous path?
+3. is the existing `test` mail service enough for development verification?
+4. does the mail behavior belong to a user-access lifecycle event or a broader business event workflow?
+
+That helps AI keep email delivery aligned with Vona’s operational and event-driven backend model.

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

@@ -0,0 +1,80 @@
+# Menu Guide
+
+## Why menus matter in Cabloy SSR flows
+
+In Cabloy, SSR menu retrieval can be treated as a reusable backend capability instead of a one-off frontend-only concern.
+
+That matters because shared menu retrieval makes it easier to reuse navigation logic across modules and editions.
+
+## Core SSR menu model
+
+The `a-ssr` module provides a general SSR menu system.
+
+A project can ignore the system menu model and implement its own retrieval logic, but the built-in model is useful because it improves reuse, consistency, and scalability.
+
+## `bean.ssr`
+
+Vona exposes a global bean `bean.ssr` for SSR-facing menu retrieval.
+
+A representative usage pattern is:
+
+```typescript
+const res = await this.bean.ssr.retrieveMenus(publicPath);
+```
+
+This allows a module-level menu service to:
+
+1. ask the shared SSR menu system for the effective menu set
+2. fall back to default local menus when needed
+
+The current `home-base` implementation in this repo follows exactly that pattern in its menu service, which keeps this guide grounded in the real out-of-the-box SSR path.
+
+## Fallback strategy
+
+A practical menu service can:
+
+- try shared SSR menu retrieval first
+- return a module-defined default menu if no shared menu is available
+
+That keeps menu integration flexible without giving up framework-level reuse.
+
+## Menu API shape
+
+A backend controller can expose the menu retrieval path directly:
+
+```typescript
+@Web.get(':publicPath?')
+@Api.body(v.object(DtoMenus))
+@Passport.public()
+async retrieveMenus(@Arg.param('publicPath', v.optional()) publicPath?: string) {
+  return await this.scope.service.menu.retrieveMenus(publicPath);
+}
+```
+
+This makes menu retrieval part of the broader backend contract surface.
+
+In the current repo implementation, the out-of-the-box menu controller is public and delegates directly to `this.scope.service.menu.retrieveMenus(publicPath)`.
+
+## Relationship to frontend integration
+
+Menu retrieval is especially relevant in SSR-sensitive frontend flows.
+
+The backend menu contract should be read together with frontend routing, SSR, and page-loading behavior, especially when different editions expose different module or menu structures.
+
+A practical boundary is:
+
+- backend decides how menus are retrieved, merged, and defaulted
+- frontend decides how those menu DTOs are rendered into route or navigation state
+
+That split helps avoid re-implementing menu policy independently on both sides.
+
+## Implementation checks for SSR menu changes
+
+When editing SSR menu behavior, ask:
+
+1. should the logic use `bean.ssr.retrieveMenus(...)` instead of inventing a parallel retrieval path?
+2. is there a default fallback menu that should remain available?
+3. does the menu contract belong in backend API design, frontend route design, or both?
+4. does the active edition affect the menu structure or public path assumptions?
+
+That helps AI keep menu behavior aligned with Cabloy’s shared SSR architecture.

package/cabloy-docs/backend/migration-and-changes.md

@@ -0,0 +1,192 @@
+# Migration and Changes
+
+This guide explains how migration and change management work in Vona within the Cabloy monorepo.
+
+## Why this system exists
+
+Vona provides a migration mechanism designed for long-lived modular projects.
+
+Several important characteristics define this migration system:
+
+- module-aware migration
+- multi-tenant initialization support
+- test-data support
+- production-safe execution
+- full access to the Vona ecosystem inside migration code
+
+This makes migration in Vona more than a one-off schema script. It is part of the framework’s modular lifecycle.
+
+## Migration in the backend contract loop
+
+A useful backend-contract-loop lifecycle mental model is:
+
+- entity and model define the current structural contract
+- DTOs and controllers define the API contract on top of that structure
+- `meta.version` manages schema evolution and initialization data
+- tests verify that the migrated backend still satisfies the intended contract
+
+That is why migration should be understood as part of the same backend thread, not as a separate maintenance topic.
+
+## Define data version
+
+Each module declares its current data version in its own `package.json`.
+
+Representative pattern:
+
+```json
+{
+  "name": "vona-module-demo-student",
+  "vonaModule": {
+    "fileVersion": 1
+  }
+}
+```
+
+The key rule is:
+
+- increment `fileVersion` when a released module introduces a new schema change that must be applied in sequence
+
+In the scaffolded CRUD workflow, this is not an isolated maintenance step. The generator-driven thread treats `fileVersion` as part of the same backend evolution path that also touches entity/model/controller/test resources.
+
+## `meta.version`
+
+Vona uses a bean named `meta.version` to organize migration code for a module.
+
+Create it with:
+
+```bash
+npm run vona :create:bean meta version -- --module=demo-student
+```
+
+Representative shell:
+
+```typescript
+@Meta()
+export class MetaVersion extends BeanBase {}
+```
+
+## Three change scenarios
+
+Three migration scenarios are defined:
+
+| Scenario | Purpose                                          |
+| -------- | ------------------------------------------------ |
+| `update` | schema evolution such as tables and fields       |
+| `init`   | instance- or tenant-specific initialization data |
+| `test`   | test-only data for the test environment          |
+
+This split is one of the most important Vona migration ideas because it separates:
+
+- structural change
+- initialization logic
+- test data setup
+
+A practical generated-thread interpretation is:
+
+- `update` follows schema and entity/model evolution
+- `init` follows instance-aware initialization needs introduced by the backend feature
+- `test` keeps the generated or refined contract easy to verify under the test lifecycle
+
+## Update: schema migration
+
+Representative pattern:
+
+```typescript
+@Meta()
+export class MetaVersion extends BeanBase implements IMetaVersionUpdate {
+  async update(options: IMetaVersionUpdateOptions) {
+    if (options.version === 1) {
+      await this.bean.model.createTable('demoStudent', table => {
+        table.basicFields();
+        table.string('name', 50);
+        table.string('description', 255);
+      });
+    }
+  }
+}
+```
+
+A typed style based on entity metadata is also supported, and it is usually the better long-term default when possible.
+
+## Init: tenant-aware initialization
+
+Representative pattern:
+
+```typescript
+@Meta()
+export class MetaVersion extends BeanBase implements IMetaVersionInit {
+  async init(options: IMetaVersionInitOptions) {
+    if (options.version === 1) {
+      await this.scope.model.student.insert({
+        name: 'Tom',
+        description: 'This is a student',
+      });
+    }
+  }
+}
+```
+
+The important point is that initialization can run per instance or tenant, which keeps tenant data isolated.
+
+## Test: test-only data
+
+Representative pattern:
+
+```typescript
+@Meta()
+export class MetaVersion extends BeanBase implements IMetaVersionTest {
+  async test() {
+    await this.scope.model.student.insert({
+      name: 'Jimmy',
+      description: 'Only used in unit test',
+    });
+  }
+}
+```
+
+This is valuable because test data becomes part of the structured migration lifecycle instead of being scattered across unrelated setup code.
+
+## Version changes across the generated backend thread
+
+When the generated CRUD thread evolves, migration should evolve with it.
+
+A practical sequence is:
+
+1. increment `fileVersion`
+2. add or adjust entity/model structure
+3. update `meta.version` logic
+4. rerun migration locally
+5. verify the contract through tests and controller actions
+
+This keeps schema change, backend contract change, and verification tightly connected.
+
+## Local development workflow
+
+One important distinction for local development is:
+
+- when iterating locally, you often want to recreate the database and re-run migration logic without bumping `fileVersion`
+
+Representative commands:
+
+```bash
+npm run test
+cd vona && npm run db:reset
+```
+
+A practical decision rule is:
+
+- use `db:reset` when you mainly need to replay migration/database setup locally
+- use `test` when you need to verify that migration, controller behavior, and the broader generated contract thread still work together
+
+## Implementation checks for migration-sensitive changes
+
+When changing backend schema or module initialization behavior, do not only edit entities and models.
+
+Also ask:
+
+1. does this change require a `fileVersion` increment?
+2. does `meta.version` need an `update`, `init`, or `test` branch?
+3. should the local verification path include `test` or `db:reset`?
+4. does the change affect the CRUD-generated thread or frontend-facing API contract as well?
+
+That prevents schema changes from being documented in code but never integrated into the module lifecycle.