# bdata SDK API 变更总结

## 📋 变更概述

**变更时间**：2026-05-21  
**变更类型**：破坏性变更  
**影响范围**：Activity 和 Plan 查询接口

---

## 🔧 核心变更

### 参数替换

将 `ExtendPropertyValues` 参数替换为 `AdvancedQuery` 参数。

#### QueryActivitiesParams

```go
// 旧参数（已移除）
ExtendPropertyValues map[string][]any `json:"extendPropertyValues,omitempty"`

// 新参数
AdvancedQuery *AdvancedQueryParams `json:"advancedQuery,omitempty"`
```

#### QueryPlansParams

```go
// 旧参数（已移除）
ExtendPropertyValues map[string][]any `json:"extendPropertyValues,omitempty"`

// 新参数
AdvancedQuery *AdvancedQueryParams `json:"advancedQuery,omitempty"`
```

---

## 📊 对比示例

### 旧方式（ExtendPropertyValues）

```go
params := managesdk.QueryActivitiesParams{
    TenantID: "tenant-001",
    ExtendPropertyValues: map[string][]any{
        "(extend_properties->>'priority')::numeric = ?": {1},
        "(extend_properties->>'progress')::numeric > ?": {50},
    },
    PageNo:   1,
    PageSize: 10,
}
```

**缺点**：
- ❌ 需要手动编写 SQL 片段
- ❌ 容易出错（SQL 语法、类型转换）
- ❌ 不支持复杂的 OR 逻辑
- ❌ 代码可读性差

### 新方式（AdvancedQuery）

```go
params := managesdk.QueryActivitiesParams{
    TenantID: "tenant-001",
    AdvancedQuery: managesdk.AndQuery(
        managesdk.AndGroup(
            managesdk.Equal("priority", 1),
            managesdk.GreaterThan("progress", 50),
        ),
    ),
    PageNo:   1,
    PageSize: 10,
}
```

**优点**：
- ✅ 类型安全
- ✅ 语义清晰
- ✅ 支持复杂逻辑组合
- ✅ 代码可读性强
- ✅ 易于维护

---

## 🎯 支持的操作符

| 操作符 | 函数 | 示例 |
|--------|------|------|
| = | `Equal(field, value)` | `Equal("priority", 1)` |
| != | `NotEqual(field, value)` | `NotEqual("status", "closed")` |
| > | `GreaterThan(field, value)` | `GreaterThan("progress", 50)` |
| >= | `GreaterEqual(field, value)` | `GreaterEqual("duration", 2.0)` |
| < | `LessThan(field, value)` | `LessThan("progress", 100)` |
| <= | `LessEqual(field, value)` | `LessEqual("duration", 8.0)` |
| LIKE | `Like(field, value)` | `Like("name", "%项目%")` |
| NOT LIKE | `NotLike(field, value)` | `NotLike("name", "%测试%")` |
| STARTS WITH | `StartsWith(field, value)` | `StartsWith("name", "项目")` |
| ENDS WITH | `EndsWith(field, value)` | `EndsWith("name", "完成")` |
| IS NULL | `IsNull(field)` | `IsNull("remark")` |
| IS NOT NULL | `IsNotNull(field)` | `IsNotNull("remark")` |
| IN | `In(field, values)` | `In("priority", []int{1, 2})` |
| NOT IN | `NotIn(field, values)` | `NotIn("status", []string{"closed"})` |

---

## 💡 常用查询模式

### 1. 简单查询

```go
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
    ),
)
```

### 2. 多条件 AND

```go
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
        managesdk.GreaterThan("progress", 50),
        managesdk.Equal("deptName", "技术部"),
    ),
)
```

### 3. 多条件 OR

```go
AdvancedQuery: managesdk.OrQuery(
    managesdk.OrGroup(
        managesdk.Equal("priority", 1),
        managesdk.Equal("priority", 2),
    ),
)
```

### 4. 范围查询

```go
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.GreaterEqual("duration", 2.0),
        managesdk.LessEqual("duration", 8.0),
    ),
)
```

### 5. IN 查询

```go
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.In("complex", []int{2, 3}),
    ),
)
```

### 6. 模糊查询

```go
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Like("memberName", "%张%"),
    ),
)
```

### 7. 复杂组合

```go
// (priority = 1 AND progress > 50) OR (priority = 2 AND progress > 80)
AdvancedQuery: managesdk.OrQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
        managesdk.GreaterThan("progress", 50),
    ),
    managesdk.AndGroup(
        managesdk.Equal("priority", 2),
        managesdk.GreaterThan("progress", 80),
    ),
)
```

---

## 📝 迁移清单

### 修改的文件

- ✅ `bdata/model.go` - 更新 QueryActivitiesParams 和 QueryPlansParams
- ✅ `bdata/ACTIVITY_PLAN_USAGE.md` - 更新使用文档
- ✅ `bdata/ADVANCED_QUERY_MIGRATION.md` - 创建迁移指南
- ✅ `bdata/API_CHANGE_SUMMARY.md` - 创建变更总结

### 需要迁移的代码

所有使用以下参数的代码需要迁移：
- `QueryActivitiesParams.ExtendPropertyValues`
- `QueryPlansParams.ExtendPropertyValues`

---

## ⚠️ 注意事项

### 1. 破坏性变更

这是一个破坏性变更，所有使用 `ExtendPropertyValues` 的代码必须迁移。

### 2. 字段名不需要前缀

```go
// ✅ 正确
managesdk.Equal("priority", 1)

// ❌ 错误（不需要加前缀）
managesdk.Equal("extend_properties->>'priority'", 1)
```

### 3. 自动类型转换

底层服务会自动处理类型转换，无需手动转换：

```go
// ✅ 正确
managesdk.Equal("priority", 1)

// ❌ 不需要（底层自动处理）
managesdk.Equal("(extend_properties->>'priority')::numeric", 1)
```

### 4. 底层处理

底层服务会将 `AdvancedQueryParams` 解析为 `ExtendPropertyValues`，开发者无需关心实现细节。

---

## 📚 相关文档

1. **ADVANCED_QUERY_MIGRATION.md** - 详细的迁移指南
2. **ACTIVITY_PLAN_USAGE.md** - 完整的使用文档
3. **advanced_query.go** - AdvancedQuery 实现源码

---

## ✅ 优势总结

| 特性 | 旧方式 | 新方式 |
|------|--------|--------|
| 类型安全 | ❌ | ✅ |
| 易于使用 | ❌ | ✅ |
| 支持 OR 逻辑 | ❌ | ✅ |
| 支持嵌套条件 | ❌ | ✅ |
| 代码可读性 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
| 可维护性 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
| 扩展性 | ⭐⭐ | ⭐⭐⭐⭐⭐ |

---

**变更完成时间**：2026-05-21  
**变更人员**：Kiro AI  
**状态**：✅ 已完成