Files
ssw-ontology/CLAUDE.md
T

9.3 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.


What this is

通用本体元数据平台(Go + Gin + PostgreSQL + Vue3 + Element Plus)。设计对标 Palantir Ontology:6 元原语(Object / Property / Link / Interface / Action / Function)+ Materialization / Backing Source + Dynamic Security。README.md 与 docs/README.md 有完整能力清单,本文件只挑"读代码不易看出来"的部分。

Commands

# 构建(前端 build → 同步 webroot → go build 注入 -ldflags 版本/Commit/BuildTime)
./build.sh

# 本机启动(自动加载 .env;不存在则参考 .env.example;不存在 bin/server 自动 build)
./run.sh

# 直跑二进制(用 shell 环境覆盖 .env)
DATABASE_URL=postgres://ssw:[email protected]:5432/ssw-ontology?sslmode=disable \
HTTP_PORT=8081 ./bin/server

# 前端单独 dev 模式(vite,监听全部接口)
cd web && npm run dev

# 单元测试
go test ./server/...

# 集成测试(带 //go:build integration 标签:issue6_* / issue7_* / issue8_* /
# snapshot_router_test.go / integration_test.go)
go test -tags=integration ./server/...

# 最小冒烟
curl --noproxy '*' http://127.0.0.1:8081/health
curl --noproxy '*' http://127.0.0.1:8081/api/v1/connector/object-types

Docker 镜像自包含 PG:docker run -d --name ontology -p 8081:8081 -v ~/ontology-data:/data crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/ssw-ontology:1.0.0。本地起 PG:docker compose up -d(jnpf-postgres,端口 15432)。

架构关键事实(读代码才看得出的)

两层模型 + 治理平级

Semantic 层:Object / Property / Link / Interface(描述"有什么/什么状态")。Kinetic 层:Action / Function / Materialization / Backing Source(描述"如何计算/如何变化")。Dynamic Security(Principal + Grant + Marking + FieldPolicy)与对象/链接/动作平级,不建模为业务对象类型——这是早先 DataClassification / AccessControlPolicy 业务对象方案被撤回后的产物(PLAN.md §3.2)。修改时不要新增"安全类对象类型"。

dbRunner 接口(snapshot_router.go)

a.pool 字段类型是 dbRunner 接口(snapshot_router.go:54),实现是 *pgxpool.Pool 和 txPool 两套。snapshotMiddleware 通过 X-Snapshot-Id / X-Snapshot-Ts 头把 a.pool 临时换为事务视图(SET LOCAL search_path TO backups_<id>, public),业务代码 a.pool.Query/Exec 一行不改即命中快照。带快照头的写请求被 403。新代码不要绕过 a.pool(例如直接拿包级 pool 变量)—— 会绕过快照。

主体 / API Key 模型

  • 真源:principals 表。内置主体:manager / connector / public / ingest。
  • 首次启动:seedAccessControlDefaults 为内置主体随机生成 api_key,关键:必须从 stdout 把它们抄下来(生产环境是访问的唯一凭据;UI 重置/清空后旧 key 立即失效)。
  • dev 模式豁免:managerKeySet() 返回 false 时(全新库 + seed 未跑过),匿名请求被视作 manager 主体;一旦 manager 配置了 key,真实鉴权生效,匿名回退为 public(仅 L0 只读)。
  • 优先级:X-Principal header > cookie session > principals.api_key(X-API-Key 或 ?key=)。鉴权由 access_control.go::principalFromRequest 单一入口完成。
  • connectorAuth(main.go:411)v2 起放行任意主体的有效 key(不止 connector),让连接器读路径走真实身份 → Dynamic Security 按真实 clearance 过滤。

