chore: 版本 0.1.0 更新 TypeORM 适配包 toFindOptionsWhere/applyToQueryBuilder

2026-08-07 11:30:15 +08:00
commit 324b995f05
12 changed files with 3974 additions and 0 deletions
@@ -0,0 +1,44 @@
+# @windychen/trans-form-typeorm — Design
+
+> 设计基线：grill-me 61 题访谈结论（2026-08-06），决策 #24（"middleware 零依赖，另做 ORM 适配包"）的 TypeORM 落地。
+
+## 角色定位
+
+接收 `@windychen/trans-form-middleware` 的 `parseFilters` 输出，转为 TypeORM 可消费的查询条件。**不重新解析语义** —— 校验、白名单、状态标记过滤都在 middleware 层完成，本包只做「结构化 → TypeORM」。
+
+## 核心决策
+
+| # | 决策 |
+|---|------|
+| 1 | **独立 Gitea 仓库**，独立 CI、独立发版（沿用 Q3 模式） |
+| 2 | 零运行时依赖；`typeorm@^0.3` 为 peerDependency |
+| 3 | ESM only，不打包（`exports: "./src/index.js"`） |
+| 4 | 两种输出：`FindOptionsWhere[]`（对象式）+ QueryBuilder 条件（表达式式） |
+| 5 | AND 项合并同一对象；OR 项拆数组元素（TypeORM 语义） |
+| 6 | 嵌套分组（Q6）用括号表达式递归生成 |
+| 7 | 参数化绑定（`:p1 :p2`），杜绝字符串拼接注入 |
+| 8 | 空 value 且非 NULL 查询自动跳过；LIKE 自动补 `%` |
+| 9 | `disabled`/`hidden` 默认跳过（对齐 Q60/Q61），`skipEmpty` 可配 |
+| 10 | 测试用真实 typeorm（FindOperator 断言），Vitest |
+
+## API 表面
+
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `toFindOptionsWhere` | `(filters, { skipFlags, skipEmpty, operatorMap })` | → `FindOptionsWhere[]` |
+| `applyToQueryBuilder` | `(qb, filters, { skipFlags, skipEmpty, operatorMap, alias, paramPrefix, method })` | → `{ qb, parameters }` |
+| `mapOperator` | `(query, operatorMap?)` | 操作符码 → 工厂函数 |
+| `DEFAULT_OPERATOR_MAP` | — | 12 种操作符映射 |
+
+## 操作符覆盖（对齐 middleware 码表）
+
+EQ NE GT GTE LT LTE LIKE IN NOT_IN BETWEEN IS_NULL IS_NOT_NULL
+
+## CI
+
+复制 windychen-utils 模式：commit message 含 `chore` + `版本` + `更新` 触发 → Verdaccio + Gitea Packages + Release + 钉钉通知。
+
+## 未决项 / 后续
+
+- TypeORM `FindOptionsWhere` 对深层 OR 嵌套（如 `A OR (B AND C)` 内嵌）表达能力有限，深层场景建议走 `applyToQueryBuilder`
+- 可选：`trans-form-knex`（决策 #24 提及的另一适配方向）