@pylonts/dsl 1.1.6 → 1.1.11

package/docs/ddd-principles.md

@@ -0,0 +1,75 @@
+# DDD 落地原则（DDD Principles）
+
+> 状态：**已决策**
+> 背景：ts-libs 会话「dd DDD 扩展讨论」；姊妹篇：[aggregate.md](./aggregate.md)（聚合/仓储规划）、[domain-event.md](./domain-event.md)（领域事件规划）
+
+## 1. 决策摘要
+
+1. **不纠结实体胖瘦**——胖瘦是结果，复用是判据；
+2. **领域对象全部是 plain POJO**——纯数据、无行为（贫血模型，但规则不散落）；
+3. **不纠结代码写在哪里**——`order.cancel()` 与 `service.cancel(order)` 没有实质区别；
+4. **规则归属只有两条路**：
+   - **不需要调用外部**（纯函数、单值校验）→ **utils 谓词**（已落地）；
+   - **需要做流程**（编排、跨步骤、跨聚合）→ **service 方法**（已支持）。
+
+**推论**：DDD 落地**不需要新增"实体方法"概念**——现有 `service_schema + flow` 已是规则复用归属地，`AggregateSchema` / 领域事件仍按各自规划做。
+
+## 2. 为什么这样定
+
+### 2.1 胖瘦是假问题，复用才是本质
+
+```
+一个规则 → 被几处用？
+  被 1 处用  → 留在 flow 里，不为理论正确而挪
+  被 ≥2 处用 → 提取到归属地（utils / service），一处维护
+```
+
+"取消"进归属地，不是因为实体该胖，而是因为用户取消、超时自动取消、客服取消三个流程复用同一套取消规则。没有复用，留在 flow 完全合理。
+
+### 2.2 归属地之争是假问题
+
+```
+order.cancel()              service.cancel(order)
+─── ──────────              ─── ──────────────────
+规则住在 Order 对象          规则住在 Service 对象
+flow: invoke(order.cancel)  flow: invoke(service.cancel, order)
+```
+
+两者都是"规则提取 + 复用"，无实质区别。**分水岭不在 order.cancel vs service.cancel，在"有没有 cancel 这个提取物"**——有就是规则内聚，没有就是散落。
+
+### 2.3 复用 ≠ 抽象
+
+- 抽象/预测（坏）："未来可能用到，先抽出来" → 过度设计；
+- 复用/实际（好）："现在被三个流程用到，提取" → 唯一正确触发条件。
+
+遵循"三行相似胜过过早抽象"——用到了才内聚，不预测。
+
+### 2.4 主观标准不可执行（最硬的理由）
+
+**胖瘦标准无法统一**：什么样的实体算"胖"、算"瘦"，每个人判断都不同——有的人觉得状态机进实体是对的，有的人觉得一个方法就算胖。没有客观刻度，团队协作时必然争论，代码评审无法给出确定性结论。
+
+```
+实体胖瘦 = 主观判断 → 无法统一标准 → 不可执行、不可 lint
+复用归属 = 客观判据 → 标准统一可执行 → 机器可校验
+
+POJO + utils/service 归属的每个判断都是确定性的：
+  调不调用外部？→ 是纯函数还是流程？→ 归 utils 还是 service
+```
+
+这符合 pylon 的 DSL 哲学：**声明式、机器校验**（lint 是权威事实来源）。"这条规则该放哪"必须能由一个确定的判据回答，而不是靠某个人对"胖瘦"的品味。**规则归属是"放 utils 还是 service"的二分，机器可判；实体胖瘦是"放多少进实体"的连续光谱，人各执一词。** 选二分、弃光谱。
+
+## 3. 规则归属决策表
+
+| 场景 | 归属 | 现状 |
+|------|------|------|
+| 纯函数/单值校验（如金额两位小数） | utils 谓词 | ✅ 已落地（BLE：AmtUtils 等） |
+| 跨步骤业务流程（下单、取消） | service 方法 + flow | ✅ 已支持 |
+| 跨聚合协作规则（定价、扣库存） | service 方法（领域服务角色） | ✅ 已支持 |
+| 状态机规则（取消校验 + 流转） | service 方法 | ✅ 已支持 |
+| 实体方法（order.cancel） | **不采用**（与 service 等价，选零成本） | 不需要 |
+
+## 4. 对扩展规划的影响
+
+- **聚合/仓储（aggregate.md）**：照做——解决多表一致性，不引入实体行为；
+- **领域事件（domain-event.md）**：照做——`publish` 由 service（flow）发起，与"规则归属 service"一致；
+- **实体方法/defineEntity**：**不立项**——`service.cancel(order)` 已覆盖，避免为一个无实质区别的语法糖增加 DSL 面。