实例治理(INSTANCE_GOVERNANCE.md,2026-09-05)

  • create_object 默认 merge(不丢字段);replace=true 才全量替换并回显 removed。merge 模式下 properties:{key:null} 是删除该字段的唯一方式。
  • source_ts < 现存值 → stale_write 丢弃;source_ts=0 跳过乱序检查(向后兼容)。
  • delete_object 级联删边(source 或 target 匹配即删)+ 写 object_changes.snapshot + object_changes.links_snapshot(issue #4),可 restore_object 回滚。
  • objects.deleted 是真实列 + 部分索引;不放 properties_json(避免占业务属性命名空间 + upsert 误洗)。
  • objects.same_as 非空 = 该实例是重复实体,canonical 指向同类型另一 pk。

Schema 审计双轨

  • 实例层 object_changes:字段级 diff(added/removed/changed)+ snapshot + links_snapshot;记录 actor/via/source。
  • Schema 层 ontology_audit_log(2026-09-11,schema_audit.go):对象类型 / 属性 / 链接类型 / 链接属性 / 动作类型 的增删改,update/delete 落 before,create 落 after。失败仅记日志,不阻断主流程。

AI 摄取

  • AI_ENABLED=false 走 ai/heuristic.go(占位/启发式);开启后 AI_BASE_URL 含 /anthropic 走 Anthropic 协议,否则 OpenAI Chat Completions 兼容(DeepSeek / 通义 / Ollama 都可)。
  • ai/prompt.go 系统提示词 250+ 行 + 动态上下文注入:每次 Suggest 前查 DB 拉已注册类型清单追加到 system prompt,让 LLM 复用而非重复创建。
  • 摄取入口 3 类:粘贴文本 /api/v1/ai/ingest、archive 批量 /api/v1/km/extract、数据连接资源 /api/v1/km/connections/:id/import。

内置注册(启动时同步,幂等)

  • 4 个 builtin Function:mask_field_by_policy / compute_object_link_strength / compute_data_asset_value / derive_object_completeness。
  • 6 个 builtin Interface:list_object_types / list_objects / get_object / search_ontology / get_facets / query_related。
  • 物化调度器:启动时开 60s ticker 自动 refresh interval 策略的物化;也可 POST /api/v1/ontology/materializations/:name/refresh 手动触发。

显示名

object_types.title_property 是规范机制;objects.name 是物化缓存。server/display_name.go 回退链:title_property(类型声明) → name → title → real_name → display_name → label。每次 create/update 走 applyObjectUpsert 同步 objects.name 列。新增对象类型后:UPDATE object_types SET title_property='你的显示名属性' WHERE api_name='X'——不配会复现 INSTANCE_GOVERNANCE.md §1 "本库 name 列 45% 空缺"问题。

关键陷阱(踩过的)

  1. 改前端后必须 ./build.sh:main.go:32 //go:embed all:webroot 把 server/webroot/ 内嵌进二进制。光替换磁盘文件不生效——必须重新 build Go 二进制。

  2. ON CONFLICT ... DO UPDATE 必须加 source 兜底(2026-08-24 修复 4 处):source=COALESCE(NULLIF(EXCLUDED.source,''), objects.source)。表名必须限定(objects.source 不能只写 source)——否则 PostgreSQL 报 column reference "source" is ambiguous。出处:PLAN.md §6、docs/README.md §10/§12、IMPORT.md §"常见问题"。

  3. 数据库迁移:所有 schema 都在 server/db.go::migrate() 里用 CREATE TABLE IF NOT EXISTS + ALTER TABLE ADD COLUMN IF NOT EXISTS 幂等写入。没有独立迁移工具——加新表/列直接加到 migrate() 函数体。存量库升级靠 ADD COLUMN IF NOT EXISTS + CREATE INDEX IF NOT EXISTS 兜底。

  4. 极简种子:首次启动 seedIfEmpty 灌入 1 个对象类型「合作企业」+ 3 条示例。SEED_ON_START=false 跳过;管理界面可一键删除。

  5. MCP 路径:/api/v1/mcp 走 mcpAuth + 在进程内复用连接器 handler(a.engine),避免 REST 与 MCP 两套授权逻辑漂移。MCP 工具清单当前是硬编码(24 个工具,2026-09-05)——Function 自动注册为 MCP 工具是待办(PLAN.md §5.3)。

  6. 路径挂载点:/api/v1/classification/* 挂在 /ontology 组而非 /objects 组,避免与 /objects/:type/:pk 参数路由冲突被抢占匹配(main.go:192 注释)。

  7. 集成测试标签:integration 测试有 //go:build integration(不在默认 go test 范围)。要跑:go test -tags=integration ./server/...。每个 issue 有对应 issueN_*_test.go。

  8. 审计日志保留:access_log 默认保留 90 天,ACCESS_LOG_RETENTION_DAYS 覆盖(main.go:113)。

文档与导航

路径 用途
README.md 项目门面 + Docker 启动 + 适用场景
docs/README.md 架构总览 + 6 元原语 + API 全清单 + Palantir 对标
docs/PLAN.md 设计目标 + 演进计划(P1/P2/P3)+ 文档/实现一致性原则
docs/INSTANCE_GOVERNANCE.md 实例治理:merge / 软删除 / 批量 / 审计 / 血统传播 / source_ts
docs/USAGE.md 启动 + 连接器查询 + AI 摄取 实战
docs/IMPORT.md 外部数据源导入
docs/TESTING.md 测试约定
docs/WORKBUDDY.md 一键注册到 WorkBuddy
docs/BACKUP.md 备份与快照路由
docs/STANDARD_GB48000_3_2026_GAP.md GB/T 48000.3-2026《标准数字化 本体建模要求》差距分析:借鉴其通用建模方法(IRI/OWL 导出/schema 版本,已列入 PLAN.md §8 P1),标准领域实体类型(18 类业务类)由采用方建模、不内置(PLAN.md §8"明确不做")
skills/ssw-ontology-reviewer/ 本体差距自动扫描技能(独立 SKILL)

代码状态以代码、schema 和运行接口为准。README/PLAN 里写"已实现"以代码为准;写"预留/待办"的就是还没做。