# ExtendPropertyValues 迁移到 AdvancedQuery 说明

## 变更时间
2026-05-21

## 变更原因
为了提供更强大、更易用的查询功能，将原有的 `ExtendPropertyValues` 参数替换为 `AdvancedQuery` 参数。底层服务会将 `AdvancedQueryParams` 解析为 `ExtendPropertyValues`。

---

## 变更内容

### 1. QueryActivitiesParams 变更

#### 修改前
```go
type QueryActivitiesParams struct {
    Name                 string           `json:"name,omitempty"`
    ActorID              string           `json:"actorId,omitempty"`
    BusinessType         []string         `json:"businessType,omitempty"`
    ExtendPropertyValues map[string][]any `json:"extendPropertyValues,omitempty"`  // 旧参数
    CreateUserID         string           `json:"createUserId,omitempty"`
    TenantID             string           `json:"tenantId"`
    PageNo               int              `json:"pageNo"`
    PageSize             int              `json:"pageSize"`
}
```

#### 修改后
```go
type QueryActivitiesParams struct {
    Name          string               `json:"name,omitempty"`
    ActorID       string               `json:"actorId,omitempty"`
    BusinessType  []string             `json:"businessType,omitempty"`
    AdvancedQuery *AdvancedQueryParams `json:"advancedQuery,omitempty"`  // 新参数
    CreateUserID  string               `json:"createUserId,omitempty"`
    TenantID      string               `json:"tenantId"`
    PageNo        int                  `json:"pageNo"`
    PageSize      int                  `json:"pageSize"`
}
```

### 2. QueryPlansParams 变更

#### 修改前
```go
type QueryPlansParams struct {
    PlanType             string           `json:"planType,omitempty"`
    Name                 string           `json:"name,omitempty"`
    ActorID              string           `json:"actorId,omitempty"`
    State                string           `json:"state,omitempty"`
    BusinessType         []string         `json:"businessType,omitempty"`
    ExtendPropertyValues map[string][]any `json:"extendPropertyValues,omitempty"`  // 旧参数
    CreateUserID         string           `json:"createUserId,omitempty"`
    TenantID             string           `json:"tenantId"`
    PageNo               int              `json:"pageNo"`
    PageSize             int              `json:"pageSize"`
}
```

#### 修改后
```go
type QueryPlansParams struct {
    PlanType      string               `json:"planType,omitempty"`
    Name          string               `json:"name,omitempty"`
    ActorID       string               `json:"actorId,omitempty"`
    State         string               `json:"state,omitempty"`
    BusinessType  []string             `json:"businessType,omitempty"`
    AdvancedQuery *AdvancedQueryParams `json:"advancedQuery,omitempty"`  // 新参数
    CreateUserID  string               `json:"createUserId,omitempty"`
    TenantID      string               `json:"tenantId"`
    PageNo        int                  `json:"pageNo"`
    PageSize      int                  `json:"pageSize"`
}
```

---

## AdvancedQueryParams 结构

```go
type AdvancedQueryParams struct {
    ConditionGroups []ConditionGroup `json:"conditionGroups"`
    GroupLogic      LogicOperator    `json:"groupLogic"`
}

type ConditionGroup struct {
    Conditions []ConditionItem `json:"conditions"`
    Logic      LogicOperator   `json:"logic"`
}

type ConditionItem struct {
    Condition       *ConditionGroup `json:"condition,omitempty"`
    SingleCondition *QueryCondition `json:"singleCondition,omitempty"`
}

type QueryCondition struct {
    Field    string        `json:"field"`
    Operator QueryOperator `json:"operator"`
    Value    any           `json:"value,omitempty"`
}

type QueryOperator string
type LogicOperator string
```

---

## 迁移指南

### 旧方式（ExtendPropertyValues）

```go
// 旧的查询方式
params := managesdk.QueryActivitiesParams{
    TenantID: "tenant-001",
    ExtendPropertyValues: map[string][]any{
        "(extend_properties->>'priority')::numeric = ?": {1},
        "(extend_properties->>'progress')::numeric > ?": {50},
        "extend_properties->>'deptName' = ?": {"技术部"},
    },
    PageNo:   1,
    PageSize: 10,
}
```

**缺点**：
- 需要手动编写 SQL 片段
- 容易出错（SQL 语法、类型转换）
- 不够直观
- 难以构建复杂的逻辑组合

### 新方式（AdvancedQuery）

```go
// 新的查询方式
params := managesdk.QueryActivitiesParams{
    TenantID: "tenant-001",
    AdvancedQuery: managesdk.AndQuery(
        managesdk.AndGroup(
            managesdk.Equal("priority", 1),
            managesdk.GreaterThan("progress", 50),
            managesdk.Equal("deptName", "技术部"),
        ),
    ),
    PageNo:   1,
    PageSize: 10,
}
```

**优点**：
- 类型安全
- 语义清晰
- 易于构建复杂查询
- 支持嵌套条件
- 自动处理类型转换

---

## 查询操作符对照表

| 旧方式（SQL） | 新方式（AdvancedQuery） | 说明 |
|--------------|------------------------|------|
| `field = ?` | `Equal("field", value)` | 等于 |
| `field != ?` | `NotEqual("field", value)` | 不等于 |
| `field > ?` | `GreaterThan("field", value)` | 大于 |
| `field >= ?` | `GreaterEqual("field", value)` | 大于等于 |
| `field < ?` | `LessThan("field", value)` | 小于 |
| `field <= ?` | `LessEqual("field", value)` | 小于等于 |
| `field LIKE ?` | `Like("field", value)` | 模糊查询 |
| `field NOT LIKE ?` | `NotLike("field", value)` | 不包含 |
| `field LIKE 'prefix%'` | `StartsWith("field", "prefix")` | 以...开头 |
| `field LIKE '%suffix'` | `EndsWith("field", "suffix")` | 以...结尾 |
| `field IS NULL` | `IsNull("field")` | 为空 |
| `field IS NOT NULL` | `IsNotNull("field")` | 不为空 |
| `field IN (?, ?)` | `In("field", []any{v1, v2})` | IN 查询 |
| `field NOT IN (?, ?)` | `NotIn("field", []any{v1, v2})` | NOT IN 查询 |

