@pylonts/dsl 1.1.19 → 1.1.21

package/dist/typebox-driver.js

@@ -1,4 +1,4 @@
-import { isDtoField, isDtoMessage } from './dto.js';
+import { isDtoField, isDtoMessage, resolveDtoRefChain } from './dto.js';
 import { collectEnumRefs } from './dsl.js';
 function renderString(s) {
     return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
@@ -16,20 +16,6 @@ function fieldDescription(field) {
 function dtoFieldDescription(f) {
     return f.description ?? fieldDescription(f.field);
 }
-/** Resolve a ref chain to its terminal field (the one without .ref).
- *  Cycles are a DSL definition error — fail loudly at render time. */
-function resolveRefChain(f) {
-    const seen = new Set();
-    let cur = f;
-    while (cur.ref !== undefined) {
-        if (seen.has(cur.ref)) {
-            throw new Error(`dto field ${cur.name}: circular ref chain (field references itself)`);
-        }
-        seen.add(cur.ref);
-        cur = cur.ref;
-    }
-    return cur;
-}
 function renderBasic(field, pattern, defaultValue, resolver, indent = 0, description) {
     if (pattern !== undefined && field.type !== 'string') {
         throw new Error(`pattern is only supported on string fields, got ${field.type} (${field.name})`);
@@ -176,7 +162,7 @@ function renderField(f, indent, resolver) {
  *  chain, inherit the terminal field's type/constraints, keep the referencing
  *  field's own overrides (pattern / default / description). */
 function renderRefBase(f, indent, resolver) {
-    const target = resolveRefChain(f);
+    const target = resolveDtoRefChain(f);
     const targetField = target.field;
     const pattern = f.pattern ?? target.pattern;
     const defaultValue = f.default ?? target.default;
@@ -187,7 +173,7 @@ function renderRefBase(f, indent, resolver) {
  *  override first, then the chain's DtoField-level optional, then the bare
  *  column optionality. */
 function renderRefField(f, indent, resolver) {
-    const target = resolveRefChain(f);
+    const target = resolveDtoRefChain(f);
     const optional = f.optional ?? target.optional ?? target.field.optional ?? false;
     const base = renderRefBase(f, indent, resolver);
     return optional ? `Type.Optional(${base})` : base;
@@ -225,7 +211,7 @@ function renderValue(f, indent, resolver) {
 }
 function collectEnumImports(f, resolver, out) {
     if (f.ref !== undefined) {
-        collectEnumImports(resolveRefChain(f), resolver, out);
+        collectEnumImports(resolveDtoRefChain(f), resolver, out);
         return;
     }
     if (f.field.type === 'array') {
@@ -270,14 +256,25 @@ export function collectDtoImports(schema, resolver, out) {
     for (const f of Object.values(schema.fields))
         collectEnumImports(f, resolver, out);
 }
+/** JSON Schema readOnly annotation on a rendered scalar schema: the token
+ *  owns the field, the client must not send it (the __inject adapter
+ *  overwrites any client-supplied value anyway). Injection fields are always
+ *  scalar columns (tables forbid nested columns), so the only object literal
+ *  in a rendered scalar base is its options block. */
+function withReadOnly(base) {
+    const idx = base.lastIndexOf('{');
+    if (idx === -1)
+        return base.replace(/\(\s*\)$/, '({ readOnly: true })');
+    return `${base.slice(0, idx + 1)} readOnly: true,${base.slice(idx + 1)}`;
+}
 /** Render the server-injection base: token-injected fields as Optional
- *  properties of a TypeBox object, plus a non-enumerable __inject adapter
- *  (same mechanism as hand-written bases, see pylon __inject docs) that fills
- *  each field from the token at runtime. */
+ *  readOnly properties of a TypeBox object, plus a non-enumerable __inject
+ *  adapter (same mechanism as hand-written bases, see pylon __inject docs)
+ *  that fills each field from the token at runtime. */
 function renderInjectBase(fields, resolver) {
     const entries = Object.entries(fields).map(([name, f]) => {
         const base = f.ref !== undefined ? renderRefBase(f, 1, resolver) : renderValue(f, 1, resolver);
-        return `  ${name}: Type.Optional(${base})`;
+        return `  ${name}: Type.Optional(${withReadOnly(base)})`;
     });
     const inner = `Type.Object({\n${entries.join(',\n')}\n})`;
     const assigns = Object.keys(fields)

package/dist/utils.d.ts

@@ -1,5 +1,6 @@
 import type { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
 import type { DtoField } from './dto.js';
+import type { ExceptionSchema } from './exception.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 /** A utility method with a full signature. */
 export interface UtilsMethodSchema extends SchemaBase {
@@ -10,8 +11,14 @@ export interface UtilsMethodSchema extends SchemaBase {
     args: Record<string, DtoField>;
     /** Output field — a plain inline Field (boolean for checks, decimal for
      *  computed amounts, ...). The method output is a fresh value, never a
-     *  shared table column. */
-    result: Field;
+     *  shared table column. Omit for void methods (pure actions). */
+    result?: Field;
+    /** Exceptions this method may throw — the failure contract of a defense
+     *  guard (assert/validate/ensure: void, throws internally). Flows route
+     *  invoked guards' throws into their escape set automatically, so a
+     *  guard's throws must be declared by the calling service method (or
+     *  caught in a TRY). Predicates (can/is/has, boolean) do not throw. */
+    throws?: ExceptionSchema[];
 }
 /** Method input for defineUtils: type/schema/name are set by the builder. */
 export type UtilsMethodDef = Omit<UtilsMethodSchema, 'type' | 'schema' | 'name'>;

package/dist/utils.js

@@ -1,3 +1,4 @@
+import { assertNoInlineContainers } from './dto.js';
 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}'`);
@@ -12,6 +13,9 @@ export function defineUtils(options) {
     };
     for (const key of Object.keys(options.methods)) {
         const method = options.methods[key];
+        // Same rule as DTO fields: args must not nest inline containers — use a
+        // DTO field reference (args: { items: SubmitRequest.fields.items }).
+        assertNoInlineContainers(options.name, method.args);
         const methodSchema = {
             type: 'utilsMethod',
             name: key,
@@ -19,14 +23,18 @@ export function defineUtils(options) {
             schema,
             args: method.args,
             result: method.result,
+            throws: method.throws,
         };
         // Args: write back on the DtoField wrapper only (safe: wrappers are
-        // created per method via dtoField(), never shared). Inline fields get
-        // their underlying Field written back too; fields wrapping table columns
-        // (domain rules) keep the shared column instance untouched — its
-        // name/schema already point to the table.
+        // created per method via dtoField(), never shared). Shared instances —
+        // DTO fields passed by reference (args: { items: OrderSubmitRequest.fields.items })
+        // and fields wrapping table columns (domain rules) — stay untouched: the
+        // DTO owns its field name/schema, the shared column instance keeps its
+        // table identity.
         for (const argKey of Object.keys(methodSchema.args)) {
             const df = methodSchema.args[argKey];
+            if (df.schema !== undefined)
+                continue;
             df.name = argKey;
             df.schema = schema;
             if (df.field.schema === undefined) {
@@ -34,9 +42,13 @@ export function defineUtils(options) {
                 df.field.schema = schema;
             }
         }
-        // Result: a plain inline Field — write name/schema back directly.
-        methodSchema.result.name = key;
-        methodSchema.result.schema = schema;
+        // Result (optional): a plain inline Field — write name/schema back only
+        // when it is unowned (schema === undefined); shared instances (table
+        // columns, fields already claimed by another container) stay untouched.
+        if (methodSchema.result !== undefined && methodSchema.result.schema === undefined) {
+            methodSchema.result.name = key;
+            methodSchema.result.schema = schema;
+        }
         schema.methods[key] = methodSchema;
     }
     return schema;

package/docs/aggregate-implementation.md

@@ -0,0 +1,174 @@
+# 聚合 DSL 极简落盘记录
+
+> 日期：本次会话
+> 范围：`@pylonts/dsl` 聚合声明层
+> 目标：让“多对一 / 一对多”先落地，扩展表（一对一）只设计不实现。
+
+## 1. 背景
+
+聚合判断标准已收敛为：
+
+> 创建 / 保存 / 删除时，是否必须一起做？
+> - 是 → 聚合成员
+> - 否 → 不聚合（引用）
+
+本次落盘只实现最常用的“一对多”聚合成员：
+
+```ts
+defineAggregate({
+  root: order,
+  members: {
+    items: [orderItem],
+  },
+});
+```
+
+- 数组成员 `[orderItem]` = 一对多；
+- 非数组成员（扩展表 / 一对一）暂不落代码，保留设计。
+
+## 2. 本次落盘改了什么
+
+### 2.1 源码
+
+| 文件 | 改动 |
+|---|---|
+| `dsl/src/aggregate.ts` | 极简化 `defineAggregate` |
+| `dsl/src/repository.ts` | 注释同步为 `FK / extends` |
+
+`dsl/src/aggregate.ts` 关键变化：
+
+- 去掉 `name` 必填，聚合名自动取 `root.name`；
+- `members` 类型简化为：
+
+```ts
+Record<string, TableSchema | TableSchema[]>
+```
+
+- 删除 `via` / `one` 复杂配置；
+- 数组成员校验：
+  - 必须恰好包含一张表；
+  - 该表必须有且仅有一个外键指向 root 主键；
+  - 多个外键指向 root 时明确报错；
+- 非数组成员（扩展表）暂不支持，明确报错。
+
+### 2.2 测试
+
+| 文件 | 改动 |
+|---|---|
+| `dsl/test/aggregate.test.ts` | 改为新极简 API，并增加“非数组成员暂不支持”测试 |
+| `dsl/test/repository.test.ts` | 改为新极简 API |
+
+### 2.3 文档
+
+| 文件 | 改动 |
+|---|---|
+| `dsl/docs/aggregate.md` | 示例去掉 `name`，成员表达改为数组/扩展表，同步扩展表规则 |
+| `dsl/docs/table.md` | 新增“扩展表（extends）”设计说明，标注暂不落代码 |
+| `dsl/docs/aggregate-implementation.md` | 本文档 |
+
+## 3. 当前 API 形态
+
+```ts
+import { defineAggregate } from '@pylonts/dsl';
+
+const orderAggregate = defineAggregate({
+  root: order,
+  members: {
+    items: [orderItem],
+  },
+});
+```
+
+约束：
+
+- `root` 必须有主键；
+- `members` 的数组元素必须是普通表；
+- 数组元素必须有外键指向 `root` 的主键；
+- 如果有多条外键指向 root，必须收敛为一条，否则无法自动推导。
+
+## 4. 如何验证
+
+在仓库根目录或 `dsl/` 目录执行。
+
+### 4.1 运行 DSL 测试
+
+```bash
+# 方式一：workspace
+npm test --workspace @pylonts/dsl
+
+# 方式二：进入 dsl 目录
+cd dsl
+npm test
+```
+
+可只跑聚合相关测试：
+
+```bash
+cd dsl
+npx vitest run test/aggregate.test.ts test/repository.test.ts
+```
+
+预期结果：
+
+- `aggregate.test.ts` 全部通过；
+- `repository.test.ts` 全部通过；
+- 新增的“非数组成员暂不支持”用例通过。
+
+### 4.2 类型检查
+
+```bash
+npm run typecheck --workspace @pylonts/dsl
+```
+
+或：
+
+```bash
+cd dsl
+npm run typecheck
+```
+
+预期结果：无 TypeScript 错误。
+
+### 4.3 构建
+
+```bash
+npm run build --workspace @pylonts/dsl
+```
+
+或：
+
+```bash
+cd dsl
+npm run build
+```
+
+预期结果：`dist/` 正常生成。
+
+### 4.4 全量回归（如项目要求）
+
+在仓库根按项目现有脚本执行：
+
+```bash
+npm run lint all
+npm run typecheck
+```
+
+或按仓库实际脚本执行 `api tsc + lint all`。
+
+## 5. 验证重点
+
+1. 新的极简 `defineAggregate` 能正常声明聚合；
+2. 不再需要传 `name`；
+3. `members.items` 直接是 `[orderItem]`，不再有 `via` / `one`；
+4. 没有外键指向 root 时会报错；
+5. 非数组成员会报“扩展表未实现”；
+6. 旧测试已全部迁移到新 API。
+
+## 6. 暂未实现（保留设计）
+
+- 扩展表 `extends: root`：一对一成员；
+- 非数组成员：当前会抛错；
+- Repository 生成器：仍未实现；
+- flow 调用 repository：仍未实现。
+
+这些内容在 `dsl/docs/aggregate.md` 和 `dsl/docs/table.md` 中保留设计。

package/docs/aggregate.md

@@ -24,17 +24,54 @@
 | 应用服务编排 | service_schema + flow ✅ | 已具备 |
 | 防腐层 | ThirdServiceSchema 只隔离 | 缺模型映射 |
 
-## 2. 扩展一：AggregateSchema（核心）
+## 2. 什么情况下需要聚合？
+
+**核心判断标准**：
+
+> 创建 / 保存 / 删除时，是否必须一起做？
+> - 是 → 聚合（成员）
+> - 否 → 不聚合（引用）
+
+### 2.1 成员 vs 引用
+
+| 维度 | 聚合成员 | 聚合间引用 |
+|------|---------|-----------|
+| 生命周期 | 与根同生共死 | 独立生命周期 |
+| 创建 | 随根一起创建 | 不随根创建 |
+| 保存 | 随根一起保存 | 不随根保存 |
+| 删除 | 随根级联删除 | 不随根删除 |
+| 关联 | 成员表 FK 指向根 / 扩展表 extends 根 | 本表 FK 指向其他聚合根 |
+| 示例 | order_item / order_address 快照 | order.user_id / order.address_id |
+
+### 2.2 案例：地址可复用 vs 地址快照
+
+**场景**：一个订单对应一个地址，但地址可以被多个订单复用。
+
+- 如果地址可复用 → 不是聚合成员，是引用：
+  - 创建订单不会创建地址；
+  - 删除订单不会删除地址；
+  - 多个订单可以指向同一个地址；
+  - 建模为 `references: { address: 'AddressAggregate' }`，外键不需要 unique。
+
+- 如果地址是下单时的快照（copy）→ 是聚合成员：
+  - 下单时复制一份地址到订单；
+  - 之后修改地址簿不影响已下单订单；
+  - 删除订单时该快照一起删除；
+  - 建模为 `members: { address: orderAddress }`；
+  - 此时 `orderAddress` 应为**扩展表**（`extends: order`），主键与根主键同义、类型一致，天然保证一对一。
+
+**lint 规则**：声明为一对一成员时，成员表必须是扩展表（`extends` 指向根），主键与根主键同义且类型一致；否则它要么是一对多，要么应改为 references。
+
+## 3. 扩展一：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
+  members: {                                // 成员表：数组=一对多，非数组=一对一
+    items:   [orderItemsTable],             // 1:N，外键自动推导
+    address: orderAddressTable,             // 1:1，扩展表
   },
   invariants: [                             // 跨成员表不变式，挂聚合上，可被生成代码消费
     { name: 'total = sum(items.price * items.qty)',
@@ -47,8 +84,8 @@ defineAggregate({
 | 声明项 | 含义 | 缺了会怎样 |
 |--------|------|-----------|
 | `root` | 谁是聚合根 | 分不清一致性入口 |
-| `members` | 包含哪几个 table schema | "包含"只是列表，无结构 |
-| `members[i].via` | 成员表靠哪个外键挂根 | 工具无法推导 join / 级联关系 |
+| `members` | 包含哪几个 table schema；数组=普通表=1:N，非数组=扩展表=1:1 | 无法推导成员关系 |
+| 成员外键 | 由 TableSchema.foreignKeys / extends 自动推导 | 工具无法推导 join / 级联关系 |
 | `invariants` | 跨成员一致性规则 | "总额=Σ明细"又回到 flow 里手工写 |
 | `references` | 聚合间只按 ID 引用 | 无法 lint 跨聚合直接持表引用 |
 
@@ -60,7 +97,7 @@ defineAggregate({
 
 **多表映射三种模式**（聚合↔表）：A 单表=单聚合（1:1，几乎透明）；B 一聚合=多表（1:N，最常见，Order 案例）；C 多聚合共享表（N:1，DDD 不推荐）。
 
-## 3. 扩展二：RepositorySchema（可推导，也可显式声明）
+## 4. 扩展二：RepositorySchema（可推导，也可显式声明）
 
 **作用**：聚合粒度的存储入口，把"哪些表一起查、怎么拼成聚合"的知识从 service flow 下沉到仓储。调用方只面对领域概念（Order），不面对表。
 
@@ -76,7 +113,7 @@ defineRepository({
 
 **聚合内 join 下沉、聚合间禁止 join**：
 
-- 聚合内：加载整个 Order（根 + 明细 + 地址）由 Repository 内部完成，调用方一行，join 知识声明在 `members[].via`；
+- 聚合内：加载整个 Order（根 + 明细 + 地址）由 Repository 内部完成，调用方一行，join 知识由成员表 `foreignKeys` / `extends` 自动推导；
 - 聚合间：只按 ID 引用，跨聚合 join 是 DDD 禁止的；展示商品名这类信息走读模型 / 查询服务（CQRS 的 Q 侧），或应用服务分步查 + 内存组装。
 
 **分层对照**：
@@ -87,7 +124,7 @@ defineRepository({
 | Repository | **聚合** | orders + order_items 一个事务 | **本扩展** |
 | DAO | **表** | 单表一条 SQL | dao_schema ✅ |
 
-## 4. 扩展三：引入支持 DDD 的 TS 库（选型，待决策）
+## 5. 扩展三：引入支持 DDD 的 TS 库（选型，待决策）
 
 dsl 是**声明期**（`defineAggregate` 声明结构），引入的库是**运行期**（代码跑起来时持久化/发事件）。两者互补，不冲突——声明可翻译为运行期库的配置。
 
@@ -101,9 +138,9 @@ dsl 是**声明期**（`defineAggregate` 声明结构），引入的库是**运
 
 **建议**：运行时持久化参考/选用 **MikroORM**（聚合持久化设计最完整）；领域事件参考 **Remesh**。dsl 的 `AggregateSchema` 声明层本身无现成开源，属本项目的增量设计空间。
 
-## 5. 落地步骤（待办，未开工）
+## 6. 落地步骤（待办，未开工）
 
-1. `AggregateSchema` 类型 + `defineAggregate` + 定义期校验（root 必须在其表内、via 外键存在、成员表不能是其他聚合的 root 等）；
+1. `AggregateSchema` 类型 + `defineAggregate` + 定义期校验（root 必须在其表内、成员表必须有外键指向 root 或 extends root、成员表不能是其他聚合的 root 等）；
 2. `RepositorySchema` 类型 + `defineRepository`（或从 aggregate 自动推导生成）；
 3. `gen` 生成 Repository 代码：加载/保存/删除三套骨架 + 同事务包装（`@Trans()` 从声明推导）；
 4. `lint` 聚合边界检查：聚合外禁止直接改成员表、聚合间禁止跨表引用；

package/docs/dto.md

@@ -1,74 +1,131 @@
-# 定义 DTO（四种方向）
-
-DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
-
-| 构建器 | 方向 | 可选性规则 |
-|---|---|---|
-| `buildInput` | input | 按 DB 列规则：主键 → 必填；可空（未写 `optional` 或 `optional: true`）/ 有默认 → 可选；`optional: false` 无默认 → 必填 |
-| `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
-| `buildQuery` | query | 全部可选 |
-| `buildPk` | pk | 主键字段必填，其他字段可选 |
-
-## 从字段集合投影
-
-`from(source, fields)` 接受两类字段集合源：**表**（`TableSchema`）或**第三方方法消息**（`ThirdMethodSchema`，见 [third-service.md](./third-service.md)），投影字段包装为 DTO 字段，字段实例与源共享，`name/schema` 保持指向源。
-
-```ts
-import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
-
-// 输入：新增订单
-buildInput('OrderAddRequest', { ...from(order, [order.columns.mer_id, order.columns.amount]) });
-
-// 输出：订单行
-buildOutput('OrderRow', from(order, [order.columns.id, order.columns.order_no]));
-
-// 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
-buildQuery('OrderPageQuery', {
-  keyword: dtoField(stringField({ maxLength: 32 })).setOperator('like'),
-  ...from(order, [order.columns.mer_id]),
-});
-
-// 主键：按 id 取详情
-buildPk('OrderDetailRequest', from(order, [order.columns.id]));
-
-// 转发：透传第三方方法消息（wire-format 字段名保持协议原样，不转 camelCase）
-buildOutput('BalanceResult', from(queryBalance.results, [queryBalance.results.fields.balance]));
-```
-
-- **表源**：DTO 字段名转 camelCase（`mer_id` → `merId`），与 DB 列名（snake_case）分离。
-- **第三方方法源**：字段名即线格式协议名（`out_trade_no`、`appId`），保持不变。
-- `from()` 本身不做任何可选性推断——推断在各方向工厂，且按字段的 schema 判断：共享实体列按列规则推断（Rule A），wire 自有字段保留声明值。
-
-## 独立字段
-
-不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`、`default`。
-
-```ts
-dtoField(stringField({ maxLength: 32 })).setOperator('like')
-dtoField(intField()).setDefault(0)        // TypeBox default 注解
-```
-
-## 默认值
-
-- `setDefault(v)` 设 DTO 层默认值，渲染为 TypeBox `default:` 注解（`Type.String({ default: 'PENDING' })`、`Type.Enum(OrderStatus, { default: OrderStatus.PENDING })`）。
-- 枚举默认值必须是该枚举的成员值（value），渲染时解析为成员引用；非成员值直接报错。
-- 未显式设置时，fallback 到字段构建器的 `default`（DB 默认值，string），`from()` 提取的字段自动带出。
-
-## 继承基础 schema
-
-```ts
-buildQuery('OrderPageQuery', { ... })
-  .include({ from: '@pylonts/core', name: 'PageRequest' });   // 渲染 Type.Intersect([PageRequest, ...])
-```
-
-## 关键语义
-
-- **字段两层名**：`DtoField.name` 是接口字段名（DTO map key 反写）；`field.name` 是数据库列名（表反写）。
-- **可选性优先级**：DTO 层 `optional` 优先于字段层；query 方向所有字段强制可选。
-- **HTTP 传 string**：bigint / decimal / date / time 在接口层渲染为 `Type.String()`，保证精度与序列化语义。
-
-## 文件组织
-
-- `dto_schema/{module}/*.dto.ts`：DTO 源文件，一个文件可导出多个 DtoMessage；`module` = `project.config.ts` 的 `apps.name`，另加 `common/` 放跨 app 共享 DTO。
-- `pylonts gen dto` 按 module 逐个扫描：`dto_schema/{module}/*.dto.ts` → 生成 `dto/{module}/{Name}.dto.ts`。
+# 定义 DTO（四种方向）
+
+DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
+
+| 构建器 | 方向 | 可选性规则 |
+|---|---|---|
+| `buildInput` | input | 按 DB 列规则：主键 → 必填；可空（未写 `optional` 或 `optional: true`）/ 有默认 → 可选；`optional: false` 无默认 → 必填 |
+| `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
+| `buildQuery` | query | 全部可选 |
+| `buildPk` | pk | 主键字段必填，其他字段可选 |
+
+## 从字段集合投影
+
+`from(source, fields)` 接受两类字段集合源：**表**（`TableSchema`）或**第三方方法消息**（`ThirdMethodSchema`，见 [third-service.md](./third-service.md)），投影字段包装为 DTO 字段，字段实例与源共享，`name/schema` 保持指向源。
+
+```ts
+import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
+
+// 输入：新增订单
+buildInput('OrderAddRequest', { ...from(order, [order.columns.mer_id, order.columns.amount]) });
+
+// 输出：订单行
+buildOutput('OrderRow', from(order, [order.columns.id, order.columns.order_no]));
+
+// 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
+buildQuery('OrderPageQuery', {
+  keyword: dtoField(stringField({ maxLength: 32 })).setOperator('like'),
+  ...from(order, [order.columns.mer_id]),
+});
+
+// 主键：按 id 取详情
+buildPk('OrderDetailRequest', from(order, [order.columns.id]));
+
+// 转发：透传第三方方法消息（wire-format 字段名保持协议原样，不转 camelCase）
+buildOutput('BalanceResult', from(queryBalance.results, [queryBalance.results.fields.balance]));
+```
+
+- **表源**：DTO 字段名转 camelCase（`mer_id` → `merId`），与 DB 列名（snake_case）分离。
+- **第三方方法源**：字段名即线格式协议名（`out_trade_no`、`appId`），保持不变。
+- `from()` 本身不做任何可选性推断——推断在各方向工厂，且按字段的 schema 判断：共享实体列按列规则推断（Rule A），wire 自有字段保留声明值。
+
+## 独立字段
+
+不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`、`default`。
+
+```ts
+dtoField(stringField({ maxLength: 32 })).setOperator('like')
+dtoField(intField()).setDefault(0)        // TypeBox default 注解
+```
+
+## 容器字段：禁止内联嵌套（构建期校验）
+
+**DTO 不内联**——嵌套结构必须命名引用，构建期（`buildInput/buildOutput/buildQuery/buildPk` 及 `defineUtils` args）机器校验：
+
+| 形态 | 允许 | 禁止 |
+|---|---|---|
+| 数组字段 `dtoArrayField` | `items: 命名 DTO`（`items: orderItemDto` → `OrderItemDto[]`）或 `items: 标量字段`（`string[]`） | `items: dtoObjectField(...)` 内联对象元素、`items: dtoArrayField(...)` 内联数组元素 |
+| 对象字段 | 裸 `objectField(...)`（wire 格式嵌套，渲染内联 `Type.Object({...})`） | `dtoObjectField(...)`、`dtoField(dtoObjectField(...))`——DtoField 类容器必须命名引用（数组元素），或改用裸 `objectField` |
+
+**理由**：DtoField 类容器（`dtoObjectField` / `dtoArrayField`）内联时无法跨 DTO 复用，生成类型要么靠字符串拼接（`Array<{...}>`），要么塌缩（`any[]`）——命名引用让结构有单一事实来源（DTO 定义处）且生成精确类型。裸 `objectField` / `arrayField` 属于 wire 格式嵌套（随消息直接内联渲染），不在禁用范围。校验错误示例：
+
+```
+[dto] "OrderSubmitRequest" field "items": inline container elements are not allowed — array items must be a named DTO or a scalar field
+```
+
+```ts
+// ✗ 内联对象元素
+items: dtoArrayField({ items: dtoObjectField({ properties: { skuId: ..., qty: ... } }) })
+
+// ✓ 命名 DTO 引用（OrderItemDto 单独 buildOutput 声明）
+export const OrderItemDto = buildOutput('OrderItemDto', { skuId: ..., qty: ... });
+items: dtoArrayField({ items: OrderItemDto })
+```
+
+## 字段引用规格（Reference Spec）
+
+`DtoField` 通过 `setRef(other)` 或共享字段实例引用其他字段，表达"本字段来源于 X"。**引用不是任意的**——只有业务契约 DTO（controller/service 消费的 `dto_schema/{app}` 或 `dto_schema/common` DTO）的字段可以作为引用方，且只能引用三类被引用方：
+
+| # | 引用 | 语法 | 语义 |
+|---|---|---|---|
+| 1 | **field 引用** | `dtoField(table.columns.x)`（共享实例）或 `setRef` 指向包装表列的 DtoField | 与数据库字段同义（来源：库） |
+| 2 | **token 引用** | `fromToken(token, [...])` 或 `setRef(token 字段)` | 字段来源于登录身份（服务端注入） |
+| 3 | **third 引用** | `setRef(third 消息字段)` | 字段来源于第三方消息（参数或结果） |
+
+**方向约束**：
+
+- 引用方：业务契约 DTO 的字段；
+- 被引用方：token 字段 / third 消息字段 / 表列 field——**业务 DTO 之间不能互相引用**（convert 的 sources/target 各自独立，映射由搬运生成推导，不靠 DTO 互 ref）；
+- third 字段、token 字段不可反向引用业务 DTO；
+- ref 链无环（渲染期强校验，循环引用报错）。
+
+**对 convert 自动搬运的意义**：同源判定 = ref 链终端 / 共享 field 实例，且只有规格内合法引用构成可推导搬运——业务 DTO ← third（防腐翻译，`setRef(thirdField)` = "本字段从 third 参数/结果来"）、业务 DTO ← entity（共享表列实例）都是可自动生成搬运的映射；越界引用是声明错误。
+
+> entity 列是裸 `Field` 实例：DTO 字段 `dtoField(order.columns.x)` 与 entity 列共享同一实例即构成 field 引用。
+
+### token 引用的注入与 readOnly
+
+`fromToken(token, fields)` 是 token 引用的标准入口：每个投影字段 `setRef(token 字段)`（复用类型/约束）+ 标记 `injectFrom`（服务端注入）。typebox 生成物中注入字段渲染为 **`Type.Optional(...)` + `readOnly: true` 注解**（JSON Schema annotation）——服务器字段，客户端不得上送：
+
+```ts
+id: Type.Optional(Type.Integer({ readOnly: true })),
+```
+
+同时生成非枚举 `__inject` 适配器，fastify RPC 层在进 controller 前执行 `body.k = token.k` 从登录身份填充——**客户端即使上送也会被覆盖**（上送无效）。三层闭环：声明 readOnly（不可上送语义）+ Optional（可不传）+ 运行时覆盖（上送无效）。
+
+注意：**只有 `fromToken()` 自动设置 `injectFrom`**；手写 `setRef(token 字段)` 只表达引用关系，不触发注入渲染（如需注入须显式标记或改走 fromToken）。
+
+## 默认值
+
+- `setDefault(v)` 设 DTO 层默认值，渲染为 TypeBox `default:` 注解（`Type.String({ default: 'PENDING' })`、`Type.Enum(OrderStatus, { default: OrderStatus.PENDING })`）。
+- 枚举默认值必须是该枚举的成员值（value），渲染时解析为成员引用；非成员值直接报错。
+- 未显式设置时，fallback 到字段构建器的 `default`（DB 默认值，string），`from()` 提取的字段自动带出。
+
+## 继承基础 schema
+
+```ts
+buildQuery('OrderPageQuery', { ... })
+  .include({ from: '@pylonts/core', name: 'PageRequest' });   // 渲染 Type.Intersect([PageRequest, ...])
+```
+
+## 关键语义
+
+- **字段两层名**：`DtoField.name` 是接口字段名（DTO map key 反写）；`field.name` 是数据库列名（表反写）。
+- **可选性优先级**：DTO 层 `optional` 优先于字段层；query 方向所有字段强制可选。
+- **HTTP 传 string**：bigint / decimal / date / time 在接口层渲染为 `Type.String()`，保证精度与序列化语义。
+
+## 文件组织
+
+- `dto_schema/{module}/*.dto.ts`：DTO 源文件，一个文件可导出多个 DtoMessage；`module` = `project.config.ts` 的 `apps.name`，另加 `common/` 放跨 app 共享 DTO。
+- `pylonts gen dto` 按 module 逐个扫描：`dto_schema/{module}/*.dto.ts` → 生成 `dto/{module}/{Name}.dto.ts`。
 - 枚举字段引用 `enums/` 下生成的枚举源文件，DTO 文件通过 `../../enums/{JsName}.enum` 导入。