145 lines
5.2 KiB
Markdown
145 lines
5.2 KiB
Markdown
# @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 变量**（11 个：`--tf-bg` `--tf-border` `--tf-radius` `--tf-gap` `--tf-label-color` `--tf-name-cols` `--tf-query-cols` `--tf-value-cols` `--tf-span` `--tf-unknown-bg` `--tf-unknown-color`） |
|
||
|
||
### 内置控件（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 更新 ..."
|
||
```
|