# Activity 和 Plan SDK 使用指南

## 概述

bdata SDK 现已支持 Activity（活动）和 Plan（计划）服务的接口调用。

## 新增服务类型

```go
const (
    ServiceTypePerson   ServiceType = "person"
    ServiceTypeResource ServiceType = "resource"
    ServiceTypeActivity ServiceType = "activity"  // 新增
    ServiceTypePlan     ServiceType = "plan"      // 新增
)
```

## 默认 BaseURL

```go
const (
    DefaultActivityBaseURL = "http://10.0.0.210:30684/mbrms/api"
    DefaultPlanBaseURL     = "http://10.0.0.210:30684/mbrms/api"
)
```

---

## Activity（活动）使用示例

### 1. 创建客户端

```go
import "managesdk"

// 使用默认 BaseURL
client := managesdk.NewClient(managesdk.Config{
    Type:    managesdk.ServiceTypeActivity,
    Timeout: 10,
})

// 或者自定义 BaseURL
client := managesdk.NewClient(managesdk.Config{
    Type:    managesdk.ServiceTypeActivity,
    BaseURL: "http://localhost:8080/mbrms/api",
    Timeout: 10,
})
```

### 2. 保存活动

```go
params := managesdk.SaveActivityParams{
    Name:        "测试活动",
    Description: "这是一个测试活动",
    ActorID:     "user-001",
    BusinessType: []string{"mbact", "daily"},
    ExtendProperties: map[string]any{
        "categoryId":   "cat-001",
        "categoryName": "研发",
        "deptId":       "dept-001",
        "deptName":     "技术部",
        "priority":     1,
        "progress":     50,
        "duration":     4.5,
        "onPlan":       1,
        "year":         2026,
        "week":         21,
    },
    TenantID:         "tenant-001",
    CreateUserID:     "user-001",
    UpdateUserID:     "user-001",
    OperatorUserName: "测试用户",
}

id, err := client.Manage().Save(params)
if err != nil {
    log.Fatalf("保存活动失败: %v", err)
}
fmt.Printf("活动ID: %s\n", id)
```

### 3. 查询活动列表

```go
params := managesdk.QueryActivitiesParams{
    Name:     "测试",
    ActorID:  "user-001",
    TenantID: "tenant-001",
    PageNo:   1,
    PageSize: 10,
}

result, err := client.Manage().Query(params)
if err != nil {
    log.Fatalf("查询活动列表失败: %v", err)
}

fmt.Printf("总数: %d\n", result.TotalCount)
for _, activity := range result.Infos {
    fmt.Printf("活动: %+v\n", activity)
}
```

### 4. 按扩展属性查询

```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,
}

result, err := client.Manage().Query(params)
if err != nil {
    log.Fatalf("查询失败: %v", err)
}
```

### 5. 获取活动详情

```go
params := managesdk.GetActivityParams{
    ID: "activity-id-123",
}

activity, err := client.Manage().Get(params)
if err != nil {
    log.Fatalf("获取活动详情失败: %v", err)
}
fmt.Printf("活动详情: %+v\n", activity)
```

### 6. 删除活动

```go
// 删除部分业务类型
params := managesdk.DeleteActivityParams{
    ID:               "activity-id-123",
    BusinessType:     []string{"daily"},
    DeleteWhole:      false,
    DeleteUserID:     "user-001",
    OperatorUserName: "测试用户",
}

err := client.Manage().Delete(params)
if err != nil {
    log.Fatalf("删除失败: %v", err)
}

// 删除整条记录
params := managesdk.DeleteActivityParams{
    ID:               "activity-id-123",
    BusinessType:     []string{"mbact"},
    DeleteWhole:      true,
    DeleteUserID:     "user-001",
    OperatorUserName: "测试用户",
}

err := client.Manage().Delete(params)
```

### 7. 获取预定义字段

```go
fields, err := client.Manage().PredefinedFields()
if err != nil {
    log.Fatalf("获取预定义字段失败: %v", err)
}

for _, field := range fields {
    fmt.Printf("字段: %+v\n", field)
}
```

---

## Plan（计划）使用示例

### 1. 创建客户端

```go
import "managesdk"

// 使用默认 BaseURL
client := managesdk.NewClient(managesdk.Config{
    Type:    managesdk.ServiceTypePlan,
    Timeout: 10,
})

// 或者自定义 BaseURL
client := managesdk.NewClient(managesdk.Config{
    Type:    managesdk.ServiceTypePlan,
    BaseURL: "http://localhost:8080/mbrms/api",
    Timeout: 10,
})
```

### 2. 保存计划

```go
params := managesdk.SavePlanParams{
    PlanType:    "短期活动",
    Name:        "测试计划",
    Description: "这是一个测试计划",
    ActorID:     "user-001",
    State:       "进行中",
    BusinessType: []string{"mbact", "project"},
    ExtendProperties: map[string]any{
        "no":                  32,
        "level":               3,
        "matterType":          2,
        "projectId":           "9b92a7e75abc4d56bc5f5120df89a76c",
        "storyPoints":         5,
        "estimatedWork":       80,
        "actualCompleteness":  50,
    },
    StartTime:        "2026-05-20T09:00:00Z",
    EndTime:          "2026-05-25T18:00:00Z",
    TenantID:         "tenant-001",
    CreateUserID:     "user-001",
    UpdateUserID:     "user-001",
    OperatorUserName: "测试用户",
}

id, err := client.Manage().Save(params)
if err != nil {
    log.Fatalf("保存计划失败: %v", err)
}
fmt.Printf("计划ID: %s\n", id)
```

