@pylonts/dsl 1.1.5 → 1.1.11

package/dist/service.js

@@ -1,3 +1,63 @@
-export function defineService(name, app, description) {
-    return { name, type: 'service', app, description };
+import { exceptionEndNames } from './flow.js';
+export function defineService(options) {
+    if (!options.api.apps.includes(options.app)) {
+        throw new Error(`service ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+    }
+    const schema = {
+        type: 'service',
+        name: options.name,
+        description: options.description,
+        api: options.api,
+        app: options.app,
+        methods: {},
+    };
+    for (const key of Object.keys(options.methods)) {
+        const method = options.methods[key];
+        schema.methods[key] = { type: 'method', schema, ...method, name: key };
+    }
+    validateFlowBindings(schema);
+    return schema;
+}
+// A method bound to a flow: the flow's escape set (its exception ends) must
+// equal the method's declared throws, the flow's own args/results (when
+// present) must be the same objects as the method's, and one flow may serve
+// only one method.
+//
+// Notes: (1) the unique-binding check is per defineService call — a flow
+// shared across two service schemas is not detected; (2) escape-set equality
+// means exceptions swallowed by an internal catch (or routed through a
+// catch-all end) disappear from the contract, so the method must not declare
+// them.
+function validateFlowBindings(schema) {
+    const seenFlows = new Set();
+    for (const key of Object.keys(schema.methods)) {
+        const m = schema.methods[key];
+        if (!m.flow)
+            continue;
+        if (seenFlows.has(m.flow)) {
+            throw new Error(`service ${schema.name}: flow "${m.flow.name}" is bound to more than one method`);
+        }
+        seenFlows.add(m.flow);
+        if (m.flow.args !== undefined && m.flow.args !== m.args) {
+            throw new Error(`service ${schema.name}: method "${key}" args and its flow "${m.flow.name}" args must be the same object`);
+        }
+        if (m.flow.results !== undefined && m.flow.results !== m.results) {
+            throw new Error(`service ${schema.name}: method "${key}" results and its flow "${m.flow.name}" results must be the same object`);
+        }
+        const escaped = exceptionEndNames(m.flow);
+        const declared = new Set((m.throws ?? []).map((t) => t.name));
+        for (const e of escaped) {
+            if (!declared.has(e)) {
+                throw new Error(`service ${schema.name}: method "${key}" flow escapes ${e} but the method does not declare it`);
+            }
+        }
+        for (const d of declared) {
+            if (!escaped.has(d)) {
+                throw new Error(`service ${schema.name}: method "${key}" declares throw ${d} but its flow never escapes it`);
+            }
+        }
+        if (m.flow.name !== key) {
+            console.warn(`service ${schema.name}: method "${key}" flow name "${m.flow.name}" differs from the method key`);
+        }
+    }
 }

package/dist/third-service.d.ts

@@ -0,0 +1,80 @@
+import { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
+import type { ExceptionSchema } from './exception.js';
+import type { FieldRuleEnd, FieldRuleSchema } from './field-rule.js';
+import type { ThirdApiSchema } from './project.js';
+/** A third-party integration service (e.g. tenpay wechat pay).
+ *  Distinct from ServiceSchema (backend service bound to an app) and
+ *  ThirdApiSchema (project topology: the dir the integration lives in).
+ *  Describes the adapter class contract: constructor config + methods. */
+export interface ThirdServiceSchema extends SchemaBase {
+    type: 'thirdService';
+    /** The third-party system this service integrates (topology reference). */
+    schema: ThirdApiSchema;
+    /** Methods keyed by name — the map key is written back as the method name. */
+    methods: Record<string, ThirdServiceMethodSchema>;
+}
+/** A method exposed by a third-party service. */
+export interface ThirdServiceMethodSchema extends SchemaBase {
+    type: 'method';
+    schema: ThirdServiceSchema;
+    /** Input message — the Field-collection counterpart of a DtoMessage. */
+    args: ThirdMethodSchema;
+    /** Output message. */
+    results: ThirdMethodSchema;
+    /** Exceptions this method may throw (e.g. IOException, CodeException). */
+    throws?: ExceptionSchema[];
+}
+/** Field binding to a rule: which end the local wire field stands on.
+ *  The ref always stands on the other end — from/to carry no extra information. */
+export interface ConvertFieldSchema {
+    /** The rule binding field and ref (rule = name + two ends). */
+    rule: FieldRuleSchema;
+    /** The end instance the local wire field stands on. */
+    end: FieldRuleEnd;
+}
+/** Same-fact variant link: a wire field carrying the same fact as a local
+ *  entity column under a different type/format (e.g. total_fee in fen vs amount in yuan). */
+export interface ThirdFieldRef {
+    /** Wire field defined in this message (local definition). */
+    field: Field;
+    /** Field in another schema (table column or another message). */
+    ref: Field;
+    /** Optional rule binding — omitted when the fact is merely linked, not converted. */
+    convert?: ConvertFieldSchema;
+}
+/** A directional message of a third-party method: a Field collection mirroring
+ *  TableSchema.columns, but fields hold wire-format names/types. A field may be
+ *  a shared instance of a local entity column (same fact, same type) — its
+ *  name/schema keep pointing at the table and the DTO projection inherits
+ *  type/semantics from the entity, exactly like from(table). */
+export interface ThirdMethodSchema extends CollectionSchemaBase {
+    type: 'thirdMethod';
+    /** The method this message belongs to (direction implied by args/results slot). */
+    schema: ThirdServiceMethodSchema;
+    /** Wire-format fields. */
+    fields: Record<string, Field>;
+    /** Same-fact variant links: wire field -> local entity column. */
+    refs?: ThirdFieldRef[];
+}
+/** Message input for defineThirdMethod: type/schema are set by the builder. */
+export type ThirdMethodDef = Omit<ThirdMethodSchema, 'type' | 'schema'>;
+/** Build a third-party method message. Writes back name/schema on own fields
+ *  (top-level and nested); shared entity columns keep their table identity and
+ *  must be keyed by their column name. */
+export declare function defineThirdMethod(def: ThirdMethodDef): ThirdMethodSchema;
+/** Method input for defineThirdService: name is written back from the methods map key. */
+export interface ThirdServiceMethodDef {
+    /** Input message. */
+    args: ThirdMethodDef;
+    /** Output message. */
+    results: ThirdMethodDef;
+    /** Exceptions this method may throw (e.g. IOException, CodeException). */
+    throws?: ExceptionSchema[];
+    description?: string;
+}
+export declare function defineThirdService(options: {
+    schema: ThirdApiSchema;
+    name: string;
+    methods: Record<string, ThirdServiceMethodDef>;
+    description?: string;
+}): ThirdServiceSchema;

package/dist/third-service.js

@@ -0,0 +1,97 @@
+/** Build a third-party method message. Writes back name/schema on own fields
+ *  (top-level and nested); shared entity columns keep their table identity and
+ *  must be keyed by their column name. */
+export function defineThirdMethod(def) {
+    const message = {
+        type: 'thirdMethod',
+        name: def.name,
+        description: def.description,
+        // Filled by defineThirdService.
+        schema: undefined,
+        fields: def.fields,
+        refs: def.refs,
+    };
+    for (const key of Object.keys(message.fields)) {
+        const field = message.fields[key];
+        if (field.schema === undefined) {
+            field.name = key;
+            field.schema = message;
+        }
+        else if (field.schema.type === 'table') {
+            // Shared entity column: from() names the projection after field.name, so
+            // a mismatched key would silently rename the wire field. Same-fact fields
+            // with different names go through refs instead.
+            if (field.name !== key) {
+                throw new Error(`thirdMethod '${message.name}': shared column key '${key}' must match the column name '${field.name}' — ` +
+                    `same-fact fields with different names go through refs instead`);
+            }
+        }
+        else if (field.schema !== message) {
+            throw new Error(`thirdMethod '${message.name}': field '${key}' already belongs to ${field.schema.type} '${field.schema.name}', cannot reuse`);
+        }
+        writeBackNested(message, field);
+    }
+    if (message.refs !== undefined) {
+        const ownFields = Object.values(message.fields);
+        for (const link of message.refs) {
+            if (!ownFields.includes(link.field)) {
+                throw new Error(`thirdMethod '${message.name}': ref field must be one of its fields`);
+            }
+            if (link.ref.schema === undefined || link.ref.schema === message) {
+                throw new Error(`thirdMethod '${message.name}': ref target '${link.ref.name}' must be defined in another schema`);
+            }
+            if (link.convert !== undefined) {
+                const ends = Object.values(link.convert.rule.ends);
+                if (!ends.includes(link.convert.end)) {
+                    throw new Error(`thirdMethod '${message.name}': convert end '${link.convert.end.name}' must be one of rule '${link.convert.rule.name}' ends`);
+                }
+            }
+        }
+    }
+    return message;
+}
+/** Write back name/schema on nested wire fields (array items, object properties);
+ *  shared entity columns keep their table identity. */
+function writeBackNested(message, field) {
+    if (field.type === 'array') {
+        writeBackNested(message, field.items);
+        return;
+    }
+    if (field.type !== 'object')
+        return;
+    for (const key of Object.keys(field.properties)) {
+        const child = field.properties[key];
+        if (child.schema === undefined) {
+            child.name = key;
+            child.schema = message;
+        }
+        writeBackNested(message, child);
+    }
+}
+export function defineThirdService(options) {
+    const schema = {
+        type: 'thirdService',
+        name: options.name,
+        description: options.description,
+        schema: options.schema,
+        methods: {},
+    };
+    for (const key of Object.keys(options.methods)) {
+        const method = options.methods[key];
+        const methodSchema = {
+            type: 'method',
+            name: key,
+            description: method.description,
+            schema,
+            args: undefined,
+            results: undefined,
+            throws: method.throws,
+        };
+        methodSchema.args = defineThirdMethod(method.args);
+        methodSchema.results = defineThirdMethod(method.results);
+        methodSchema.args.schema = methodSchema;
+        methodSchema.results.schema = methodSchema;
+        schema.methods[key] = methodSchema;
+    }
+    return schema;
+}

package/dist/typebox-driver.d.ts

@@ -1,4 +1,5 @@
 import { DtoMessage, ImportBase } from './dto.js';
+import type { ThirdMethodSchema } from './third-service.js';
 export type EnumResolver = (enumName: string) => ImportBase | undefined;
 /** Collect all imports needed to render a DTO: include() bases + enum references. */
 export declare function collectDtoImports(schema: DtoMessage, resolver: EnumResolver | undefined, out: Map<string, ImportBase>): void;
@@ -10,3 +11,8 @@ export declare function renderDtoMessage(schema: DtoMessage, options?: {
     resolver?: EnumResolver;
     source?: string;
 }): string;
+/** Render one third-party method message export (const only — pair with
+ *  renderDtoTypeExport for the Static type). */
+export declare function renderThirdMethodExport(schema: ThirdMethodSchema, resolver: EnumResolver | undefined): string;
+/** Collect all imports needed to render a third-party method message: enum references. */
+export declare function collectThirdMethodImports(schema: ThirdMethodSchema, resolver: EnumResolver | undefined, out: Map<string, ImportBase>): void;

package/dist/typebox-driver.js

@@ -6,7 +6,7 @@ function renderDefault(v) {
         return renderString(v);
     return JSON.stringify(v);
 }
-function renderBasic(field, pattern, defaultValue, resolver) {
+function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
     if (pattern !== undefined && field.type !== 'string') {
         throw new Error(`pattern is only supported on string fields, got ${field.type} (${field.name})`);
     }
@@ -62,14 +62,36 @@ function renderBasic(field, pattern, defaultValue, resolver) {
             }
             return `Type.Enum(${ref.name})`;
         }
+        case 'aggregate':
+            // Aggregate query outputs: count/sum(int) are numbers, everything else
+            // arrives as a precision string.
+            return field.jsType === 'number' ? 'Type.Number()' : 'Type.String()';
+        case 'array':
+            return `Type.Array(${renderFieldValue(field.items, indent, resolver)})`;
+        case 'object':
+            return renderFieldObject(field.properties, indent + 1, resolver);
         default:
             // Field union is exhaustive; this branch is unreachable at runtime.
             throw new Error(`unsupported field type: ${String(field.type)}`);
     }
 }
+/** Render a plain Field value (wire-format nested fields), wrapping optional. */
+function renderFieldValue(field, indent, resolver) {
+    const base = renderBasic(field, undefined, undefined, resolver, indent);
+    return field.optional ? `Type.Optional(${base})` : base;
+}
+/** Render a plain Field object (wire-format nested object). */
+function renderFieldObject(properties, indent, resolver) {
+    const pad = '  '.repeat(indent);
+    const entries = Object.entries(properties).map(([name, f]) => `${pad}${name}: ${renderFieldValue(f, indent, resolver)}`);
+    return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+}
 function renderObject(fields, indent, resolver) {
     const pad = '  '.repeat(indent);
-    const entries = Object.entries(fields).map(([name, f]) => `${pad}${name}: ${renderField(f, indent, resolver)}`);
+    const entries = Object.entries(fields).map(([name, f]) => {
+        const rendered = isDtoField(f) ? renderField(f, indent, resolver) : renderFieldValue(f, indent, resolver);
+        return `${pad}${name}: ${rendered}`;
+    });
     return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
 }
 function renderField(f, indent, resolver) {
@@ -82,7 +104,9 @@ function renderValue(f, indent, resolver) {
         // Referenced DTO element — render by name (same-file export), not expanded.
         if (isDtoMessage(items))
             return `Type.Array(${items.name})`;
-        return `Type.Array(${renderField(items, indent + 1, resolver)})`;
+        if (isDtoField(items))
+            return `Type.Array(${renderField(items, indent + 1, resolver)})`;
+        return `Type.Array(${renderFieldValue(items, indent, resolver)})`;
     }
     if (f.field.type === 'object') {
         return renderObject(f.field.properties, indent + 1, resolver);
@@ -90,7 +114,7 @@ function renderValue(f, indent, resolver) {
     // DtoField only wraps a database Field; array/object defs live in the subclasses.
     // Only DTO-level defaults (setDefault) are emitted as TypeBox default
     // annotations; DB field defaults are not carried into the API contract.
-    return renderBasic(f.field, f.pattern, f.default, resolver);
+    return renderBasic(f.field, f.pattern, f.default, resolver, indent);
 }
 /** Structural check — DtoMessage instances may come from a different module copy, so instanceof is unreliable. */
 function isDtoMessage(v) {
@@ -98,24 +122,55 @@ function isDtoMessage(v) {
         return false;
     return v.type === 'dto';
 }
+/** Structural check — a DtoField wraps a Field in a .field property and has no .type of its own. */
+function isDtoField(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    return 'field' in v && !('type' in v);
+}
 function collectEnumImports(f, resolver, out) {
     if (f.field.type === 'array') {
         const items = f.field.items;
-        if (!isDtoMessage(items))
+        if (isDtoMessage(items))
+            return;
+        if (isDtoField(items)) {
             collectEnumImports(items, resolver, out);
+            return;
+        }
+        collectFieldEnumImports(items, resolver, out);
         return;
     }
     if (f.field.type === 'object') {
-        for (const child of Object.values(f.field.properties))
-            collectEnumImports(child, resolver, out);
+        for (const child of Object.values(f.field.properties)) {
+            if (isDtoField(child))
+                collectEnumImports(child, resolver, out);
+            else
+                collectFieldEnumImports(child, resolver, out);
+        }
         return;
     }
-    if (f.field.type === 'enum') {
-        const ref = resolver?.(f.field.enum.jsName);
-        if (!ref)
-            throw new Error(`enum field ${f.field.name}: no import ref for ${f.field.enum.jsName} — pass an EnumResolver`);
-        out.set(`${ref.from}#${ref.name}`, ref);
+    if (f.field.type === 'enum')
+        collectEnumRef(f.field, resolver, out);
+}
+/** Enum import collection over a plain Field (wire-format nested fields). */
+function collectFieldEnumImports(field, resolver, out) {
+    if (field.type === 'array') {
+        collectFieldEnumImports(field.items, resolver, out);
+        return;
+    }
+    if (field.type === 'object') {
+        for (const child of Object.values(field.properties))
+            collectFieldEnumImports(child, resolver, out);
+        return;
     }
+    if (field.type === 'enum')
+        collectEnumRef(field, resolver, out);
+}
+function collectEnumRef(field, resolver, out) {
+    const ref = resolver?.(field.enum.jsName);
+    if (!ref)
+        throw new Error(`enum field ${field.name}: no import ref for ${field.enum.jsName} — pass an EnumResolver`);
+    out.set(`${ref.from}#${ref.name}`, ref);
 }
 /** Collect all imports needed to render a DTO: include() bases + enum references. */
 export function collectDtoImports(schema, resolver, out) {
@@ -161,3 +216,13 @@ function renderBase(base) {
     const args = base.args.map((a) => (typeof a === 'string' ? a : a.name));
     return `${base.name}(${args.join(', ')})`;
 }
+/** Render one third-party method message export (const only — pair with
+ *  renderDtoTypeExport for the Static type). */
+export function renderThirdMethodExport(schema, resolver) {
+    return `export const ${schema.name} = ${renderFieldObject(schema.fields, 1, resolver)};`;
+}
+/** Collect all imports needed to render a third-party method message: enum references. */
+export function collectThirdMethodImports(schema, resolver, out) {
+    for (const f of Object.values(schema.fields))
+        collectFieldEnumImports(f, resolver, out);
+}

package/dist/utils.d.ts

@@ -1,13 +1,35 @@
-/** snake_case → camelCase: mer_id → merId; names without underscores are unchanged */
-export declare function toCamelCase(name: string): string;
-/** snake_case → PascalCase: mer_id → MerId */
-export declare function toPascalCase(snake: string): string;
-import { SchemaBase } from './dsl.js';
-import { FrontAppSchema } from './project.js';
-/** A utility module bound to exactly one frontend app. */
+import type { Field, SchemaBase } from './dsl.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+/** A utility method with a full signature. */
+export interface UtilsMethodSchema extends SchemaBase {
+    type: 'utilsMethod';
+    /** The utility module this method belongs to. */
+    schema: UtilsSchema;
+    /** Input fields. */
+    args: Record<string, Field>;
+    /** Output field. */
+    result: Field;
+}
+/** Method input for defineUtils: type/schema/name are set by the builder. */
+export type UtilsMethodDef = Omit<UtilsMethodSchema, 'type' | 'schema' | 'name'>;
+/** A base utility module (e.g. DateTimeUtils). */
 export interface UtilsSchema extends SchemaBase {
     type: 'utils';
-    /** The frontend app this utility module belongs to (shared instance from project.config). */
-    app: FrontAppSchema;
+    /** Backend binding — the api module this utils belongs to (shared instance
+     *  from project.config.ts apis). With `app` it serves that frontend
+     *  ({api}/{app}/utils/); alone it is the api's public module
+     *  ({api}/common/utils/). Unset = not backend-side. */
+    api?: ProjectApiSchema;
+    /** Optional binding — the frontend app this utils serves (shared instance
+     *  from project.config.ts apps). Empty means a shared public module. */
+    app?: FrontAppSchema;
+    /** Methods keyed by name — the map key is written back as the method name. */
+    methods: Record<string, UtilsMethodSchema>;
 }
-export declare function defineUtils(name: string, app: FrontAppSchema, description?: string): UtilsSchema;
+export declare function defineUtils(options: {
+    name: string;
+    api?: ProjectApiSchema;
+    app?: FrontAppSchema;
+    methods: Record<string, UtilsMethodDef>;
+    description?: string;
+}): UtilsSchema;

package/dist/utils.js

@@ -1,12 +1,33 @@
-// ── naming conversions ──
-/** snake_case → camelCase: mer_id → merId; names without underscores are unchanged */
-export function toCamelCase(name) {
-    return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
-}
-/** snake_case → PascalCase: mer_id → MerId */
-export function toPascalCase(snake) {
-    return snake.replace(/(^|_)([a-z])/g, (_m, _p, c) => c.toUpperCase());
-}
-export function defineUtils(name, app, description) {
-    return { name, type: 'utils', app, description };
+export function defineUtils(options) {
+    if (options.api !== undefined && options.app !== undefined && !options.api.apps.includes(options.app)) {
+        throw new Error(`utils ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+    }
+    const schema = {
+        type: 'utils',
+        name: options.name,
+        description: options.description,
+        api: options.api,
+        app: options.app,
+        methods: {},
+    };
+    for (const key of Object.keys(options.methods)) {
+        const method = options.methods[key];
+        const methodSchema = {
+            type: 'utilsMethod',
+            name: key,
+            description: method.description,
+            schema,
+            args: method.args,
+            result: method.result,
+        };
+        for (const argKey of Object.keys(methodSchema.args)) {
+            const field = methodSchema.args[argKey];
+            field.name = argKey;
+            field.schema = methodSchema;
+        }
+        methodSchema.result.name = key;
+        methodSchema.result.schema = methodSchema;
+        schema.methods[key] = methodSchema;
+    }
+    return schema;
 }

package/docs/aggregate.md

@@ -0,0 +1,110 @@
+# 聚合与仓储 DSL 扩展规划（Aggregate / Repository）
+
+> 状态：**规划中（未实现）**
+> 关联代码：`dsl/src/db.ts`（TableSchema）、`dsl/src/dao.ts`（DaoSchema）、`dsl/src/service.ts`（ServiceSchema）
+> 背景对话：ts-libs 会话「dd DDD 扩展讨论」（商城下单用例）
+
+## 1. 背景：pylon 现状与 DDD 缺口
+
+**现状**：
+
+- `TableSchema` 是全局扁平数据字典（"表无物理归属"），orders / order_items 是两张互相独立声明、无聚合关系的表；
+- `DaoSchema` 是单表单 SQL（knex 透明代理），粒度 = 表，无跨表能力；
+- 多表读写由 service flow 手工编排：`dao.insert(orders) → dao.insert(order_items)` + 手工 `@Trans()`，"总额 = Σ明细"这类一致性靠开发者自觉，无强制约束。
+
+**DDD 缺口对照**（战术模式）：
+
+| DDD 概念 | dsl 现状 | 缺口 |
+|---------|---------|------|
+| 聚合 / 聚合根 | 无 | **全新概念** |
+| 值对象 | mock 识别"金额/手机号"语义 | 无声明层 |
+| 领域事件 | 只有 UI 组件事件（event.ts） | **全新概念** |
+| 领域服务 | 全混在应用服务（service_schema） | 需拆分 |
+| 仓储 | 无（DAO 粒度是表） | **全新概念** |
+| 应用服务编排 | service_schema + flow ✅ | 已具备 |
+| 防腐层 | ThirdServiceSchema 只隔离 | 缺模型映射 |
+
+## 2. 扩展一：AggregateSchema（核心）
+
+**作用**：显式声明"哪些表属于同一个聚合、谁是聚合根、成员如何挂载、跨成员不变式、聚合间引用规则"。这是把"多表一致性从约定变约束"的落点。
+
+```ts
+defineAggregate({
+  name: 'Order',
+  root: ordersTable,                        // 聚合根表
+  members: {                                // 成员表（"包含几个 table schema" 的声明）
+    items:   { table: orderItemsTable,  via: 'order_no' },   // 1:N，外键挂根
+    address: { table: orderAddressTable, via: 'order_no', one: true },  // 1:1
+  },
+  invariants: [                             // 跨成员表不变式，挂聚合上，可被生成代码消费
+    { name: 'total = sum(items.price * items.qty)',
+      check: 'totalAmount == sum(items.price * items.qty)' },
+  ],
+  references: { productId: 'ProductAggregate' },  // 聚合间只按 ID 引用
+});
+```
+
+| 声明项 | 含义 | 缺了会怎样 |
+|--------|------|-----------|
+| `root` | 谁是聚合根 | 分不清一致性入口 |
+| `members` | 包含哪几个 table schema | "包含"只是列表，无结构 |
+| `members[i].via` | 成员表靠哪个外键挂根 | 工具无法推导 join / 级联关系 |
+| `invariants` | 跨成员一致性规则 | "总额=Σ明细"又回到 flow 里手工写 |
+| `references` | 聚合间只按 ID 引用 | 无法 lint 跨聚合直接持表引用 |
+
+**消费方**（声明一旦存在即可自动推导）：
+
+1. **生成 Repository**：按"加载 / 保存 / 删除"三套固定骨架自动产出（见下），`orders + order_items` 自动同事务，不再手工 `@Trans()`；
+2. **lint 约束**：禁止聚合外代码直接 `insert/update/delete` 成员表（只准经 root 走）；
+3. **不变式挂载**：save 前后强制校验。
+
+**多表映射三种模式**（聚合↔表）：A 单表=单聚合（1:1，几乎透明）；B 一聚合=多表（1:N，最常见，Order 案例）；C 多聚合共享表（N:1，DDD 不推荐）。
+
+## 3. 扩展二：RepositorySchema（可推导，也可显式声明）
+
+**作用**：聚合粒度的存储入口，把"哪些表一起查、怎么拼成聚合"的知识从 service flow 下沉到仓储。调用方只面对领域概念（Order），不面对表。
+
+```ts
+defineRepository({
+  name: 'OrderRepository',
+  aggregate: orderAggregate,   // 绑定聚合
+  // 内部如何落到 DAO 由 generator 按 aggregate 结构自动展开：
+  //   save(order)     = tx { ordersDao.upsert + orderItemsDao 级联 }
+  //   findByOrderNo() = ordersDao.get + orderItemsDao 按 order_no 查
+});
+```
+
+**聚合内 join 下沉、聚合间禁止 join**：
+
+- 聚合内：加载整个 Order（根 + 明细 + 地址）由 Repository 内部完成，调用方一行，join 知识声明在 `members[].via`；
+- 聚合间：只按 ID 引用，跨聚合 join 是 DDD 禁止的；展示商品名这类信息走读模型 / 查询服务（CQRS 的 Q 侧），或应用服务分步查 + 内存组装。
+
+**分层对照**：
+
+| 层 | 操作单元 | 一次操作覆盖 | dsl |
+|----|---------|------------|-----|
+| Service | 用例 | 跨多个聚合/服务 | service_schema ✅ |
+| Repository | **聚合** | orders + order_items 一个事务 | **本扩展** |
+| DAO | **表** | 单表一条 SQL | dao_schema ✅ |
+
+## 4. 扩展三：引入支持 DDD 的 TS 库（选型，待决策）
+
+dsl 是**声明期**（`defineAggregate` 声明结构），引入的库是**运行期**（代码跑起来时持久化/发事件）。两者互补，不冲突——声明可翻译为运行期库的配置。
+
+| 库 | 类型 | 聚合能力 | 与本扩展关系 |
+|----|------|---------|-------------|
+| **MikroORM** | ORM | Entity / Repository / Unit of Work / Identity Map / cascade persist | **首选参考**：`@OneToMany(cascade, orphanRemoval)` + `em.persist(order)` 就是"orders + order_items 同事务整体落库"的标准实现；AggregateSchema 声明可翻译成它的映射配置 |
+| **Remesh** | DDD 框架 | CQRS + 领域事件 + Command/Query 分离 | 领域事件 / CQRS 参考 |
+| **Emmett** | 事件溯源 | 聚合状态由事件重建 | 事件溯源聚合参考 |
+| TypeORM | ORM | Repository + cascade，无 UoW / Identity Map | 弱支持，不推荐 |
+| Prisma / Drizzle | 查询构建器 | 不支持聚合 | 需手工包 Repository |
+
+**建议**：运行时持久化参考/选用 **MikroORM**（聚合持久化设计最完整）；领域事件参考 **Remesh**。dsl 的 `AggregateSchema` 声明层本身无现成开源，属本项目的增量设计空间。
+
+## 5. 落地步骤（待办，未开工）
+
+1. `AggregateSchema` 类型 + `defineAggregate` + 定义期校验（root 必须在其表内、via 外键存在、成员表不能是其他聚合的 root 等）；
+2. `RepositorySchema` 类型 + `defineRepository`（或从 aggregate 自动推导生成）；
+3. `gen` 生成 Repository 代码：加载/保存/删除三套骨架 + 同事务包装（`@Trans()` 从声明推导）；
+4. `lint` 聚合边界检查：聚合外禁止直接改成员表、聚合间禁止跨表引用；
+5. 运行期库选型落地（MikroORM 或保持 DAO 同事务包装）。