一次收口 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]>
180 lines
7.0 KiB
Go
180 lines
7.0 KiB
Go
package main
|
||
|
||
// 本体 schema 层审计(2026-09-11)
|
||
//
|
||
// 实例级变更已有 object_changes(字段级 diff + 快照),但 schema 层
|
||
// (对象类型 / 属性 / 链接类型 / 链接属性 / 动作类型)此前只有 access_log 的
|
||
// method+path 间接痕迹,没有 before/after 内容 —— 本文件补齐:
|
||
// - 全部 schema 增删改写入 ontology_audit_log(target_pk 落库)
|
||
// - update/delete 记录变更前快照(before),create 记录输入(after)
|
||
// - 同点追加 schema_versions(append-only 全局版本流水,GB/T 48000.3 版本追踪)
|
||
// 失败只打日志,不阻断主流程(与 recordChange 同策略)。
|
||
|
||
import (
|
||
"context"
|
||
"encoding/json"
|
||
"fmt"
|
||
"log"
|
||
|
||
"github.com/gin-gonic/gin"
|
||
)
|
||
|
||
// schemaAudit 写一条 schema 层审计记录。
|
||
func (a *app) schemaAudit(c *gin.Context, action, targetType, targetPK string, details map[string]any) {
|
||
actor := a.principalFromRequest(c)
|
||
if actor == "" {
|
||
actor = "anonymous"
|
||
}
|
||
// 失败仅记日志,绝不阻断 schema 写主流程(与既有策略一致)。
|
||
if _, err := a.schemaAuditVersion(context.Background(), actor, action, targetType, targetPK, details); err != nil {
|
||
log.Printf("[schema_audit] 写入失败 %s %s/%s: %v", action, targetType, targetPK, err)
|
||
}
|
||
}
|
||
|
||
// schemaAuditVersion 写「审计行 + 版本流水行 + 全量结构快照」,返回新版本号(失败时 0)。
|
||
//
|
||
// 与 schemaAudit 的差别只有两点:
|
||
// 1. 不吞错误 —— 调用方(导入事务)需要在审计写失败时整体回滚,
|
||
// 因为 pgx 里一条语句失败后整个事务即进入 aborted 状态,继续写只会连环报错;
|
||
// 2. 显式传 ctx —— 导入时 a.pool 已被换成事务视图,必须用调用方的 ctx 才能落进同一事务。
|
||
func (a *app) schemaAuditVersion(ctx context.Context, actor, action, targetType, targetPK string, details map[string]any) (int64, error) {
|
||
if actor == "" {
|
||
actor = "anonymous"
|
||
}
|
||
if details == nil {
|
||
details = map[string]any{}
|
||
}
|
||
b, _ := json.Marshal(details)
|
||
if _, err := a.pool.Exec(ctx,
|
||
`INSERT INTO ontology_audit_log(actor, action, target_type, target_pk, details, affected_rows)
|
||
VALUES($1,$2,$3,$4,$5::jsonb,$6)`,
|
||
actor, action, targetType, targetPK, string(b), 1); err != nil {
|
||
return 0, fmt.Errorf("写 schema 审计失败: %w", err)
|
||
}
|
||
// 同步追加一条全局单调版本(schema_versions,append-only)。
|
||
// version 列走 DEFAULT 序列(nextval),INSERT 不显式传。
|
||
var ver int64
|
||
if err := a.pool.QueryRow(ctx,
|
||
`INSERT INTO schema_versions(action, target_kind, target_name, actor, details)
|
||
VALUES($1,$2,$3,$4,$5::jsonb) RETURNING version`,
|
||
action, targetType, targetPK, actor, string(b)).Scan(&ver); err != nil {
|
||
return 0, fmt.Errorf("写版本流水失败: %w", err)
|
||
}
|
||
// 版本落定 → 落一份全量结构快照(跨版本 diff 的底座,见 schema_diff.go)。
|
||
// 快照 = 变更「之后」的实时结构,故在审计之后采集。
|
||
if err := a.captureAndStoreSchemaSnapshot(ctx, ver,
|
||
fmt.Sprintf("版本 %d 变更后的结构(%s %s)", ver, action, targetPK)); err != nil {
|
||
return ver, fmt.Errorf("写结构快照失败: %w", err)
|
||
}
|
||
return ver, nil
|
||
}
|
||
|
||
// schemaAuditOnly 只写 ontology_audit_log(不产版本行)。
|
||
//
|
||
// 用于「一次操作改 N 个实体」的场景(本体 schema 导入):逐实体产版本会让
|
||
// schema_snapshots 变成 O(N²) 份全量结构快照,版本流水也会被噪声淹没。
|
||
// 导入的版本策略是「一次导入 = 一个版本 + 一个快照」,实体级明细落审计日志。
|
||
func (a *app) schemaAuditOnly(ctx context.Context, actor, action, targetType, targetPK string, details map[string]any) error {
|
||
if actor == "" {
|
||
actor = "anonymous"
|
||
}
|
||
if details == nil {
|
||
details = map[string]any{}
|
||
}
|
||
b, _ := json.Marshal(details)
|
||
if _, err := a.pool.Exec(ctx,
|
||
`INSERT INTO ontology_audit_log(actor, action, target_type, target_pk, details, affected_rows)
|
||
VALUES($1,$2,$3,$4,$5::jsonb,$6)`,
|
||
actor, action, targetType, targetPK, string(b), 1); err != nil {
|
||
return fmt.Errorf("写 schema 审计失败: %w", err)
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// toMap 结构体 → map(审计 details 用,nil 安全)。
|
||
func toMap(v any) map[string]any {
|
||
if v == nil {
|
||
return nil
|
||
}
|
||
b, err := json.Marshal(v)
|
||
if err != nil {
|
||
return nil
|
||
}
|
||
var m map[string]any
|
||
_ = json.Unmarshal(b, &m)
|
||
return m
|
||
}
|
||
|
||
// objectTypeSnapshot 读取对象类型(含属性)当前状态,作 update/delete 的 before 快照。
|
||
func (a *app) objectTypeSnapshot(c *gin.Context, name string) map[string]any {
|
||
o, err := loadObjectType(c, a.pool, name)
|
||
if err != nil {
|
||
return nil
|
||
}
|
||
return toMap(o)
|
||
}
|
||
|
||
// propertySnapshot 按 properties.id 读取属性当前状态(含所属类型 api_name)。
|
||
func (a *app) propertySnapshot(c *gin.Context, id int64) map[string]any {
|
||
var p Property
|
||
var enum, defVal []byte
|
||
var typeName string
|
||
err := a.pool.QueryRow(c, `
|
||
SELECT p.id, p.object_type_id, p.api_name, p.display_name, p.data_type, p.required,
|
||
p.enum_values, p.description, p.format, p.default_value, p.indexable,
|
||
p.vector_index, p.backing_column, COALESCE(p.sensitivity,''), COALESCE(p.iri,''), ot.api_name
|
||
FROM properties p JOIN object_types ot ON ot.id = p.object_type_id
|
||
WHERE p.id=$1`, id).
|
||
Scan(&p.ID, &p.ObjectID, &p.APIName, &p.DisplayName, &p.DataType, &p.Required,
|
||
&enum, &p.Description, &p.Format, &defVal, &p.Indexable,
|
||
&p.VectorIndex, &p.BackingColumn, &p.Sensitivity, &p.IRI, &typeName)
|
||
if err != nil {
|
||
return nil
|
||
}
|
||
p.EnumValues = parseStringArray(enum)
|
||
p.DefaultValue = jsonRaw(defVal)
|
||
m := toMap(p)
|
||
if m != nil {
|
||
m["object_type"] = typeName
|
||
}
|
||
return m
|
||
}
|
||
|
||
// linkTypeSnapshot 读取链接类型当前状态。
|
||
func (a *app) linkTypeSnapshot(c *gin.Context, name string) map[string]any {
|
||
var l LinkType
|
||
err := a.pool.QueryRow(c, `
|
||
SELECT id, api_name, display_name, source_type, target_type, cardinality,
|
||
COALESCE(description,''), directional, COALESCE(source_property,''), COALESCE(target_property,''), COALESCE(iri,'')
|
||
FROM link_types WHERE api_name=$1`, name).
|
||
Scan(&l.ID, &l.APIName, &l.DisplayName, &l.SourceType, &l.TargetType, &l.Cardinality,
|
||
&l.Description, &l.Directional, &l.SourceProperty, &l.TargetProperty, &l.IRI)
|
||
if err != nil {
|
||
return nil
|
||
}
|
||
return toMap(l)
|
||
}
|
||
|
||
// linkPropertySnapshot 按 link_properties.id 读取链接属性当前状态(含所属链接类型 api_name)。
|
||
func (a *app) linkPropertySnapshot(c *gin.Context, id int64) map[string]any {
|
||
var p LinkProperty
|
||
var enum []byte
|
||
var ltName string
|
||
err := a.pool.QueryRow(c, `
|
||
SELECT p.id, p.link_type_id, p.api_name, p.display_name, p.data_type, p.required,
|
||
p.enum_values, COALESCE(p.description,''), lt.api_name
|
||
FROM link_properties p JOIN link_types lt ON lt.id = p.link_type_id
|
||
WHERE p.id=$1`, id).
|
||
Scan(&p.ID, &p.LinkTypeID, &p.APIName, &p.DisplayName, &p.DataType, &p.Required,
|
||
&enum, &p.Description, <Name)
|
||
if err != nil {
|
||
return nil
|
||
}
|
||
p.EnumValues = parseStringArray(enum)
|
||
m := toMap(p)
|
||
if m != nil {
|
||
m["link_type"] = ltName
|
||
}
|
||
return m
|
||
}
|