# @windychen/trans-form-component — Design (Q1–Q61)

> 设计基线：grill-me 61 题访谈结论（2026-08-06）。配套包：`@windychen/trans-form-middleware`。

## 角色定位

Schema 驱动的 Vue 3 动态查询表单：接收 schema 数组，输出扁平 filter 数组（含可选 `logic`、状态标记、`empty` 标记）。

```jsonc
// 输入 schema 示例
[
  {
    "row": 6,
    "value-component": "input",
    "field": "name",
    "field-name": "名称",
    "query-option": [
      { "value": "EQ", "label": "=", "desc-cn": "等于" },
      { "value": "GT", "label": ">", "desc-cn": "大于" }
    ]
  }
]

// 输出 filters 示例
[
  { "field": "name", "value": "xx", "query": "EQ", "op": "=" }
]
```

---

## 一、架构与发布

| # | 决策 |
|---|------|
| 1 | middleware：Node.js 纯 JS |
| 2 | middleware 输出：结构化过滤器，不碰 SQL |
| 3 | **两个独立 Gitea 仓库**，各自 CI、各自发版 |
| 4 | component：**无 UI 库依赖**，slot/渲染器由宿主提供 |
| 5 | 字符串 `value-component`：**内置 headless 原生控件** |
| 10 | component 源码：**纯 JavaScript**（与 middleware 一致） |
| 20 | component 发布：**ESM only** |
| 21 | CI：**复制 windychen-utils 模式**（三关键词 → Verdaccio + Gitea Packages + Release + 钉钉） |
| 22 | 包名：`@windychen/trans-form-component`、`@windychen/trans-form-middleware` |
| 23 | `peerDependencies: vue@^3.4`（Vue 3 only） |
| 26 | component 构建：**vue-tsc + Vite**（library 模式） |
| 28 | 测试：**Vitest**，CI 里 `npm test` 通过才发布 |
| 29 | 版本号：**完全独立**，兼容性写 README |
| 47 | component 仓库带 **Storybook** |
| 48 | 宿主通过 `app.use(TransFormPlugin)` 全局注册 |

---

## 二、Schema / 布局 / 渲染

### 布局

| # | 决策 |
|---|------|
| 15 | `row`：**12 栅格**，一行总宽 12，累加超 12 自动换行 |
| 30 | field 布局：同一 row 内 **name 3 / query 2 / value 7**（inline） |
| 35 | 栅格比例：**全局固定**，`setConfig` 一次设定 |

### 条件逻辑

| # | 决策 |
|---|------|
| 16 | 输入 schema 每条可带 **`logic: 'AND'\|'OR'`** |
| 17 | 操作符：**下拉可改**；支持 **`query-component`**（规则同 `value-component`） |
| 18 | 未指定 `query-component` 时：**继承 value renderer**，绑定 query 字段 |
| 19 | `setConfig` / `component-map`：**全局单例** |
| 34 | 未写 `default-query`：默认 **`query-option` 第一项** |
| 57 | logic：**UI 可改** AND/OR，输出以 UI 为准 |

### 组件解析

| # | 决策 |
|---|------|
| 36 | 未注册 `value-component`：**占位 + console warn**，不阻断其它 field |
| 37 | 未注册 `query-component`：同上，默认继承 value renderer |
| 43 | 自定义组件 props：`{ field, fieldName, queryOption, schema }` 等上下文 |
| 45 | `options`：**组件自主维护**，schema 不强制固定字段 |

### 样式

| # | 决策 |
|---|------|
| 42 | 样式：**内置最小样式 + `--tf-*` CSS 变量**（5 个变量） |

### 内置控件（v1）

| # | 决策 |
|---|------|
| 58 | 内置类型：`input`、`textarea`、`select`、`number`、`date` + **`tags`** |
| 32 | BETWEEN UI：可配 `between-ui`，**默认双 input** |
| 33 | IN/NOT_IN UI：可配 `in-ui`，**默认 tags** |

### 字段状态

| # | 决策 |
|---|------|
| 59 | field 状态：支持 **`hidden` / `disabled` / `readOnly`** |
| 31 | IS_NULL/IS_NOT_NULL：value **禁用但占位** |
| 55 | `schema`：**响应式 prop**，变化时保留同名 field 状态 |
| 56 | 匹配 key：按 **`field` 名** |

---

## 三、输出协议

| # | 决策 |
|---|------|
| 6 | 多条件：**schema 可配 and/or，支持嵌套分组** |
| 7 | 输出形态：**扁平数组 + `logic` 字段** |
| 9 | 空 value：**保留并标记 `empty: true`** |
| 11 | 对外 API：**emit `@change` + ref `getFilters()`** |
| 12 | v1 操作符：比较 + LIKE/IN/NOT_IN + BETWEEN/IS_NULL/IS_NOT_NULL |
| 13 | 多值 `value`：**逗号分隔字符串**（如 `"10,20"`、`"a,b,c"`） |
| 51 | 只内置 **重置**（`reset()` + 可选按钮），查询由宿主触发 |
| 52 | 重置：回到 **schema 初始态** |
| 53 | `@change`：`changeEmit: 'immediate' \| 'debounce' \| 'manual'`，默认 immediate |
| 54 | **第一条不带 `logic`**，从第二条起表示与前一条的连接 |
| 60 | filters **全部输出带状态标记**（`disabled` / `hidden` / `readOnly`） |

---

## 四、与 middleware 的协议对齐

| 项 | 约定 |
|----|------|
| 输出字段 | `field`、`value`、`query`（原始码）、`op`（标准符号）、`logic?`、`values?`、`empty?` |
| 状态标记 | `disabled: true` / `hidden: true` → middleware 默认跳过；`readOnly` → 正常解析 |
| 空值 | `empty: true` → middleware 默认保留，`skipEmpty` 可配 |
| 操作符码表 | `EQ NE GT GTE LT LTE LIKE IN NOT_IN BETWEEN IS_NULL IS_NOT_NULL` |

---

## 五、CI 触发约定

commit message 必须同时包含 `chore` + `版本` + `更新` 才触发构建发布；否则 job 显示 skipped（设计行为，防误触）。

```bash
git commit -m "chore: 版本 0.1.0 更新 ..."
```