trans-form-component/DESIGN.md

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

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

角色定位

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

// 输入 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() / setFilters() / loadFilters() / reset()
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（设计行为，防误触）。

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