# @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 | **深层 OR 嵌套（v0.1.1）**：`toFindOptionsWhere` 接受 `toTree` 树输入，递归 + 分配律展开（`X AND (A OR B)` → `[{X,A},{X,B}]`），同字段 AND 用 `And()` 组合 |
| 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 + 钉钉通知。

## 未决项 / 后续

- 可选：`trans-form-knex`（决策 #24 提及的另一适配方向）
- 分配律展开的最坏情况指数增长：极端复杂布尔树走 `applyToQueryBuilder`（括号表达式，无展开成本）