9.3 KiB
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-Principalheader > 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% 空缺"问题。
关键陷阱(踩过的)
-
改前端后必须
./build.sh:main.go:32 //go:embed all:webroot把server/webroot/内嵌进二进制。光替换磁盘文件不生效——必须重新 build Go 二进制。 -
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 §"常见问题"。 -
数据库迁移:所有 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兜底。 -
极简种子:首次启动
seedIfEmpty灌入 1 个对象类型「合作企业」+ 3 条示例。SEED_ON_START=false跳过;管理界面可一键删除。 -
MCP 路径:
/api/v1/mcp走mcpAuth+ 在进程内复用连接器 handler(a.engine),避免 REST 与 MCP 两套授权逻辑漂移。MCP 工具清单当前是硬编码(24 个工具,2026-09-05)——Function 自动注册为 MCP 工具是待办(PLAN.md §5.3)。 -
路径挂载点:
/api/v1/classification/*挂在/ontology组而非/objects组,避免与/objects/:type/:pk参数路由冲突被抢占匹配(main.go:192 注释)。 -
集成测试标签:integration 测试有
//go:build integration(不在默认go test范围)。要跑:go test -tags=integration ./server/...。每个 issue 有对应 issueN_*_test.go。 -
审计日志保留:
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 里写"已实现"以代码为准;写"预留/待办"的就是还没做。