feat: Add vector database support (v0.8.0-alpha)

Author: sim-wangyan

AI_MAINTAINABILITY_ANALYSIS.md

@@ -0,0 +1,221 @@
+# GitHub Issue 内容（待创建）
+
+**标题**: feat: Add vector database support (v0.8.0-alpha)
+
+**标签**: enhancement, v0.8.0
+
+---
+
+## 📋 Summary
+
+Add vector database support to sqlxb, making it **the first unified ORM for both relational and vector databases**.
+
+---
+
+## ✨ Features
+
+### Core Capabilities
+
+- ✅ **Vector Type**: `sqlxb.Vector` with database compatibility (driver.Valuer, sql.Scanner)
+- ✅ **Distance Metrics**: Cosine Distance, L2 Distance, Inner Product
+- ✅ **Vector Search API**: `VectorSearch()` for unified query interface
+- ✅ **Distance Control**: `VectorDistance()` for flexible metrics
+- ✅ **Threshold Filtering**: `VectorDistanceFilter()` for distance-based filtering
+- ✅ **SQL Generator**: `SqlOfVectorSearch()` with hybrid query optimization
+- ✅ **Auto-Optimization**: Scalar filtering + vector search combined
+
+### Key Advantages
+
+1. **Unified API** (Zero learning curve)
+   ```go
+   // MySQL (existing)
+   sqlxb.Of(&Order{}).Eq("status", 1).Build().SqlOfSelect()
+   
+   // VectorDB (new) - Same API!
+   sqlxb.Of(&CodeVector{}).
+       Eq("language", "golang").
+       VectorSearch("embedding", queryVector, 10).
+       Build().SqlOfVectorSearch()
+   ```
+
+2. **Type-Safe** (Compile-time checks)
+3. **Auto-Ignore nil/0** (Dynamic queries made easy)
+4. **AI-Friendly** (Functional API)
+
+---
+
+## 🏗️ Implementation
+
+### New Files (5)
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `vector_types.go` | 169 | Vector type, distance metrics, calculations |
+| `cond_builder_vector.go` | 136 | CondBuilder vector methods |
+| `builder_vector.go` | 56 | BuilderX vector methods |
+| `to_vector_sql.go` | 195 | Vector SQL generator |
+| `vector_test.go` | 203 | Complete unit tests |
+
+**Total**: ~760 lines of new code
+
+### Modified Files (1)
+
+- `oper.go`: +2 lines (added `VECTOR_SEARCH`, `VECTOR_DISTANCE_FILTER` constants)
+
+### Unchanged Files
+
+- ✅ `bb.go` - Perfect abstraction, no changes needed
+- ✅ All other core files - Zero modifications
+
+---
+
+## ✅ Quality Assurance
+
+### Test Results
+
+```
+Existing tests: 3/3 passed ✅
+  - TestInsert
+  - TestUpdate
+  - TestDelete
+
+Vector tests: 7/7 passed ✅
+  - TestVectorSearch_Basic
+  - TestVectorSearch_WithScalarFilter
+  - TestVectorSearch_L2Distance
+  - TestVectorDistanceFilter
+  - TestVectorSearch_AutoIgnoreNil
+  - TestVector_Distance
+  - TestVector_Normalize
+
+Total: 10/10 (100%)
+```
+
+### Compatibility
+
+- ✅ 100% backward compatible
+- ✅ Zero breaking changes
+- ✅ All existing code works unchanged
+
+---
+
+## 📚 Documentation
+
+### Technical Documentation (100+ pages)
+
+1. **VECTOR_README.md** - Documentation index
+2. **VECTOR_EXECUTIVE_SUMMARY.md** - Executive summary (12 pages)
+3. **VECTOR_DATABASE_DESIGN.md** - Complete technical design (40+ pages)
+4. **VECTOR_PAIN_POINTS_ANALYSIS.md** - Pain points analysis (30+ pages)
+5. **VECTOR_QUICKSTART.md** - Quick start guide (5 minutes)
+6. **VECTOR_RELEASE_NOTES.md** - Release notes
+7. **AI_MAINTAINABILITY_ANALYSIS.md** - AI maintainability analysis
+8. **FROM_BUILDER_OPTIMIZATION_EXPLAINED.md** - Complex code explanation
+9. **MAINTENANCE_STRATEGY.md** - 80/15/5 maintenance model
+
+---
+
+## 🎯 Use Cases
+
+- ✅ Code search and recommendations
+- ✅ Document similarity retrieval
+- ✅ RAG (Retrieval-Augmented Generation) systems
+- ✅ Intelligent Q&A systems
+- ✅ Recommendation systems
+- ✅ Image/Audio search (after vectorization)
+
+---
+
+## 🚀 Example
+
+```go
+package main
+
+import "github.com/x-ream/sqlxb"
+
+type CodeVector struct {
+    Id        int64        `db:"id"`
+    Content   string       `db:"content"`
+    Embedding sqlxb.Vector `db:"embedding"`
+    Language  string       `db:"language"`
+    Layer     string       `db:"layer"`
+}
+
+func (CodeVector) TableName() string {
+    return "code_vectors"
+}
+
+func main() {
+    queryVector := sqlxb.Vector{0.1, 0.2, 0.3, ...}
+    
+    // Search similar code
+    sql, args := sqlxb.Of(&CodeVector{}).
+        Eq("language", "golang").
+        Eq("layer", "repository").
+        VectorSearch("embedding", queryVector, 10).
+        Build().
+        SqlOfVectorSearch()
+    
+    // Execute: db.Select(&results, sql, args...)
+}
+```
+
+**Output SQL**:
+```sql
+SELECT *, embedding <-> ? AS distance
+FROM code_vectors
+WHERE language = ? AND layer = ?
+ORDER BY distance
+LIMIT 10
+```
+
+---
+
+## 📊 Comparison
+
+| Feature | sqlxb | Milvus | Qdrant | ChromaDB | pgvector |
+|---------|-------|--------|--------|----------|----------|
+| Unified API | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
+| ORM Support | ⭐⭐⭐⭐⭐ | ❌ | ❌ | ❌ | ⭐⭐⭐ |
+| Type Safety | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ |
+| Learning Curve | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
+| AI-Friendly | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
+
+**Unique Value**: Only unified ORM for relational + vector databases
+
+---
+
+## 🎯 Next Steps
+
+### Phase 2 (1 month)
+- Query optimizer enhancements
+- Batch vector operations
+- Performance benchmarking
+- More database adapters
+
+### Phase 3 (3 months)
+- Production-grade quality
+- Complete toolchain
+- Community validation
+- Official v0.8.0 release
+
+---
+
+## 💬 Discussion
+
+**Questions? Feedback? Suggestions?**
+
+Comment below or join the discussion!
+
+---
+
+## 📄 Related
+
+- Documentation: [VECTOR_README.md](./VECTOR_README.md)
+- Technical Design: [VECTOR_DATABASE_DESIGN.md](./VECTOR_DATABASE_DESIGN.md)
+- Pain Points: [VECTOR_PAIN_POINTS_ANALYSIS.md](./VECTOR_PAIN_POINTS_ANALYSIS.md)
+
+---
+
+**This is a major milestone for sqlxb - making it the AI-First ORM for the AI era!** 🚀
+