### 3. 查询计划列表

```go
params := managesdk.QueryPlansParams{
    PlanType: "短期活动",
    Name:     "测试",
    ActorID:  "user-001",
    State:    "进行中",
    TenantID: "tenant-001",
    PageNo:   1,
    PageSize: 10,
}

result, err := client.Manage().Query(params)
if err != nil {
    log.Fatalf("查询计划列表失败: %v", err)
}

fmt.Printf("总数: %d\n", result.TotalCount)
for _, plan := range result.Infos {
    fmt.Printf("计划: %+v\n", plan)
}
```

### 4. 按扩展属性查询

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

result, err := client.Manage().Query(params)
if err != nil {
    log.Fatalf("查询失败: %v", err)
}
```

### 5. 获取计划详情

```go
params := managesdk.GetPlanParams{
    ID: "plan-id-123",
}

plan, err := client.Manage().Get(params)
if err != nil {
    log.Fatalf("获取计划详情失败: %v", err)
}
fmt.Printf("计划详情: %+v\n", plan)
```

### 6. 删除计划

```go
// 删除部分业务类型
params := managesdk.DeletePlanParams{
    ID:               "plan-id-123",
    BusinessType:     []string{"project"},
    DeleteWhole:      false,
    DeleteUserID:     "user-001",
    OperatorUserName: "测试用户",
}

err := client.Manage().Delete(params)
if err != nil {
    log.Fatalf("删除失败: %v", err)
}

// 删除整条记录
params := managesdk.DeletePlanParams{
    ID:               "plan-id-123",
    BusinessType:     []string{"mbact"},
    DeleteWhole:      true,
    DeleteUserID:     "user-001",
    OperatorUserName: "测试用户",
}

err := client.Manage().Delete(params)
```

### 7. 获取预定义字段

```go
fields, err := client.Manage().PredefinedFields()
if err != nil {
    log.Fatalf("获取预定义字段失败: %v", err)
}

for _, field := range fields {
    fmt.Printf("字段: %+v\n", field)
}
```

---

## 完整示例

### Activity 完整示例

```go
package main

import (
    "fmt"
    "log"
    "managesdk"
)

func main() {
    // 创建客户端
    client := managesdk.NewClient(managesdk.Config{
        Type:    managesdk.ServiceTypeActivity,
        BaseURL: "http://localhost:8080/mbrms/api",
        Timeout: 10,
    })

    // 1. 保存活动
    saveParams := managesdk.SaveActivityParams{
        Name:        "日常工作活动",
        Description: "完成项目需求文档编写",
        ActorID:     "user-001",
        BusinessType: []string{"mbact", "daily"},
        ExtendProperties: map[string]any{
            "categoryName": "研发",
            "deptName":     "技术部",
            "memberName":   "张三",
            "priority":     1,
            "progress":     50,
            "duration":     4.5,
            "onPlan":       1,
            "year":         2026,
            "week":         21,
        },
        TenantID:         "tenant-001",
        CreateUserID:     "user-001",
        UpdateUserID:     "user-001",
        OperatorUserName: "测试用户",
    }

    activityID, err := client.Manage().Save(saveParams)
    if err != nil {
        log.Fatalf("保存活动失败: %v", err)
    }
    fmt.Printf("创建活动成功，ID: %s\n", activityID)

    // 2. 查询活动列表
    queryParams := managesdk.QueryActivitiesParams{
        TenantID: "tenant-001",
        ExtendPropertyValues: map[string][]any{
            "(extend_properties->>'priority')::numeric = ?": {1},
        },
        PageNo:   1,
        PageSize: 10,
    }

    result, err := client.Manage().Query(queryParams)
    if err != nil {
        log.Fatalf("查询活动列表失败: %v", err)
    }
    fmt.Printf("查询到 %d 条活动\n", result.TotalCount)

    // 3. 获取活动详情
    getParams := managesdk.GetActivityParams{
        ID: activityID,
    }

    activity, err := client.Manage().Get(getParams)
    if err != nil {
        log.Fatalf("获取活动详情失败: %v", err)
    }
    fmt.Printf("活动详情: %+v\n", activity)

    // 4. 获取预定义字段
    fields, err := client.Manage().PredefinedFields()
    if err != nil {
        log.Fatalf("获取预定义字段失败: %v", err)
    }
    fmt.Printf("预定义字段数量: %d\n", len(fields))
}
```

### Plan 完整示例

```go
package main

import (
    "fmt"
    "log"
    "managesdk"
)

