Files
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

180 lines
7.0 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
// 本体 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, &ltName)
if err != nil {
return nil
}
p.EnumValues = parseStringArray(enum)
m := toMap(p)
if m != nil {
m["link_type"] = ltName
}
return m
}