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",
    AdvancedQuery: managesdk.AndQuery(
        managesdk.AndGroup(
            managesdk.Equal("priority", 1),
            managesdk.GreaterThan("progress", 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",
    AdvancedQuery: managesdk.AndQuery(
        managesdk.AndGroup(
            managesdk.Equal("level", 1),
            managesdk.GreaterThan("estimatedWork", 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",
        AdvancedQuery: managesdk.AndQuery(
            managesdk.AndGroup(
                managesdk.Equal("priority", 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",
        AdvancedQuery: managesdk.AndQuery(
            managesdk.AndGroup(
                managesdk.Equal("level", 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))
}

---

扩展属性查询说明

使用 AdvancedQuery 进行查询

SDK 提供了强大的高级查询功能，通过 AdvancedQuery 参数可以构建复杂的查询条件。

基本查询操作符

// 等于
managesdk.Equal("priority", 1)

// 不等于
managesdk.NotEqual("priority", 1)

// 大于
managesdk.GreaterThan("progress", 50)

// 大于等于
managesdk.GreaterEqual("progress", 50)

// 小于
managesdk.LessThan("progress", 100)

// 小于等于
managesdk.LessEqual("progress", 100)

// 模糊查询
managesdk.Like("deptName", "%技术%")

// 不包含
managesdk.NotLike("deptName", "%销售%")

// 以...开头
managesdk.StartsWith("memberName", "张")

// 以...结尾
managesdk.EndsWith("memberName", "三")

// 为空
managesdk.IsNull("remark")

// 不为空
managesdk.IsNotNull("remark")

// IN 查询
managesdk.In("complex", []int{2, 3})

// NOT IN 查询
managesdk.NotIn("complex", []int{1})

简单查询示例

// 单个条件
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
    ),
)

// 多个 AND 条件
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
        managesdk.GreaterThan("progress", 50),
        managesdk.Equal("deptName", "技术部"),
    ),
)

// 多个 OR 条件
AdvancedQuery: managesdk.OrQuery(
    managesdk.OrGroup(
        managesdk.Equal("priority", 1),
        managesdk.Equal("priority", 2),
    ),
)

复杂查询示例

// 组合查询：(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),
    ),
)

// 范围查询：duration BETWEEN 2.0 AND 8.0
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.GreaterEqual("duration", 2.0),
        managesdk.LessEqual("duration", 8.0),
    ),
)

// IN 查询：complex IN (2, 3)
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.In("complex", []int{2, 3}),
    ),
)

// 字符串模糊查询
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Like("memberName", "%张%"),
        managesdk.Equal("deptName", "技术部"),
    ),
)

嵌套条件组

// 复杂嵌套：(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),
            ),
        ),
    ),
)

完整查询示例

// Activity 查询示例
params := managesdk.QueryActivitiesParams{
    Name:     "项目",  // 基础字段查询
    TenantID: "tenant-001",
    AdvancedQuery: managesdk.AndQuery(
        managesdk.AndGroup(
            managesdk.Equal("priority", 1),
            managesdk.GreaterThan("progress", 50),
            managesdk.Like("categoryName", "%研发%"),
        ),
    ),
    PageNo:   1,
    PageSize: 10,
}

// Plan 查询示例
params := managesdk.QueryPlansParams{
    State:    "进行中",
    TenantID: "tenant-001",
    AdvancedQuery: managesdk.OrQuery(
        managesdk.AndGroup(
            managesdk.Equal("level", 1),
            managesdk.GreaterThan("estimatedWork", 50),
        ),
        managesdk.AndGroup(
            managesdk.Equal("level", 2),
            managesdk.GreaterThan("estimatedWork", 100),
        ),
    ),
    PageNo:   1,
    PageSize: 10,
}

---

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. 参数类型

   • 使用 AdvancedQuery 进行扩展属性查询
   • 支持丰富的查询操作符：等于、不等于、大于、小于、模糊查询、IN、范围查询等
   • 支持 AND/OR 逻辑组合
   • 支持嵌套条件组

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