func main() {
    // 创建客户端
    client := managesdk.NewClient(managesdk.Config{
        Type:    managesdk.ServiceTypePlan,
        BaseURL: "http://localhost:8080/mbrms/api",
        Timeout: 10,
    })

    // 1. 保存计划
    saveParams := managesdk.SavePlanParams{
        PlanType:    "短期活动",
        Name:        "项目开发计划",
        Description: "完成项目开发任务",
        ActorID:     "user-001",
        State:       "进行中",
        BusinessType: []string{"mbact", "project"},
        ExtendProperties: map[string]any{
            "no":                 32,
            "level":              1,
            "matterType":         1,
            "projectId":          "9b92a7e75abc4d56bc5f5120df89a76c",
            "storyPoints":        5,
            "estimatedWork":      80,
            "actualCompleteness": 50,
        },
        StartTime:        "2026-05-20T09:00:00Z",
        EndTime:          "2026-05-25T18:00:00Z",
        TenantID:         "tenant-001",
        CreateUserID:     "user-001",
        UpdateUserID:     "user-001",
        OperatorUserName: "测试用户",
    }

    planID, err := client.Manage().Save(saveParams)
    if err != nil {
        log.Fatalf("保存计划失败: %v", err)
    }
    fmt.Printf("创建计划成功，ID: %s\n", planID)

    // 2. 查询计划列表
    queryParams := managesdk.QueryPlansParams{
        State:    "进行中",
        TenantID: "tenant-001",
        ExtendPropertyValues: map[string][]any{
            "(extend_properties->>'level')::numeric = ?": {1},
        },
        PageNo:   1,
        PageSize: 10,
    }

    result, err := client.Manage().Query(queryParams)
    if err != nil {
        log.Fatalf("查询计划列表失败: %v", err)
    }
    fmt.Printf("查询到 %d 条计划\n", result.TotalCount)

    // 3. 获取计划详情
    getParams := managesdk.GetPlanParams{
        ID: planID,
    }

    plan, err := client.Manage().Get(getParams)
    if err != nil {
        log.Fatalf("获取计划详情失败: %v", err)
    }
    fmt.Printf("计划详情: %+v\n", plan)

    // 4. 获取预定义字段
    fields, err := client.Manage().PredefinedFields()
    if err != nil {
        log.Fatalf("获取预定义字段失败: %v", err)
    }
    fmt.Printf("预定义字段数量: %d\n", len(fields))
}
```

---

## 扩展属性查询说明

### 数值字段查询

```go
// 等于
ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'priority')::numeric = ?": {1},
}

// 大于
ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'progress')::numeric > ?": {50},
}

// 范围查询
ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'duration')::numeric BETWEEN ? AND ?": {2.0, 8.0},
}

// IN 查询
ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'complex')::numeric IN (?, ?)": {2, 3},
}
```

### 字符串字段查询

```go
// 等于
ExtendPropertyValues: map[string][]any{
    "extend_properties->>'deptName' = ?": {"技术部"},
}

// 模糊查询
ExtendPropertyValues: map[string][]any{
    "extend_properties->>'memberName' LIKE ?": {"%张%"},
}

// IN 查询
ExtendPropertyValues: map[string][]any{
    "extend_properties->>'categoryName' IN (?, ?)": {"研发", "行政"},
}
```

### 组合查询

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

---

## API 路径映射

| 服务类型 | API 路径前缀 |
|---------|-------------|
| Activity | `/v1/activity` |
| Plan | `/v1/plan` |

### 接口列表

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/v1/activity/save` | 保存活动 |
| POST | `/v1/activity/query` | 查询活动列表 |
| POST | `/v1/activity/get` | 获取活动详情 |
| POST | `/v1/activity/delete` | 删除活动 |
| GET | `/v1/activity/predefined-fields` | 获取预定义字段 |
| POST | `/v1/plan/save` | 保存计划 |
| POST | `/v1/plan/query` | 查询计划列表 |
| POST | `/v1/plan/get` | 获取计划详情 |
| POST | `/v1/plan/delete` | 删除计划 |
| GET | `/v1/plan/predefined-fields` | 获取预定义字段 |

---

## 注意事项

1. **扩展属性类型**
   - Activity 数值字段：priority, progress, duration, onPlan, year, week, stage, complex
   - Plan 数值字段：no, level, matterType, storyPoints, estimatedWork, actualCompleteness
   - 数值字段查询时需要使用 `::numeric` 转换

2. **参数类型**
   - 数值查询参数使用数值类型：`{1}`, `{2.0, 8.0}`
   - 字符串查询参数使用字符串类型：`{"技术部"}`
   - `ExtendPropertyValues` 的类型是 `map[string][]any`

3. **业务类型**
   - BusinessType 是字符串数组
   - 删除时可以指定删除部分业务类型或整条记录

4. **BaseURL**
   - Activity 和 Plan 使用相同的 BaseURL（都在 mbrms 服务下）
   - 可以通过 Config.BaseURL 自定义

---

## 相关文档

- bdata SDK README: `README.md`
- Activity 测试用例: `ActivityManage/http_test/activity.http`
- Plan 测试用例: `ActivityManage/http_test/plan.http`
- 数据类型说明: `ActivityManage/http_test/DATA_TYPES.md`