Files
ssw-ontology/server/functions.go
T
admin e7b39805fb feat(backup): 按 schema 镜像 + 请求级 search_path 切库 (issue #4 #5 后续)
「让客户端敢操作」的关键能力:写前/写后打一份快照 → 任意 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]。
2026-09-07 11:35:47 +08:00

335 lines
11 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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)
}
}