feat: Add Interceptor + Extension Guides (v0.9.2)

## 🎯 Core Updates

### 1. Interceptor (Infrastructure)

New `interceptor/` package for global SQL build observation:

- **Type-safe boundaries**: `BeforeBuild(meta *Metadata)` compile-time enforced
- **Global**: Register once, apply to all queries
- **Use for**: Logging, monitoring (Prometheus), auditing, distributed tracing
- **NOT for**: Business logic (multi-tenancy, permissions should be explicit)

**Design Highlight**:
```go
// ✅ Can only set metadata (compile-time constraint)
func (i *MyInterceptor) BeforeBuild(meta *interceptor.Metadata) error {
    meta.UserID = 123        // ✅ OK
    meta.Eq("tenant_id", x)  // ❌ Compilation Error
    return nil
}
```

**Files**:
- `interceptor/metadata.go` - Strongly-typed metadata
- `interceptor/interceptor.go` - Interceptor interface
- `interceptor/registry.go` - Global registry
- `interceptor_test.go` - 5 tests (tests as docs)
- `builder_x.go` - Integrate Meta() and interceptor calls
- `to_sql.go` - Built passes Meta

---

### 2. Extension Guides

New extension guides for users:

- `doc/CUSTOM_VECTOR_DB_GUIDE.md` - How to support Milvus, Weaviate, etc.
- `doc/CUSTOM_JOINS_GUIDE.md` - How to extend custom JOINs (ASOF, LATERAL, etc.)

**Principles**:
- ✅ Extend in your own package, don't modify sqlxb core
- ✅ Keep method chaining
- ✅ Follow sqlxb style

---

### 3. Documentation Cleanup

Removed 7 outdated design docs:
- VECTOR_DATABASE_DESIGN.md
- VECTOR_DIVERSITY_API_DESIGN.md
- VECTOR_EXECUTIVE_SUMMARY.md
- VECTOR_IMPLEMENTATION_COMPLETE.md
- VECTOR_PAIN_POINTS_ANALYSIS.md
- VECTOR_SUMMARY.md
- VECTOR_RELEASE_NOTES.md

Updated all API examples to match actual implementation.

---

## 🎊 Philosophy

### Grassroots Culture

- **Interceptor**: No docs, no examples, tests as documentation
  - Don't use = Zero learning cost
  - Use = Learn from tests
  - Hit limit = Understand design

- **Clear Boundaries**:
  - Interceptor for infrastructure only
  - Business logic must be explicit

---

## ✅ Tests

- 5 new Interceptor tests, all passing ✅
- All existing tests passing ✅
- 100% backward compatible ✅

---

**Co-authored-by**: AI Assistant (Claude)
**Philosophy**: Grassroots culture, Explicit over implicit, Simple over complex

Author: sim-wangyan

CHANGELOG_v0.9.2.md

@@ -0,0 +1,50 @@
+# v0.9.2 更新日志
+
+**发布日期**: 2025-10-27
+
+---
+
+## ✨ 新增功能
+
+### 1. Interceptor 拦截器
+
+独立的 `interceptor/` 包，用于全局观察 SQL 构建过程。
+
+**特点**：
+- ✅ 类型安全：`BeforeBuild(meta *Metadata)` 编译时限制
+- ✅ 全局性：注册一次，所有查询生效
+- ✅ 用途：日志、监控、审计
+- ❌ 不用于：业务逻辑（多租户、权限应显式写）
+
+**文件**：
+- `interceptor/metadata.go`
+- `interceptor/interceptor.go`
+- `interceptor/registry.go`
+- `interceptor_test.go` (5 个测试)
+
+---
+
+### 2. 扩展指南
+
+新增两份扩展指南：
+- `doc/CUSTOM_VECTOR_DB_GUIDE.md` - 如何支持 Milvus, Weaviate 等
+- `doc/CUSTOM_JOINS_GUIDE.md` - 如何扩展自定义 JOIN
+
+---
+
+## 🧹 文档清理
+
+删除 7 个过时文档，更新所有 API 示例。
+
+---
+
+## ✅ 测试
+
+- 新增 5 个 Interceptor 测试 ✅
+- 所有现有测试通过 ✅
+- 100% 向后兼容 ✅
+
+---
+
+**升级**：`go get github.com/x-ream/[email protected]`
+

README.md

@@ -105,8 +105,9 @@ This makes sqlxb **one of the first major Go ORM projects successfully maintaine
 Quick links:
 - [Vector Database Quick Start](./doc/VECTOR_QUICKSTART.md)
 - [Vector Diversity + Qdrant Guide](./doc/VECTOR_DIVERSITY_QDRANT.md)
-- [API Design](./doc/VECTOR_DIVERSITY_API_DESIGN.md)
 - [All Filtering Mechanisms](./doc/ALL_FILTERING_MECHANISMS.md)
