Files
ssw-ontology/server/handlers_objects.go
adminandClaude Code d14440a3ed feat(server): v1.8.0 本体导入 + 分区 + 行级归属 + 认证位 + 结构 diff + 分页 + 进度回报
一次收口 2026-11-06 的九项能力(CHANGELOG 1.5.4 → 1.8.0):

- 自检探针(readiness.go):check_readiness / check_answerable 两个只读探针,把
  「本体里没有」「我没权限看」「模型没抽全」三种空结果原因拆开
- 读路径语义钉死(scope.go):标记与分级的可见范围统一由 Scope 产出,实例分级
  为空时继承类型默认级(fail-closed),列表与详情口径一致
- 行级可改性轴(object_owner.go):归属只收窄不宽于 grants,所有对象写路径统一
  走 canWriteObject,归属查询失败即拒绝
- 公理第 6 类 certification:认证位保护人工策展内容,AI 重摄取不再覆盖已认证条目
- 跨版本结构 diff(schema_diff.go):schema_snapshots 全量快照 + diff 端点,机器
  事实与人工策展分组呈现
- 分区维度 zone:分区绑类型、命中任一即可见,读路径一律带 zone 条件
- 统一分页信封(pagination.go):列表回包统一 count/total/limit/offset/has_more/
  truncated,total 与 items 同源
- MCP 长任务进度(mcp_progress.go):客户端带 progressToken 才走 SSE 进度帧
- 本体 schema 导入(ontology_import.go):Turtle 导入 + 四道 fail-fast 闸门 +
  整事务 + (source, external_id) 幂等 + IRI 往返不变式

MCP 工具清单并入单一注册表(mcp_registry.go),对外声明与实际可调不再各说各话;
工具数 42 → 54(只读 27 / 写入 27),注册表与分发 case 的双向漂移由 AST 单测拦截。

CHANGELOG 编号整理:新「认证位 + 行级归属」条目由 1.6.0 改为 1.5.6(1.6.x 留给
分区与结构 diff),2026-09-20 的 GB/T 规划稿改标「规划稿·未发布」——该能力已并入
v1.5.1,避免与正式发布的版本号重复。

Co-Authored-By: Claude Code <[email protected]>
2026-11-06 13:51:48 +08:00

516 lines
19 KiB
Go
Raw Permalink 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"
"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 的可见范围 Scope 决定(见 scope.go):
// 对象的所有 marking 都必须在主体 clearance 内;没有任何 marking 的对象视为公开;
// 主体一条 clearance 都没有 → 什么都看不到(DenyAll),而不是「没有过滤条件所以全放行」。
//
// 参数: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{}) {
return markingCond(markingScope(authz), alias, typeCol, pkCol, 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, classArgs := a.classificationCond(c, authz, "o", visArgs)
classOnly := append([]interface{}{}, classArgs...) // 分区过滤之前的参数快照
// 分区过滤下推(zone,2026-11-06):落在主体无权访问的分区里的类型,其实例整体不可见
zoneCond, visArgs := a.zoneCond(c, authz, "o", "type_api_name", classArgs)
fullWhere := where + ` AND ` + visCond + ` AND ` + classCond + ` AND ` + zoneCond
// 真实总数(已过授权 + 分级 + 分区过滤)
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)
restrictedByZone := int64(0)
if classCond != "TRUE" || zoneCond != "TRUE" {
visOnlyTotal := total
if classCond != "TRUE" {
var n int64
if err := a.pool.QueryRow(c,
`SELECT count(*) FROM objects o WHERE `+where+` AND `+visCond, visOnly...).Scan(&n); err == nil {
visOnlyTotal = n
}
}
classPassTotal := total
if zoneCond != "TRUE" {
var n int64
if err := a.pool.QueryRow(c,
`SELECT count(*) FROM objects o WHERE `+where+` AND `+visCond+` AND `+classCond, classOnly...).Scan(&n); err == nil {
classPassTotal = n
}
}
restricted = visOnlyTotal - classPassTotal
restrictedByZone = classPassTotal - 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{}
}
resp := gin.H{
"items": out,
"principal": principal,
"restricted_by_classification": restricted,
"restricted_by_zone": restrictedByZone,
}
for k, v := range pageEnvelope(len(out), total, limit, offset) {
resp[k] = v
}
c.JSON(200, resp)
}
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
}
// 分区拦截(zone,2026-11-06):分区是授权边界,越区与不存在同样返回 404
if !a.zoneAllowed(c, authz, typ) {
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 !a.canWriteObject(c, authz, "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 !a.canWriteObject(c, authz, "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 !a.canWriteObject(c, authz, "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 !a.canWriteObject(c, authz, "write", in.SourceType, in.SourcePK) ||
!a.canWriteObject(c, authz, "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 !a.canWriteObject(c, authz, "delete", st, spk) || !a.canWriteObject(c, authz, "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})
}