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

906 lines
29 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
// ---------- 数据分级(2026-09-07,issue #5) ----------
//
// 设计红线:**平台不硬编码 data_level 之类的字段名、也不硬编码 L0~L3 的级别名**。
// 分级被建模成一条通用能力:
//
// 「某个对象类型的某个属性,承载一组有序的级别取值」
//
// 数字孪生本体里的 data_level=L0~L3 只是这套能力的一份配置而已;换成
// 公开/内部/秘密、或 public/internal/confidential 同样能跑。
//
// 三处接线:
// 1. 物化:objects.classification 列 = max(属性分级值, 来源文件分级),写入时算、迁移时回填。
// (沿用 objects.name 显示名物化的既有套路:一个真实列 + 索引,而不是每次现算 JSONB)
// 2. 过滤:读路径(列表/详情/检索/查询/图谱邻居)按主体 clearance 下推 SQL,默认屏蔽越级记录。
// 3. 字段级:properties.sensitivity 声明单个字段的敏感度,越级时对当前主体 redact。
//
// 主体可见上限 = 该类型 levels 里「出现在 principal_clearances 中」的最大下标。
// 未分级(空值)一律视为最低(公开),与 marking「无标记即公开」口径一致。
import (
"context"
"fmt"
"log"
"path/filepath"
"sort"
"strconv"
"strings"
"sync"
"time"
"github.com/gin-gonic/gin"
)
// ---------- 配置模型与缓存 ----------
type classConfig struct {
Property string `json:"classification_property"`
Levels []string `json:"classification_levels"`
Default string `json:"classification_default"`
}
// enabled 该类型是否启用了分级(属性名非空即启用;levels 缺失时退化为「按词汇精确匹配 clearance」)
func (c classConfig) enabled() bool { return c.Property != "" }
var (
classMu sync.RWMutex
classCache = map[string]classConfig{}
classAt = time.Time{}
enumCache = map[string]map[string][]string{} // type -> property -> enum_values
enumAt = time.Time{}
sensCache = map[string]map[string]string{} // type -> property -> sensitivity
)
const classCacheTTL = 60 * time.Second
// loadClassConfigs 载入全部分级配置(含字段级敏感度),结果缓存 60s。
func (a *app) loadClassConfigs(ctx context.Context) (map[string]classConfig, map[string]map[string]string) {
classMu.RLock()
if time.Since(classAt) < classCacheTTL && classCache != nil {
cc, sc := classCache, sensCache
classMu.RUnlock()
return cc, sc
}
classMu.RUnlock()
cfgs := map[string]classConfig{}
sens := map[string]map[string]string{}
if rows, err := a.pool.Query(ctx,
`SELECT api_name, COALESCE(classification_property,''), COALESCE(classification_levels,'[]'::jsonb),
COALESCE(classification_default,'')
FROM object_types`); err == nil {
for rows.Next() {
var t, prop, def string
var lv []byte
if err := rows.Scan(&t, &prop, &lv, &def); err == nil {
cfgs[t] = classConfig{Property: prop, Levels: parseStringArray(lv), Default: def}
}
}
rows.Close()
}
if rows, err := a.pool.Query(ctx,
`SELECT ot.api_name, p.api_name, COALESCE(p.sensitivity,'')
FROM properties p JOIN object_types ot ON ot.id=p.object_type_id
WHERE COALESCE(p.sensitivity,'') <> ''`); err == nil {
for rows.Next() {
var t, p, s string
if err := rows.Scan(&t, &p, &s); err == nil {
if sens[t] == nil {
sens[t] = map[string]string{}
}
sens[t][p] = s
}
}
rows.Close()
}
classMu.Lock()
classCache, sensCache, classAt = cfgs, sens, time.Now()
classMu.Unlock()
return cfgs, sens
}
func (a *app) classConfigOf(ctx context.Context, typ string) classConfig {
cfgs, _ := a.loadClassConfigs(ctx)
return cfgs[typ]
}
// invalidateClassCache 类型/属性定义变更后调用。
// 同时清 classCache / enumCache / axiomsCache / uriCache 四层(共用 classMu)。
func invalidateClassCache() {
classMu.Lock()
classAt = time.Time{}
enumAt = time.Time{}
axiomsAt = time.Time{}
uriAt = time.Time{}
classMu.Unlock()
}
// ---------- 级别计算 ----------
// levelIndex 返回级别在有序级别表里的下标;-1 表示不在表内(未知级别)。
func levelIndex(levels []string, v string) int {
for i, l := range levels {
if l == v {
return i
}
}
return -1
}
// maxLevel 取两个级别里更高的那个。
// 两者都在级别表内 → 比下标;只有一个在表内 → 表内的那个(已知优于未知);
// 都不在表内 → 字典序兜底(保证确定性,且升级配置后仍可通过 recompute 修正)。
func maxLevel(a, b string, levels []string) string {
if a == "" {
return b
}
if b == "" {
return a
}
ia, ib := levelIndex(levels, a), levelIndex(levels, b)
if ia >= 0 && ib >= 0 {
if ia >= ib {
return a
}
return b
}
if ia >= 0 {
return a
}
if ib >= 0 {
return b
}
if a >= b {
return a
}
return b
}
// materializeClassification 计算实例的「生效分级」= max(属性分级值, 来源下界)。
// floor 一般来自 KM 源文件级分级(issue #5-⑤):文件的分级只会把产物往高处抬,不会拉低。
func materializeClassification(cfg classConfig, props map[string]interface{}, floor string) string {
if !cfg.enabled() {
return floor
}
v := propString(props[cfg.Property])
if v == "" {
v = cfg.Default
}
return maxLevel(v, floor, cfg.Levels)
}
// principalMaxIndex 主体在该级别词汇下的可见上限下标。
// manager 恒等于全部;其余主体 = levels 中出现在其 clearance 里的最大下标。
// 完全无交集 → -1(越级全屏蔽,fail-closed:分级一旦启用就不静默失效)。
func principalMaxIndex(authz *Authz, levels []string) int {
if authz == nil || authz.Principal == "manager" {
return len(levels) - 1
}
max := -1
for i, l := range levels {
if authz.Clearances[l] {
max = i
}
}
return max
}
// deniedLevelsFor 某类型对某主体应屏蔽的级别列表。
//
// 由「可见范围 Scope」反推(见 scope.go):可见集合的补集。
// 与该主体与类型级别完全无交集时(ScopeDenyAll),屏蔽全部级别,
// 并额外屏蔽空串「未定义级别」——fail-closed:级别未定义的实例也不放行。
func deniedLevelsFor(authz *Authz, cfg classConfig) []string {
return deniedLevels(levelScope(authz, cfg), cfg.Levels)
}
// ---------- 读路径过滤(issue #5-③④) ----------
// classificationCond 把分级过滤下推成 SQL 条件(与 visibilityCond 同构)。
//
// 未启用分级的类型一律放行,保证「不配置 = 零影响」。
// 实例自身分级为空时**继承类型默认级**(不是「无限制」)。
// 返回 "TRUE" 表示无需过滤(manager 或全库未启用分级),调用方直接拼进 WHERE 即可。
func (a *app) classificationCond(ctx context.Context, authz *Authz, alias string, args []interface{}) (string, []interface{}) {
cfgs, _ := a.loadClassConfigs(ctx)
return classCondSQL(alias, cfgs, authz, args)
}
// classAllowed 单实例分级是否对主体可见(单对象详情用)。
//
// 与 classificationCond 同口径:分级为空 → 继承类型默认级;
// 主体与该类型级别完全无交集 → 该类型的实例一律不可见。
func (a *app) classAllowed(ctx context.Context, authz *Authz, typ, cls string) bool {
if authz == nil || authz.Principal == "manager" {
return true
}
cfg := a.classConfigOf(ctx, typ)
sc := levelScope(authz, cfg)
if sc.IsUnscoped() {
return true
}
if sc.IsDenyAll() {
return false
}
eff := effectiveLevel(cls, cfg)
if eff == "" {
return true // 未定义级别(类型未设默认级)= 公开
}
return sc.Allows(eff)
}
// ---------- 字段级分级(issue #5-②) ----------
// applyPropertySensitivity 按 properties.sensitivity 对越级字段做 redact。
// 与 FieldPolicy 并行生效(FieldPolicy 是「按主体」的精细策略,sensitivity 是「按属性」的声明式分级)。
func (a *app) applyPropertySensitivity(ctx context.Context, authz *Authz, typ string, props map[string]interface{}) {
if props == nil || authz == nil || authz.Principal == "manager" {
return
}
cfgs, sens := a.loadClassConfigs(ctx)
sm := sens[typ]
if len(sm) == 0 {
return
}
cfg := cfgs[typ]
max := principalMaxIndex(authz, cfg.Levels)
for prop, lvl := range sm {
if _, ok := props[prop]; !ok {
continue
}
allowed := true
if len(cfg.Levels) > 0 {
idx := levelIndex(cfg.Levels, lvl)
allowed = idx < 0 || idx <= max
} else {
// 该类型未声明级别表 → 退化为「级别值必须直接出现在主体 clearance 里」
allowed = authz.Clearances[lvl]
}
if !allowed {
props[prop] = "***"
}
}
}
// ---------- 枚举写入校验(issue #5-①) ----------
// loadEnumMap 载入 类型 → 属性 → enum_values(只保留声明了枚举的属性)。
// 子类型合并祖先链 enum(根→自身 overlay,自身覆盖父同名)——读路径一次到位。
func (a *app) loadEnumMap(ctx context.Context) map[string]map[string][]string {
classMu.RLock()
if time.Since(enumAt) < classCacheTTL && enumCache != nil {
m := enumCache
classMu.RUnlock()
return m
}
classMu.RUnlock()
// 第一段:拉声明了枚举的 own 属性(附 parent 名,顺手收集 parentOf)。
out := map[string]map[string][]string{}
parentOf := map[string]string{}
complete := true
rows, err := a.pool.Query(ctx,
`SELECT ot.api_name, p.api_name, COALESCE(p.enum_values,'[]'::jsonb),
COALESCE(pa.api_name,'')
FROM properties p
JOIN object_types ot ON ot.id = p.object_type_id
LEFT JOIN object_types pa ON pa.id = ot.parent_id
WHERE jsonb_array_length(COALESCE(p.enum_values,'[]'::jsonb)) > 0`)
if err != nil {
complete = false
} else {
for rows.Next() {
var t, p, parent string
var ev []byte
if err := rows.Scan(&t, &p, &ev, &parent); err != nil {
complete = false
break
}
vals := parseStringArray(ev)
if len(vals) == 0 {
continue
}
if out[t] == nil {
out[t] = map[string][]string{}
}
out[t][p] = vals
if parent != "" {
parentOf[t] = parent
}
}
if rows.Err() != nil {
complete = false
}
rows.Close()
}
// 第二段:补全 parentOf。第一段只覆盖「自身声明了枚举属性」的类型;
// 有父但自身无枚举的子类型同样要进合并循环,否则继承不到父 enum(校验漏网)。
if prow, perr := a.pool.Query(ctx,
`SELECT ot.api_name, pa.api_name
FROM object_types ot JOIN object_types pa ON pa.id = ot.parent_id`); perr == nil {
for prow.Next() {
var t, pa string
if err := prow.Scan(&t, &pa); err != nil {
complete = false
break
}
parentOf[t] = pa
}
if prow.Err() != nil {
complete = false
}
prow.Close()
} else {
complete = false
}
// 闭包合并:对每个有父类型 t,沿 typeClosure([self, parent, ..., root]) 自近而远
// overlay 祖先 enum;仅填自身缺失的 key(子覆盖父、近祖覆盖远祖)。
for t := range parentOf {
for _, anc := range a.typeClosure(ctx, t) {
if anc == t {
continue
}
eo := out[anc]
if eo == nil {
continue
}
if out[t] == nil {
out[t] = map[string][]string{}
}
for k, v := range eo {
if _, ok := out[t][k]; !ok {
out[t][k] = v
}
}
}
}
// 只在全量读取成功时标 fresh(与 loadTypeAxioms/loadURIProps 同策略):
// 失败的部分结果缓存 60s 会对所有写入方静默关闭 enum 校验(fail-open 跨请求)。
if complete {
classMu.Lock()
enumCache, enumAt = out, time.Now()
classMu.Unlock()
}
return out
}
// validateEnumProps 校验写入值是否落在属性声明的枚举内。
// 只校验「声明了 enum_values 的属性」,其余属性一律放行(不阻断 AI 抽取的自由字段)。
// 返回可直接回给调用方的错误描述。
func (a *app) validateEnumProps(ctx context.Context, typ string, props map[string]interface{}) error {
if len(props) == 0 {
return nil
}
em := a.loadEnumMap(ctx)[typ]
if len(em) == 0 {
return nil
}
var bad []string
keys := make([]string, 0, len(props))
for k := range props {
keys = append(keys, k)
}
sort.Strings(keys)
for _, k := range keys {
allowed, declared := em[k]
if !declared {
continue
}
v := props[k]
if v == nil {
continue // null = 删除字段,不校验
}
s := propString(v)
if s == "" {
continue // 空值 = 未填,不校验(required 是另一套约束)
}
matched := false
for _, a2 := range allowed {
if a2 == s {
matched = true
break
}
}
if matched {
continue
}
bad = append(bad, fmt.Sprintf("%s=%q(允许值: %s)", k, s, strings.Join(allowed, " / ")))
}
if len(bad) > 0 {
return fmt.Errorf("enum_violation: %s", strings.Join(bad, "; "))
}
return nil
}
// ---------- 存量回填 ----------
// backfillClassification 迁移时把 objects.classification 按「属性分级值」回填一次。
// 幂等(只处理空值),不改动 updated_at。
func backfillClassification(ctx context.Context, p dbExec) error {
tag, err := p.Exec(ctx, `
UPDATE objects o SET classification = COALESCE(
NULLIF(o.properties_json->>NULLIF(ot.classification_property,''), ''),
NULLIF(ot.classification_default,'')
)
FROM object_types ot
WHERE ot.id = o.object_type_id
AND COALESCE(o.classification,'') = ''
AND COALESCE(ot.classification_property,'') <> ''
AND COALESCE(
NULLIF(o.properties_json->>NULLIF(ot.classification_property,''), ''),
NULLIF(ot.classification_default,'')
) IS NOT NULL`)
if err != nil {
return fmt.Errorf("分级存量回填失败: %w", err)
}
if tag.RowsAffected() > 0 {
log.Printf("[migrate] 分级存量回填: %d 个实例写入了 classification", tag.RowsAffected())
}
return nil
}
// classConfigSummary 已启用分级的类型摘要,供连接器/MCP 自描述(让调用方知道有哪些级别)。
func (a *app) classConfigSummary(ctx context.Context) map[string]interface{} {
cfgs, _ := a.loadClassConfigs(ctx)
out := map[string]interface{}{}
for t, c := range cfgs {
if !c.enabled() {
continue
}
out[t] = gin.H{"classification_property": c.Property, "classification_levels": c.Levels,
"classification_default": c.Default}
}
return out
}
// validateClassConfig 校验分级配置的形状(不做跨表语义校验)。
// 级别表必须有序、无重复、无空串;指定了级别表却没给承载属性是典型手误。
func validateClassConfig(prop string, levels []string) error {
if prop == "" && len(levels) > 0 {
return fmt.Errorf("分级配置不完整:给了 classification_levels 却没给 classification_property")
}
seen := map[string]bool{}
for _, l := range levels {
if strings.TrimSpace(l) == "" {
return fmt.Errorf("分级配置非法:classification_levels 不能含空级别")
}
if seen[l] {
return fmt.Errorf("分级配置非法:级别 %q 重复", l)
}
seen[l] = true
}
return nil
}
// ---------- KM 源文件级分级(issue #5-⑤) ----------
// propagateSourceClassification 把 KM 源文件的分级传导给它产出的实例。
// 语义:文件的分级是**下界** —— 只会把产物往高处抬,不会覆盖实例自判的更高级别。
// 幂等(可重复执行),返回实际被抬高的实例数。
func (a *app) propagateSourceClassification(c *gin.Context, relPath, level string) int64 {
if relPath == "" || level == "" {
return 0
}
cfgs, _ := a.loadClassConfigs(c)
rows, err := a.pool.Query(c,
`SELECT type_api_name, pk, properties_json, COALESCE(classification,'')
FROM objects WHERE source=$1`, relPath)
if err != nil {
return 0
}
defer rows.Close()
var n int64
for rows.Next() {
var t, pk, old string
var props []byte
if err := rows.Scan(&t, &pk, &props, &old); err != nil {
continue
}
want := materializeClassification(cfgs[t], decodeProps(props), level)
if want == old {
continue
}
if _, err := a.pool.Exec(c,
`UPDATE objects SET classification=$1 WHERE type_api_name=$2 AND pk=$3`, want, t, pk); err != nil {
continue
}
n++
}
return n
}
// kmSetClassification 批量设置 KM 文件级分级,并把分级传导给该文件已产出的实例。
// 用途:整份文档本身是高敏(如合同原件),即使抽出的实体各自没标级,也应按高敏对待。
func (a *app) kmSetClassification(c *gin.Context) {
var in struct {
RelPaths []string `json:"rel_paths"`
Classification string `json:"classification"`
}
if err := c.ShouldBindJSON(&in); err != nil || len(in.RelPaths) == 0 {
c.JSON(400, gin.H{"error": "rel_paths 必填"})
return
}
updated := []string{}
raised := int64(0)
for _, rel := range in.RelPaths {
clean, err := sanitizeRel(rel)
if err != nil {
continue
}
tag, err := a.pool.Exec(c,
`INSERT INTO km_files(rel_path,name,classification)
VALUES($1,$2,$3)
ON CONFLICT(rel_path) DO UPDATE SET classification=EXCLUDED.classification, updated_at=now()`,
clean, filepath.Base(clean), in.Classification)
if err != nil || tag.RowsAffected() == 0 {
continue
}
updated = append(updated, clean)
raised += a.propagateSourceClassification(c, clean, in.Classification)
}
c.JSON(200, gin.H{"ok": true, "updated": updated, "count": len(updated),
"objects_raised": raised,
"message": fmt.Sprintf("已设置 %d 个文件的分级为 %q,并把 %d 个已抽取实例的分级抬到该下界", len(updated), in.Classification, raised)})
}
// ---------- 管理接口:分级配置总览 ----------
// classificationConfig 列出各类型的分级配置 + 实例分布 + 异常取值(不在级别表内的值)。
func (a *app) classificationConfig(c *gin.Context) {
cfgs, sens := a.loadClassConfigs(c)
rows, err := a.pool.Query(c,
`SELECT type_api_name, COALESCE(classification,''), count(*) FROM objects GROUP BY 1,2 ORDER BY 1,2`)
if err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
defer rows.Close()
dist := map[string]map[string]int64{}
for rows.Next() {
var t, cl string
var n int64
if err := rows.Scan(&t, &cl, &n); err == nil {
if dist[t] == nil {
dist[t] = map[string]int64{}
}
dist[t][cl] = n
}
}
type item struct {
APIName string `json:"api_name"`
Enabled bool `json:"enabled"`
Property string `json:"classification_property"`
Levels []string `json:"classification_levels"`
Default string `json:"classification_default"`
Distribution map[string]int64 `json:"distribution"`
Unknown []string `json:"unknown_values,omitempty"`
Sensitivity map[string]string `json:"property_sensitivity,omitempty"`
}
out := []item{}
types := make([]string, 0, len(cfgs))
for t := range cfgs {
types = append(types, t)
}
sort.Strings(types)
for _, t := range types {
cfg := cfgs[t]
it := item{APIName: t, Enabled: cfg.enabled(), Property: cfg.Property,
Levels: cfg.Levels, Default: cfg.Default, Distribution: dist[t]}
if it.Distribution == nil {
it.Distribution = map[string]int64{}
}
for v := range it.Distribution {
if v != "" && len(cfg.Levels) > 0 && levelIndex(cfg.Levels, v) < 0 {
it.Unknown = append(it.Unknown, v)
}
}
sort.Strings(it.Unknown)
if len(sens[t]) > 0 {
it.Sensitivity = sens[t]
}
out = append(out, it)
}
c.JSON(200, gin.H{"items": out, "count": len(out),
"hint": "levels 必须与 principal_clearances 使用同一套词汇,否则主体无任何交集 → 越级全屏蔽"})
}
// ---------- 管理接口:设置对象类型分级配置(v1.3.0) ----------
//
// 历史背景:
// - v1.2.0 加了 object_types.classification_property/_levels/_default 三列,但
// 只读路由 GET /classification/config 暴露,没配对应的 PUT/POST。
// - 后果:MCP 客户端 / 管理员 UI 无法把类型「启用分级」→ 587 个 data_level 实例
// 一直是裸属性,recomputeClassification 看到 enabled=false → 全部「(未分级)」。
// - 这次补 PUT 让管理员能真正写入配置;写完调用 recomputeClassification 把历史
// 裸属性一次性物化进 objects.classification 列。
//
// 设计要点:
// - 仅 manager 主体可调(mgmt.Use(loginRequired, managerAuth) 链已保证)。
// - 校验:levels 必须非空有序(低→高),default ∈ levels,property 是已存在
// 属性的 api_name(不强制强制,但建议对得上;不一致 recompute 会把空当未启用)。
// - 写库后 invalidateClassCache(),让下一次 GET config 立刻反映新值。
// - 不自动 recompute:管理员通常会一次性配齐多个类型后再统一重算;
// 自动重算会让单次 PUT 触发全库扫描 + 数百实例 write,前端体感会卡。
type setObjectTypeClassificationInput struct {
Property string `json:"classification_property"`
Levels []string `json:"classification_levels"`
Default string `json:"classification_default"`
}
// setObjectTypeClassification PUT /api/v1/ontology/object-types/:name/classification
//
// body 示例:
// {
// "classification_property": "data_level",
// "classification_levels": ["L0","L1","L2","L3"],
// "classification_default": "L0"
// }
//
// 响应:新配置快照 + recompute 提示(告诉调用方「下一步调 recompute_classification
// 让历史裸属性一次性物化」)。
func (a *app) setObjectTypeClassification(c *gin.Context) {
name := c.Param("name")
if name == "" {
c.JSON(400, gin.H{"error": "name 必填"})
return
}
var in setObjectTypeClassificationInput
if err := c.ShouldBindJSON(&in); err != nil {
c.JSON(400, gin.H{"error": "body 必须是合法 JSON: " + err.Error()})
return
}
// before 快照(审计用)
before := a.objectTypeSnapshot(c, name)
// 分级配置也是 schema 变更,统一走 ontology_audit_log(仅在成功响应时记录)
defer func() {
if c.Writer.Status() < 400 {
a.schemaAudit(c, "object_type_classification", "object_type", name, map[string]any{"before": before, "after": in})
}
}()
// 关掉分级(property=空)允许 levels=[] 与 default=""
if in.Property == "" {
// property=空直接落库:levels 与 default 都以「空」处理(不会去校验词汇)
if _, err := a.pool.Exec(c,
`UPDATE object_types
SET classification_property='',
classification_levels='[]'::jsonb,
classification_default=''
WHERE api_name=$1`, name); err != nil {
c.JSON(500, gin.H{"error": "关闭分级失败: " + err.Error()})
return
}
invalidateClassCache()
c.JSON(200, gin.H{
"ok": true,
"api_name": name,
"enabled": false,
"classification_property": "",
"classification_levels": []string{},
"classification_default": "",
})
return
}
if len(in.Levels) == 0 {
c.JSON(400, gin.H{"error": "classification_levels 不能为空(property 已设,必须提供级别表)"})
return
}
for _, lv := range in.Levels {
if strings.TrimSpace(lv) == "" {
c.JSON(400, gin.H{"error": "classification_levels 不允许空字符串"})
return
}
}
if in.Default != "" {
ok := false
for _, lv := range in.Levels {
if lv == in.Default {
ok = true
break
}
}
if !ok {
c.JSON(400, gin.H{
"error": "classification_default 必须在 classification_levels 内",
"default": in.Default,
"levels": in.Levels,
"hint": "空字符串代表「不设默认」(写入时该属性缺失则 objects.classification 也为空)",
})
return
}
}
if in.Property != "" {
// 软校验:property 必须属于该类型(attribute-level safety)
var hit int
if err := a.pool.QueryRow(c,
`SELECT count(*) FROM properties p
JOIN object_types ot ON ot.id = p.object_type_id
WHERE ot.api_name=$1 AND p.api_name=$2`, name, in.Property).Scan(&hit); err != nil {
c.JSON(500, gin.H{"error": "校验 property 失败: " + err.Error()})
return
}
if hit == 0 {
c.JSON(400, gin.H{
"error": fmt.Sprintf("类型 %q 没有属性 %q,classification_property 必须指向已存在属性", name, in.Property),
"hint": "留空 = 关闭该类型的分级(enabled=false)",
})
return
}
}
// 落库
if _, err := a.pool.Exec(c,
`UPDATE object_types
SET classification_property=$1,
classification_levels=$2::jsonb,
classification_default=$3
WHERE api_name=$4`,
in.Property, mustJSON(in.Levels), in.Default, name); err != nil {
c.JSON(500, gin.H{"error": "更新分级配置失败: " + err.Error()})
return
}
invalidateClassCache()
enabled := in.Property != ""
c.JSON(200, gin.H{
"ok": true,
"api_name": name,
"enabled": enabled,
"classification_property": in.Property,
"classification_levels": in.Levels,
"classification_default": in.Default,
"next_step": "调用 recompute_classification({type: <this>, dry_run: true}) 验证影响面," +
"再 apply=true 一次性把历史裸属性物化进 objects.classification 列",
})
}
// ---------- 管理接口:批量重算(issue #5-⑩) ----------
type recomputeInput struct {
Type string `json:"type"`
DryRun bool `json:"dry_run"`
Apply bool `json:"apply"`
Limit int `json:"limit"`
}
// recomputeClassification 重算全库(或某类型)的生效分级,默认 dry_run(只看不写)。
//
// 生效分级 = max(属性分级值, 来源文件分级)。典型场景:
// - 刚给类型补上 classification_property,历史实例还没物化;
// - 刚给 KM 源文件打上分级,需要把已有抽取产物一并抬高;
// - 级别表改名/增删后,把旧词汇映射成新词汇(先 dry_run 看影响面)。
func (a *app) recomputeClassification(c *gin.Context) {
var in recomputeInput
_ = c.ShouldBindJSON(&in)
// 安全默认:没显式 apply=true 一律 dry_run
doApply := in.Apply && !in.DryRun
limit := in.Limit
if limit <= 0 || limit > 20000 {
limit = 20000
}
cfgs, _ := a.loadClassConfigs(c)
args := []interface{}{}
where := "1=1"
if in.Type != "" {
args = append(args, in.Type)
where = "o.type_api_name=$1"
}
args = append(args, limit)
rows, err := a.pool.Query(c,
`SELECT o.type_api_name, o.pk, o.properties_json, COALESCE(o.classification,''), COALESCE(k.classification,'')
FROM objects o LEFT JOIN km_files k ON k.rel_path = o.source
WHERE `+where+` ORDER BY o.id LIMIT $`+strconv.Itoa(len(args)), args...)
if err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
defer rows.Close()
type change struct {
Type string `json:"type"`
PK string `json:"pk"`
From string `json:"from"`
To string `json:"to"`
}
var changes []change
scanned, updated := 0, 0
after := map[string]map[string]int64{}
for rows.Next() {
var t, pk, old, floor string
var props []byte
if err := rows.Scan(&t, &pk, &props, &old, &floor); err != nil {
continue
}
scanned++
// 进度回报:全库重算可能上万实例,逐条上报(总数未知,故不带 total)。
reportProgress(c.Request.Context(), float64(scanned), 0, "试算分级 "+t+"/"+pk)
want := materializeClassification(cfgs[t], decodeProps(props), floor)
if after[t] == nil {
after[t] = map[string]int64{}
}
label := want
if label == "" {
label = "(未分级)"
}
after[t][label]++
if want == old {
continue
}
updated++
if len(changes) < 50 {
changes = append(changes, change{Type: t, PK: pk, From: old, To: want})
}
}
resp := gin.H{
"dry_run": !doApply, "type": in.Type, "scanned": scanned, "would_change": updated,
"samples": changes,
"distribution_after": after,
}
if !doApply {
resp["message"] = fmt.Sprintf("试算完成:%d 个实例中 %d 个分级会变化;确认无误后带 apply=true 重放", scanned, updated)
c.JSON(200, resp)
return
}
// 落库(重跑一遍,避免把整个结果集常驻内存)
rows2, err := a.pool.Query(c,
`SELECT o.type_api_name, o.pk, o.properties_json, COALESCE(o.classification,''), COALESCE(k.classification,'')
FROM objects o LEFT JOIN km_files k ON k.rel_path = o.source
WHERE `+where+` ORDER BY o.id LIMIT $`+strconv.Itoa(len(args)), args...)
if err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
defer rows2.Close()
tx, err := a.pool.Begin(c)
if err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
defer tx.Rollback(c)
applied := 0
actor := a.principalFromRequest(c)
processed := 0
for rows2.Next() {
var t, pk, old, floor string
var props []byte
if err := rows2.Scan(&t, &pk, &props, &old, &floor); err != nil {
continue
}
processed++
// 进度回报:落库阶段逐条上报(总数未知,故不带 total)。
reportProgress(c.Request.Context(), float64(processed), 0, "重算分级 "+t+"/"+pk)
want := materializeClassification(cfgs[t], decodeProps(props), floor)
if want == old {
continue
}
if _, err := tx.Exec(c,
`UPDATE objects SET classification=$1 WHERE type_api_name=$2 AND pk=$3`, want, t, pk); err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
applied++
// 分级变更审计(issue #5-⑨):与属性变更同一张表,via 标注重算来源
if applied <= 2000 {
recordChangeDB(c, tx, objectChange{
ObjectType: t, ObjectPK: pk, Action: "update", Actor: actor, Via: "classification_recompute",
Diff: propDiff{Changed: map[string]map[string]interface{}{
"classification": {"from": old, "to": want},
}},
})
}
}
if err := tx.Commit(c); err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
resp["applied"] = applied
resp["message"] = fmt.Sprintf("已重算 %d 个实例的分级(共扫描 %d 个)", applied, scanned)
c.JSON(200, resp)
}