From ed77aa464855aa65e7408bb601de8fabdf396a02 Mon Sep 17 00:00:00 2001
From: what <what-00@qq.com>
Date: Fri, 21 Aug 2026 09:05:24 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20README=EF=BC=8C?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E=20v1-legacy=20=E5=88=86=E6=94=AF=E7=9A=84?=
 =?UTF-8?q?=E8=83=BD=E5=8A=9B=E8=8C=83=E5=9B=B4=E4=B8=8E=E5=AE=89=E8=A3=85?=
 =?UTF-8?q?=E6=96=B9=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

记录这条老线跟 master 的差异，以及依赖方（如 zg-estate）应该怎么锁定/更新
到这个分支，避免误跑 go get -u 拉到 master 上的破坏性改动。
---
 README.md | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d152cab..09cf217 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,38 @@
-# condition
+# git.fsdpf.net/go/condition（v1-legacy）
 
+老架构下的条件表达式 DSL：把一组条件（等值/比较/模糊匹配/IN 等）组织成可嵌套的 `AND`/`OR`
+树，`ToSql` 手工拼接成 SQL 字符串（`db.Raw(...)`），供权限过滤、规则引擎等场景复用同一套
+条件描述。
+
+## 这个分支有什么
+
+- `Condition`：条件树节点，`ConditionType`（`AND`/`OR`）是独立的 `string` 类型，`ToSql(m
+  TokenValue) db.Expression` 内部把子条件/表达式各自渲染成字符串、`strings.Join` 拼接、手动
+  加括号、返回 `db.Raw(sql)`——不是表达式树，是纯字符串拼接。
+- `ConditionExpr`：单个表达式（字段 + 操作符 + 值），`ConditionOperator` 是独立的 `string`
+  类型（`"="`/`"!="`/`"LIKE"`/`"IN"` 等字符串常量），`TokenValue` 接口定义在这个文件里
+  （`GetParam(k string) req.GlobalParams`，不是新架构的 `valuex.Accessor`）。
+- `engine/`：`Engine[T]` 规则引擎，`EngineParam` 包一层 `req.GlobalParams` 给条件求值用。
+
+## 这个分支的定位
+
+给还在维护、但还没迁移到新架构（`master` 分支上 `Condition.ToSql` 改用 `db-v2` 表达式树、
+`TokenValue` 改用 `reflux/valuex`、新增 JSON 序列化支持）的老项目用，比如 `zg-estate`（间接
+依赖）。只接受独立于新架构的 bug 修复。
+
+## 依赖方怎么安装/更新
+
+Go modules 不会记住某个版本是从哪个分支解析出来的，`go.mod`/`go.sum` 里存的只是一次性解析出
+的 commit 伪版本号，分支上有新提交也不会自动同步。
+
+**首次锁定，或者要拿这个分支上新提交的更新**，都执行同一条命令：
+
+```
+go get git.fsdpf.net/go/condition@v1-legacy
+```
+
+**禁止**跑裸的 `go get -u`（或者 `go get git.fsdpf.net/go/condition@latest`）——这个仓库没有
+打语义化 tag，Go 对"最新版本"的解析规则是退回到仓库默认分支（`master`）的 HEAD，会把新架构
+的破坏性改动一起拉进来，而不是停留在这个分支上。同时注意这条老线依赖的
+`git.fsdpf.net/go/db`/`git.fsdpf.net/go/req` 也要一起锁定在它们各自的 `v1-legacy` 分支，
+不能新老混用。