Files
ssw-ontology/server/object_upsert.go
T

204 lines
8.0 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
// SkipAxiomCheck 跳过 dateOrder 等公理写入校验(默认校验,与 SkipEnumCheck 覆盖面一致)。
SkipAxiomCheck 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
}
}
// 公理写入校验(GB/T 48000.3-2026 §8.2):dateOrder 等规则作用于最终属性值。
// 校验 newProps 而非 in.Properties,让 merge / replace 两条路径都按落地值走。
if !in.SkipAxiomCheck {
if err := a.validateDateOrder(ctx, in.Type, newProps); 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)
}
}