bdata/ACTIVITY_PLAN_USAGE.md

Activity 和 Plan SDK 使用指南

概述

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

新增服务类型

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

默认 BaseURL

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

---

Activity（活动）使用示例

1. 创建客户端

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. 保存活动

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. 查询活动列表

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. 按扩展属性查询

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. 获取活动详情

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. 删除活动

// 删除部分业务类型
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. 获取预定义字段

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

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

---

Plan（计划）使用示例

1. 创建客户端

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. 保存计划

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. 查询计划列表

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. 按扩展属性查询

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. 获取计划详情

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. 删除计划

// 删除部分业务类型
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. 获取预定义字段

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

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

---

完整示例

Activity 完整示例

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 完整示例

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))
}

---

扩展属性查询说明

数值字段查询

// 等于
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},
}

字符串字段查询

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

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

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

组合查询

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