---

## 迁移示例

### 示例 1：简单等值查询

#### 旧方式
```go
ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'priority')::numeric = ?": {1},
}
```

#### 新方式
```go
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
    ),
)
```

### 示例 2：多条件 AND 查询

#### 旧方式
```go
ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'priority')::numeric = ?": {1},
    "(extend_properties->>'progress')::numeric > ?": {50},
    "extend_properties->>'deptName' = ?": {"技术部"},
}
```

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

### 示例 3：范围查询

#### 旧方式
```go
ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'duration')::numeric BETWEEN ? AND ?": {2.0, 8.0},
}
```

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

### 示例 4：IN 查询

#### 旧方式
```go
ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'complex')::numeric IN (?, ?)": {2, 3},
}
```

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

### 示例 5：模糊查询

#### 旧方式
```go
ExtendPropertyValues: map[string][]any{
    "extend_properties->>'memberName' LIKE ?": {"%张%"},
}
```

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

### 示例 6：OR 查询

#### 旧方式
```go
// 旧方式不支持 OR 查询，需要多次调用
```

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

### 示例 7：复杂组合查询

#### 旧方式
```go
// 旧方式难以表达：(priority = 1 AND progress > 50) OR (priority = 2 AND progress > 80)
```

#### 新方式
```go
AdvancedQuery: managesdk.OrQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
        managesdk.GreaterThan("progress", 50),
    ),
    managesdk.AndGroup(
        managesdk.Equal("priority", 2),
        managesdk.GreaterThan("progress", 80),
    ),
)
```

---

## 新增功能

### 1. 嵌套条件组

```go
// (priority = 1 AND (progress > 50 OR duration > 4))
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
        managesdk.NewNestedConditionGroup(
            managesdk.OrGroup(
                managesdk.GreaterThan("progress", 50),
                managesdk.GreaterThan("duration", 4),
            ),
        ),
    ),
)
```

### 2. 便捷的辅助函数

```go
// 快速构建 AND 查询
managesdk.AndQuery(groups...)

// 快速构建 OR 查询
managesdk.OrQuery(groups...)

// 快速构建 AND 条件组
managesdk.AndGroup(conditions...)

// 快速构建 OR 条件组
managesdk.OrGroup(conditions...)
```

### 3. 丰富的操作符

- 基础比较：`Equal`, `NotEqual`, `GreaterThan`, `GreaterEqual`, `LessThan`, `LessEqual`
- 字符串匹配：`Like`, `NotLike`, `StartsWith`, `EndsWith`
- 空值判断：`IsNull`, `IsNotNull`
- 集合操作：`In`, `NotIn`

---

## 向后兼容性

⚠️ **这是一个破坏性变更**

- `ExtendPropertyValues` 参数已被移除
- 所有使用 `ExtendPropertyValues` 的代码需要迁移到 `AdvancedQuery`

---

## 迁移步骤

### 1. 更新 SDK 版本

确保使用最新版本的 bdata SDK。

### 2. 替换查询参数

将所有 `ExtendPropertyValues` 替换为 `AdvancedQuery`。

### 3. 重写查询逻辑

使用新的查询构建器 API 重写查询条件。

### 4. 测试验证

充分测试所有查询功能，确保结果正确。

---

## 常见问题

### Q1: 如何表达复杂的 SQL 条件？

**A**: 使用嵌套条件组和多个条件组合：

```go
// (A AND B) OR (C AND D)
managesdk.OrQuery(
    managesdk.AndGroup(A, B),
    managesdk.AndGroup(C, D),
)
```

### Q2: 如何进行 BETWEEN 查询？

**A**: 使用 `GreaterEqual` 和 `LessEqual` 组合：

```go
managesdk.AndGroup(
    managesdk.GreaterEqual("field", min),
    managesdk.LessEqual("field", max),
)
```

### Q3: 如何进行 NOT IN 查询？

**A**: 使用 `NotIn` 操作符：

```go
managesdk.NotIn("field", []any{v1, v2, v3})
```

### Q4: 字段名需要加前缀吗？

**A**: 不需要，直接使用字段名即可，底层服务会自动处理：

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

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

### Q5: 数值类型需要转换吗？

**A**: 不需要，底层服务会自动处理类型转换：

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

// 不需要手动转换
managesdk.Equal("(extend_properties->>'priority')::numeric", 1)
```

---

## 相关文档

- **ACTIVITY_PLAN_USAGE.md** - 完整的使用文档
- **advanced_query.go** - AdvancedQuery 实现源码
- **model.go** - 数据模型定义

---

## 总结

### 优势

✅ **类型安全**：编译时检查，减少运行时错误  
✅ **易于使用**：语义清晰，无需编写 SQL  
✅ **功能强大**：支持复杂的逻辑组合和嵌套  
✅ **可维护性**：代码更清晰，易于理解和修改  
✅ **扩展性**：易于添加新的操作符和功能  

### 迁移建议

1. 优先迁移简单查询
2. 逐步迁移复杂查询
3. 充分测试每个迁移点
4. 保留旧代码作为参考

---

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