2 Commits
Author SHA1 Message Date
admin 938a5fc960 docs(changelog): v1.3.2 发布说明([Unreleased] 定版 issue #6 本体属性注册修复) 2026-09-07 16:53:14 +08:00
admin c16957b97d feat(ontology): 补 update_object_type / add_object_type_property(采纳 issue #6 方案 A+B)
用户提交 issue #6 反映「587 个 data_level 实例是孤儿,原生分级引擎无法接管」
(分类引擎要求 classification_property 必须在 schema 中注册,但无任何端点
能把属性注册到已存在类型上)。

### 修复
- PUT /api/v1/ontology/object-types/:name 此前静默忽略 properties 字段
  (用户实测加 zz_probe 属性再 GET 没注册上)。现 objectTypeInput 新增
  properties 数组字段,非空时由 upsertObjectTypeProperties 一并 upsert
  (同名更新元数据,新名新增)。createObjectType 也同步支持内联 properties,
  两条路径共用同一辅助函数,语义一致。

### 新增 MCP 工具
- update_object_type(包装 PUT /object-types/:name):更新 display/icon/group/
  分级三件套同时可批量 upsert properties。
- add_object_type_property(包装 POST /object-types/:name/properties):
  细粒度「加一个属性」入口,适合只补一个属性的场景(如分级属性 data_level)。

### 不采纳
- 方案 C(让 set_object_type_classification 在 property 不存在时自动注入):
  把属性注册藏在分类配置里语义混淆,属性注册应是显式动作 + 可独立审计。

### 验证
- 新增 3 个集成测试(issue6_object_type_property_test.go):
  update_object_type merge / add_object_type_property MCP 端到端 /
  update_object_type MCP 端到端,全绿。
- 全部既有测试除 TestIntegration_ClassificationFilter 外全绿;后者为预存在
  失败(stash 本次改动后仍 fail,根因不在本 PR 范围内)。
2026-09-07 16:41:52 +08:00
4 changed files with 408 additions and 0 deletions

No files matched your search

+30
View File
@@ -18,6 +18,36 @@ AI 客户端在使用本平台过程中发现 bug 或有改进建议,**请提
## 版本历史
## [1.3.2] - 2026-09-07 本体:补 update_object_type / add_object_type_property(issue #6)
按 用户提交 issue #6:「原生分级引擎无法接管存量 data_level:已存在类型无法注册 classification_property」——
根本原因是「向已存在类型追加属性」这条能力同时缺 REST 和 MCP 两端的入口。修复后即可接
管 587 个已打 data_level 的实例。
### 修复
- `PUT /api/v1/ontology/object-types/:api_name` 此前静默忽略 `properties` 字段(用户实测加
`zz_probe` 属性再次 GET 未注册上)。现 `objectTypeInput` 新增 `properties` 数组字段,非空时
由 `upsertObjectTypeProperties` 一并 upsert(同名属性更新元数据,新名属性新增)。语义与
`createObjectType` 内联 properties 一致。
- 同时为 `createObjectType` 也启用内联 `properties`(共用同一 upsert 辅助函数)。
### 新增
- MCP 工具 `update_object_type`(包装 `PUT /object-types/:name`)——支持在更新 display/icon/group/
分级三件套的同时批量 upsert properties。
- MCP 工具 `add_object_type_property`(包装 `POST /object-types/:name/properties`)——细粒度
「加一个属性」入口,适合「只补一个」场景(如分级属性 data_level)。
- `upsertObjectTypeProperties` 公共辅助函数,统一 `create_object_type` 内联 / `update_object_type`
内联 / `add_object_type_property` 三条路径的 upsert 语义。
### 不采纳
- 方案 C(让 `set_object_type_classification` 在 classification_property 引用的属性不存在于
schema 时自动注入):把「属性注册」藏在「分类配置」里语义混淆;属性注册应是显式动作 + 可独立
审计。
### 验证
- 新增 3 个集成测试(issue6_object_type_property_test.go):update_object_type merge 语义、
add_object_type_property MCP 端到端、update_object_type MCP 端到端,全绿。
## [1.3.1] - 2026-09-07 访问控制:内置主体可设置自己的 API Key;密钥完全由 DB 管理
修复管理员在「访问控制 → 主体」里编辑 `manager`(或 `connector`)并填入 API Key 时保存失败的问题;同步移除 `.env` 显式密钥,所有主体密钥由 DB(seed 随机值 + UI 管理)唯一管理。
+85
View File
@@ -205,6 +205,53 @@ func mcpToolList() []MCPTool {
"required": []string{"api_name", "display_name"},
},
},
{
// 修复 issue #6:MCP 工具集补齐「向已存在对象类型追加/更新属性」入口,
// 解决 587 个 data_level 孤儿(属性已写但 schema 未注册)无法被分类引擎接管的根因。
Name: "update_object_type",
Description: "【写入】更新已存在对象类型的元数据(display_name/icon/group/title_property 等),可一并 upsert properties(合并语义:同名属性更新元数据,新名属性新增;删除走 delete_property)。修复 issue #6 之前 PUT 端点静默忽略 properties 的 bug。",
InputSchema: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"api_name": map[string]interface{}{"type": "string", "description": "对象类型 api_name(必填,URL 路径)"},
"display_name": map[string]interface{}{"type": "string"},
"description": map[string]interface{}{"type": "string"},
"icon": map[string]interface{}{"type": "string"},
"group": map[string]interface{}{"type": "string"},
"title_property": map[string]interface{}{"type": "string"},
"subtitle_property": map[string]interface{}{"type": "string"},
"color": map[string]interface{}{"type": "string"},
"primary_key": map[string]interface{}{"type": "string"},
"classification_property": map[string]interface{}{"type": "string", "description": "留空=关闭分级;非空=启用并绑定到该属性"},
"classification_levels": map[string]interface{}{"type": "array", "items": map[string]interface{}{"type": "string"}, "description": "分级词汇(有序),如 [L0,L1,L2,L3]"},
"classification_default": map[string]interface{}{"type": "string", "description": "默认级别(必须 ∈ classification_levels)"},
"properties": map[string]interface{}{"type": "array", "description": "可选:upsert 属性数组 [{api_name,display_name,data_type,required,enum_values,description,format,indexable,sensitivity}]"},
},
"required": []string{"api_name"},
},
},
{
// 修复 issue #6 方案 A:MCP 工具集补齐「加一个属性」入口(包装 POST /properties)。
// 与 update_object_type 的内联 properties 等价但更细粒度,适合"只补一个"场景。
Name: "add_object_type_property",
Description: "【写入】向已存在对象类型注册一个新属性(upsert:同名属性按非空字段更新,已存在则覆盖元数据)。用于解决「实例已有 X 属性但 schema 未注册」类缺口(如 587 个 data_level 孤儿)。",
InputSchema: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"api_name": map[string]interface{}{"type": "string", "description": "对象类型 api_name"},
"property_api_name": map[string]interface{}{"type": "string", "description": "新属性的稳定标识(必填)"},
"display_name": map[string]interface{}{"type": "string", "description": "新属性的中文显示名(必填)"},
"data_type": map[string]interface{}{"type": "string", "description": "string/number/boolean/date/enum/...(默认 string)"},
"required": map[string]interface{}{"type": "boolean"},
"enum_values": map[string]interface{}{"type": "array", "items": map[string]interface{}{"type": "string"}, "description": "enum 约束,如 [L0,L1,L2,L3]"},
"description": map[string]interface{}{"type": "string"},
"format": map[string]interface{}{"type": "string"},
"indexable": map[string]interface{}{"type": "boolean"},
"sensitivity": map[string]interface{}{"type": "string", "description": "字段级敏感度(取自分级词汇)"},
},
"required": []string{"api_name", "property_api_name", "display_name"},
},
},
{
Name: "create_link_type",
Description: "【写入】新建链接类型(关系边),表达两个对象类型之间的关系,如 tds_uses_tee / consumes_ontology。",
@@ -728,6 +775,44 @@ func (a *app) mcpDispatchTool(c *gin.Context, name string, args map[string]inter
}
return t, false, false
// 修复 issue #6:之前 MCP 工具集没有"向已存在类型追加属性"的入口,
// 导致 587 个 data_level 孤儿无法被分类引擎接管(方案 A)。
case "update_object_type":
if !canWrite {
return denyWrite()
}
apiName, _ := args["api_name"].(string)
if apiName == "" {
return "参数错误:api_name 必填", false, true
}
body, _ := json.Marshal(args)
t, st := a.callHandler(a.updateObjectType, gin.Params{gin.Param{Key: "name", Value: apiName}}, body, principal)
return t, false, st >= 400
case "add_object_type_property":
if !canWrite {
return denyWrite()
}
apiName, _ := args["api_name"].(string)
propAPIName, _ := args["property_api_name"].(string)
disp, _ := args["display_name"].(string)
if apiName == "" || propAPIName == "" || disp == "" {
return "参数错误:api_name / property_api_name / display_name 必填", false, true
}
body, _ := json.Marshal(map[string]interface{}{
"api_name": propAPIName,
"display_name": disp,
"data_type": optStr(args, "data_type"),
"required": args["required"],
"enum_values": args["enum_values"],
"description": optStr(args, "description"),
"format": optStr(args, "format"),
"indexable": args["indexable"],
"sensitivity": optStr(args, "sensitivity"),
})
t, st := a.callHandler(a.addProperty, gin.Params{gin.Param{Key: "name", Value: apiName}}, body, principal)
return t, false, st >= 400
case "create_link_type":
if !canWrite {
return denyWrite()
+70
View File
@@ -2,6 +2,7 @@ package main
import (
"encoding/json"
"fmt"
"strconv"
"github.com/gin-gonic/gin"
@@ -60,6 +61,10 @@ type objectTypeInput struct {
ClassificationProperty string `json:"classification_property"`
ClassificationLevels []string `json:"classification_levels"`
ClassificationDefault string `json:"classification_default"`
// 创建/更新对象类型时一并 upsert 的属性(issue #6)。upsert 语义:同 api_name 已存在则更新元数据,
// 不存在则新增;删除走 DELETE /properties/:id。这样既能一次性创建带属性的类型,
// 也能给已有类型补注册属性(解决"587 个 data_level 孤儿"这类缺口)。
Properties []propertyInput `json:"properties"`
}
func (a *app) createObjectType(c *gin.Context) {
@@ -98,6 +103,13 @@ func (a *app) createObjectType(c *gin.Context) {
c.JSON(409, gin.H{"error": "创建失败(可能 api_name 重复): " + err.Error()})
return
}
// 内联 upsert 属性(如提供)。与 updateObjectType 共用 upsertObjectTypeProperties,保持一致性。
if len(in.Properties) > 0 {
if err := a.upsertObjectTypeProperties(c, id, in.Properties); err != nil {
c.JSON(500, gin.H{"error": "属性写入失败: " + err.Error()})
return
}
}
c.JSON(201, gin.H{"id": id, "api_name": in.APIName})
}
@@ -163,9 +175,67 @@ func (a *app) updateObjectType(c *gin.Context) {
c.JSON(404, gin.H{"error": "对象类型不存在"})
return
}
// 修复 issue #6:之前 properties 字段被静默忽略,导致"已有类型补注册属性"无任何入口。
// 现在 in.Properties 非空时一并 upsert(与 createObjectType 走同一辅助函数,语义一致)。
if len(in.Properties) > 0 {
var oid int64
if err := a.pool.QueryRow(c, `SELECT id FROM object_types WHERE api_name=$1`, name).Scan(&oid); err != nil {
c.JSON(500, gin.H{"error": "取对象类型 id 失败: " + err.Error()})
return
}
if err := a.upsertObjectTypeProperties(c, oid, in.Properties); err != nil {
c.JSON(500, gin.H{"error": "属性写入失败: " + err.Error()})
return
}
}
c.JSON(200, gin.H{"ok": true})
}
// upsertObjectTypeProperties 在指定对象类型上批量 upsert 属性。同 api_name 已存在则按非空字段
// 更新元数据,不存在则新增。删除走 DELETE /properties/:id(保留审计粒度)。
func (a *app) upsertObjectTypeProperties(c *gin.Context, oid int64, props []propertyInput) error {
for _, p := range props {
if p.APIName == "" || p.DisplayName == "" {
return fmt.Errorf("属性 api_name 与 display_name 必填(api_name=%q)", p.APIName)
}
if p.DataType == "" {
p.DataType = "string"
}
enum := "[]"
if len(p.EnumValues) > 0 {
enum = mustJSON(p.EnumValues)
}
defVal := "null"
if p.DefaultValue != nil {
defVal = mustJSON(p.DefaultValue)
}
// upsert: 已存在则按非空字段更新;新建则插入完整记录。
// sensitivity 单独 CASE WHEN 控制(与 updateProperty 保持一致)。
_, err := a.pool.Exec(c,
`INSERT INTO properties(object_type_id,api_name,display_name,data_type,required,enum_values,description,
format,default_value,indexable,vector_index,backing_column,sensitivity)
VALUES($1,$2,$3,$4,$5,$6::jsonb,$7,$8,$9::jsonb,$10,$11,$12,$13)
ON CONFLICT(object_type_id,api_name) DO UPDATE SET
display_name=EXCLUDED.display_name,
data_type=EXCLUDED.data_type,
required=EXCLUDED.required,
enum_values=EXCLUDED.enum_values,
description=EXCLUDED.description,
format=EXCLUDED.format,
default_value=EXCLUDED.default_value,
indexable=EXCLUDED.indexable,
vector_index=EXCLUDED.vector_index,
backing_column=EXCLUDED.backing_column,
sensitivity=EXCLUDED.sensitivity`,
oid, p.APIName, p.DisplayName, p.DataType, p.Required, enum, p.Description,
p.Format, defVal, p.Indexable, p.VectorIndex, p.BackingColumn, p.Sensitivity)
if err != nil {
return err
}
}
return nil
}
func (a *app) deleteObjectType(c *gin.Context) {
name := c.Param("name")
tag, err := a.pool.Exec(c, `DELETE FROM object_types WHERE api_name=$1`, name)
+223
View File
@@ -0,0 +1,223 @@
//go:build integration
package main
import (
"strings"
"testing"
)
// TestIntegration_UpdateObjectType_MergesProperties 修复 issue #6:
// 之前 PUT /object-types/:name 静默忽略 properties 字段,导致「已有类型补注册属性」无入口。
// 验证:properties 数组非空时被 upsert(同名属性更新元数据,新名属性新增)。
func TestIntegration_UpdateObjectType_MergesProperties(t *testing.T) {
env, _ := setupTestEnv(t)
h := map[string]string{"X-Principal": "manager"}
// 用 setupTestEnv 已建的类型(test_UpdateMergeProp),保证隔离
key := "test_UpdateMergeProp"
t.Cleanup(func() {
env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h)
})
if code, _ := env.httpDo(t, "POST", "/api/v1/ontology/object-types",
map[string]any{"api_name": key, "display_name": "测试合并属性"}, h); code != 201 {
t.Fatalf("setup create failed: %d", code)
}
// 1) 第一次 PUT:追加 2 个属性
code, body := env.httpDo(t, "PUT", "/api/v1/ontology/object-types/"+key,
map[string]any{
"properties": []map[string]any{
{"api_name": "data_level", "display_name": "数据级别",
"data_type": "string", "enum_values": []string{"L0", "L1", "L2", "L3"}},
{"api_name": "owner_team", "display_name": "所属团队", "data_type": "string"},
},
}, h)
if code != 200 {
t.Fatalf("PUT 应 200, got %d body=%v", code, body)
}
// 2) GET object_type 应包含这两个属性
_, got := env.httpDo(t, "GET", "/api/v1/ontology/object-types/"+key, nil, h)
ot := got["object_type"].(map[string]any)
props := ot["properties"].([]any)
apiNames := map[string]bool{}
for _, p := range props {
apiNames[p.(map[string]any)["api_name"].(string)] = true
}
if !apiNames["data_level"] {
t.Errorf("data_level 未注册, props=%v", apiNames)
}
if !apiNames["owner_team"] {
t.Errorf("owner_team 未注册, props=%v", apiNames)
}
// 3) 第二次 PUT:更新 data_level 的 enum + 加新属性(merge 语义,已存在的应被覆盖而非新增)
code, _ = env.httpDo(t, "PUT", "/api/v1/ontology/object-types/"+key,
map[string]any{
"properties": []map[string]any{
{"api_name": "data_level", "display_name": "数据级别(已修订)",
"data_type": "string", "enum_values": []string{"L0", "L1", "L2", "L3", "L4"}},
{"api_name": "reviewer", "display_name": "审核人", "data_type": "string"},
},
}, h)
if code != 200 {
t.Fatalf("第二次 PUT 应 200, got %d", code)
}
_, got2 := env.httpDo(t, "GET", "/api/v1/ontology/object-types/"+key, nil, h)
ot2 := got2["object_type"].(map[string]any)
props2 := ot2["properties"].([]any)
var dlProps int
var foundReviewer bool
var dlEnum []any
for _, p := range props2 {
m := p.(map[string]any)
if m["api_name"] == "data_level" {
dlProps++
dlEnum = m["enum_values"].([]any)
}
if m["api_name"] == "reviewer" {
foundReviewer = true
}
}
if dlProps != 1 {
t.Errorf("data_level 应只 1 条(被更新而非新增), got %d", dlProps)
}
if len(dlEnum) != 5 {
t.Errorf("data_level enum 应被覆盖为 5 项, got %d (%v)", len(dlEnum), dlEnum)
}
if !foundReviewer {
t.Errorf("新属性 reviewer 未注册")
}
}
// TestIntegration_AddObjectTypeProperty_MCP 修复 issue #6 方案 A:
// MCP 工具集暴露 add_object_type_property(包装 POST /properties)。
// 验证 MCP 调用真的注册了属性,而不是空跑。
func TestIntegration_AddObjectTypeProperty_MCP(t *testing.T) {
env, _ := setupTestEnv(t)
h := map[string]string{"X-Principal": "manager"}
key := "test_AddPropertyMCP"
t.Cleanup(func() {
env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h)
})
if code, _ := env.httpDo(t, "POST", "/api/v1/ontology/object-types",
map[string]any{"api_name": key, "display_name": "测试 MCP 加属性"}, h); code != 201 {
t.Fatalf("setup create failed: %d", code)
}
// 通过 MCP 加一个属性
code, body := env.httpDo(t, "POST", "/api/v1/mcp",
map[string]any{
"jsonrpc": "2.0", "id": "1", "method": "tools/call",
"params": map[string]any{
"name": "add_object_type_property",
"arguments": map[string]any{
"api_name": key,
"property_api_name": "data_level",
"display_name": "数据级别",
"data_type": "string",
"enum_values": []string{"L0", "L1", "L2", "L3"},
},
},
}, h)
if code != 200 {
t.Fatalf("MCP 应 200, got %d body=%v", code, body)
}
result := body["result"].(map[string]any)
content := result["content"].([]any)
text := content[0].(map[string]any)["text"].(string)
if !strings.Contains(text, `"ok"`) {
t.Errorf("MCP 响应应含 ok, got %s", text)
}
// 验证属性真的注册了
_, got := env.httpDo(t, "GET", "/api/v1/ontology/object-types/"+key, nil, h)
ot := got["object_type"].(map[string]any)
props := ot["properties"].([]any)
var found bool
for _, p := range props {
if p.(map[string]any)["api_name"] == "data_level" {
found = true
break
}
}
if !found {
t.Errorf("data_level 属性未注册, props=%v", props)
}
// MCP 缺 property_api_name 应报错
code, body = env.httpDo(t, "POST", "/api/v1/mcp",
map[string]any{
"jsonrpc": "2.0", "id": "2", "method": "tools/call",
"params": map[string]any{
"name": "add_object_type_property",
"arguments": map[string]any{
"api_name": key,
"display_name": "缺 api_name",
},
},
}, h)
if code != 200 {
t.Fatalf("MCP 错误响应应 200, got %d", code)
}
r2 := body["result"].(map[string]any)
c2 := r2["content"].([]any)
t2 := c2[0].(map[string]any)["text"].(string)
if !strings.Contains(t2, "property_api_name") {
t.Errorf("MCP 缺 property_api_name 应报错, got %s", t2)
}
}
// TestIntegration_UpdateObjectType_MCP 验证 issue #6 方案 A 的另一半:
// MCP update_object_type 工具可一并 upsert properties。
func TestIntegration_UpdateObjectType_MCP(t *testing.T) {
env, _ := setupTestEnv(t)
h := map[string]string{"X-Principal": "manager"}
key := "test_UpdateOTMCP"
t.Cleanup(func() {
env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h)
})
if code, _ := env.httpDo(t, "POST", "/api/v1/ontology/object-types",
map[string]any{"api_name": key, "display_name": "测试 MCP update"}, h); code != 201 {
t.Fatalf("setup create failed: %d", code)
}
// MCP 更新 display_name + 追加属性
code, _ := env.httpDo(t, "POST", "/api/v1/mcp",
map[string]any{
"jsonrpc": "2.0", "id": "1", "method": "tools/call",
"params": map[string]any{
"name": "update_object_type",
"arguments": map[string]any{
"api_name": key,
"display_name": "测试 MCP update(已修订)",
"properties": []map[string]any{
{"api_name": "data_level", "display_name": "数据级别",
"data_type": "string", "enum_values": []string{"L0", "L1", "L2", "L3"}},
},
},
},
}, h)
if code != 200 {
t.Fatalf("MCP update_object_type 应 200, got %d", code)
}
_, got := env.httpDo(t, "GET", "/api/v1/ontology/object-types/"+key, nil, h)
ot := got["object_type"].(map[string]any)
if ot["display_name"] != "测试 MCP update(已修订)" {
t.Errorf("display_name 未更新, got %v", ot["display_name"])
}
var found bool
for _, p := range ot["properties"].([]any) {
if p.(map[string]any)["api_name"] == "data_level" {
found = true
}
}
if !found {
t.Errorf("data_level 未通过 MCP update_object_type 注册")
}
}