Files
ssw-ontology/server/object_upsert.go
T
admin da73b1091f feat(governance): restore_object 恢复关系边 + 数据分级通用能力 (issue #4 #5)
- #4 restore_object 默认连同关系边恢复:删除级联存边快照(links_snapshot),回滚重建两端在的边、跳过悬空引用,分级从快照物化
- #5 数据分级(不硬编码字段名/级别名):
  - 类型级 classification_property/levels/default 配置 + objects.classification 物化列+索引
  - 读路径按 principal_clearances 下推过滤,越级默认屏蔽且不泄漏存在性(fail-closed)
  - 字段级 properties.sensitivity 越级脱敏为 ***
  - 枚举写入校验(修复变量遮蔽导致的永不拦截 bug):越界值 400 enum_violation
  - 批量重算 recompute(dry_run 默认/apply 落库) + KM 源文件级分级传导
  - MCP +3 工具(get_classification_config/recompute_classification/set_km_classification)
- 分级路由改挂 /ontology 避免与 /objects/:type/:pk 参数路由冲突
- 更新 CHANGELOG 与 INSTANCE_GOVERNANCE.md §15-§16
- 验证:localhost:8081 真实库跑通删→恢复边、分级过滤、枚举拦截、字段脱敏、重算落库
2026-09-07 09:45:02 +08:00

194 lines
7.5 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
import (
"context"
"errors"
"fmt"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgx/v5/pgconn"
)
// dbExec 让 upsert 逻辑既能跑在 *pgxpool.Pool 上,也能跑在事务 pgx.Tx 内。
type dbExec interface {
Exec(ctx context.Context, sql string, args ...interface{}) (pgconn.CommandTag, error)
QueryRow(ctx context.Context, sql string, args ...interface{}) pgx.Row
Query(ctx context.Context, sql string, args ...interface{}) (pgx.Rows, error)
}
type objectUpsert struct {
Type string
PK string
Properties map[string]interface{}
Source string
SameAs string
Replace bool // true = 全量替换(旧行为);false = merge(默认)
Deleted *bool // nil = 不改
Actor string
Via string // api | mcp | km_extract | batch
// SourceTS 业务源时间戳(毫秒)。>0 时启用乱序检查:
// 比已有 source_ts 更旧的写入拒绝(stale_write),旧信息不覆盖新信息。
// 0 = 不提供,不做检查(向后兼容),已有值保留。
SourceTS int64
// SkipDupCheck 批量导入时跳过重复检测(省一次全类型扫描)
SkipDupCheck bool
// MinClassification 分级下界(issue #5-⑤):非空时,实例生效分级不低于该值。
// 典型来源 = KM 源文件的文件级分级;文件的分级只会把产物往高处抬,不覆盖实例自判级。
MinClassification string
// SkipEnumCheck 跳过枚举写入校验(默认校验,见 applyObjectUpsert)
SkipEnumCheck bool
}
// ErrStaleWrite 乱序写入:传入的 source_ts 比已有值旧,写入被拒绝。
var ErrStaleWrite = errors.New("stale_write")
type upsertResult struct {
Created bool
Diff propDiff
PossibleDuplicates []duplicateHit
DisplayName string
SourceTS int64 // 写入后的最终 source_ts(供响应回显)
StaleSkipped bool // true = 本次因乱序被拒绝(仅在 batch 汇总里有意义;单条直接报错)
Classification string // 生效分级(issue #5);空 = 未分级
}
// applyObjectUpsert 统一的实例写入入口(create/update/batch 共用)。
//
// 语义(2026-09-05 变更):
// - 默认 **merge**:只更新传入字段,其余保留。传 null 表示删除该字段。
// - Replace=true 才全量替换(旧行为),响应会回显被覆盖/删除的字段。
//
// 变更原因:此前 create_object 对已有 pk 一律全量替换,一次不完整的 upsert
// 就能把实例打回只剩一两个字段的状态,且无任何痕迹。虽然 9-2/9-3 的数据丢失
// 最终定位为 PGDATA 未持久化(已修),但"全量覆盖"本身仍是危险默认值。
func applyObjectUpsert(ctx context.Context, db dbExec, a *app, in objectUpsert) (*upsertResult, error) {
var oid int64
if err := db.QueryRow(ctx, `SELECT id FROM object_types WHERE api_name=$1`, in.Type).Scan(&oid); err != nil {
return nil, fmt.Errorf("对象类型不存在: %s", in.Type)
}
existing, _ := loadObjectRowDB(ctx, db, in.Type, in.PK)
// 乱序写入检查(Palantir source timestamp 语义):
// 传入业务时间戳比已有值旧 → 旧信息不覆盖新信息,直接拒绝。
if existing != nil && in.SourceTS > 0 && existing.SourceTS > 0 && in.SourceTS < existing.SourceTS {
return nil, fmt.Errorf("%w: 传入 source_ts=%d 早于已有 %d(类型 %s / pk %s)",
ErrStaleWrite, in.SourceTS, existing.SourceTS, in.Type, in.PK)
}
// 写入值:未提供时保留旧值;提供时取 max(同值幂等,重复导入不回退)
newSourceTS := int64(0)
if existing != nil {
newSourceTS = existing.SourceTS
}
if in.SourceTS > newSourceTS {
newSourceTS = in.SourceTS
}
var newProps map[string]interface{}
if existing == nil || in.Replace {
newProps = map[string]interface{}{}
for k, v := range in.Properties {
if v == nil {
continue
}
newProps[k] = v
}
} else {
newProps, _ = mergeProps(existing.Properties, in.Properties)
}
// 枚举写入校验(issue #5-①):properties.enum_values 列一直存在,但写入路径零校验,
// 于是 AI 抽取/批量导入写进去的 "L5"、"未知"、"高保" 之类越界值无人拦截,
// 等到按分级过滤时才发现这些实例落不进任何级别。这里在写入前拦一道。
if !in.SkipEnumCheck {
if err := a.validateEnumProps(ctx, in.Type, in.Properties); err != nil {
return nil, err
}
}
diff := diffProps(propOrEmpty(existing), newProps)
displayName := resolveDisplayName(a.titlePropOf(ctx, in.Type), newProps)
// 分级物化(issue #5-③):真实列 + 索引,读路径才能用 SQL 直接过滤
classification := materializeClassification(a.classConfigOf(ctx, in.Type), newProps, in.MinClassification)
sameAs := in.SameAs
if sameAs == "" && existing != nil {
sameAs = existing.SameAs
}
deleted := false
if in.Deleted != nil {
deleted = *in.Deleted
} else if existing != nil {
deleted = existing.Deleted
}
if _, err := db.Exec(ctx,
`INSERT INTO objects(object_type_id,type_api_name,pk,name,properties_json,source,same_as,deleted,source_ts,classification)
VALUES($1,$2,$3,$4,$5::jsonb,$6,$7,$8,$9,$10)
ON CONFLICT(object_type_id,pk) DO UPDATE SET
name=EXCLUDED.name,
properties_json=EXCLUDED.properties_json,
source=COALESCE(NULLIF(EXCLUDED.source,''), objects.source),
same_as=EXCLUDED.same_as,
deleted=EXCLUDED.deleted,
source_ts=EXCLUDED.source_ts,
classification=EXCLUDED.classification,
updated_at=now()`,
oid, in.Type, in.PK, displayName, mustJSON(newProps), in.Source, sameAs, deleted, newSourceTS, classification); err != nil {
return nil, err
}
action := "update"
created := existing == nil
if created {
action = "create"
}
recordChangeDB(ctx, db, objectChange{
ObjectType: in.Type, ObjectPK: in.PK, Action: action,
Actor: in.Actor, Via: in.Via, Diff: diff, Source: in.Source,
})
res := &upsertResult{Created: created, Diff: diff, DisplayName: displayName, SourceTS: newSourceTS,
Classification: classification}
if created && !in.SkipDupCheck && displayName != "" {
if hits, err := a.findDuplicatesOf(ctx, db, in.Type, displayName, in.PK, 0.9, 5); err == nil {
res.PossibleDuplicates = hits
}
}
return res, nil
}
func propOrEmpty(r *objectRow) map[string]interface{} {
if r == nil {
return map[string]interface{}{}
}
return r.Properties
}
// loadObjectRowDB 与 loadObjectRow 等价,但可在事务内执行。
func loadObjectRowDB(ctx context.Context, db dbExec, typ, pk string) (*objectRow, error) {
var r objectRow
var props []byte
err := db.QueryRow(ctx,
`SELECT id, type_api_name, pk, name, properties_json, COALESCE(source,''), COALESCE(deleted,false), COALESCE(same_as,''), COALESCE(source_ts,0), COALESCE(classification,'')
FROM objects WHERE type_api_name=$1 AND pk=$2`, typ, pk).
Scan(&r.ID, &r.TypeAPIName, &r.PK, &r.Name, &props, &r.Source, &r.Deleted, &r.SameAs, &r.SourceTS, &r.Classification)
if err != nil {
return nil, err
}
r.Properties = decodeProps(props)
return &r, nil
}
// recordChangeDB 与 recordChange 等价,但可写进事务。
func recordChangeDB(ctx context.Context, db dbExec, ch objectChange) {
_, err := db.Exec(ctx,
`INSERT INTO object_changes(object_type,object_pk,action,actor,via,diff,snapshot,source,links_snapshot)
VALUES($1,$2,$3,$4,$5,$6::jsonb,$7::jsonb,$8,$9::jsonb)`,
ch.ObjectType, ch.ObjectPK, ch.Action, ch.Actor, ch.Via,
mustJSON(ch.Diff), snapshotJSON(ch.Snapshot), ch.Source, linksJSON(ch.LinksSnapshot))
if err != nil {
fmt.Printf("[audit] 记录变更失败 %s/%s %s: %v\n", ch.ObjectType, ch.ObjectPK, ch.Action, err)
}
}