package/docs/domain-event.md

@@ -0,0 +1,137 @@
+# 领域事件 DSL 扩展规划（Domain Event）
+
+> 状态：**部分落地（步骤 1 声明层 ✅ / 步骤 3 @Trans afterCommit ✅ / 步骤 4 outbox DDL ✅ / 发布 API ✅，其余待实现）**
+> 关联代码：`dsl/src/event.ts`（UI 事件，非领域事件）、`dsl/src/flow.ts`（flow IR）、`pylon-dao/src/trans.ts`（`@Trans()`）
+> 背景对话：ts-libs 会话「dd DDD 扩展讨论」；姊妹篇：[aggregate.md](./aggregate.md)（聚合/仓储规划）
+
+## 1. 背景：pylon 事件基础设施现状
+
+- 整个 pylon 体系目前**零事件基础设施**：flow.ts 无 event，仓库无 publish/subscribe/EventEmitter；
+- `dsl/src/event.ts` 是 **UI 组件事件**（Tab onChange 的 `e.detail`），与领域事件完全无关；
+- flow 只有 `invoke`（调用方法）/ `write`（写槽）/ `THROW` / `RETURN`，**没有"发布事件"动作，也没有事件声明**。
+
+**命令 vs 事件**（必须分清）：
+
+| | Command（命令） | Event（事件） |
+|---|---|---|
+| 语义 | "去做某事"（意图） | "某事已经发生"（事实） |
+| 时态 | 未来/祈使 | 过去/陈述 |
+| 命名 | `PlaceOrder`、`CancelOrder` | `OrderPlaced`、`OrderCancelled` |
+| 接收方 | 有且一个（命令处理器） | 零到多个订阅者 |
+| 失败处理 | 调用方要感知失败 | 发布方不关心谁处理 |
+| dsl 对应 | flow 的 `invoke(m)` | **新概念** |
+
+**事件驱动的解耦价值**：命令式让 flow 依赖所有下游（扣库存、发短信、加积分都要在 flow 里 invoke）；事件式让 flow 只依赖"事实"（事件名 + 数据），下游变化不影响 flow。
+
+## 2. 事件生命周期（五步）
+
+```
+① 发生：Order.cancel() 状态 CREATED → CANCELLED
+② 收集：聚合根在内存记录"我取消了"
+③ 发布：事务提交成功后投递 OrderCancelled
+④ 订阅：库存上下文、通知服务各自注册监听
+⑤ 处理：各订阅者做自己的事（扣库存、发短信）
+```
+
+关键在 ②→③ 的**发布时机**，决定一致性。
+
+## 3. 发布时机：三种策略
+
+| 策略 | 做法 | 问题 |
+|------|------|------|
+| A. 事务内发 | tx { 改状态; 发事件; } | 订阅者失败回滚主事务；跨服务时事务管不到对方 |
+| B. 事务后发 | tx { 改状态; } → 发事件 | 发的时候进程崩了 → 事件丢失，状态改了没人知道 |
+| **C. Transactional Outbox（生产标准）** | tx { 改状态; INSERT outbox; } → 后台 relay 投递 | **保证：状态和事件要么都成要么都败，事件最终必达** |
+
+**pylon 现状对照**：knex 透明代理 + `@Trans()` 让"更新状态 + 写 outbox 表"同事务天然可行（都是 DAO 调用），outbox 在 pylon 技术上现成，缺的是声明层。
+
+## 4. dsl 扩展方向：三件新东西
+
+```ts
+// ① 事件声明（一等 schema，携带数据快照）
+defineDomainEvent({
+  name: 'OrderCancelled',
+  fields: { orderNo: str, reason: str },   // 快照，不是引用
+});
+
+// ② flow 里加 publish action（编译成同事务写 outbox 表）
+flowScript('cancelOrder', { args, slots }, ({ next, slots }) => {
+  next(
+    invoke(orderService.load, { id: slots.orderId }, 'order'),
+    invoke(order.cancel),                                    // 状态流转
+    publish('OrderCancelled', { orderNo: slots.order.orderNo, reason: 'user' }),  // 新动作
+  );
+  return flowEnd.ok;
+});
+
+// ③ 订阅声明（复用 flow 编排处理逻辑）
+defineEventHandler({
+  name: 'onOrderCancelled',
+  event: 'OrderCancelled',
+  flow: handleOrderCancelledFlow,   // 处理流程复用现有 flow 模型
+});
+```
+
+- 发布是**声明不是副作用**：`publish(...)` 在 flow 里显式可见，审查时一眼看到"此流程发什么事件"；
+- 不用引入消息队列：outbox 表 + 后台 relay 即够（BLE 案例规模不需要 RabbitMQ）；
+- 订阅：启动时扫描 handler 注册到总线 / 消费组。
+
+## 5. 发布技术选型（结论）
+
+**发布侧：已定死 —— MySQL outbox 表**（与业务同事务，knex 现成）：
+
+```sql
+CREATE TABLE event_outbox (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+  event_name VARCHAR(100) NOT NULL,      -- 'OrderCancelled'
+  payload JSON NOT NULL,                 -- 事件数据快照
+  status ENUM('pending','delivered') DEFAULT 'pending',
+  created_at DATETIME DEFAULT NOW()
+);
+```
+
+**投递侧：按部署形态分档**：
+
+| 方案 | 传输介质 | 延迟 | 依赖 | 适用 |
+|------|---------|------|------|------|
+| **A. 进程内总线** | Node 内存（EventEmitter） | 0 | 无 | **单进程（pylon 默认）** |
+| **B. MySQL 轮询 relay** | 扫 outbox 表 | ~轮询间隔 | 无（现成） | 单进程但要持久化兜底 |
+| **C. Redis Stream** | Redis | 毫秒 | ioredis（sign-redis-driver 已有） | 多进程/多服务 |
+| **D. 消息队列** | RabbitMQ / Kafka | 毫秒 | 重型中间件 | 生产大规模，超出 pylon 定位 |
+
+**推荐路径**：
+
+- **单进程（pylon 默认，先做）**：A + B 结合，零新依赖——事务提交后（afterCommit）进程内直接分发（延迟 0），outbox 兜底补投失败/崩溃遗留的 pending 记录（不丢事件）。`@Trans()` 加 afterCommit 钩子即可：
+
+  ```ts
+  // trans.ts 扩展：事务提交成功后执行注册的回调
+  export function Trans() {
+    return function (target, key, descriptor) {
+      const original = descriptor.value;
+      descriptor.value = async function (...args) {
+        return knex.transaction(async (trx) => {
+          const afterCommits: Array<() => Promise<void>> = [];
+          return txStorage.run(trx, async () => {
+            const result = await original.apply(this, args);
+            await trx.executionPromise;                 // 等事务真正提交
+            await Promise.all(afterCommits.map(fn => fn()));
+            return result;
+          });
+        });
+      };
+    };
+  }
+  ```
+
+- **多进程/多服务（未来升级）**：方案 C Redis Stream——pylon 已有 ioredis（sign-redis-driver），Redis 不算新基建；outbox relay 从进程内分发换成 `XADD`，订阅服务 `XREADGROUP` 消费。
+- **方案 D 不做**：超出 pylon"薄封装、快速开发"定位。
+
+**订阅侧**：`defineEventHandler` 声明 + 启动扫描注册；复用 flow 编排处理逻辑，不需要新执行模型。
+
+## 6. 落地步骤（待办，未开工）
+
+1. `DomainEventSchema` 类型 + `defineDomainEvent` + 定义期校验（字段类型、事件名唯一）✅；
+2. flow 加 `publish` action：编译成"同事务插 outbox 表"的 DAO 调用 + afterCommit 回调注册；
+3. `@Trans()` 扩展 afterCommit 钩子（`pylon-dao/src/trans.ts`）✅；4. `event_outbox` 表：DDL 由 gen 生成（`defineDomainEvent` 自动建表）✅（独立包 `@pylonts/event` 已含发布 API：`publishEvent` + `@EventNotifier`，outbox DDL 由 `gen-outbox.ts` + `pylonts gen sql init` 追加）；
+5. relay：单进程（进程内分发 + 启动/定时补投）→ 跨进程（Redis Stream）；
+6. `defineEventHandler` + 启动扫描注册订阅者。