+- [Custom Vector DB Guide](./doc/CUSTOM_VECTOR_DB_GUIDE.md) - 扩展其他向量数据库
+- [Custom JOINs Guide](./doc/CUSTOM_JOINS_GUIDE.md) - 扩展自定义 JOIN
 - [Contributors](./doc/CONTRIBUTORS.md)
 
 ## Contributing

builder_x.go

@@ -16,7 +16,10 @@
 // limitations under the License.
 package sqlxb
 
-import "fmt"
+import (
+	"fmt"
+	"github.com/x-ream/sqlxb/interceptor"
+)
 
 // ToId build sql, like: SELECT DISTINCT f.id FROM foo f INNER_JOIN JOIN (SELECT foo_id FROM bar) b ON b.foo_id = f.id
 // Sql for MySQL, Clickhouse....
@@ -41,6 +44,15 @@ type BuilderX struct {
 	isWithoutOptimization bool
 
 	alia string
+	meta *interceptor.Metadata // ⭐ 新增：元数据（v0.9.2）
+}
+
+// Meta 获取元数据
+func (x *BuilderX) Meta() *interceptor.Metadata {
+	if x.meta == nil {
+		x.meta = &interceptor.Metadata{}
+	}
+	return x.meta
 }
 
 func Of(tableNameOrPo interface{}) *BuilderX {
@@ -277,11 +289,27 @@ func (x *BuilderX) Build() *Built {
 		panic("sqlxb.Builder is nil")
 	}
 
+	// ⭐ 执行 BeforeBuild 拦截器（只设置元数据）
+	for _, ic := range interceptor.GetAll() {
+		if err := ic.BeforeBuild(x.Meta()); err != nil {
+			panic(fmt.Sprintf("Interceptor %s BeforeBuild failed: %v", ic.Name(), err))
+		}
+	}
+
 	if x.inserts != nil && len(*(x.inserts)) > 0 {
 		built := Built{
 			OrFromSql: x.orFromSql,
 			Inserts:   x.inserts,
+			Meta:      x.meta, // ⭐ 传递元数据
 		}
+
+		// ⭐ 执行 AfterBuild 拦截器
+		for _, ic := range interceptor.GetAll() {
+			if err := ic.AfterBuild(&built); err != nil {
+				panic(fmt.Sprintf("Interceptor %s AfterBuild failed: %v", ic.Name(), err))
+			}
+		}
+
 		return &built
 	}
 
@@ -299,11 +327,19 @@ func (x *BuilderX) Build() *Built {
 		OrFromSql:  x.orFromSql,
 		Fxs:        x.sxs,
 		Svs:        x.svs,
+		Meta:       x.meta, // ⭐ 传递元数据
 	}
 
 	if x.pageBuilder != nil {
 		built.PageCondition = &x.pageBuilder.condition
 	}
 
+	// ⭐ 执行 AfterBuild 拦截器
+	for _, ic := range interceptor.GetAll() {
+		if err := ic.AfterBuild(&built); err != nil {
+			panic(fmt.Sprintf("Interceptor %s AfterBuild failed: %v", ic.Name(), err))
+		}
+	}
+
 	return &built
 }

commit_message/COMMIT_MESSAGE_v0.9.2.txt

