Files
ssw-ontology/server/handlers_objects.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

474 lines
17 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 (
"errors"
"sort"
"strconv"
"strings"
"github.com/gin-gonic/gin"
)
// ---------- 对象实例 ----------
// maxPageSize 单次返回条数上限。超过请用 offset 翻页;
// 响应里的 total 始终是该查询条件下(已过授权过滤)的真实总数。
const maxPageSize = 1000
// defaultSortClause 全平台统一的实例排序:id 倒序(最新在前)。
// ⚠️ 管理接口(/api/v1/objects)与连接器(/api/v1/connector/objects/:type)必须用同一排序,
// 否则两边翻页时拿到的是不同的记录集(历史上这里一个 DESC 一个 ASC,导致
// "面板上看得到的实例,MCP 里搜不到")。
const defaultSortClause = "ORDER BY id DESC"
// visibilityCond 把 marking 授权过滤下推成 SQL 条件,保证 count 与分页在同一条件下计算。
// 语义与 Authz.CanRead 的 marking 部分一致:对象的所有 marking 都必须在主体 clearance 内;
// 没有任何 marking 的对象视为公开。manager 主体不加限制。
//
// 参数:alias 为对象表别名(如 "o");typeCol/pkCol 为该表中「类型」和「主键」列名,
// 默认 "type_api_name" / "pk"(兼容 objects 表)。
// args 为调用方累积的占位符参数。
// 返回:可直接拼进 WHERE 的条件片段,以及追加后的 args。
func visibilityCond(authz *Authz, alias string, args []interface{}) (string, []interface{}) {
return visibilityCondCols(authz, alias, "type_api_name", "pk", args)
}
// visibilityCondCols 与 visibilityCond 相同,但可指定 type/pk 列名(用于 links 表等)。
func visibilityCondCols(authz *Authz, alias, typeCol, pkCol string, args []interface{}) (string, []interface{}) {
if authz == nil || authz.Principal == "manager" {
return "TRUE", args
}
cls := make([]string, 0, len(authz.Clearances))
for m := range authz.Clearances {
cls = append(cls, m)
}
sort.Strings(cls)
args = append(args, cls)
ph := "$" + strconv.Itoa(len(args))
cond := `NOT EXISTS (SELECT 1 FROM object_markings om
WHERE om.object_type = ` + alias + `.` + typeCol + `
AND om.object_pk = ` + alias + `.` + pkCol + `
AND NOT (om.marking = ANY(` + ph + `::text[])))`
return cond, args
}
// fieldsOf 解析 fields 裁剪参数(逗号分隔)。为空表示不裁剪。
func fieldsOf(s string) []string {
if strings.TrimSpace(s) == "" {
return nil
}
out := []string{}
for _, p := range strings.Split(s, ",") {
if p = strings.TrimSpace(p); p != "" {
out = append(out, p)
}
}
return out
}
// trimProps 按 fields 白名单裁剪属性,减少大结果集的传输量。
// pk / type / name 始终保留;fields 只影响 properties 里的键。
func trimProps(props map[string]interface{}, fields []string) map[string]interface{} {
if len(fields) == 0 || props == nil {
return props
}
out := map[string]interface{}{}
for _, f := range fields {
if v, ok := props[f]; ok {
out[f] = v
}
}
return out
}
func (a *app) listObjects(c *gin.Context) {
typ := c.Query("type")
q := c.Query("q")
limit, _ := strconv.Atoi(c.Query("limit"))
offset, _ := strconv.Atoi(c.Query("offset"))
if limit <= 0 {
limit = 100
}
if limit > maxPageSize {
limit = maxPageSize
}
if offset < 0 {
offset = 0
}
// 管理端默认看全量(含墓碑);传 only_deleted=true 只看墓碑,便于批量清理
fields := fieldsOf(c.Query("fields"))
onlyDeleted := c.Query("only_deleted") == "true"
authz, principal := a.authzOf(c)
args := []interface{}{}
where := "1=1"
if typ != "" {
args = append(args, typ)
where += ` AND o.type_api_name=$` + strconv.Itoa(len(args))
}
if q != "" {
args = append(args, "%"+q+"%")
where += ` AND o.properties_json::text ILIKE $` + strconv.Itoa(len(args))
}
if onlyDeleted {
where += ` AND o.deleted`
}
// 授权过滤下推:total 与 items 用完全相同的 WHERE,避免"先截断再过滤"导致 count 偏小
visCond, visArgs := visibilityCond(authz, "o", args)
visOnly := append([]interface{}{}, visArgs...) // 分级过滤之前的参数快照,用于算被挡掉的量
// 分级过滤下推(issue #5-③):越级记录对当前主体不可见;未配置分级的类型零影响
classCond, visArgs := a.classificationCond(c, authz, "o", visArgs)
fullWhere := where + ` AND ` + visCond + ` AND ` + classCond
// 真实总数(已过授权 + 分级过滤)
var total int64
if err := a.pool.QueryRow(c,
`SELECT count(*) FROM objects o WHERE `+fullWhere, visArgs...).Scan(&total); err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
// 被分级挡掉的条数(只报数不报内容):让管理员知道"还有东西你看不到",
// 而不是默默少几条让人以为数据丢了。
restricted := int64(0)
if classCond != "TRUE" {
var visOnlyTotal int64
if err := a.pool.QueryRow(c,
`SELECT count(*) FROM objects o WHERE `+where+` AND `+visCond, visOnly...).Scan(&visOnlyTotal); err == nil {
restricted = visOnlyTotal - total
}
}
pageArgs := append(append([]interface{}{}, visArgs...), limit, offset)
sqlStr := `SELECT id, object_type_id, type_api_name, pk, properties_json, created_at, updated_at,
COALESCE(deleted,false), COALESCE(same_as,''), COALESCE(classification,'')
FROM objects o WHERE ` + fullWhere + `
` + defaultSortClause + ` LIMIT $` + strconv.Itoa(len(pageArgs)-1) +
` OFFSET $` + strconv.Itoa(len(pageArgs))
rows, err := a.pool.Query(c, sqlStr, pageArgs...)
if err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
defer rows.Close()
var out []Object
for rows.Next() {
var o Object
var props []byte
var deleted bool
var sameAs, cls string
if err := rows.Scan(&o.ID, &o.ObjectID, &o.TypeAPIName, &o.PK, &props, &o.CreatedAt, &o.UpdatedAt, &deleted, &sameAs, &cls); err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
o.Properties = decodeProps(props)
authz.ApplyFieldPolicy(o.TypeAPIName, o.Properties)
a.applyPropertySensitivity(c, authz, o.TypeAPIName, o.Properties)
o.Properties = trimProps(o.Properties, fields)
o.Deleted = deleted
o.SameAs = sameAs
o.Classification = cls
out = append(out, o)
}
if out == nil {
out = []Object{}
}
c.JSON(200, gin.H{
"items": out,
"count": len(out),
"total": total,
"limit": limit,
"offset": offset,
"has_more": offset+len(out) < int(total),
"principal": principal,
"restricted_by_classification": restricted,
})
}
func (a *app) getObject(c *gin.Context) {
typ := c.Param("type")
pk := c.Param("pk")
authz, principal := a.authzOf(c)
o, err := loadObject(c, a.pool, typ, pk)
if err != nil {
c.JSON(404, gin.H{"error": "对象实例不存在"})
return
}
mks := a.loadObjectMarkings(c, typ, pk)
if !authz.CanRead(typ, pk, mks) {
c.JSON(404, gin.H{"error": "对象实例不存在", "principal": principal})
return
}
// 分级拦截(issue #5-③):不泄漏存在性,越级与不存在同样返回 404
if !a.classAllowed(c, authz, typ, o.Classification) {
c.JSON(404, gin.H{"error": "对象实例不存在", "principal": principal})
return
}
if o.Properties != nil {
authz.ApplyFieldPolicy(typ, o.Properties)
a.applyPropertySensitivity(c, authz, typ, o.Properties)
}
c.JSON(200, o)
}
// objectInput 实例写入入参。
//
// 语义(2026-09-05 变更):默认 **merge**,只更新传入字段;
// 传 null 表示删除该字段;replace=true(或 merge=false)才回到旧的全量替换。
type objectInput struct {
Type string `json:"type"`
PK string `json:"pk"`
Properties map[string]interface{} `json:"properties"`
Source string `json:"source"` // 溯源标签(可选);空时保留旧值
SourceTS int64 `json:"source_ts"` // 业务源时间戳(毫秒,可选);比已有值旧则拒绝 stale_write
SameAs string `json:"same_as"` // 别名:非空表示该实例是重复实体,canonical 指向同类型另一个 pk
Deleted *bool `json:"deleted"` // 软删除墓碑标记
Replace bool `json:"replace"` // true = 全量替换(危险,响应会回显被清掉的字段)
Merge *bool `json:"merge"` // 显式 false 等价 replace=true
Via string `json:"via"` // 调用来源标记,便于审计区分 mcp / km_extract / api
// ValidateEnum *bool(issue #5-①):默认校验 properties.enum_values;显式 false 可跳过。
// 批量导入历史脏数据时用 false 放行,再用 /objects/classification/config 查 unknown_values 集中清理。
ValidateEnum *bool `json:"validate_enum"`
// MinClassification(issue #5-⑤):分级下界,非空时该实例的生效分级不低于此值。
// KM 源文件级分级通过这里传导给抽取产物。
MinClassification string `json:"min_classification"`
}
func (a *app) createObject(c *gin.Context) {
var in objectInput
if err := c.ShouldBindJSON(&in); err != nil {
c.JSON(400, gin.H{"error": err.Error()})
return
}
if in.Type == "" || in.PK == "" {
c.JSON(400, gin.H{"error": "type 与 pk 必填"})
return
}
authz, _ := a.authzOf(c)
if !authz.CanWrite("write", in.Type, in.PK) {
a.abortForbidden(c, "无 create 权限")
return
}
replace := in.Replace || (in.Merge != nil && !*in.Merge)
via := in.Via
if via == "" {
via = viaOf(c)
}
skipEnum := in.ValidateEnum != nil && !*in.ValidateEnum
res, err := applyObjectUpsert(c, a.pool, a, objectUpsert{
Type: in.Type, PK: in.PK, Properties: in.Properties, Source: in.Source,
SameAs: in.SameAs, Replace: replace, Deleted: in.Deleted, SourceTS: in.SourceTS,
Actor: a.principalFromRequest(c), Via: via,
MinClassification: in.MinClassification, SkipEnumCheck: skipEnum,
})
if err != nil {
if errors.Is(err, ErrStaleWrite) {
c.JSON(409, gin.H{"error": "stale_write", "detail": err.Error()})
return
}
if strings.HasPrefix(err.Error(), "enum_violation") {
c.JSON(400, gin.H{"error": "enum_violation", "detail": err.Error(),
"hint": "值不在属性声明的 enum_values 内;确认是历史脏数据可带 validate_enum=false 放行"})
return
}
c.JSON(400, gin.H{"error": err.Error()})
return
}
resp := gin.H{
"ok": true, "type": in.Type, "pk": in.PK,
"created": res.Created,
"merged": !replace && !res.Created,
"replaced": replace && !res.Created,
"display_name": res.DisplayName,
"source_ts": res.SourceTS,
"classification": res.Classification,
"added": res.Diff.Added,
"changed": keysOf(res.Diff.Changed),
// ⚠️ 全量替换时,这里会列出被清掉的字段——正是旧版"静默丢数据"的痕迹
"removed": res.Diff.Removed,
}
if res.Diff.empty() && !res.Created {
resp["unchanged"] = true
}
if len(res.PossibleDuplicates) > 0 {
resp["possible_duplicates"] = res.PossibleDuplicates
resp["warning"] = "存在高度相似的已有实例,建议用 same_as 归并或改用已有 pk,避免重复实体"
}
c.JSON(201, resp)
}
func (a *app) updateObject(c *gin.Context) {
typ := c.Param("type")
pk := c.Param("pk")
var in objectInput
if err := c.ShouldBindJSON(&in); err != nil {
c.JSON(400, gin.H{"error": err.Error()})
return
}
authz, _ := a.authzOf(c)
if !authz.CanWrite("write", typ, pk) {
a.abortForbidden(c, "无 write 权限")
return
}
replace := in.Replace || (in.Merge != nil && !*in.Merge)
via := in.Via
if via == "" {
via = viaOf(c)
}
skipEnum := in.ValidateEnum != nil && !*in.ValidateEnum
res, err := applyObjectUpsert(c, a.pool, a, objectUpsert{
Type: typ, PK: pk, Properties: in.Properties, Source: in.Source,
SameAs: in.SameAs, Replace: replace, Deleted: in.Deleted, SourceTS: in.SourceTS,
Actor: a.principalFromRequest(c), Via: via,
MinClassification: in.MinClassification, SkipEnumCheck: skipEnum,
})
if err != nil {
if errors.Is(err, ErrStaleWrite) {
c.JSON(409, gin.H{"error": "stale_write", "detail": err.Error()})
return
}
if strings.HasPrefix(err.Error(), "enum_violation") {
c.JSON(400, gin.H{"error": "enum_violation", "detail": err.Error(),
"hint": "值不在属性声明的 enum_values 内;确认是历史脏数据可带 validate_enum=false 放行"})
return
}
c.JSON(400, gin.H{"error": err.Error()})
return
}
c.JSON(200, gin.H{
"ok": true, "type": typ, "pk": pk,
"created": res.Created, "merged": !replace,
"display_name": res.DisplayName,
"source_ts": res.SourceTS,
"classification": res.Classification,
"added": res.Diff.Added,
"changed": keysOf(res.Diff.Changed),
"removed": res.Diff.Removed,
})
}
// deleteObject 物理删除实例并级联清理其所有关系边。
// 幂等:实例不存在时返回 200 + deleted=false(重复删除不报错)。
// 删除前的属性快照写入 object_changes,可用 POST /objects/:type/:pk/restore 回滚。
// propagate=true(query 或 JSON body):沿 source 溯源传播,把来源文档/连接的全部
// 抽取产物一并清理(Palantir Lineage-Aware Deletion 语义)。默认 false,只回显 source_ref。
func (a *app) deleteObject(c *gin.Context) {
typ := c.Param("type")
pk := c.Param("pk")
authz, _ := a.authzOf(c)
if !authz.CanWrite("delete", typ, pk) {
a.abortForbidden(c, "无 delete 权限")
return
}
propagate := c.Query("propagate") == "true"
if !propagate {
var body struct {
Propagate bool `json:"propagate"`
}
if c.ShouldBindJSON(&body) == nil {
propagate = body.Propagate
}
}
out, err := deleteObjectCascade(c, a, typ, pk, a.principalFromRequest(c), viaOf(c), propagate)
if err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
c.JSON(200, out)
}
func loadObject(c *gin.Context, p dbExec, typ, pk string) (*Object, error) {
var o Object
var props []byte
err := p.QueryRow(c,
`SELECT id, object_type_id, type_api_name, pk, properties_json, created_at, updated_at,
COALESCE(classification,'')
FROM objects WHERE type_api_name=$1 AND pk=$2`, typ, pk).
Scan(&o.ID, &o.ObjectID, &o.TypeAPIName, &o.PK, &props, &o.CreatedAt, &o.UpdatedAt, &o.Classification)
if err != nil {
return nil, err
}
o.Properties = decodeProps(props)
return &o, nil
}
// ---------- 链接实例 ----------
type linkInput struct {
Type string `json:"type"`
SourceType string `json:"source_type"`
SourcePK string `json:"source_pk"`
TargetType string `json:"target_type"`
TargetPK string `json:"target_pk"`
// 边属性(2026-09-05):如任职起止时间、角色、溯源 source
Properties map[string]interface{} `json:"properties"`
Source string `json:"source"`
}
func (a *app) createLink(c *gin.Context) {
var in linkInput
if err := c.ShouldBindJSON(&in); err != nil {
c.JSON(400, gin.H{"error": err.Error()})
return
}
if in.Type == "" || in.SourceType == "" || in.SourcePK == "" || in.TargetType == "" || in.TargetPK == "" {
c.JSON(400, gin.H{"error": "type/source/target 必填"})
return
}
authz, _ := a.authzOf(c)
if !authz.CanWrite("write", in.SourceType, in.SourcePK) || !authz.CanWrite("write", in.TargetType, in.TargetPK) {
a.abortForbidden(c, "无 write 权限创建此链接")
return
}
// 校验类型存在
var cnt int
if err := a.pool.QueryRow(c, `SELECT count(*) FROM link_types WHERE api_name=$1`, in.Type).Scan(&cnt); err != nil || cnt == 0 {
c.JSON(400, gin.H{"error": "链接类型不存在: " + in.Type})
return
}
props := "{}"
if len(in.Properties) > 0 {
props = mustJSON(in.Properties)
}
// 边已存在时:传了 properties 就覆盖,没传则保留(避免重建边把属性洗掉)
_, err := a.pool.Exec(c,
`INSERT INTO links(link_type,source_type,source_pk,target_type,target_pk,properties_json,source)
VALUES($1,$2,$3,$4,$5,$6::jsonb,$7)
ON CONFLICT(link_type,source_type,source_pk,target_type,target_pk) DO UPDATE SET
properties_json = CASE WHEN EXCLUDED.properties_json <> '{}'::jsonb
THEN EXCLUDED.properties_json ELSE links.properties_json END,
source = COALESCE(NULLIF(EXCLUDED.source,''), links.source)`,
in.Type, in.SourceType, in.SourcePK, in.TargetType, in.TargetPK, props, in.Source)
if err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
c.JSON(201, gin.H{"ok": true})
}
func (a *app) deleteLink(c *gin.Context) {
authz, _ := a.authzOf(c)
id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
// 先查链接属于哪些对象
var st, spk, tt, tpk string
if err := a.pool.QueryRow(c, `SELECT source_type, source_pk, target_type, target_pk FROM links WHERE id=$1`, id).Scan(&st, &spk, &tt, &tpk); err == nil {
if !authz.CanWrite("delete", st, spk) || !authz.CanWrite("delete", tt, tpk) {
a.abortForbidden(c, "无 delete 权限")
return
}
}
tag, err := a.pool.Exec(c, `DELETE FROM links WHERE id=$1`, id)
if err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
if tag.RowsAffected() == 0 {
c.JSON(404, gin.H{"error": "链接不存在"})
return
}
c.JSON(200, gin.H{"ok": true})
}