package/docs/keyword-matcher.md

@@ -0,0 +1,182 @@
+# Keyword 智能匹配扩展规划（Keyword Matcher）
+
+> 状态：**规划中（未实现）**
+> 关联代码：`dsl/src/filter.ts`（FilterSchema.keyword）、`gen/src/filter-render.ts`（keyword OR-like 渲染）、`curd/src/service.ts`（keyword query 端点）
+> 背景：curd 搜索框输一个值，需要判断它"像什么"（手机号 / 订单号 / 商户号），再决定精确查询哪一列；不像任何已知形状才回退模糊匹配。
+
+## 1. 背景：问题与现状
+
+**问题**：管理页搜索框只有一个 keyword 输入，业务上常见输入是"可直接定位到一行的值"：
+
+| 用户输入 | 业务含义 | 期望查询 |
+|---------|---------|---------|
+| `13800138000` | 手机号（11 位，1 开头） | `user.phone = '13800138000'`（精确） |
+| `ORD17230000001234` | 订单号（ORD 前缀） | `order.order_no = ...`（精确） |
+| `M17230001234` | 商户号（M 前缀） | `merchant.mer_no = ...`（精确） |
+| `张三` | 人名 | 名称列 LIKE（模糊） |
+
+**现状**：`FilterSchema.keyword = { columns: Field[] }` 只有一种行为——对声明列 OR 拼接 `LIKE %kw%`：
+
+```ts
+// 现状声明（filter_schema/examples-api/admin/filter/user-list.filter.ts）
+keyword: { columns: [user.columns.username] },
+```
+
+```ts
+// 现状产物（api/src/modules/admin/filter/UserListFilter.ts）
+if (args.keyword) {
+  q.where(function (this: QueryBuilder) {
+    this.where('user.username', 'like', `%${args.keyword}%`);
+  });
+}
+```
+
+手机号按 LIKE 查 `username` 永远查不到（username 是昵称），用户输入"138..."期望按手机号定位用户却得到空结果——**输入形状与查询列不匹配**。
+
+**形状知识现状**：`@pylonts/mock` 的生成器已经持有形状约定（生成侧），识别侧没有：
+
+| 生成器 | 形状 | 位置 |
+|--------|------|------|
+| `mockPhone` | 11 位，运营商前缀段（134/135/... 白名单） | `pylon-mock/src/generators/phone.ts` |
+| `mockMerchantId` | `M` + 8 位时间戳 + 2 位随机 | `pylon-mock/src/generators/id.ts` |
+| `mockOrderId` | `ORD` + 时间戳 + 2 位随机 | `pylon-mock/src/generators/id.ts` |
+| 身份证 / 银行卡 | 生成规则已存在 | `pylon-mock/src/generators/identity.ts`、`data/bankcard.json` |
+
+生成与识别是同一形状的两面，识别器应从同一形状知识推导，而不是在 filter 声明里再写一遍。
+
+## 2. 方案：keyword.rules 形状规则
+
+`FilterSchema.keyword` 扩展 `rules`，声明"keyword 像什么时精确查哪一列"：
+
+```ts
+keyword: {
+  columns: [user.columns.username],           // fallback：仍按模糊 OR-like
+  rules: [
+    { field: user.columns.phone, when: 'phone' },              // 内置语义名
+    { field: order.columns.order_no, when: /^ORD\d+$/ },       // 项目自定义正则
+  ],
+},
+```
+
+```ts
+// dsl/src/filter.ts 类型扩展
+export interface KeywordRule {
+  /** 命中后精确查询的列。 */
+  field: Field;
+  /** 形状判定：内置语义名（字符串）或项目正则（RegExp 字面量）。 */
+  when: string | RegExp;
+}
+
+export interface FilterSchema {
+  // ...
+  keyword?: {
+    columns: Field[];
+    /** 形状规则，按声明顺序判定，首个命中短路（可选）。 */
+    rules?: KeywordRule[];
+  };
+}
+```
+
+**判定语义**：
+
+1. `keyword` 为空 → 整个 keyword 块跳过（现状不变）；
+2. 遍历 `rules`（**声明顺序即判定顺序**，确定性）：
+   - `when` 是字符串 → 查内置语义 matcher 表，命中则 `where(field, '=', kw)` 并**短路**；
+   - `when` 是 RegExp → `pattern.test(kw)` 命中则 `where(field, '=', kw)` 并**短路**；
+3. 所有 rules 未命中 → 原 `columns` 的 OR `LIKE %kw%` fallback（现状行为）。
+
+**命中即短路**：形状与列是一对一映射（手机号形状只可能精确查手机号列），不需要多规则 OR 合并。若同一列要接受多种形状（如手机号列同时收 11 位手机号与座机号），声明多条 rule 指向同列即可。
+
+**生成物**：
+
+```ts
+import { isPhone } from '@pylonts/mock/matcher';
+import type { QueryBuilder } from '@pylonts/dao';
+
+export const userListFilter = (args: UserListFilterArgs) =>
+  (q: QueryBuilder) => {
+  if (args.keyword) {
+    if (isPhone(args.keyword)) {
+      q.where('user.phone', '=', args.keyword);
+    } else if (/^ORD\d+$/.test(args.keyword)) {
+      q.where('order.order_no', '=', args.keyword);
+    } else {
+      q.where(function (this: QueryBuilder) {
+        this.where('user.username', 'like', `%${args.keyword}%`);
+      });
+    }
+  }
+  return q;
+  };
+```
+
+- 内置语义名 → 产物 import `@pylonts/mock` 的 matcher 纯函数（`isPhone` 等），不内联正则——形状知识单点维护，与生成器共享常量；
+- 项目正则 → 产物内联 `pattern.test(kw)`（`RegExp.toString()` 直出字面量，每次调用新建，无 `lastIndex` 状态问题）；
+- 精确查询走 `eq`（`=`），值经 knex 参数绑定，无注入面。
+
+## 3. 内置语义 matcher 注册表（@pylonts/mock）
+
+**依赖方向**：mock 已是纯 JS 无依赖包，api 项目产物可直接 import。matcher 与 generator 同文件维护，形状常量共享：
+
+```
+pylon-mock/src/generators/phone.ts    // mockPhone（生成） + isPhone（识别），共享 MOBILE_PREFIXES 等常量
+pylon-mock/src/generators/id.ts       // mockMerchantId/mockOrderId + isMerchantId/isOrderId
+pylon-mock/src/generators/identity.ts // + isIdCard
+pylon-mock/src/generators/finance.ts  // + isBankCard
+pylon-mock/src/matcher.ts             // 注册表 + 导出（子路径 '@pylonts/mock/matcher'）
+```
+
+**注册表**（mirror 现有 MockRegistry 风格，`name → matcher fn`）：
+
+| 语义名 | 判定 | 对应生成器 |
+|--------|------|-----------|
+| `phone` | 11 位、前缀在白名单段 | `mockPhone` |
+| `merchantId` | `M` 前缀 + 数字 | `mockMerchantId` |
+| `orderId` | `ORD` 前缀 + 数字 | `mockOrderId` |
+| `idcard` | 18 位 / 15 位校验 | `mockIdCard` |
+| `bankcard` | Luhn 校验 | `mockBankCard` |
+
+名单在 dsl 侧也需要可见（声明期校验语义名是否存在）。dsl 不依赖 mock（依赖方向不成立），处理：
+
+- **方案 A**：dsl 硬编码语义名单（`KEYWORD_MATCHERS = ['phone', 'merchantId', ...] as const`），defineFilter 校验名字 ∈ 名单；mock 的注册表与之对齐（mock 侧的名单即权威实现）。dsl 只持"名字"，实现永远在 mock。
+- **方案 B**：dsl 不校验，gen loadFilters 校验（查 mock 注册表）——校验时机后移，声明错误要到生成才发现。
+
+**推荐 A**：`defineFilter` 当场报错（与 conditions/keyword 非空校验一致），名单不长且是封闭枚举。mock 已依赖 `@pylonts/dsl`（^1.1.5），注册表 `Record<语义名, (s: string) => boolean>` 可直接用 dsl 导出的名单类型驱动，名单一处定义。
+
+## 4. 端点与前后端一致性（不变量）
+
+- **keyword 端点不变**：`query(keyword)` 统一入口，响应类型仍 `Row[]`，分页/tenant 语义不变；
+- **前端无感知**：判定全在后端 filter 产物，前端搜索框仍只传一个字符串——"前后一样"由生成链路保证（页面 search model、DTO、controller、service、DAO 全部不变，只换 filter 产物内部行为）；
+- **conditions 不变**：rules 命中与否，声明的 AND 条件仍照常拼接。
+
+## 5. 校验与错误
+
+| 校验点 | 时机 | 行为 |
+|--------|------|------|
+| 语义名 ∈ 内置名单 | `defineFilter` | 抛错（与 conditions/keyword 非空校验同风格） |
+| `rules` 非空 | `defineFilter` | 空数组等价于不声明，不报错 |
+| 正则无 `g`/`y` 标志 | `defineFilter` | 抛错（带全局标志的 RegExp 有 lastIndex 状态，test 结果不确定） |
+| rule.field 跨表 | `loadFilters` | 复用现有跨表 filter 机制（usage-site JOIN），不新增规则 |
+| 语义名注册表漂移 | mock 单测 | 名单与实现一一对应（缺实现/多名均报错） |
+
+## 6. 安全
+
+- **SQL**：精确查询值与 LIKE 值同走 knex 参数绑定，无拼接；
+- **ReDoS**：内置 matcher 是库作者维护的白名单正则（无嵌套量词陷阱）；项目自定义正则由 schema 作者负责，文档提示避免 `(a+)+` 类回溯炸弹（只 `test` 用户输入，恶意输入可触发正则回溯——风险与任何服务端正则相同）；
+- **无执行面**：matcher 只返回 boolean，无回调 / 无用户代码注入。
+
+## 7. 分阶段落地（未开始）
+
+| 阶段 | 内容 | 产出 |
+|------|------|------|
+| 1 | dsl：`KeywordRule` + `keyword.rules` 声明 + defineFilter 校验（语义名单、正则标志） | `dsl/src/filter.ts` + 测试 |
+| 2 | mock：matcher 注册表（phone/merchantId/orderId 起步，与生成器共享形状常量）+ 子路径导出 | `pylon-mock/src/matcher.ts` + 测试 |
+| 3 | gen：keyword 块渲染 if/else-if 链（语义名 → import matcher；正则 → 内联 test；fallback → 现有 OR like） | `gen/src/filter-render.ts` + 测试 |
+| 4 | examples：user-list.filter 加 `{ field: phone, when: 'phone' }`，验证产物与 api tsc | examples 回归 |
+
+## 8. 待决策问题
+
+1. **内置语义名单范围**：起步只做 `phone`（最常见）还是 phone/merchantId/orderId 三件套？身份证/银行卡的校验规则重（校验位），是否首期引入？
+2. **matcher 实现归属**：`@pylonts/mock` 是"Mock 数据生成器"定位，形状识别放这里是否符合包边界？备选是新建 `@pylonts/matcher` 或放 `@pylonts/core`（框架无关标准层，依赖方向更干净，但形状常量与 mock 生成器要共享——共享方式：mock 依赖 core，或 matcher 独立包被 mock 依赖）。
+3. **命中后是否允许继续 like**：本方案短路（命中即纯精确）。备选：命中规则后仍追加 OR like 扩大召回（多返回行），由 schema 作者选择。首期短路即可，若业务要"模糊召回"可后续加 `rule.fallbackLike?: boolean`。
+4. **精确查询的操作符**：本方案固定 `eq`。订单号/商户号等唯一键列 eq 合理；若出现"前缀精确"需求（如输入 `ORD17` 查今年订单），是否允许 rule 声明 `op: 'like'`（精确列上的前缀 LIKE）？