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 } } // URI 数据类型写入校验(GB/T 48000.3-2026 附录 A.3):作用于本次写入值 in.Properties, // 与 enum 同策略(部分写只校验本次带的键)。无 validate_uri 后门——uri 是新 opt-in 类型。 if err := a.validateURIProps(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) } }