一次收口 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]>
659 lines
22 KiB
Go
659 lines
22 KiB
Go
package main
|
||
|
||
// 跨版本结构 diff(2026-11-06 · S4.4)
|
||
//
|
||
// 借鉴 NVIDIA auto-ontology catalog/diff.py 的 diff 原则:
|
||
// 增量 diff **只比源拥有的事实**,明确排除人工撰写的内容
|
||
// ("it is curated in the UI and must survive a re-ingest")。
|
||
//
|
||
// 本仓的对应实现:
|
||
// - 事实底座 = schema_snapshots(每次 schema 变更后落一份全量结构快照)
|
||
// - 比对口径 = 每条结构事实拆成【机器事实】与【人工策展】两组字段,
|
||
// diff 结果逐字段标出 class,汇总里分别计数
|
||
// - 认证位(axioms.certification,2026-11-06 落地)标记「这条已被人工确认」,
|
||
// 其策展字段在 AI 重摄取中被保护(见 ai/ai.go),diff 里单独标出
|
||
//
|
||
// 为什么用全量快照而不是回放 schema_versions 流水:
|
||
// schema_versions 是增量流水(一次变更一行),而 update 语义是 COALESCE 部分更新
|
||
// (见 handlers_ontology.go::updateObjectType),流水里的 after **不是完整状态**
|
||
// ——靠回放重建历史状态必然失真。全量快照让「任意两版本」退化成两次读文件的比较。
|
||
|
||
import (
|
||
"context"
|
||
"encoding/json"
|
||
"fmt"
|
||
"sort"
|
||
"strings"
|
||
)
|
||
|
||
// 结构事实的种类(与 ontology 六元原语对齐)。
|
||
const (
|
||
factKindObjectType = "object_type" // 对象类型
|
||
factKindObjectProp = "object_property" // 对象属性
|
||
factKindLinkType = "link_type" // 链接类型
|
||
factKindLinkProp = "link_property" // 链接属性
|
||
factKindActionType = "action_type" // 动作类型
|
||
)
|
||
|
||
// 字段归属分类:机器事实 vs 人工策展。
|
||
const (
|
||
classMachine = "machine_fact" // 机器事实:结构与配置,重摄取可覆盖
|
||
classCurated = "curated" // 人工策展:人写的文本与认证记录,重摄取须保留
|
||
)
|
||
|
||
// schemaFact 一条结构事实(一个类型 / 属性 / 链接类型 / 链接属性 / 动作类型)。
|
||
//
|
||
// Machine 与 Curated 两组字段互不重叠:前者是「结构与配置」,后者是「人写的内容」。
|
||
type schemaFact struct {
|
||
Kind string `json:"kind"`
|
||
Name string `json:"name"`
|
||
Machine map[string]any `json:"machine"`
|
||
Curated map[string]any `json:"curated"`
|
||
Certified bool `json:"certified"`
|
||
}
|
||
|
||
// schemaFieldChange 一个字段级变更。
|
||
type schemaFieldChange struct {
|
||
Field string `json:"field"`
|
||
Class string `json:"class"` // machine_fact | curated
|
||
Old any `json:"old"`
|
||
New any `json:"new"`
|
||
}
|
||
|
||
// schemaDiffEntry 一条结构事实的差异。
|
||
type schemaDiffEntry struct {
|
||
Kind string `json:"kind"`
|
||
Name string `json:"name"`
|
||
Change string `json:"change"` // added | removed | changed
|
||
Certified bool `json:"certified"`
|
||
Fields []schemaFieldChange `json:"fields,omitempty"`
|
||
}
|
||
|
||
// schemaDiffSummary 差异汇总:机器事实与人工策展分开计数。
|
||
type schemaDiffSummary struct {
|
||
Added int `json:"added"`
|
||
Removed int `json:"removed"`
|
||
Changed int `json:"changed"`
|
||
MachineFactFields int `json:"machine_fact_fields"`
|
||
CuratedFields int `json:"curated_fields"`
|
||
// CertifiedTouched 落在「已认证条目」上的差异条数——这类条目的策展内容
|
||
// 已被声明为受保护(重摄取不覆盖),改动它们需要人工确认。
|
||
CertifiedTouched int `json:"certified_entries_touched"`
|
||
}
|
||
|
||
// schemaDiffReport 跨版本结构 diff 报告。
|
||
type schemaDiffReport struct {
|
||
FromVersion any `json:"from_version"` // int64;0 = 基线
|
||
ToVersion any `json:"to_version"` // int64;"live" = 当前实时结构
|
||
FromLabel string `json:"from_label"`
|
||
ToLabel string `json:"to_label"`
|
||
Summary schemaDiffSummary `json:"summary"`
|
||
Entries []schemaDiffEntry `json:"entries"`
|
||
}
|
||
|
||
// ---------- 采集 ----------
|
||
|
||
// jsonbValue JSONB → 通用 Go 值(读路径统一走它,避免各处分类型不一致)。
|
||
func jsonbValue(raw []byte) any {
|
||
if len(raw) == 0 {
|
||
return nil
|
||
}
|
||
var v any
|
||
if err := json.Unmarshal(raw, &v); err != nil {
|
||
return nil
|
||
}
|
||
return v
|
||
}
|
||
|
||
// splitAxioms 把公理拆成「结构部分」(机器事实)与「认证部分」(人工策展)。
|
||
//
|
||
// 返回:结构部分(map,键与 typeAxioms 的 JSON 键同名)、是否带认证位。
|
||
func splitAxioms(ax *typeAxioms) (map[string]any, bool) {
|
||
structural := map[string]any{}
|
||
if ax == nil {
|
||
return structural, false
|
||
}
|
||
if len(ax.DisjointWith) > 0 {
|
||
structural["disjointWith"] = ax.DisjointWith
|
||
}
|
||
if len(ax.EquivalentTo) > 0 {
|
||
structural["equivalentTo"] = ax.EquivalentTo
|
||
}
|
||
if len(ax.FunctionalLinks) > 0 {
|
||
structural["functionalLinks"] = ax.FunctionalLinks
|
||
}
|
||
if len(ax.InverseOf) > 0 {
|
||
structural["inverseOf"] = ax.InverseOf
|
||
}
|
||
if len(ax.DateOrder) > 0 {
|
||
structural["dateOrder"] = ax.DateOrder
|
||
}
|
||
return structural, ax.Certification != nil
|
||
}
|
||
|
||
// certificationValue 认证位内容(人工策展:无认证位时为 nil)。
|
||
func certificationValue(ax *typeAxioms) any {
|
||
if ax == nil || ax.Certification == nil {
|
||
return nil
|
||
}
|
||
return ax.Certification
|
||
}
|
||
|
||
// captureSchemaFacts 采集当前实时结构(快照与 diff 共用同一份口径)。
|
||
func (a *app) captureSchemaFacts(ctx context.Context) ([]schemaFact, error) {
|
||
facts := []schemaFact{}
|
||
|
||
// ---- 对象类型 ----
|
||
rows, err := a.pool.Query(ctx, `
|
||
SELECT ot.api_name, ot.display_name, COALESCE(ot.description,''), COALESCE(ot.icon,''),
|
||
COALESCE(ot.group_name,''), COALESCE(ot.title_property,''), COALESCE(ot.subtitle_property,''),
|
||
COALESCE(ot.color,''), COALESCE(ot.primary_key,''),
|
||
COALESCE(ot.classification_property,''), COALESCE(ot.classification_levels,'[]'::jsonb),
|
||
COALESCE(ot.classification_default,''), COALESCE(ot.iri,''),
|
||
COALESCE(ot.axioms,'{}'::jsonb), COALESCE(ot.display_name_lang,'{}'::jsonb),
|
||
COALESCE(parent.api_name,'')
|
||
FROM object_types ot LEFT JOIN object_types parent ON ot.parent_id = parent.id`)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
for rows.Next() {
|
||
var (
|
||
apiName, dispName, desc, icon, groupName string
|
||
titleProp, subTitleProp, color, primaryKey string
|
||
clsProp, clsDefault, iri, parentName string
|
||
clsLevels, axiomsRaw, langRaw []byte
|
||
)
|
||
if err := rows.Scan(&apiName, &dispName, &desc, &icon, &groupName, &titleProp,
|
||
&subTitleProp, &color, &primaryKey, &clsProp, &clsLevels, &clsDefault, &iri,
|
||
&axiomsRaw, &langRaw, &parentName); err != nil {
|
||
rows.Close()
|
||
return nil, err
|
||
}
|
||
ax := parseAxiomsLenient(axiomsRaw)
|
||
structural, certified := splitAxioms(ax)
|
||
facts = append(facts, schemaFact{
|
||
Kind: factKindObjectType, Name: apiName, Certified: certified,
|
||
Machine: map[string]any{
|
||
"parent_api_name": parentName,
|
||
"iri": iri,
|
||
"title_property": titleProp,
|
||
"subtitle_property": subTitleProp,
|
||
"primary_key": primaryKey,
|
||
"icon": icon,
|
||
"color": color,
|
||
"group": groupName,
|
||
"classification_property": clsProp,
|
||
"classification_levels": jsonbValue(clsLevels),
|
||
"classification_default": clsDefault,
|
||
"axioms": structural,
|
||
},
|
||
Curated: map[string]any{
|
||
"display_name": dispName,
|
||
"description": desc,
|
||
"display_name_lang": jsonbValue(langRaw),
|
||
"certification": certificationValue(ax),
|
||
},
|
||
})
|
||
}
|
||
rows.Close()
|
||
|
||
// ---- 对象属性 ----
|
||
rows, err = a.pool.Query(ctx, `
|
||
SELECT ot.api_name, p.api_name, p.display_name, p.data_type, p.required,
|
||
COALESCE(p.enum_values,'[]'::jsonb), COALESCE(p.description,''),
|
||
COALESCE(p.format,''), p.default_value, p.indexable, p.vector_index,
|
||
COALESCE(p.backing_column,''), COALESCE(p.sensitivity,''), COALESCE(p.iri,''),
|
||
COALESCE(p.display_name_lang,'{}'::jsonb)
|
||
FROM properties p JOIN object_types ot ON ot.id = p.object_type_id`)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
for rows.Next() {
|
||
var (
|
||
typeName, apiName, dispName, dataType string
|
||
required bool
|
||
enumRaw, defRaw, langRaw []byte
|
||
desc, format, backing, sensitivity, iri string
|
||
indexable, vectorIndex bool
|
||
)
|
||
if err := rows.Scan(&typeName, &apiName, &dispName, &dataType, &required,
|
||
&enumRaw, &desc, &format, &defRaw, &indexable, &vectorIndex,
|
||
&backing, &sensitivity, &iri, &langRaw); err != nil {
|
||
rows.Close()
|
||
return nil, err
|
||
}
|
||
facts = append(facts, schemaFact{
|
||
Kind: factKindObjectProp, Name: typeName + "." + apiName,
|
||
Machine: map[string]any{
|
||
"data_type": dataType,
|
||
"required": required,
|
||
"enum_values": jsonbValue(enumRaw),
|
||
"format": format,
|
||
"default_value": jsonbValue(defRaw),
|
||
"indexable": indexable,
|
||
"vector_index": vectorIndex,
|
||
"backing_column": backing,
|
||
"sensitivity": sensitivity,
|
||
"iri": iri,
|
||
},
|
||
Curated: map[string]any{
|
||
"display_name": dispName,
|
||
"description": desc,
|
||
"display_name_lang": jsonbValue(langRaw),
|
||
},
|
||
})
|
||
}
|
||
rows.Close()
|
||
|
||
// ---- 链接类型 ----
|
||
rows, err = a.pool.Query(ctx, `
|
||
SELECT api_name, display_name, source_type, target_type, cardinality,
|
||
COALESCE(description,''), directional, COALESCE(source_property,''),
|
||
COALESCE(target_property,''), COALESCE(iri,''), COALESCE(display_name_lang,'{}'::jsonb)
|
||
FROM link_types`)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
for rows.Next() {
|
||
var (
|
||
apiName, dispName, srcType, tgtType, cardinality string
|
||
desc, srcProp, tgtProp, iri string
|
||
directional bool
|
||
langRaw []byte
|
||
)
|
||
if err := rows.Scan(&apiName, &dispName, &srcType, &tgtType, &cardinality,
|
||
&desc, &directional, &srcProp, &tgtProp, &iri, &langRaw); err != nil {
|
||
rows.Close()
|
||
return nil, err
|
||
}
|
||
facts = append(facts, schemaFact{
|
||
Kind: factKindLinkType, Name: apiName,
|
||
Machine: map[string]any{
|
||
"source_type": srcType,
|
||
"target_type": tgtType,
|
||
"cardinality": cardinality,
|
||
"directional": directional,
|
||
"source_property": srcProp,
|
||
"target_property": tgtProp,
|
||
"iri": iri,
|
||
},
|
||
Curated: map[string]any{
|
||
"display_name": dispName,
|
||
"description": desc,
|
||
"display_name_lang": jsonbValue(langRaw),
|
||
},
|
||
})
|
||
}
|
||
rows.Close()
|
||
|
||
// ---- 链接属性 ----
|
||
rows, err = a.pool.Query(ctx, `
|
||
SELECT lt.api_name, p.api_name, p.display_name, p.data_type, p.required,
|
||
COALESCE(p.enum_values,'[]'::jsonb), COALESCE(p.description,'')
|
||
FROM link_properties p JOIN link_types lt ON lt.id = p.link_type_id`)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
for rows.Next() {
|
||
var (
|
||
ltName, apiName, dispName, dataType string
|
||
required bool
|
||
enumRaw []byte
|
||
desc string
|
||
)
|
||
if err := rows.Scan(<Name, &apiName, &dispName, &dataType, &required, &enumRaw, &desc); err != nil {
|
||
rows.Close()
|
||
return nil, err
|
||
}
|
||
facts = append(facts, schemaFact{
|
||
Kind: factKindLinkProp, Name: ltName + "." + apiName,
|
||
Machine: map[string]any{
|
||
"data_type": dataType,
|
||
"required": required,
|
||
"enum_values": jsonbValue(enumRaw),
|
||
},
|
||
Curated: map[string]any{
|
||
"display_name": dispName,
|
||
"description": desc,
|
||
},
|
||
})
|
||
}
|
||
rows.Close()
|
||
|
||
// ---- 动作类型 ----
|
||
rows, err = a.pool.Query(ctx, `
|
||
SELECT api_name, display_name, COALESCE(description,''), COALESCE(params,'[]'::jsonb),
|
||
COALESCE(submission_criteria,'{}'::jsonb), COALESCE(side_effects,'{}'::jsonb),
|
||
COALESCE(impl_function_id,0), COALESCE(return_type,''),
|
||
COALESCE(when_to_suggest,'[]'::jsonb), COALESCE(llm_tool_description,'')
|
||
FROM action_types`)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
for rows.Next() {
|
||
var (
|
||
apiName, dispName, desc, retType, llmDesc string
|
||
paramsRaw, criteriaRaw, effectsRaw []byte
|
||
whenRaw []byte
|
||
implFn int64
|
||
)
|
||
if err := rows.Scan(&apiName, &dispName, &desc, ¶msRaw, &criteriaRaw, &effectsRaw,
|
||
&implFn, &retType, &whenRaw, &llmDesc); err != nil {
|
||
rows.Close()
|
||
return nil, err
|
||
}
|
||
facts = append(facts, schemaFact{
|
||
Kind: factKindActionType, Name: apiName,
|
||
Machine: map[string]any{
|
||
"params": jsonbValue(paramsRaw),
|
||
"submission_criteria": jsonbValue(criteriaRaw),
|
||
"side_effects": jsonbValue(effectsRaw),
|
||
"impl_function_id": implFn,
|
||
"return_type": retType,
|
||
"when_to_suggest": jsonbValue(whenRaw),
|
||
},
|
||
Curated: map[string]any{
|
||
"display_name": dispName,
|
||
"description": desc,
|
||
"llm_tool_description": llmDesc,
|
||
},
|
||
})
|
||
}
|
||
rows.Close()
|
||
|
||
sortSchemaFacts(facts)
|
||
return facts, nil
|
||
}
|
||
|
||
// sortSchemaFacts 稳定排序(kind → name),保证快照与 diff 结果确定性。
|
||
func sortSchemaFacts(facts []schemaFact) {
|
||
sort.Slice(facts, func(i, j int) bool {
|
||
if facts[i].Kind != facts[j].Kind {
|
||
return facts[i].Kind < facts[j].Kind
|
||
}
|
||
return facts[i].Name < facts[j].Name
|
||
})
|
||
}
|
||
|
||
// ---------- 比对 ----------
|
||
|
||
// canonicalJSON 归一化取值(用于比较):JSON 编码后字节一致即视为相等。
|
||
//
|
||
// 必要性:实时采集的值是 Go 强类型([]string / int64),快照读回的是通用 JSON 类型
|
||
// ([]any / float64)——按值直接比较会误判为「变了」。
|
||
func canonicalJSON(v any) string {
|
||
if v == nil {
|
||
return "null"
|
||
}
|
||
b, err := json.Marshal(v)
|
||
if err != nil {
|
||
return fmt.Sprintf("%v", v)
|
||
}
|
||
return string(b)
|
||
}
|
||
|
||
// diffSchemaFacts 比对两组结构事实(纯函数,可单测)。
|
||
func diffSchemaFacts(oldFacts, newFacts []schemaFact) []schemaDiffEntry {
|
||
oldIdx := indexSchemaFacts(oldFacts)
|
||
newIdx := indexSchemaFacts(newFacts)
|
||
|
||
keys := make([]string, 0, len(oldIdx)+len(newIdx))
|
||
seen := map[string]bool{}
|
||
for k := range oldIdx {
|
||
if !seen[k] {
|
||
seen[k] = true
|
||
keys = append(keys, k)
|
||
}
|
||
}
|
||
for k := range newIdx {
|
||
if !seen[k] {
|
||
seen[k] = true
|
||
keys = append(keys, k)
|
||
}
|
||
}
|
||
sort.Strings(keys)
|
||
|
||
entries := []schemaDiffEntry{}
|
||
for _, k := range keys {
|
||
of, okO := oldIdx[k]
|
||
nf, okN := newIdx[k]
|
||
switch {
|
||
case okO && okN:
|
||
fields := diffFactFields(of, nf)
|
||
if len(fields) == 0 {
|
||
continue
|
||
}
|
||
entries = append(entries, schemaDiffEntry{
|
||
Kind: nf.Kind, Name: nf.Name, Change: "changed",
|
||
Certified: nf.Certified || of.Certified,
|
||
Fields: fields,
|
||
})
|
||
case okN:
|
||
entries = append(entries, schemaDiffEntry{
|
||
Kind: nf.Kind, Name: nf.Name, Change: "added", Certified: nf.Certified,
|
||
Fields: factFields(nf, classMachine, classCurated, true),
|
||
})
|
||
case okO:
|
||
entries = append(entries, schemaDiffEntry{
|
||
Kind: of.Kind, Name: of.Name, Change: "removed", Certified: of.Certified,
|
||
Fields: factFields(of, classMachine, classCurated, false),
|
||
})
|
||
}
|
||
}
|
||
return entries
|
||
}
|
||
|
||
// indexSchemaFacts 按 kind/name 建索引。
|
||
func indexSchemaFacts(facts []schemaFact) map[string]schemaFact {
|
||
idx := make(map[string]schemaFact, len(facts))
|
||
for _, f := range facts {
|
||
idx[f.Kind+"/"+f.Name] = f
|
||
}
|
||
return idx
|
||
}
|
||
|
||
// diffFactFields 逐字段比对一条事实(机器事实组 + 人工策展组)。
|
||
func diffFactFields(oldF, newF schemaFact) []schemaFieldChange {
|
||
changes := []schemaFieldChange{}
|
||
changes = append(changes, diffFieldGroup(oldF.Machine, newF.Machine, classMachine)...)
|
||
changes = append(changes, diffFieldGroup(oldF.Curated, newF.Curated, classCurated)...)
|
||
sort.Slice(changes, func(i, j int) bool { return changes[i].Field < changes[j].Field })
|
||
return changes
|
||
}
|
||
|
||
// diffFieldGroup 比对同一组字段(机器事实组或人工策展组)。
|
||
func diffFieldGroup(oldM, newM map[string]any, class string) []schemaFieldChange {
|
||
changes := []schemaFieldChange{}
|
||
for field, ov := range oldM {
|
||
nv, ok := newM[field]
|
||
if !ok {
|
||
changes = append(changes, schemaFieldChange{Field: field, Class: class, Old: ov, New: nil})
|
||
continue
|
||
}
|
||
if canonicalJSON(ov) != canonicalJSON(nv) {
|
||
changes = append(changes, schemaFieldChange{Field: field, Class: class, Old: ov, New: nv})
|
||
}
|
||
}
|
||
for field, nv := range newM {
|
||
if _, ok := oldM[field]; !ok {
|
||
changes = append(changes, schemaFieldChange{Field: field, Class: class, Old: nil, New: nv})
|
||
}
|
||
}
|
||
return changes
|
||
}
|
||
|
||
// factFields 展开一条事实的全部字段(新增/删除条目用;added=true 时新值在 New 侧)。
|
||
func factFields(f schemaFact, machineClass, curatedClass string, added bool) []schemaFieldChange {
|
||
changes := []schemaFieldChange{}
|
||
for field, v := range f.Machine {
|
||
if added {
|
||
changes = append(changes, schemaFieldChange{Field: field, Class: machineClass, Old: nil, New: v})
|
||
} else {
|
||
changes = append(changes, schemaFieldChange{Field: field, Class: machineClass, Old: v, New: nil})
|
||
}
|
||
}
|
||
for field, v := range f.Curated {
|
||
if added {
|
||
changes = append(changes, schemaFieldChange{Field: field, Class: curatedClass, Old: nil, New: v})
|
||
} else {
|
||
changes = append(changes, schemaFieldChange{Field: field, Class: curatedClass, Old: v, New: nil})
|
||
}
|
||
}
|
||
sort.Slice(changes, func(i, j int) bool { return changes[i].Field < changes[j].Field })
|
||
return changes
|
||
}
|
||
|
||
// summarizeSchemaDiff 汇总差异(机器事实与人工策展分开计数)。
|
||
func summarizeSchemaDiff(entries []schemaDiffEntry) schemaDiffSummary {
|
||
var s schemaDiffSummary
|
||
for _, e := range entries {
|
||
switch e.Change {
|
||
case "added":
|
||
s.Added++
|
||
case "removed":
|
||
s.Removed++
|
||
case "changed":
|
||
s.Changed++
|
||
}
|
||
if e.Certified {
|
||
s.CertifiedTouched++
|
||
}
|
||
for _, f := range e.Fields {
|
||
if f.Class == classCurated {
|
||
s.CuratedFields++
|
||
} else {
|
||
s.MachineFactFields++
|
||
}
|
||
}
|
||
}
|
||
return s
|
||
}
|
||
|
||
// ---------- 快照存储 ----------
|
||
|
||
// storeSchemaSnapshot 落一份全量结构快照(按版本唯一;重复落覆盖)。
|
||
func (a *app) storeSchemaSnapshot(ctx context.Context, version int64, label string, facts []schemaFact) error {
|
||
b, err := json.Marshal(facts)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
_, err = a.pool.Exec(ctx,
|
||
`INSERT INTO schema_snapshots(version, label, snapshot) VALUES($1,$2,$3::jsonb)
|
||
ON CONFLICT (version) DO UPDATE SET snapshot=EXCLUDED.snapshot, label=EXCLUDED.label, created_at=now()`,
|
||
version, label, string(b))
|
||
return err
|
||
}
|
||
|
||
// loadSchemaSnapshot 读回某版本的结构快照。
|
||
func (a *app) loadSchemaFactsSnapshot(ctx context.Context, version int64) ([]schemaFact, string, error) {
|
||
var (
|
||
raw []byte
|
||
label string
|
||
)
|
||
err := a.pool.QueryRow(ctx,
|
||
`SELECT snapshot, COALESCE(label,'') FROM schema_snapshots WHERE version=$1`, version).
|
||
Scan(&raw, &label)
|
||
if err != nil {
|
||
return nil, "", err
|
||
}
|
||
facts := []schemaFact{}
|
||
if err := json.Unmarshal(raw, &facts); err != nil {
|
||
return nil, "", err
|
||
}
|
||
return facts, label, nil
|
||
}
|
||
|
||
// captureAndStoreSchemaSnapshot 采集实时结构并按版本落快照(跨版本 diff 的底座)。
|
||
func (a *app) captureAndStoreSchemaSnapshot(ctx context.Context, version int64, label string) error {
|
||
facts, err := a.captureSchemaFacts(ctx)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
return a.storeSchemaSnapshot(ctx, version, label, facts)
|
||
}
|
||
|
||
// ensureSchemaBaseline 首次启用结构快照时落一份基线(version=0)。
|
||
//
|
||
// 基线 = 「快照机制启用那一刻的实时结构」——它不是历史某个时刻的真值,
|
||
// 因此标签写明来源,避免被误读成「版本 0 时刻的结构」。
|
||
func (a *app) ensureSchemaBaseline(ctx context.Context) {
|
||
var n int
|
||
if err := a.pool.QueryRow(ctx, `SELECT count(*) FROM schema_snapshots WHERE version=0`).Scan(&n); err != nil {
|
||
return
|
||
}
|
||
if n > 0 {
|
||
return
|
||
}
|
||
facts, err := a.captureSchemaFacts(ctx)
|
||
if err != nil {
|
||
return
|
||
}
|
||
_ = a.storeSchemaSnapshot(ctx, 0, "基线(结构快照机制启用时的实时结构)", facts)
|
||
}
|
||
|
||
// ---------- diff 组装 ----------
|
||
|
||
// parseSchemaVersionParam 解析版本参数:"" / "baseline" → 0(基线),"live" → 实时,其余为整数。
|
||
func parseSchemaVersionParam(s string, allowLive bool) (int64, bool, error) {
|
||
s = strings.TrimSpace(s)
|
||
switch strings.ToLower(s) {
|
||
case "", "baseline", "基线":
|
||
return 0, false, nil
|
||
case "live", "current", "实时":
|
||
if !allowLive {
|
||
return 0, false, fmt.Errorf("该参数不支持 live")
|
||
}
|
||
return 0, true, nil
|
||
}
|
||
var v int64
|
||
if _, err := fmt.Sscanf(s, "%d", &v); err != nil {
|
||
return 0, false, fmt.Errorf("版本参数非法: %q(应为整数、baseline 或 live)", s)
|
||
}
|
||
return v, false, nil
|
||
}
|
||
|
||
// buildSchemaDiffReport 组装 diff 报告。to == nil 表示与当前实时结构比。
|
||
func (a *app) buildSchemaDiffReport(ctx context.Context, from int64, to *int64) (*schemaDiffReport, error) {
|
||
oldFacts, fromLabel, err := a.loadSchemaFactsSnapshot(ctx, from)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("版本 %d 无结构快照(可用的快照版本见 GET /api/v1/ontology/schema/snapshots): %w", from, err)
|
||
}
|
||
if fromLabel == "" {
|
||
fromLabel = fmt.Sprintf("版本 %d 变更后的结构", from)
|
||
}
|
||
|
||
var (
|
||
newFacts []schemaFact
|
||
toLabel string
|
||
)
|
||
if to == nil {
|
||
newFacts, err = a.captureSchemaFacts(ctx)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
toLabel = "当前实时结构"
|
||
} else {
|
||
newFacts, toLabel, err = a.loadSchemaFactsSnapshot(ctx, *to)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("版本 %d 无结构快照(可用的快照版本见 GET /api/v1/ontology/schema/snapshots): %w", *to, err)
|
||
}
|
||
if toLabel == "" {
|
||
toLabel = fmt.Sprintf("版本 %d 变更后的结构", *to)
|
||
}
|
||
}
|
||
|
||
entries := diffSchemaFacts(oldFacts, newFacts)
|
||
report := &schemaDiffReport{
|
||
FromVersion: from,
|
||
ToVersion: "live",
|
||
FromLabel: fromLabel,
|
||
ToLabel: toLabel,
|
||
Summary: summarizeSchemaDiff(entries),
|
||
Entries: entries,
|
||
}
|
||
if to != nil {
|
||
report.ToVersion = *to
|
||
}
|
||
return report, nil
|
||
}
|