@@ -0,0 +1,88 @@
+feat: 新增 Interceptor 拦截器 + 扩展指南文档 (v0.9.2)
+
+## 🎯 核心更新
+
+### 1. Interceptor 拦截器（基础设施）
+
+新增独立的 `interceptor/` 包，用于全局观察 SQL 构建过程：
+
+- **类型安全边界**：`BeforeBuild(meta *Metadata)` 编译时强制只能设置元数据
+- **全局性**：注册一次，所有查询自动执行
+- **用途**：日志、监控（Prometheus）、审计、分布式追踪
+- **不用于**：业务逻辑（多租户、权限、软删除应显式写）
+
+**设计亮点**：
+```go
+// ✅ 只能设置元数据（编译时限制）
+func (i *MyInterceptor) BeforeBuild(meta *interceptor.Metadata) error {
+    meta.UserID = 123        // ✅ 可以
+    meta.Eq("tenant_id", x)  // ❌ 编译错误
+    return nil
+}
+```
+
+**文件**：
+- `interceptor/metadata.go` - 强类型元数据结构
+- `interceptor/interceptor.go` - 拦截器接口
+- `interceptor/registry.go` - 全局注册管理
+- `interceptor_test.go` - 5 个测试（测试即文档）
+- `builder_x.go` - 集成 Meta() 和拦截器调用
+- `to_sql.go` - Built 传递 Meta
+
+---
+
+### 2. 扩展指南文档
+
+新增两份扩展指南，帮助用户扩展 sqlxb：
+
+- `doc/CUSTOM_VECTOR_DB_GUIDE.md` - 如何支持 Milvus, Weaviate 等向量数据库
+- `doc/CUSTOM_JOINS_GUIDE.md` - 如何扩展 ClickHouse ASOF JOIN 等
+
+**设计原则**：
+- ✅ 在自己包内扩展，不修改 sqlxb 核心
+- ✅ 保持链式调用
+- ✅ 遵循 sqlxb 风格
+
+---
+
+### 3. 文档清理
+
+删除 7 个早期设计文档（已过时）：
+- VECTOR_DATABASE_DESIGN.md
+- VECTOR_DIVERSITY_API_DESIGN.md  
+- VECTOR_EXECUTIVE_SUMMARY.md
+- VECTOR_IMPLEMENTATION_COMPLETE.md
+- VECTOR_PAIN_POINTS_ANALYSIS.md
+- VECTOR_SUMMARY.md
+- VECTOR_RELEASE_NOTES.md
+
+更新所有文档的 API 示例，确保与实际实现一致。
+
+---
+
+## 🎊 设计哲学
+
+### 草根文化
+
+- **Interceptor**：无文档、无示例，测试即文档
+  - 不用 = 零学习成本
+  - 用了 = 看测试学习
+  - 遇到限制 = 理解设计
+
+- **边界清晰**：
+  - Interceptor 只用于基础设施
+  - 业务逻辑必须显式（多租户、权限应显式写）
+
+---
+
+## ✅ 测试
+
+- 新增 5 个 Interceptor 测试，全部通过 ✅
+- 所有现有测试保持通过 ✅
+- 100% 向后兼容 ✅
+
+---
+
+**Co-authored-by**: AI Assistant (Claude)
+**Philosophy**: 草根文化、显式优于隐式、简洁优于复杂
+

commit_message/COMMIT_MESSAGE_v0.9.2_EN.txt

@@ -0,0 +1,88 @@
+feat: Add Interceptor + Extension Guides (v0.9.2)
+
+## 🎯 Core Updates
+
+### 1. Interceptor (Infrastructure)
+
+New `interceptor/` package for global SQL build observation:
+
+- **Type-safe boundaries**: `BeforeBuild(meta *Metadata)` compile-time enforced
+- **Global**: Register once, apply to all queries
+- **Use for**: Logging, monitoring (Prometheus), auditing, distributed tracing
+- **NOT for**: Business logic (multi-tenancy, permissions should be explicit)
+
+**Design Highlight**:
+```go
+// ✅ Can only set metadata (compile-time constraint)
+func (i *MyInterceptor) BeforeBuild(meta *interceptor.Metadata) error {
+    meta.UserID = 123        // ✅ OK
+    meta.Eq("tenant_id", x)  // ❌ Compilation Error
+    return nil
+}
+```
+
+**Files**:
+- `interceptor/metadata.go` - Strongly-typed metadata
+- `interceptor/interceptor.go` - Interceptor interface
+- `interceptor/registry.go` - Global registry
+- `interceptor_test.go` - 5 tests (tests as docs)
+- `builder_x.go` - Integrate Meta() and interceptor calls
+- `to_sql.go` - Built passes Meta
+
+---
+
+### 2. Extension Guides
+
+New extension guides for users:
+
+- `doc/CUSTOM_VECTOR_DB_GUIDE.md` - How to support Milvus, Weaviate, etc.
+- `doc/CUSTOM_JOINS_GUIDE.md` - How to extend custom JOINs (ASOF, LATERAL, etc.)
+
+**Principles**:
+- ✅ Extend in your own package, don't modify sqlxb core
+- ✅ Keep method chaining
+- ✅ Follow sqlxb style
+
+---
+
+### 3. Documentation Cleanup
+
+Removed 7 outdated design docs:
+- VECTOR_DATABASE_DESIGN.md
+- VECTOR_DIVERSITY_API_DESIGN.md
+- VECTOR_EXECUTIVE_SUMMARY.md
+- VECTOR_IMPLEMENTATION_COMPLETE.md
+- VECTOR_PAIN_POINTS_ANALYSIS.md
+- VECTOR_SUMMARY.md
+- VECTOR_RELEASE_NOTES.md
+
+Updated all API examples to match actual implementation.
+
+---
+
+## 🎊 Philosophy
+
+### Grassroots Culture
+
+- **Interceptor**: No docs, no examples, tests as documentation
+  - Don't use = Zero learning cost
+  - Use = Learn from tests
+  - Hit limit = Understand design
+
+- **Clear Boundaries**:
+  - Interceptor for infrastructure only
+  - Business logic must be explicit
+
+---
+
+## ✅ Tests
+
+- 5 new Interceptor tests, all passing ✅
+- All existing tests passing ✅
+- 100% backward compatible ✅
+
+---
+
+**Co-authored-by**: AI Assistant (Claude)
+**Philosophy**: Grassroots culture, Explicit over implicit, Simple over complex
+