「让客户端敢操作」的关键能力:写前/写后打一份快照 → 任意 GET 带 X-Snapshot-Id
头即可命中 backups_<id> schema 的同名表(业务 SQL 不带 schema 前缀照样切)。
设计要点:
- 备份 = 独立 schema backups_<id>(真表,不是单存 JSONB)—— 查询性能与活库一致
- snapshotRouter 中间件:BeginTx + SET LOCAL search_path → 把 a.pool 临时换
为事务视图 txPool → handler 结束 commit + 还原 a.pool。业务代码一行不改。
- a.pool 字段类型从 *pgxpool.Pool 升级为 dbRunner interface(中间件可换 txPool)。
- 11 个 helper 函数签名同步改为 dbExec(与现有 dbExec 共存,无破坏性)。
- 写方法(POST/PUT/PATCH/DELETE)带快照头 → 403 拒绝(mistake-safety)。
接口:
- POST /api/v1/backups 创建
- GET /api/v1/backups 列表
- GET /api/v1/backups/:id 元信息(含 schema_name)
- GET /api/v1/backups/:id/switch 切库提示
- DELETE /api/v1/backups/:id 级联删 schema
- 支持 X-Snapshot-Id (直接 run id) + X-Snapshot-Ts (秒级时间戳) 两种切换入口
MCP 工具 (5 个):backup_create / backup_list / backup_inspect / backup_switch / backup_delete
测试 (22 个全绿,~5.5s 集成):
- SnapshotRouter:改前建快照 → 改后读快照只见改前
- SnapshotSearchPathPersist:不污染下一个请求
- SnapshotByTimestamp:ts 头也能切库
- SnapshotDeleteCleansSchema:delete 真 DROP schema
- BackupLifecycle / BackupDiffAfterMutation:完整 create→list→inspect→switch→delete
文档:docs/BACKUP.md 写清用法、机制、客户端工作流;CHANGELOG.md [1.3.0]。
335 lines
11 KiB
Go
335 lines
11 KiB
Go
package main
|
||
|
||
// Function 元原语(Kinetic 层 ⑤Function)
|
||
//
|
||
// 设计要点:
|
||
// - 4 个内置 builtin 函数:mask_field_by_policy / compute_object_link_strength /
|
||
// compute_data_asset_value / derive_object_completeness
|
||
// - builtin registry 通过 api_name 直接映射到 Go handler
|
||
// - 启动时 ensureBuiltinFunctions 幂等同步到 DB
|
||
// - 调用接口:POST /api/v1/ontology/function-types/:name/invoke
|
||
// - 可被 Action 编排(createActionType 时声明 function_call 步骤),也可暴露为 MCP tool
|
||
//
|
||
// 与 Action 的区别:Function 无副作用(pure),可被反复调用,可作为 MCP tool 暴露。
|
||
|
||
import (
|
||
"context"
|
||
"fmt"
|
||
"log"
|
||
"strings"
|
||
"time"
|
||
)
|
||
|
||
// FunctionHandler builtin 函数的执行体
|
||
type FunctionHandler func(ctx context.Context, a *app, args map[string]interface{}) (map[string]interface{}, error)
|
||
|
||
// builtinRegistry 通过 builtin_fn key 查找实现
|
||
var builtinRegistry = map[string]FunctionHandler{
|
||
"mask_field_by_policy": fnMaskFieldByPolicy,
|
||
"compute_object_link_strength": fnComputeLinkStrength,
|
||
"compute_data_asset_value": fnComputeAssetValue,
|
||
"derive_object_completeness": fnDeriveCompleteness,
|
||
}
|
||
|
||
// builtinDefs builtin 函数定义(启动时同步到 function_types 表)
|
||
var builtinDefs = []struct {
|
||
APIName string
|
||
DisplayName string
|
||
Description string
|
||
Inputs string
|
||
Outputs string
|
||
}{
|
||
{
|
||
"mask_field_by_policy",
|
||
"按字段策略脱敏",
|
||
"读取 FieldPolicy,对指定对象按 principal 视角应用 redact/hide 规则。返回脱敏后的属性 map。",
|
||
`[{"name":"object_type","type":"string","required":true},{"name":"object_pk","type":"string","required":true},{"name":"principal","type":"string","required":false},{"name":"properties","type":"object","required":true}]`,
|
||
`[{"name":"redacted","type":"object"},{"name":"hidden","type":"array"},{"name":"applied","type":"array"}]`,
|
||
},
|
||
{
|
||
"compute_object_link_strength",
|
||
"计算对象链接强度",
|
||
"基于对象作为源/目标的链接数量与最近活动时间,计算其关系强度(0~1)。强度高的对象处于本体核心。",
|
||
`[{"name":"object_type","type":"string","required":true},{"name":"object_pk","type":"string","required":true}]`,
|
||
`[{"name":"strength","type":"number"},{"name":"as_source","type":"integer"},{"name":"as_target","type":"integer"},{"name":"latest_link_at","type":"string"}]`,
|
||
},
|
||
{
|
||
"compute_data_asset_value",
|
||
"数据资产估值",
|
||
"基于对象属性的启发式数据资产估值:行业系数 × 规模 × 时效 × 完整度。可写入 DataProduct.price_estimate。",
|
||
`[{"name":"object_type","type":"string","required":true},{"name":"object_pk","type":"string","required":true},{"name":"industry","type":"string","required":false},{"name":"scale_score","type":"number","required":false}]`,
|
||
`[{"name":"value_score","type":"number"},{"name":"components","type":"object"},{"name":"explanation","type":"string"}]`,
|
||
},
|
||
{
|
||
"derive_object_completeness",
|
||
"对象完整度计算",
|
||
"按对象类型的所有 required 属性填充率计算完整度(0~1),可用于评估知识管理 / 数据接入的质量。",
|
||
`[{"name":"object_type","type":"string","required":true},{"name":"object_pk","type":"string","required":true}]`,
|
||
`[{"name":"completeness","type":"number"},{"name":"filled","type":"integer"},{"name":"required_count","type":"integer"},{"name":"missing","type":"array"}]`,
|
||
},
|
||
}
|
||
|
||
// ensureBuiltinFunctions 启动时把 builtin 函数同步到 function_types(幂等)
|
||
func ensureBuiltinFunctions(ctx context.Context, p dbExec) error {
|
||
for _, d := range builtinDefs {
|
||
_, err := p.Exec(ctx,
|
||
`INSERT INTO function_types(api_name,display_name,description,inputs,outputs,impl_kind,impl_ref,is_pure,builtin_fn)
|
||
VALUES($1,$2,$3,$4::jsonb,$5::jsonb,'builtin','',true,$1)
|
||
ON CONFLICT(api_name) DO UPDATE SET
|
||
display_name=EXCLUDED.display_name,
|
||
description=EXCLUDED.description,
|
||
inputs=EXCLUDED.inputs,
|
||
outputs=EXCLUDED.outputs,
|
||
impl_kind='builtin',
|
||
builtin_fn=EXCLUDED.api_name,
|
||
is_pure=true,
|
||
updated_at=now()`,
|
||
d.APIName, d.DisplayName, d.Description, d.Inputs, d.Outputs)
|
||
if err != nil {
|
||
return fmt.Errorf("sync builtin function %s 失败: %w", d.APIName, err)
|
||
}
|
||
}
|
||
log.Printf("[function] 内置函数就绪: %d 个 builtin (mask_field_by_policy / compute_object_link_strength / compute_data_asset_value / derive_object_completeness)", len(builtinDefs))
|
||
return nil
|
||
}
|
||
|
||
// ============ 内置函数实现 ============
|
||
|
||
// fnMaskFieldByPolicy 应用 FieldPolicy 到对象属性
|
||
func fnMaskFieldByPolicy(ctx context.Context, a *app, args map[string]interface{}) (map[string]interface{}, error) {
|
||
typ, _ := args["object_type"].(string)
|
||
pk, _ := args["object_pk"].(string)
|
||
principal, _ := args["principal"].(string)
|
||
if typ == "" || pk == "" {
|
||
return nil, fmt.Errorf("object_type 与 object_pk 必填")
|
||
}
|
||
if principal == "" {
|
||
principal = "public"
|
||
}
|
||
props, _ := args["properties"].(map[string]interface{})
|
||
|
||
// 加载 FieldPolicy
|
||
rows, err := a.pool.Query(ctx, `SELECT property, effect FROM field_policies WHERE object_type=$1 AND principal=$2`, typ, principal)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
defer rows.Close()
|
||
rules := map[string]string{}
|
||
for rows.Next() {
|
||
var p, e string
|
||
if rows.Scan(&p, &e) == nil {
|
||
rules[p] = e
|
||
}
|
||
}
|
||
|
||
redacted := map[string]interface{}{}
|
||
hidden := []string{}
|
||
applied := []string{}
|
||
for k, v := range props {
|
||
if eff, ok := rules[k]; ok {
|
||
applied = append(applied, k+"="+eff)
|
||
switch eff {
|
||
case "hide":
|
||
hidden = append(hidden, k)
|
||
case "redact":
|
||
redacted[k] = "***"
|
||
case "full":
|
||
redacted[k] = v
|
||
}
|
||
} else {
|
||
redacted[k] = v
|
||
}
|
||
}
|
||
return map[string]interface{}{
|
||
"redacted": redacted,
|
||
"hidden": hidden,
|
||
"applied": applied,
|
||
}, nil
|
||
}
|
||
|
||
// fnComputeLinkStrength 计算对象的链接强度
|
||
func fnComputeLinkStrength(ctx context.Context, a *app, args map[string]interface{}) (map[string]interface{}, error) {
|
||
typ, _ := args["object_type"].(string)
|
||
pk, _ := args["object_pk"].(string)
|
||
if typ == "" || pk == "" {
|
||
return nil, fmt.Errorf("object_type 与 object_pk 必填")
|
||
}
|
||
var asSource, asTarget int
|
||
var latest interface{}
|
||
_ = a.pool.QueryRow(ctx,
|
||
`SELECT count(*), max(created_at) FROM links WHERE source_type=$1 AND source_pk=$2`, typ, pk).Scan(&asSource, &latest)
|
||
_ = a.pool.QueryRow(ctx,
|
||
`SELECT count(*) FROM links WHERE target_type=$1 AND target_pk=$2`, typ, pk).Scan(&asTarget)
|
||
|
||
total := asSource + asTarget
|
||
// 简单 sigmoid: total/(total+10) 把强度压到 0~1
|
||
strength := float64(total) / (float64(total) + 10.0)
|
||
latestStr := ""
|
||
if t, ok := latest.(time.Time); ok {
|
||
latestStr = t.Format(time.RFC3339)
|
||
}
|
||
return map[string]interface{}{
|
||
"strength": strength,
|
||
"as_source": asSource,
|
||
"as_target": asTarget,
|
||
"total_links": total,
|
||
"latest_link_at": latestStr,
|
||
}, nil
|
||
}
|
||
|
||
// fnComputeAssetValue 启发式数据资产估值
|
||
func fnComputeAssetValue(ctx context.Context, a *app, args map[string]interface{}) (map[string]interface{}, error) {
|
||
typ, _ := args["object_type"].(string)
|
||
pk, _ := args["object_pk"].(string)
|
||
if typ == "" || pk == "" {
|
||
return nil, fmt.Errorf("object_type 与 object_pk 必填")
|
||
}
|
||
|
||
// 读取对象属性
|
||
var propsBytes []byte
|
||
if err := a.pool.QueryRow(ctx,
|
||
`SELECT properties_json FROM objects WHERE type_api_name=$1 AND pk=$2`, typ, pk).Scan(&propsBytes); err != nil {
|
||
return nil, fmt.Errorf("对象不存在: %w", err)
|
||
}
|
||
props := decodeProps(propsBytes)
|
||
|
||
// 行业系数
|
||
industry := strings.TrimSpace(fmt.Sprintf("%v", args["industry"]))
|
||
if industry == "" {
|
||
if v, ok := props["industry"].(string); ok {
|
||
industry = v
|
||
}
|
||
}
|
||
industryScore := 1.0
|
||
switch industry {
|
||
case "医疗健康", "医疗":
|
||
industryScore = 1.5
|
||
case "物流":
|
||
industryScore = 1.2
|
||
case "金融", "智慧金融":
|
||
industryScore = 1.4
|
||
case "汽车", "具身智能":
|
||
industryScore = 1.3
|
||
case "茶业", "生态环保":
|
||
industryScore = 0.9
|
||
}
|
||
|
||
// 规模系数
|
||
scale := 1.0
|
||
if v, ok := args["scale_score"].(float64); ok && v > 0 {
|
||
scale = v
|
||
} else if s, ok := props["scale"].(string); ok {
|
||
if strings.Contains(s, "亿") {
|
||
scale = 1.5
|
||
} else if strings.Contains(s, "万") {
|
||
scale = 1.0
|
||
} else {
|
||
scale = 0.6
|
||
}
|
||
}
|
||
|
||
// 时效系数(用 updated_at)
|
||
freshness := 1.0
|
||
var updatedAt time.Time
|
||
if err := a.pool.QueryRow(ctx,
|
||
`SELECT updated_at FROM objects WHERE type_api_name=$1 AND pk=$2`, typ, pk).Scan(&updatedAt); err == nil {
|
||
days := time.Since(updatedAt).Hours() / 24
|
||
if days < 30 {
|
||
freshness = 1.2
|
||
} else if days < 180 {
|
||
freshness = 1.0
|
||
} else if days < 365 {
|
||
freshness = 0.7
|
||
} else {
|
||
freshness = 0.4
|
||
}
|
||
}
|
||
|
||
// 完整度
|
||
completeness := 1.0
|
||
if c, ok := args["_completeness"].(float64); ok {
|
||
completeness = c
|
||
}
|
||
|
||
value := industryScore * scale * freshness * completeness * 100 // 0~100+ 分
|
||
return map[string]interface{}{
|
||
"value_score": value,
|
||
"components": map[string]interface{}{
|
||
"industry": industryScore,
|
||
"scale": scale,
|
||
"freshness": freshness,
|
||
"completeness": completeness,
|
||
},
|
||
"explanation": fmt.Sprintf("行业(%s)=%.1f × 规模=%.1f × 时效=%.1f × 完整度=%.1f → 估值分 %.1f",
|
||
industry, industryScore, scale, freshness, completeness, value),
|
||
}, nil
|
||
}
|
||
|
||
// fnDeriveCompleteness 计算对象完整度
|
||
func fnDeriveCompleteness(ctx context.Context, a *app, args map[string]interface{}) (map[string]interface{}, error) {
|
||
typ, _ := args["object_type"].(string)
|
||
pk, _ := args["object_pk"].(string)
|
||
if typ == "" || pk == "" {
|
||
return nil, fmt.Errorf("object_type 与 object_pk 必填")
|
||
}
|
||
|
||
// 读 required 属性
|
||
var required []string
|
||
rows, _ := a.pool.Query(ctx, `SELECT api_name FROM properties WHERE object_type_id=(SELECT id FROM object_types WHERE api_name=$1) AND required=true`, typ)
|
||
for rows.Next() {
|
||
var n string
|
||
if rows.Scan(&n) == nil {
|
||
required = append(required, n)
|
||
}
|
||
}
|
||
rows.Close()
|
||
|
||
var propsBytes []byte
|
||
if err := a.pool.QueryRow(ctx, `SELECT properties_json FROM objects WHERE type_api_name=$1 AND pk=$2`, typ, pk).Scan(&propsBytes); err != nil {
|
||
return nil, fmt.Errorf("对象不存在: %w", err)
|
||
}
|
||
props := decodeProps(propsBytes)
|
||
|
||
filled := 0
|
||
missing := []string{}
|
||
for _, r := range required {
|
||
if v, ok := props[r]; ok && v != nil && fmt.Sprintf("%v", v) != "" {
|
||
filled++
|
||
} else {
|
||
missing = append(missing, r)
|
||
}
|
||
}
|
||
comp := 0.0
|
||
if len(required) > 0 {
|
||
comp = float64(filled) / float64(len(required))
|
||
}
|
||
return map[string]interface{}{
|
||
"completeness": comp,
|
||
"filled": filled,
|
||
"required_count": len(required),
|
||
"missing": missing,
|
||
}, nil
|
||
}
|
||
|
||
// invokeFunction 按 api_name 调用(先查 impl_kind)
|
||
func invokeFunction(ctx context.Context, a *app, apiName string, args map[string]interface{}) (map[string]interface{}, error) {
|
||
var implKind, implRef, builtinFn string
|
||
err := a.pool.QueryRow(ctx,
|
||
`SELECT impl_kind, COALESCE(impl_ref,''), COALESCE(builtin_fn,'') FROM function_types WHERE api_name=$1`, apiName).
|
||
Scan(&implKind, &implRef, &builtinFn)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("function_type 不存在: %s", apiName)
|
||
}
|
||
switch implKind {
|
||
case "builtin":
|
||
handler, ok := builtinRegistry[builtinFn]
|
||
if !ok {
|
||
return nil, fmt.Errorf("builtin function %q 未注册", builtinFn)
|
||
}
|
||
return handler(ctx, a, args)
|
||
case "script", "external_api":
|
||
return nil, fmt.Errorf("impl_kind=%s 暂未实现(预留接口;当前只支持 builtin)", implKind)
|
||
default:
|
||
return nil, fmt.Errorf("未知 impl_kind: %s", implKind)
|
||
}
|
||
} |