From fd5f7a075273a477b3888a61ffbf3bc09703a32b Mon Sep 17 00:00:00 2001
From: windychen <windychen00n@gmail.com>
Date: Fri, 7 Aug 2026 10:25:52 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=A8=20Q1-Q61=20=E5=AE=8C?=
 =?UTF-8?q?=E6=95=B4=E8=AE=BE=E8=AE=A1=E5=86=B3=E7=AD=96=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 DESIGN.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 136 insertions(+), 24 deletions(-)

diff --git a/DESIGN.md b/DESIGN.md
index 0c3ea5c..a607f38 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -1,32 +1,144 @@
-# trans-form-component — Design (Q1–Q61)
+# @windychen/trans-form-component — Design (Q1–Q61)
 
-Status: **implementation scaffold** (v0.1.0)
+> 设计基线：grill-me 61 题访谈结论（2026-08-06）。配套包：`@windychen/trans-form-middleware`。
 
-Companion package: `@windychen/trans-form-middleware`.
+## 角色定位
 
-## Role
+Schema 驱动的 Vue 3 动态查询表单：接收 schema 数组，输出扁平 filter 数组（含可选 `logic`、状态标记、`empty` 标记）。
 
-Schema-driven Vue 3 query form → flat filter array with optional `logic`, state flags, and `empty` markers.
+```jsonc
+// 输入 schema 示例
+[
+  {
+    "row": 6,
+    "value-component": "input",
+    "field": "name",
+    "field-name": "名称",
+    "query-option": [
+      { "value": "EQ", "label": "=", "desc-cn": "等于" },
+      { "value": "GT", "label": ">", "desc-cn": "大于" }
+    ]
+  }
+]
 
-## Key decisions (selected)
+// 输出 filters 示例
+[
+  { "field": "name", "value": "xx", "query": "EQ", "op": "=" }
+]
+```
 
-| # | Decision |
-|---|----------|
-| 4–5 | No UI framework; headless native controls for string `value-component` |
-| 7 | Flat array + `logic` between adjacent conditions |
-| 11 | `@change` + `getFilters()` ref API |
-| 15 | 12-column grid via `row` |
-| 17–18 | Query dropdown; optional `query-component` (defaults to value renderer) |
-| 19 | Global singleton `setConfig` / `componentMap` |
-| 20 | ESM only (Vite library build) |
-| 30, 35 | Inline layout 3:2:7 (name/query/value), globally configurable |
-| 47 | Storybook included |
-| 48 | `app.use(TransFormPlugin)` |
-| 51 | Built-in reset only (`showReset`, `reset()`) |
-| 54 | First filter item has no `logic` |
-| 55–59 | Reactive schema; preserve matching fields; AND/OR editable; v1 types include tags |
-| 60 | Output includes state flags for middleware |
+---
 
-## CI
+## 一、架构与发布
 
-Same as windychen-utils: commit must contain `chore` + `版本` + `更新`.
+| # | 决策 |
+|---|------|
+| 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 更新 ..."
+```