Files
ssw-ontology/server/handlers_objects.go
T

507 lines
18 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"`
// ValidateAxioms *bool(GB/T 48000.3-2026 §8.2):默认校验 dateOrder 等公理;显式 false 可跳过。
// 覆盖面与 ValidateEnum 一致——AI 抽取/历史脏数据可豁免。
ValidateAxioms *bool `json:"validate_axioms"`
// 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
skipAxiom := in.ValidateAxioms != nil && !*in.ValidateAxioms
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,
SkipAxiomCheck: skipAxiom,
})
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
}
if strings.HasPrefix(err.Error(), "axiom_violation") {
c.JSON(400, gin.H{"error": "axiom_violation", "detail": err.Error(),
"hint": "validate_axioms=false 可豁免(同 enum_violation 模式)"})
return
}
if strings.HasPrefix(err.Error(), "uri_violation") {
c.JSON(400, gin.H{"error": "uri_violation", "detail": err.Error(),
"hint": "值需为绝对 URI(http/https/mailto/urn 等)"})
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
skipAxiom := in.ValidateAxioms != nil && !*in.ValidateAxioms
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,
SkipAxiomCheck: skipAxiom,
})
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
}
if strings.HasPrefix(err.Error(), "axiom_violation") {
c.JSON(400, gin.H{"error": "axiom_violation", "detail": err.Error(),
"hint": "validate_axioms=false 可豁免(同 enum_violation 模式)"})
return
}
if strings.HasPrefix(err.Error(), "uri_violation") {
c.JSON(400, gin.H{"error": "uri_violation", "detail": err.Error(),
"hint": "值需为绝对 URI(http/https/mailto/urn 等)"})
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
}
// 功能属性边校验(GB/T 48000.3-2026 §8.2):source 类型闭包内若声明 linkType 为 functional,
// 则同 source 已有指向不同 target 的出边即违例;同 target 重设允许。无 validate_axioms 后门。
if err := a.validateFunctionalLink(c, a.pool, in.Type, in.SourceType, in.SourcePK, in.TargetType, in.TargetPK); err != nil {
c.JSON(400, gin.H{"error": "functional_violation", "detail": err.Error()})
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})
}