diff --git a/.gitignore b/.gitignore index cf48b40..ee05c5e 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ server/webroot/ # 系统与工具数据 .DS_Store .workbuddy/ +ontology-v2.db # 知识文件目录(测试用技术标准/上传文档, 由 docker-compose ARCHIVE_DIR 挂载, 不入库) archive/ diff --git a/CLAUDE.md b/CLAUDE.md index e96128b..f521c03 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,7 +36,7 @@ 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)。 +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.8.0`。本地起 PG:`docker compose up -d`(jnpf-postgres,端口 15432)。 ## 架构关键事实(读代码才看得出的) @@ -44,6 +44,28 @@ Docker 镜像自包含 PG:`docker run -d --name ontology -p 8081:8081 -v ~/ont Semantic 层:Object / Property / Link / Interface(描述"有什么/什么状态")。Kinetic 层:Action / Function / Materialization / Backing Source(描述"如何计算/如何变化")。Dynamic Security(Principal + Grant + Marking + FieldPolicy)**与对象/链接/动作平级**,**不**建模为业务对象类型——这是早先 `DataClassification` / `AccessControlPolicy` 业务对象方案被撤回后的产物(PLAN.md §3.2)。修改时不要新增"安全类对象类型"。 +### 行级可改性轴(object_owners,2026-11-06) + +`clearance` 决定"看不看得到",`owner` 决定"能不能改"——两条轴正交。`grants` 表仍是"能做什么动作"的唯一真源,归属只在 grant 之上**收窄**:对象未设归属 → 行为与从前完全一致(存量库零影响);设有归属 → 非归属方即便持有该类型写授权也不能改这一行。所有对象写路径统一走 `server/object_owner.go::canWriteObject`(create/update/delete/restore/batch/action/链接两端),归属查询失败即拒绝(fail-closed),manager 豁免。归属可为账号或组(`principal_groups`,组权限只对该行生效、不扩大全局权限);归属方可转交行,解除归属仅 manager。REST 在 `/api/v1/ownership/*`(归属方可读写)与 `/api/v1/access/groups`(仅 manager);MCP 工具 `get_object_owners` / `set_object_owners` / `list_groups` / `set_group`。新增写路径时**走 `canWriteObject`,不要直接调 `authz.CanWrite`**——否则绕过归属收窄。 + +### 分区维度(zone,2026-11-06) + +标记/分级管**实例**,分区管**类型**,三者叠加(AND),不是互斥。`server/zone.go` 是判定核心:`zones` / `object_zones` / `principal_zones` 三张表;类型未入任何分区 = 公共区(全体可见),入区后主体须持有该分区才可见;主体零分区 → 所有被分区类型不可见(fail-closed);类型同属多个分区时**命中任一即可见**。分区绑在类型上(不是实例上)——这样一条条件能覆盖**全部**读路径,不会出现"新加的读接口忘了过滤"的旁路;代价是粒度到类型为止。分区只收窄可见性,**不改可改性**(写仍由 grants + `canWriteObject` 决定)。manager 豁免。REST 在 `/api/v1/access/zones`(仅 manager),MCP 工具 `list_zones` / `set_zone` / `delete_zone`。**新增读路径时必须带 `zoneCond`**(列表类)或 `zoneAllowed`(详情类)——`server/zone_integration_test.go::TestIntegration_ZoneEveryReadPathCarriesScope` 会逐条读路径断言探针不泄漏。 + +### 空结果与存在性三态(2026-11-06) + +**空结果必须带原因,「不可见」≠「不存在」。** `server/empty_reason.go`:读路径空回包带 `empty_reason`(`no_data` 真没数据 / `not_visible` 有数据但被标记·分级·分区挡住 / `no_type` 类型未注册 / `not_materialized` 物化没跑 / `no_match` 检索无匹配)。原因只说被哪一维挡住,**不报条数**(条数即存在性泄漏)。`server/existence.go`:三态存在性探针 `GET /api/v1/access/existence?type=&pk=&principal=` + MCP `probe_existence`(**仅 manager**),返回 `exists` / `invisible`(附 `blocked_by`:grant/marking/classification/zone)/ `not_exists`。**读路径对越权实例仍一律 404**——不要为了三态把 404 改成 403/200。 + +### 统一分页信封(pagination.go,2026-11-06) + +所有列表读路径回包带同一套分页字段:`count` / `total` / `limit` / `offset` / `has_more` / `truncated`。**`total` 必须与 `items` 同源**(同一 WHERE,授权·分级·分区过滤都在内)——先过滤再截断;反过来 `total` 偏小,调用方以为翻完了其实后面还有。`has_more` / `truncated` 由 `total` 推导,不按「本页条数 == limit」猜。新增列表读路径时用 `pageEnvelope(count, total, limit, offset)`(`server/pagination.go`),别自己拼字段名。总数用独立 `COUNT` 而非 `count(*) OVER ()`:窗口函数在空页时没有行可返回,`total` 会丢成 0。 + +### MCP 长任务进度(mcp_progress.go,2026-11-06) + +MCP 客户端在超时里会把「没动静」当卡死然后重试,重试叠加负载。长任务因此主动汇报进度,但**客户端显式要才给**:`tools/call` 的 `_meta` 带 `progressToken` + `Accept` 含 `text/event-stream` → 服务端进 SSE 模式,吐 `notifications/progress` 帧后补一条结果帧;**不带 → 走的还是原来那份单响应,行为与从前完全一致**(别为了「统一」把每个请求都 SSE 化)。 + +进度回调挂在 request context 上(`withProgress` / `reportProgress`,`server/mcp_progress.go`)。MCP 层的进程内子请求(`mcpCall` / `callHandler` / `callConn`)**必须继承调用方的 ctx**(`req.WithContext(ctx)`)——否则长任务 handler 里 `reportProgress(c.Request.Context(), ...)` 拿不到回调。新增长任务时:分母明确就给 `total`,事先不可知就只给 `progress`(宁可少给一个字段,也不给猜出来的数)。已有四类:`km_extract` / `backup_create` / `recompute_classification` / `batch_create_objects`。 + ### 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_, public`),业务代码 `a.pool.Query/Exec` 一行不改即命中快照。**带快照头的写请求被 403**。新代码不要绕过 `a.pool`(例如直接拿包级 `pool` 变量)—— 会绕过快照。 @@ -72,11 +94,30 @@ Semantic 层:Object / Property / Link / Interface(描述"有什么/什么状 ### 标准兼容层(GB/T 48000.3-2026,2026-09-20) - `object_types` / `properties` / `link_types` 三表 `iri` 列:值 = `ONTOLOGY_BASE_IRI`(默认 `http://example.org/standard-ontology#`)+ `#` + api_name,**创建即固化**;存量启动回填(`backfillMissingIRI`),旁路写入位点同请求内回填治愈;**配置变更不重写存量、读路径不重算**(用存量列值)。 -- 三个只读端点:`GET /api/v1/ontology/meta`(base_iri/profile/version 自描述)、`GET /api/v1/ontology/export?format=turtle`(单向导出、无导入,其余 format 400)、`GET /api/v1/ontology/versions[/:version]`(版本流水 + 按版本读回旧定义 JSON,**不走快照 search_path 路由**)。 +- 三个只读端点:`GET /api/v1/ontology/meta`(base_iri/profile/version 自描述)、`GET /api/v1/ontology/export?format=turtle`(导出,其余 format 400)、`GET /api/v1/ontology/versions[/:version]`(版本流水 + 按版本读回旧定义 JSON,**不走快照 search_path 路由**)。 + +### 本体 schema 导入(2026-11-06) + +- `POST /api/v1/ontology/import`(Turtle,与导出对称)+ MCP 工具 `ontology_import`。约束见 `docs/ONTOLOGY_IMPORT.md`(**改动前先读**),实现落 `server/ontology_import.go` + `ontology_import_turtle.go`。 +- 四道 fail-fast 闸门按序:G1 根键不匹配 / G2 空文档 / G3 作用域内无实体 / G4 逐实体校验失败——拒绝时响应带 `gate` 字段,**库零变化**。G1–G3 在开事务前拦,G4 在事务内拦(整体回滚)。 +- **整事务**:导入把 `a.pool` 换成 `txPool` 再写(`importMu` 串行化——`a.pool` 是进程级字段,不串行会串库)。回滚时审计与版本流水一起回滚,因为它们也走 `a.pool`。 +- **幂等**:`(source, external_id)` 映射落 `import_identities`(DDL 在 `server/db.go::migrate()`)。同一文档重复导入 = 0 新建 0 更新、**不产新 `schema_versions`**;版本策略是「一次导入一条汇总版本 + 逐实体审计明细」,逐实体产版本会让 `schema_snapshots` 变成 O(N²)。 +- **只支持 `mode=merge`**:`replace`(范围对账删除)明确拒绝,与 append-only 版本流水 + 软删回滚方向相反。 +- 写闸门走 `requireManageLevel`(grants 的 manage 级),**不是 `managerAuth`**——后者写死主体名,与 grants 设计冲突。 +- Turtle 解析器自研:只认本仓导出的那一小子集,集合 `()` / 嵌套空白节点属性列表 `[]` / 多行字符串**遇到即报错**(不能当空文档放行)。 +- **词汇表坑**:RDF Schema 命名空间是 `http://www.w3.org/2000/01/rdf-schema#`(**2000 不是 2001**,导出侧用的是标准值);导入侧常量必须与导出一致,否则 `rdfs:label`/`domain`/`range` 一条都认不出来。 - `schema_versions`:append-only 全局版本流水(`schema_version_seq` 单调),与 schemaAudit 同点挂钩,`details` 与 `ontology_audit_log` 同构。 - **公理声明**(2026-09-20 续):`object_types.axioms JSONB` 五类(disjointWith/equivalentTo/functionalLinks/inverseOf/dateOrder),三层校验(形状/schema/写入),随 Turtle 导出为 OWL 公理。覆盖面 == 枚举校验覆盖面(applyObjectUpsert + createLink/batchCreateLinks);AI ApplySuggestion / KM import / restore / seed 旁路不守约——延续既有局限,与 schemaAudit 覆盖范围一致。 - **类型继承 + 多语 + URI**(同上):`object_types.parent_id` 声明 SubclassOf,属性读路径与写入校验走 `typeClosure` 闭包;`display_name_lang` 三表 + Turtle `@lang` 字面量;`data_type='uri'` 写入校验 + `xsd:anyURI`。单亲继承下等价类/不交类无实例层可达违例,以"声明 + 父子互斥守卫 + OWL 导出"满足(GAP §5.3 不做推理边界)。 +### 跨版本结构 diff(schema_snapshots,2026-11-06) + +- `schema_snapshots`:每次 schema 变更后(`schemaAudit` 落 `schema_versions` 同点)写一份**全量结构**快照,`version` 与 `schema_versions.version` 对齐;`version=0` 是基线(启动时 `ensureSchemaBaseline` 落一次,来源写在 `label` 里,**不是历史某刻的真值**)。 +- 比对:`GET /api/v1/ontology/schema/diff?from=<版本|baseline>&to=<版本|live>`;只能比有快照的版本。覆盖对象类型 / 对象属性 / 链接类型 / 链接属性 / 动作类型。 +- 字段分两类:`machine_fact`(结构与配置)/ `curated`(人写的显示名、描述、多语标签、`certification` 认证记录)——**curated 正是重摄取不许覆盖的那部分**,与认证位共同划出「机器重算不冲掉人工编辑」的边界。 +- **不要改用回放 `schema_versions` 流水重建历史**:流水一次变更一行,且更新走部分更新语义(`after` 不是完整状态),回放出来会掺假。 +- 纯函数在 `server/schema_diff.go`(`diffSchemaFacts` / `summarizeSchemaDiff` / `canonicalJSON`),单测 `schema_diff_test.go`,集成测 `schema_diff_integration_test.go`。 + ### AI 摄取 - `AI_ENABLED=false` 走 `ai/heuristic.go`(占位/启发式);开启后 `AI_BASE_URL` 含 `/anthropic` 走 Anthropic 协议,否则 OpenAI Chat Completions 兼容(DeepSeek / 通义 / Ollama 都可)。 @@ -103,7 +144,7 @@ Semantic 层:Object / Property / Link / Interface(描述"有什么/什么状 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)。 +5. **MCP 路径**:`/api/v1/mcp` 走 `mcpAuth` + 在进程内复用连接器 handler(`a.engine`),避免 REST 与 MCP 两套授权逻辑漂移。工具清单是**单一注册表** `server/mcp_registry.go`(54 个工具,2026-11-06),`tools/list` / annotations / 按名查询均由其派生,分发前按注册表准入——**新增工具改注册表 + `mcpDispatchTool` 的 case,两处都要动**(AST 漂移测试会拦)。**Function 自动注册为 MCP 工具是待办**(PLAN.md §5.3)。 6. **路径挂载点**:`/api/v1/classification/*` 挂在 `/ontology` 组而非 `/objects` 组,避免与 `/objects/:type/:pk` 参数路由冲突被抢占匹配(main.go:192 注释)。 @@ -121,6 +162,7 @@ Semantic 层:Object / Property / Link / Interface(描述"有什么/什么状 | docs/INSTANCE_GOVERNANCE.md | 实例治理:merge / 软删除 / 批量 / 审计 / 血统传播 / source_ts | | docs/USAGE.md | 启动 + 连接器查询 + AI 摄取 实战 | | docs/IMPORT.md | 外部数据源导入 | +| docs/ONTOLOGY_IMPORT.md | 本体导入(schema 级)的设计约束:四道 fail-fast 闸门 / 整事务 / 幂等 / 产生新 `schema_versions` / IRI↔内部 pk 双空间映射。**已实现 2026-11-06**,偏差与实现期修掉的缺陷见文末 §12 | | docs/TESTING.md | 测试约定 | | docs/WORKBUDDY.md | 一键注册到 WorkBuddy | | docs/BACKUP.md | 备份与快照路由 | diff --git a/README.md b/README.md index 01bfb95..d6339f4 100644 --- a/README.md +++ b/README.md @@ -41,13 +41,13 @@ mkdir -p ~/ontology-data/pg ~/ontology-data/archive docker run -d --name ontology -p 8081:8081 \ -v ~/ontology-data:/data --restart unless-stopped \ - crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/ssw-ontology:1.0.0 + crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/ssw-ontology:1.8.0 ``` - 自带 PostgreSQL(容器内 5432,**本体后端映射到宿主机 8081**) - 默认账户:数据库 `ssw-ontology` / 用户 `ssw` / 密码 `ssw` - 挂 `-v /host/x:/data` 后,`/data/pg` 存 PG 数据、`/data/archive` 存文档;不挂则匿名卷,重启丢 -- 健康检查:`wget --spider http://127.0.0.1:8081/api/v1/connector/object-types`,`docker ps` 看 STATUS 是否 `(healthy)` +- 健康检查:`wget --spider http://127.0.0.1:8081/api/v1/version`,`docker ps` 看 STATUS 是否 `(healthy)` - 详见 [Dockerfile](Dockerfile) 与 [docker/entrypoint.sh](docker/entrypoint.sh) ### 方式 B:本机 `./run.sh`(开发用) @@ -78,12 +78,12 @@ docker run ... -e POSTGRES_USER=myuser -e POSTGRES_PASSWORD=mypwd -e POSTGRES_DB # 用自己的目录存 PG(不挂 /data/pg 时这条才生效) docker run -d --name ontology -p 8081:8081 \ -e PGDATA=/var/lib/postgresql/data/myapp \ - crpi-.../ssw188/ssw-ontology:1.0.0 + crpi-.../ssw188/ssw-ontology:1.8.0 # 或结合挂载:让 /data/pg 路径下再分一层 docker run -d --name ontology -p 8081:8081 \ -v ~/pgdata:/var/lib/postgresql/data \ - crpi-.../ssw188/ssw-ontology:1.0.0 + crpi-.../ssw188/ssw-ontology:1.8.0 ``` **连外部 PG**(不跑镜像自带 PG,`-e EXTERNAL_PG=true` 跳过自带 PG 启动): @@ -92,7 +92,7 @@ docker run -d --name ontology -p 8081:8081 \ docker run -d --name ontology -p 8081:8081 \ -e EXTERNAL_PG=true \ -e DATABASE_URL=postgres://user:pwd@host:port/dbname?sslmode=disable \ - crpi-.../ssw188/ssw-ontology:1.0.0 + crpi-.../ssw188/ssw-ontology:1.8.0 ``` 适用场景:连宿主已有的 PG(如 `localhost:15432/shangshu` 的 jnpf-postgres)、其他 PG 容器、外部云库等。`DATABASE_URL` 是 ontology 二进制的连接串(Go 端 `loadConfig` 读取,PGDATA/POSTGRES_USER 等内置 PG 环境变量在外部 PG 模式下被忽略)。 @@ -105,7 +105,7 @@ docker run -d --name ontology -p 8081:8081 \ -e AI_BASE_URL=https://api.minimaxi.com/anthropic \ -e AI_KEY= \ -e AI_MODEL=MiniMax-M3 \ - crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/ssw-ontology:1.0.0 + crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/ssw-ontology:1.8.0 ``` - URL 含 `/anthropic` 子串 → Anthropic Messages 协议;其余按 OpenAI Chat Completions 兼容协议(DeepSeek / 通义千问 / Ollama 等均可) - 4 个变量必须全设;只设 KEY 但 `AI_ENABLED=false` 仍走启发式 @@ -115,7 +115,14 @@ docker run -d --name ontology -p 8081:8081 \ **本地构建镜像**(如需): ```bash -docker build --provenance=false --sbom=false -t ontology:1.0.0 . +# 1) 先编 Linux 静态二进制(Dockerfile 从 bin/server-linux 取产物) +VERSION=$(git describe --tags --always --dirty) +CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \ + -ldflags "-s -w -X main.Version=${VERSION} -X main.Commit=$(git rev-parse --short HEAD) -X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + -o bin/server-linux ./server + +# 2) 再打镜像 +docker build --provenance=false --sbom=false -t ontology:1.8.0 . ``` > `--provenance=false --sbom=false` 是推私仓的前提:buildx 默认附带的 attestation manifest > 私仓不认,本地 build 正常但 push 会报 `unknown manifest class`。详见 `Dockerfile` 头部注释。 diff --git a/docs/ONTOLOGY_IMPORT.md b/docs/ONTOLOGY_IMPORT.md new file mode 100644 index 0000000..dd21959 --- /dev/null +++ b/docs/ONTOLOGY_IMPORT.md @@ -0,0 +1,302 @@ +# 本体导入设计约束(S3 · 文档先行) + +> **状态:已实现(2026-11-06)。** +> 本文件不是需求描述,是「实现导入功能时必须满足的硬约束」。 +> 每一条都对应一个已知的失败模式;实现时若要改某条,先改本文件并说明理由。 +> 实现落点与偏差见文末 §12「实现落地」。 + +导出已有(`GET /api/v1/ontology/export?format=turtle`,单向),导入没有。 +「导出 → 导入」闭环一旦补上,导入就是本仓**最大的事故面**:一次误导入可以清空或污染整个语义目录, +而语义目录是所有下游(连接器读路径、MCP 工具、AI 摄取、GR 兼容层)的地基。 +所以约束先写死,成本最低。 + +--- + +## 0. 参照与差异 + +参照 NVIDIA auto-ontology 的 `server/model_interchange`(导入)与 `dal/model_interchange.py`。 +它的核心判据(`service.py:82-92`): + +> Only a root holding Auto Ontology's own keys is read as native. Anything else goes to the +> Ossie converter, which rejects what it cannot read; read as native, it would validate as an +> empty document, and an import with `replace` would then wipe the catalog. + +即:**读不出来就拒绝,绝不当成空文档**。本仓据此定出 §2 的三重闸门。 + +与 NVIDIA 的差异(本仓明确不照抄的部分): + +| NVIDIA | 本仓 | 理由 | +|---|---|---| +| 范围对账删除(范围内但载荷里没有的语义要删) | **不做** | 见 §7 | +| `column_id` ↔ `column_live_id` 双空间映射 | IRI ↔ 内部 pk 双空间映射 | 本仓的稳定标识是 IRI,不是导入方的列 id,见 §6 | +| 整事务导入 | 整事务导入(**照做**) | 见 §3 | +| `coalesce(imported_id, id)` 幂等 | `(source, external_id)` 幂等键 | 见 §4 | + +--- + +## 1. 失败模式清单(约束的来源) + +| # | 失败模式 | 后果 | 对应约束 | +|---|---|---|---| +| F1 | 空文档 / 读不出来的文档被当成合法文档 | `replace` 语义下清空目录 | §2 · G2 | +| F2 | 根键不匹配仍「尽力解析」 | 把别人的 schema 当成本仓的写进库 | §2 · G1 | +| F3 | 范围参数写错,范围内一个实体都没有 | 静默导入 0 条,看起来「成功」 | §2 · G3 | +| F4 | 导入中途失败 | 目录里一半新语义一半旧语义 | §3 | +| F5 | 同一文档导入两次 | 重复建类型 / 重复建属性 | §4 | +| F6 | 就地覆盖,不记版本 | 版本流水断掉,无法回答「这份 schema 什么时候变的」 | §5 | +| F7 | IRI 漂移 | 导出再导入后 IRIs 变了,外部引用全部失效 | §6 | +| F8 | 悬空边(link 的 source/target 指向不存在的类型) | 图谱查询报错 | §6 | + +--- + +## 2. 三重 fail-fast 校验(准入闸门) + +**顺序固定:G1 → G2 → G3 → 才允许开事务、才允许有任何写操作。** + +### G1 · 根键匹配 + +文档根必须携带本仓的标识键,否则**整体拒绝**(不是「尽力解析后导入能认的那部分」)。 + +- 判定依据:Turtle 根 ` a owl:Ontology`(与 `buildTurtle` 输出一致), + 或等价的 JSON 载荷里的 `ontology_root` 键。 +- 根 IRI 的 base 必须落在本仓 `ONTOLOGY_BASE_IRI` 命名空间内,或载荷显式声明目标命名空间。 +- 拒绝时返回明确的诊断(缺哪个键 / 根 IRI 是什么),**不回退到「当成空文档」**。 + +### G2 · 文档非空 + +解析结果为空 → 拒绝。**空文档绝不进导入流程**——这是 F1 的直接堵口。 + +- 空 = 没有任何类型、没有链接类型、没有属性。 +- 只含公理声明(`owl:disjointWith` 等)而无实体:也算空 → 拒绝(公理依附于类型,无类型无公理可落)。 + +### G3 · 作用域内必须有实体 + +导入声明的作用域内至少有一个实体,否则拒绝。 + +- 作用域 = 载荷声明的命名空间 / base IRI 前缀。 +- 拒绝的理由是操作面:G1/G2 拦的是「文档不对」,G3 拦的是「**参数写错了**」—— + 例如把作用域写成 `http://example.org/other#`,而库里没有该命名空间的类型, + 此时静默导入 0 条会让调用方误以为导入成功。 + +### G4(附加)· 逐实体校验失败即整体拒绝 + +不设「部分成功」模式。一个实体校验不过 → 整个导入拒绝(库保持导入前状态)。 +若将来需要「尽力导入」,那是另一个端点(`mode=best_effort`),必须显式指定且逐条报告。 + +--- + +## 3. 整事务导入 + +- **整个导入在一个事务里**。任一实体失败 → 回滚,库保持导入前状态(不留半截语义)。 +- 事务通过 `a.pool`(`dbRunner` 接口)取得,**不得绕过 `a.pool`**: + - 绕过 `a.pool` 会让快照路由(`X-Snapshot-Id` / `X-Snapshot-Ts`)失效; + - 写请求带快照头一律 403(`snapshot_router.go`),导入是写操作,故带快照头的导入必须被拒。 +- 复用现成写路径,不另起炉灶:类型 / 属性 / 链接类型走 `applyObjectUpsert` 与现有 handler, + 实例走 `create_object` 的 merge 语义(**禁用 `replace:true`**)。 + +### 审计与回滚的分工(重要) + +| 写入 | 失败时 | 理由 | +|---|---|---| +| 公理良构校验(`validateAxiomsWellFormed`) | **必须阻断 → 回滚** | 公理非法 = schema 自相矛盾,落库就是脏数据 | +| URI 数据类型校验(`property_uri_check.go`) | **必须阻断 → 回滚** | 同上 | +| `schemaAudit` / `schema_versions` 写入 | 仅记日志,**不阻断** | 既有约定:审计失败不该让业务写失败 | +| 实例层 `object_changes` | 仅记日志,不阻断 | 同上 | + +注意事务内的 `schemaAudit` 用 `context.Background()` 调 `a.pool.Exec`—— +在事务视图下它会落在同一事务里(`a.pool` 已被换成 `txPool`),回滚时一起回滚。 +这一点依赖「审计也走 `a.pool`」的实现细节,实现时**不得**给审计另开连接,否则回滚后审计会留下 +「记录了但其实没导入」的假账。 + +--- + +## 4. 幂等 + +- 每个导入实体带**外部稳定标识**:`(source, external_id)`。 + - `source`:导入来源的命名空间(如 `gbt48000`、`partner-x`); + - `external_id`:来源侧对该实体的稳定 id(不是显示名,显示名会改)。 +- 已存在映射 → **更新**该实体,不新建;不存在 → 新建并写映射。 +- 幂等键约束:`(source, external_id)` 唯一。 +- 同一文档导入两次,第二次必须产生「0 新建 / N 更新 / 0 重复」的结果, + 且**不产生新的 `schema_versions` 行**(因为语义没变)——见 §5。 + +### 映射表 + +新增一张表(不塞进 `objects.properties_json`——那是业务属性命名空间): + +``` +import_identities( + source TEXT NOT NULL, + external_id TEXT NOT NULL, + kind TEXT NOT NULL, -- object_type / property / link_type / link_property + target_kind TEXT NOT NULL, -- 对应本仓类型 + target_name TEXT NOT NULL, -- 对应本仓 api_name + iri TEXT NOT NULL, -- 对外稳定标识(§6) + imported_at TIMESTAMPTZ DEFAULT now(), + PRIMARY KEY (source, external_id, kind) +) +``` + +DDL 落点:与其他 schema 一样写进 `server/db.go::migrate()`,用 +`CREATE TABLE IF NOT EXISTS` 幂等建表(本仓无独立迁移工具,见 `CLAUDE.md` 陷阱 3)。 + +--- + +## 5. 导入必须产生新的 `schema_versions` 行 + +- `schema_versions` 是 **append-only 全局单调流水**(`schema_version_seq`),现有 schema 变更 + 已经通过 `schemaAudit` 同点挂钩写入。 +- **导入不得绕过 `schemaAudit`**——绕过即版本流水断点,无法回答「这份 schema 是什么时候变的」。 +- 一次导入事件产生 **≥1 条** `schema_versions` 行: + - 建议 1 条汇总行(`action='import'`, `target_kind='ontology'`, `details` 里带受影响的类型清单、 + 导入来源、幂等键统计), + - 外加每个受影响实体的明细行(沿用现有 `create`/`update` 词表,`details` 与 + `ontology_audit_log.details` 同构)。 +- **导入不是「就地覆盖」**:语义是「把这一版 schema 的定义落进来」,历史版本流水保留。 + 已有类型的属性被移除时,走 `delete` 语义记审计(`schemaAudit` 的 update/delete 落 before 快照), + 而不是物理删表行——现有 schema 删除路径已经这么做了。 + +--- + +## 6. IRI ↔ 内部 pk 双空间映射 + +- 本仓的**对外稳定标识是 IRI**(`object_types.iri` / `properties.iri` / `link_types.iri`, + 值 = `ONTOLOGY_BASE_IRI` + `#` + api_name,**创建即固化**;配置变更不重写存量,读路径不重算)。 +- 内部标识是 `api_name`(唯一键)与库内自增 `id`。 +- 导入必须同时维护两个方向: + - 文档 IRI → 本仓 api_name(写路径用); + - 本仓 api_name → 文档 IRI(回给调用方 / 导出用)。 +- 载体就是 §4 的 `import_identities`(含 `iri` 列),**不需要第二张表**。 + +### 两个必须注意的坑 + +1. **IRI 不是主键**:`properties.iri` 按属性名全局拼接,**同名属性跨类型共享同一个 IRI** + (OWL 语义上成立)。所以导入时不能拿 IRI 当属性主键——属性的主键是 + `(object_type_id, api_name)`。IRI 只作「同一实体的跨系统对应」用。 +2. **悬空边(F8)**:`link_types.source_type` / `target_type` 引用的是**类型 api_name**, + 而 Turtle 里写的是 IRI。导入必须先解析全部类型 → 建好 `api_name ↔ IRI` 映射, + **再**写链接类型;解析不到的类型视为校验失败(→ §2 · G4 整体拒绝), + 不允许写出一个指向不存在类型的边。 + +### 往返不变式(实现完成的验收标准) + +`导出 → 导入 → 再导出`,两次导出的 **IRI 集合与链接拓扑(source/target 指向)必须完全一致**。 +这条要写成测试(§10 末条)。 + +--- + +## 7. 范围对账删除:本仓明确不做 + +NVIDIA 有「范围内但载荷里没有的语义要删,跨范围共享的实体不删」。本仓**不做**,理由: + +1. **本仓没有「范围」概念**:没有 catalog / space / 多租户隔离(多本体仍是「仅规划,不执行」, + 见 `docs/PLAN.md`)。没有范围就无从「对账」。 +2. **与既有机制冲突**:删除语义与「append-only 版本流水」+「软删除 + `restore_object` 回滚」 + 两套机制的方向相反,硬做会产出「历史版本说它存在、现在说它没了且无法回滚」的状态。 +3. 若将来做(比如引入多本体后),必须: + - 走 `delete_object` 的审计与快照路径(`object_changes.snapshot` / `links_snapshot`), + - **默认关闭**,需显式 `mode=replace` + 二次确认; + - 跨范围共享的实体(`properties.iri` 全局共享那一类)一律不删。 + +--- + +## 8. 必须复用的既有机制(实现时不得另起炉灶) + +| 约束 | 复用对象 | 位置 | +|---|---|---| +| 写类型 / 属性 / 链接类型 | `applyObjectUpsert` + 现有 handler | `server/object_upsert.go`、`server/handlers_ontology.go` | +| 公理良构校验(**阻断**) | `validateAxiomsWellFormed` | `server/ontology_axioms_check.go` | +| 继承闭包(父类属性 / 链接解析) | `typeClosure` | `server/ontology_axioms_check.go` | +| URI 数据类型校验(**阻断**) | 属性 uri 写入校验 | `server/property_uri_check.go` | +| schema 审计 + 版本流水 | `schemaAudit` | `server/schema_audit.go` | +| 实例层审计与回滚 | `object_changes` / `delete_object` / `restore_object` | `server/instance_governance.go` | +| 快照路由 | `a.pool`(`dbRunner`) | `server/snapshot_router.go` | +| 分级语义(实例分级空 → 继承类型默认级) | `effectiveLevel` / `classCondSQL` | `server/scope.go` | +| 显示名物化 | `applyObjectUpsert` 同步 `objects.name` | `server/display_name.go` | + +--- + +## 9. 端点与载荷(占位,实现时定稿) + +``` +POST /api/v1/ontology/import +{ + "format": "turtle", // 首版只支持 turtle(与导出对称) + "payload": "", // 或 "payload_json": {...} + "mode": "merge", // merge(默认,只增改) | replace(**默认关闭**,见 §7) + "source": "gbt48000", // 幂等键的 source 部分 + "dry_run": true // 先校验不落库,出具逐条计划(强烈建议先跑) +} +``` + +- 鉴权:manager(schema 级变更),走 `grants` 表(`authz.CanWrite("write", "*", "*")`), + 与 MCP 写闸门口径一致——**不写死主体名**。 +- 响应:`{created, updated, skipped, failed, versions:[...], plan:[逐条明细]}`。 +- `dry_run=true` 时只跑 §2 的闸门 + 校验,不开写事务,输出逐条计划。 + 仓内已有同款约定(`server/handlers_action.go` 的 Action 执行预览),沿用即可。 + +--- + +## 10. 实现前必须先写出来的测试(清单) + +1. G1:根键不匹配的文档 → 拒绝,库零变化 +2. G2:空文档 → 拒绝,库零变化 +3. G3:作用域内无实体 → 拒绝,库零变化 +4. G4:其中一个实体公理非法 → **整体拒绝**,库逐表指纹与导入前一致 +5. 事务:注入中途失败 → 回滚,库状态与导入前逐表指纹一致 +6. 幂等:同一 `(source, external_id)` 导入两次 → 第二次 0 新建、不产生新的 `schema_versions` +7. 版本:一次导入产生 ≥1 条新的 `schema_versions`,`version` 单调递增,且 `ontology_audit_log` + 有对应记录(两者同点) +8. 悬空边:链接类型指向不存在的类型 → 拒绝,不写出悬空边 +9. IRI 往返:导出 → 导入 → 再导出,IRI 集合与链接拓扑完全一致 +10. 写闸门:非 manager 主体调用导入 → 403,且不产生任何写 + +--- + +## 11. 明确不做 + +- **不做 RDF/OWL 双存储**:Turtle 只是交换格式,不做推理、不存 RDF 图。 +- **`replace` 不做默认行为**:危险操作必须显式指定 + 二次确认,且默认关闭(§7)。 +- **不做跨本体 / 跨租户导入**:多本体仍是「仅规划,不执行」(`docs/PLAN.md`)。 +- **不做「尽力导入」默认路径**:部分成功必须走独立的显式模式(§2 · G4)。 + +--- + +## 12. 实现落地(2026-11-06) + +**落点**:`server/ontology_import.go`(导入核心)、`server/ontology_import_turtle.go`(Turtle 解析器)、 +`server/ontology_import_test.go`(单元)、`server/ontology_import_integration_test.go`(集成,§10 十条全覆盖)。 + +**端点**:`POST /api/v1/ontology/import`;MCP 工具 `ontology_import`(注册表 + 分发两处同改)。 + +**闸门实际返回**:拒绝时 HTTP 400,响应带 `gate` 字段(`G1`/`G2`/`G3`/`G4`)与 `error` 文本; +闸门内失败时带 `rolled_back: true`。 + +### 与本文档的偏差(逐条说明) + +| 条目 | 本文档写法 | 实际实现 | 理由 | +|---|---|---|---| +| §9 鉴权 | `authz.CanWrite("write","*","*")` | `requireManageLevel`:manager 主体或 `CanWrite("manage","*","*")` | schema 级写要 manage 级,比 write 级更严;且与 MCP 写闸门同一把尺 | +| §9 `mode=replace` | 默认关闭 | **直接拒绝**(400),只有 `mode=merge` | §7 已论证范围对账删除与 append-only 版本流水、软删回滚方向相反 | +| §5 版本流水 | 1 条汇总行 + 逐实体明细行 | 1 条汇总版本行(`action='import'`)+ 逐实体**审计**行(只落 `ontology_audit_log`,不产版本) | 逐实体产版本会让 `schema_snapshots` 变成 O(N²) 份全量结构快照 | +| §8 复用机制 | 写类型/属性/链接类型走 `applyObjectUpsert` | 直接 INSERT/UPDATE,复用 `validateAxiomsWellFormed` / `checkParentCycle` / `checkParentDisjoint` / `resolveParentID` | `applyObjectUpsert` 是**实例**写入路径(同步 `objects.name`),导入只动 schema 不建实例,没有实例可 upsert | +| §8 URI 数据类型校验 | 阻断 | 不适用 | URI 校验校验的是**实例取值**;schema 导入只写属性定义(`data_type='uri'`),没有实例值可校验 | +| §6 属性 IRI 全局共享 | 提示坑 | 幂等键用 `owner + "/" + IRI`,属性主键仍是 `(object_type_id, api_name)` | 同名属性跨类型共享一个 IRI,IRI 不能当属性主键 | +| §9 Turtle 载荷 | 未限定方言 | 自研最小解析器:只认本仓导出的那一小子集;集合 `()`、嵌套空白节点属性列表 `[]`、多行字符串遇到即报错 | 引入 RDF 依赖链不划算;「读不出来就报错」正是 G2 要的 | +| §6 往返不变式 | IRI 集合 + 链接拓扑 | 同上(验收断言即此二者) | 公理宿主类型在导入时可能换人,Turtle 文本不保证字节相同 | + +### 实现期发现并修掉的缺陷 + +- **RDF Schema 命名空间年份不一致**:导出侧写 `http://www.w3.org/2000/01/rdf-schema#`(标准), + 导入侧常量写成了 `2001/01`,导致「导出 → 导入」时 `rdfs:label` / `domain` / `range` 一条都认不出来 + (链接类型报「缺 rdfs:domain」)。已把导入侧常量改回标准值,并额外兼容误写成 `2001/01` 的外部文档。 +- **认证位谓词可被冒名**:原先判定条件是「命名空间以 `annotation` 结尾」,任何第三方命名空间都能 + 伪造 `certified`。改为与本仓注解命名空间**精确相等**才算认证位。 + +### 已知边界 + +- 导入只覆盖 **schema 层**(对象类型 / 属性 / 链接类型 / 公理),不导实例、不导边数据。 +- 载荷里带 `@lang` 的 label 时,朴素 label 不落库(显示名取标签值)——与导出侧规则一致。 +- 公理按「族」合并:`disjointWith` / `equivalentTo` / `functionalLinks` / `inverseOf` / `certification` + 各自独立覆盖,载荷没带的族保留库里既有。 +- 认证位的注解命名空间 = `ONTOLOGY_BASE_IRI` 去尾 `#` 后拼 `annotation`(与导出侧 `@prefix sswo:` 同源)。 diff --git a/docs/PLAN.md b/docs/PLAN.md index fc9b45c..62f7d0b 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -321,10 +321,10 @@ curl --noproxy '*' -X POST http://127.0.0.1:8081/api/v1/mcp \ ### 优先级 P2:行为层深化 - Action 调用 Function 的编排定义 -- **公理/约束声明机制**(差距分析 P2 #4)——**已落地(2026-09-20),见 CHANGELOG 1.6.0**:`object_types.axioms JSONB` 声明 disjointWith / functionalLinks / inverseOf / equivalentTo / 跨属性日期序(dateOrder),三层校验(形状 / schema 良构 / 写入),统一入口 `applyObjectUpsert` + `createLink`/`batchCreateLinks`,随 Turtle 导出为 OWL 公理;Function 输入输出 schema 校验仍为待办(本项合流部分已完成) +- **公理/约束声明机制**(差距分析 P2 #4)——**已落地(2026-09-20),见 CHANGELOG 1.5.1**:`object_types.axioms JSONB` 声明 disjointWith / functionalLinks / inverseOf / equivalentTo / 跨属性日期序(dateOrder),三层校验(形状 / schema 良构 / 写入),统一入口 `applyObjectUpsert` + `createLink`/`batchCreateLinks`,随 Turtle 导出为 OWL 公理;Function 输入输出 schema 校验仍为待办(本项合流部分已完成) - Function 结果写回对象的受控流程 - `script` 和 `external_api` 执行器的隔离、超时、网络和权限控制 -- 类型继承(SubclassOf,差距分析 P2 #5)、多语标签(#6)、`uri` 数据类型(#7)——**已落地(2026-09-20,M5),见 CHANGELOG 1.6.0**:`parent_id` + 属性继承(子类型读路径合并祖先属性 + 校验走 `typeClosure` 闭包)/ 三表 `display_name_lang`(Turtle `@lang`)/ `data_type='uri'`(写入校验 + `xsd:anyURI`) +- 类型继承(SubclassOf,差距分析 P2 #5)、多语标签(#6)、`uri` 数据类型(#7)——**已落地(2026-09-20,M5),见 CHANGELOG 1.5.1**:`parent_id` + 属性继承(子类型读路径合并祖先属性 + 校验走 `typeClosure` 闭包)/ 三表 `display_name_lang`(Turtle `@lang`)/ `data_type='uri'`(写入校验 + `xsd:anyURI`) ### 优先级 P3:平台化 diff --git a/docs/README.md b/docs/README.md index 6250a56..c27ac23 100644 --- a/docs/README.md +++ b/docs/README.md @@ -48,12 +48,41 @@ | 方法 | 路径 | 用途 | |---|---|---| | GET | `/api/v1/ontology/meta` | 本体自描述:`base_iri`(`ONTOLOGY_BASE_IRI` 配置)+ `profile` + 服务版本;类型/属性/链接的 `iri` = base_iri + `#` + api_name,创建即固化、存量启动回填;默认 `ONTOLOGY_BASE_IRI` 为 example.org 占位,生产部署应改为自有命名空间 | -| GET | `/api/v1/ontology/export?format=turtle` | schema 导出为 W3C Turtle(ObjectType→`owl:Class`、数据属性→`owl:DatatypeProperty`、LinkType→`owl:ObjectProperty`),含 OWL 公理(`owl:disjointWith`/`owl:equivalentClass`/`owl:inverseOf`/`owl:FunctionalProperty`)、`rdfs:subClassOf`、多语 `rdfs:label "…"@lang`、`xsd:anyURI`;Protégé 等标准工具可加载;单向导出,其余 format 返回 400 | +| GET | `/api/v1/ontology/export?format=turtle` | schema 导出为 W3C Turtle(ObjectType→`owl:Class`、数据属性→`owl:DatatypeProperty`、LinkType→`owl:ObjectProperty`),含 OWL 公理(`owl:disjointWith`/`owl:equivalentClass`/`owl:inverseOf`/`owl:FunctionalProperty`)、`rdfs:subClassOf`、多语 `rdfs:label "…"@lang`、`xsd:anyURI`;Protégé 等标准工具可加载;其余 format 返回 400 | +| POST | `/api/v1/ontology/import` | schema 导入(Turtle,与导出对称):四道 fail-fast 闸门(根键 G1 / 空文档 G2 / 作用域内无实体 G3 / 逐实体校验 G4)→ 整事务写入 → 幂等(`source`+`external_id` 映射落 `import_identities`,重复导入 0 新建、0 更新、不产新版本);只支持 `mode=merge`(`replace` 明确拒绝),`dry_run=true` 出逐条计划不落库;写闸门走 grants 的 manage 级授权;对应 MCP 工具 `ontology_import`。约束与偏差见 `docs/ONTOLOGY_IMPORT.md` | | GET | `/api/v1/ontology/object-types` · `/api/v1/ontology/object-types/:name` | 返回含 `axioms` 与 `parent_api_name`(属性含 `inherited` 标;类型/属性/链接均回显 `display_name_lang`) | | POST / PUT | `/api/v1/ontology/object-types[/:name]` | 接受 `axioms`(五类公理声明)、`parent`(SubclassOf,环/自指/父子互斥守卫)、`display_name_lang`(BCP47 典型形式标签,非法 400) | | POST / PUT | `/api/v1/ontology/object-types/:name/properties` · `/api/v1/ontology/properties/:id`(link-types 同) | 接受 `display_name_lang`、`data_type=uri`(写入校验绝对 URI) | | POST | `/api/v1/links` · `/api/v1/connector/links/batch` | 受 `functionalLinks` 公理边写入校验(同一功能性链接类型:同源指向不同 target 拒绝,无 `validate_axioms` 后门) | | GET | `/api/v1/ontology/versions?kind=&name=&limit=&offset=` | schema 版本流水(最新在前);`GET /api/v1/ontology/versions/:version` 按版本读回该次变更完整 details(含 before/after 快照,JSON,不走快照路由) | +| GET | `/api/v1/ontology/schema/diff?from=&to=` | 跨版本结构 diff(见 §1.3);`GET /api/v1/ontology/schema/snapshots` 列出可比较的快照版本;`POST /api/v1/ontology/schema/snapshot` 手动标记锚点 | + +### 1.3 跨版本结构 diff(2026-11-06) + +「改了什么」的对照面:任意两个 schema 版本之间,**机器事实**与**人工策展**分开列。 + +``` +GET /api/v1/ontology/schema/diff?from=<版本|baseline>&to=<版本|live> +GET /api/v1/ontology/schema/snapshots +POST /api/v1/ontology/schema/snapshot # 手动标记当前结构为锚点 +``` + +| 概念 | 说明 | +|---|---| +| 快照 | 每次 schema 变更后落一份**全量结构**(`schema_snapshots` 表);`version` 对应 `schema_versions.version` | +| 基线 | `version=0`,快照机制启用那一刻的实时结构(来源写在 `label` 里,不是历史某刻的真值) | +| `from` / `to` | 整数版本号 / `baseline`(默认基线)/ `live`(默认当前实时结构);只能比较有快照的版本 | + +比对口径:每条结构事实(对象类型 / 对象属性 / 链接类型 / 链接属性 / 动作类型)拆成两组字段—— + +- `machine_fact`:结构与配置(IRI、父子继承、约束、公理、分级、显示名绑定…); +- `curated`:人工内容(显示名、描述、多语标签、`certification` 认证记录)——**正是重摄取不许覆盖的那部分**。 + +带 `certification` 认证位的条目在 diff 里额外标 `certified=true`:改动这类条目前值得人工确认。响应 `summary` 分别给出 `machine_fact_fields` 与 `curated_fields` 计数。 + +为什么用全量快照而不是回放 `schema_versions` 流水:流水一次变更一行,且更新走部分更新语义(流水里的 `after` 不是完整状态),回放重建的历史状态会掺假。 + +MCP 工具:`diff_schema_versions` / `list_schema_snapshots` / `capture_schema_snapshot`。 --- @@ -173,10 +202,12 @@ http://127.0.0.1:8081 | GET | `/api/v1/connector/object-types` | 列出对象类型及属性定义 | | GET | `/api/v1/connector/objects/:type` | 按类型列出可见对象 | | GET | `/api/v1/connector/object/:type/:pk` | 获取单个可见对象 | -| GET | `/api/v1/connector/search?q=&type=&field=&limit=` | 关键词检索可见对象 | +| GET | `/api/v1/connector/search?q=&type=&field=&limit=&offset=` | 关键词检索可见对象 | | GET | `/api/v1/connector/facets?type=` | 获取过滤维度取值 | -| POST | `/api/v1/connector/query` | 按类型+属性过滤,可展开关系邻居 | +| POST | `/api/v1/connector/query` | 按类型+属性过滤,可展开关系邻居(body 支持 `limit` / `offset`) | | GET | `/api/v1/connector/graph?type=&pk=` | 查询对象关系图 | +| GET | `/api/v1/connector/readiness` | 自检探针:本体现在能不能用(`ready` + `blockers`/`unverified`/`warnings` 分档) | +| POST | `/api/v1/connector/answerable` | 可答性评估:`{"question":"..."}` → `coverage`/`answerable`/`uncovered`/`candidates` | ### 6.2 MCP 端点(Streamable HTTP) @@ -185,17 +216,75 @@ http://127.0.0.1:8081 | GET | `/api/v1/mcp/manifest` | 人类可读 MCP 自描述(供 WorkBuddy 注册) | | POST | `/api/v1/mcp` | JSON-RPC 2.0 Streamable HTTP(按 `Accept` 自动 JSON/SSE) | -原生暴露 24 个工具(2026-09-05),按组分类: +原生暴露 54 个工具(只读 27 / 写入 27),按组分类: | 组 | 工具 | |---|---| -| 查询(只读) | `get_object_types` / `get_objects_by_type` / `get_object` / `search_ontology` / `get_facets` / `query_related` / `whoami` | -| 知识管理 | `km_list_tree` / `km_list_files` / `km_create_folder` / `km_upload_markdown` / `km_extract` / `km_delete` | -| 类型管理 | `create_object_type` / `create_link_type` / `update_enum` | -| **实例写入** | `create_object` / `batch_create_objects` / `batch_create_links` / `create_link` / `delete_object` / `restore_object` / `get_object_history` / `find_duplicates` | +| **自检探针(只读)** | `check_readiness` / `check_answerable` | +| 查询(只读) | `get_object_types` / `get_objects_by_type` / `get_object` / `search_ontology` / `get_facets` / `query_related` / `whoami` / `get_server_info` / `get_usage_guide` | +| 治理(只读) | `get_object_history` / `find_duplicates` / `get_classification_config` / `list_principals` / `get_principal` | +| 知识库(只读) | `km_list_tree` / `km_list_files` | +| 备份(只读) | `backup_list` / `backup_inspect` / `backup_switch` | +| **结构版本(只读)** | `diff_schema_versions` / `list_schema_snapshots` | +| **行级归属(只读)** | `get_object_owners` / `list_groups` | +| **分区(只读)** | `list_zones` | +| **存在性(只读,manager 专属)** | `probe_existence` | +| 知识管理 | `km_create_folder` / `km_upload_markdown` / `km_extract` / `km_delete` / `set_km_classification` | +| 类型管理 | `create_object_type` / `update_object_type` / `add_object_type_property` / `create_link_type` / `update_enum` / `set_object_type_classification` | +| **实例写入** | `create_object` / `batch_create_objects` / `batch_create_links` / `create_link` / `delete_object` / `restore_object` | +| 分级与权限 | `recompute_classification` / `set_principal_clearance` | +| **行级归属(写入)** | `set_object_owners` / `set_group` | +| **结构版本(写入)** | `capture_schema_snapshot` | +| **本体导入(写入,manage 级)** | `ontology_import` | +| **分区(写入)** | `set_zone` / `delete_zone` | +| 备份 | `backup_create` / `backup_delete` | 实例写入的语义约定(merge 默认、软删除、source_ts 乱序丢弃、delete propagate 血统传播、审计回滚)详见 [INSTANCE_GOVERNANCE.md](INSTANCE_GOVERNANCE.md)。 +**工具清单单一事实来源**:54 个工具的元数据(`title` / `description` / `inputSchema` / `read_only` / `destructive` / `idempotent`)全部登记在 `server/mcp_registry.go` 一份注册表里,`tools/list` 的 wire 清单、annotations、按名查询均由此派生,分发前按注册表准入。三条测试守住一致性:① 注册表不得重名、不得缺字段;② 注册表与 `mcpDispatchTool` 的 case 双向一致(AST 解析,防「声明了却调不通」与「能调却不声明」两种漂移);③ 只读工具全量调用前后比对平台状态指纹,只读性由测试保证而非注释。 + +**读路径的可见范围**(`server/scope.go`):过滤结果用显式类型 `Scope` 承载,分三档——`ScopeUnscoped` 不施加任何过滤、`ScopeDenyAll` 过滤生效且拒绝全部、`ScopeAllow` 只放行可见取值(取值集合为空 = 一个都不放行)。「不施加过滤」与「过滤后为空」在类型层面分开,不再靠 `len(x)==0` 的疏忽区分。配套语义:实例分级为空继承类型默认级(不是「无限制」);主体无任何 clearance 记录则看不到任何实例;列表路径与详情路径共用同一套判定,列表看不到的实例详情一律 404。 + +**三条正交的可见性轴**(叠加生效,不是互斥): + +| 轴 | 粒度 | 判定 | +|---|---|---| +| 标记 / clearance | 实例级 | 实例带标记,主体 clearance 覆盖该标记才可见 | +| 分级 | 实例级(可继承类型默认级) | 生效级别 ≤ 主体最高 clearance 才可见 | +| 分区(zone) | 类型级 | 类型入区后,主体持有该分区才可见 | + +分区是**目录分区 + 授权边界**,不是相关度过滤:越区即完全不可见(列表与详情口径一致,看不到就是 404)。类型未入任何分区 = 公共区,全体可见;主体一个分区都不持有 → 所有被分区的类型都不可见(fail-closed);类型同时属于多个分区时**命中任一即可见**。分区只收窄可见性,不改可改性——写权限仍由 grants 与行级归属决定。 + +**空结果与存在性**(`server/empty_reason.go` / `server/existence.go`):空结果必须带原因,「不可见」与「不存在」严格分开。读路径回包新增 `empty_reason`: + +| code | 含义 | 该做什么 | +|---|---|---| +| `no_data` | 该类型在当前快照下真的没实例 | 去摄取 / 建模 | +| `not_visible` | 有实例,但当前主体被标记 / 分级 / 分区挡住 | 调权限,**不要**回答「不存在」 | +| `no_type` | 对象类型未注册 | 先建模 | +| `not_materialized` | 数据来自物化,物化还没跑 | 先 refresh 物化 | +| `no_match` | 检索无匹配(跨类型,无法归因) | 换关键词,或按类型定位 | + +原因只说「被哪一维挡住」,**不报条数**——条数本身就是存在性泄漏。三态存在性探针 `GET /api/v1/access/existence?type=&pk=&principal=`(仅 manager)返回 `exists` / `invisible`(附 `blocked_by`:grant / marking / classification / zone)/ `not_exists`;读路径对越权实例仍一律 404,三态只走这条管理面探针。 + +**统一分页信封**(`server/pagination.go`):所有列表读路径(管理面 `/api/v1/objects`、连接器实例列表 / 检索 / 图式查询)回包带同一套分页字段: + +| 字段 | 含义 | +|---|---| +| `count` | 本次实际返回的条数 | +| `total` | 过滤后的真实总数(与 `items` 同一 WHERE:授权 / 分级 / 分区过滤都在内) | +| `limit` / `offset` | 本页上限与起始偏移 | +| `has_more` | 是否还有下一页 | +| `truncated` | 结果是否被 limit 截断(与 `has_more` 同值,语义更直白) | + +`total` 必须与 `items` 同源——先过滤再截断;反过来会让 `total` 偏小,调用方以为翻完了其实后面还有。`total` 与 `count` 由 `total` 推导 `has_more`(总数正好是 limit 整数倍时不会误报「还有下一页」)。检索(`search_ontology` / `GET /connector/search`)与图式查询(`query_related` / `POST /connector/query`)均支持 `offset` 翻页;`offset` 翻过头时空页返回 `count=0` 但 `total` 仍是真实总数——空页 ≠ 没有数据。各端点的 `limit` 上限仍不统一(检索 200 / 查询 500 / 列表 1000),是既有 API 行为。 + +**长任务进度回报**(`server/mcp_progress.go`):MCP 客户端在自己的超时里会把「没动静」当成卡死,然后重试——重试又叠加负载。长任务因此主动汇报进度,但**客户端显式要才给**:在 `tools/call` 的 `_meta` 里带 `progressToken`、且 `Accept` 里有 `text/event-stream` 时,服务端才进 SSE 进度模式。 + +带了就以 SSE 帧流式吐 `notifications/progress`(规范格式:`event: message` + `data: {"jsonrpc":"2.0","method":"notifications/progress","params":{progressToken,progress,total,message}}`),`progressToken` 原样回带,最后照常补一条 `message` 帧承载最终结果——进度不能顶掉结果。不带 → 走的还是原来那份单响应,行为与从前完全一致。 + +覆盖四类长任务:`km_extract`(逐份文档)、`backup_create`(逐张表)、`recompute_classification`(逐实例,试算与落库两轮都报)、`batch_create_objects`(逐条)。进度回调挂在请求 context 上,MCP 层的进程内子请求继承同一个 context;REST 直连路径没有回调时为空操作。进度帧做了节流(最小间隔 200ms),全库重算上万实例不会把 SSE 刷爆;被节流压下的最后一条一定补发,保证客户端看到终态。 + ### 6.3 一键注册到 WorkBuddy ```json @@ -285,6 +374,11 @@ GET / POST / DELETE /api/v1/ontology/backing-sources | Grant | `(principal, action, scope) → allow/deny` 授权规则;deny 优先 | | FieldPolicy | 字段级 `redact` / `hide` / `full` 策略 | +另有两条与上面正交的轴: + +- **分级(Classification)**:`objects.classification` + `object_markings`,决定「这一行的敏感度」,与主体 clearance 求交得到「看不看得到」。 +- **行级归属(ObjectOwner)**:`object_owners`,决定「谁能改这一行」。 + ### 9.2 运行时处理链 ```text @@ -292,6 +386,7 @@ GET / POST / DELETE /api/v1/ontology/backing-sources → 识别 principal → 检查 grant → 检查 object marking + → 检查类型分区(zone) → 过滤对象 / 关系 → 应用字段策略 → 写入 access_log(allow/deny/filter/redact 四种 decision) @@ -323,10 +418,45 @@ GET /api/v1/access/field-policies POST /api/v1/access/field-policies DELETE /api/v1/access/field-policies/:id GET /api/v1/access/preview?principal= +GET /api/v1/access/existence?type=&pk=&principal= GET /api/v1/access/log GET /api/v1/access/log/stats +GET /api/v1/access/groups +PUT /api/v1/access/groups/:name +DELETE /api/v1/access/groups/:name +GET /api/v1/access/zones +POST /api/v1/access/zones +DELETE /api/v1/access/zones/:name ``` +### 9.4 行级可改性轴(object_owners) + +`clearance` 决定「看不看得到」,`owner` 决定「能不能改」——两条轴互不影响。 + +| 概念 | 载体 | 语义 | +|---|---|---| +| 归属 | `object_owners(object_type, object_pk, owner_kind, owner_name)` | `owner_kind` = `principal`(账号)或 `group`(组) | +| 组 | `principal_groups(principal, group_name)` | 组只是归属的载体,本身不带任何全局权限 | + +判定口径(`server/object_owner.go::canWriteObject`,所有对象写路径统一走它): + +- `grants` 表仍是「能做什么动作」的唯一真源;归属只在 grant 之上**收窄**——对象设有归属时,非归属方即便持有该类型的写授权也不能改这一行; +- 对象**未设归属** → 不限制,历史行为一字不变(存量库零影响); +- `manager` 豁免;归属查询失败 → 拒绝(fail-closed); +- 组的成员获得该行的可改性,**且仅限该行**,不扩大任何全局权限; +- 归属方可转交行(加协作者、换归属方);解除归属仅 `manager`; +- 删组会连带解除引用该组的归属行——否则那些行会变成「谁都改不了」的静默死锁。 + +接口(`/ownership` 组只要求登录,归属方本人也能查/转交;组管理在 `/access` 组,仅 `manager`): + +``` +GET /api/v1/ownership/objects/:type/:pk/owners +PUT /api/v1/ownership/objects/:type/:pk/owners +DELETE /api/v1/ownership/objects/:type/:pk/owners +``` + +MCP 工具:`get_object_owners` / `set_object_owners` / `list_groups` / `set_group`。 + --- ## 10. AI 与知识管理 diff --git a/docs/auto-ontology-benchmark-20261106.md b/docs/auto-ontology-benchmark-20261106.md new file mode 100644 index 0000000..f0439b5 --- /dev/null +++ b/docs/auto-ontology-benchmark-20261106.md @@ -0,0 +1,640 @@ +# 对标 NVIDIA Auto Ontology · 借鉴与优化清单 + +> **对象**:[NVIDIA/auto-ontology](https://github.com/NVIDIA/auto-ontology) v1.2.0(HEAD `c4495670947e`,2026-11-05) +> **镜像**:内网 Gitea `NVIDIA/auto-ontology`(`gh-proxy` 线路,30m 自同步) +> **对标本仓**:SSW 通用本体元数据平台(Go + Gin + PostgreSQL + Vue3,6 元原语 + Dynamic Security) +> **生成时间**:2026-11-06 +> **性质**:机制借鉴清单,**不含任何代码实施**;涉及本仓的改动一律标注落点文件,不自动执行 +> **口径**:结论分三类——①值得借鉴 ②明确不要照搬 ③本仓已领先、可反哺。NVIDIA 侧出处用 `文件:行`(相对其仓库根) + +--- + +## 0. 摘要 + +### 一句话 + +Auto Ontology 是**「关系型语义层 + 目录层」**(不是 RDF/OWL),主打**给 agent 提供可信上下文**:语义层是唯一入口、MCP 只读、查询前做就绪校验、答案带证据。它的**语义模型版本管理、字段级审计、快照回滚、GB/T 标准兼容层在本仓面前是空白**——而这恰恰是本仓的上游。 + +所以借鉴方向不是「抄它的建模」,而是**抄它的三类工程纪律**: + +| # | 纪律 | 一句话 | +|---|---|---| +| 1 | **对外只读 + 工具白名单** | agent 的安全论证建立在「只读」上,写必须走别的面 | +| 2 | **可信度拆成若干可判定闸门** | 不给一个总分,每类失效一个独立检查器,各自判定各自降级 | +| 3 | **「无过滤」与「空结果」语义分离** | `None` ≠ `[]`;混淆二者是权限洞的成因 | + +### 值得借鉴的 Top 8(按本仓收益/成本排序) + +| 优先级 | 机制 | 本仓落点 | 成本 | +|---|---|---|---| +| P0 | `check_readiness` 探针工具 | ✅ 新增 MCP 工具 `check_readiness`(2026-11-06 已落地) | 半天 | +| P0 | `check_answerable` 实体覆盖判定 | ✅ 新增 MCP 工具 `check_answerable`(2026-11-06 已落地) | 1 天 | +| P0 | 导入 fail-fast 三重校验 + 整事务 + 幂等 + 范围对账 | ✅ 已落地(2026-11-06):`server/ontology_import.go` + `ontology_import_turtle.go`,端点 `POST /api/v1/ontology/import` + MCP `ontology_import`(**范围对账删除明确不做**,见 `docs/ONTOLOGY_IMPORT.md` §7) | 2-3 天 | +| P0 | `None` vs `[]` 语义分离 | Dynamic Security 全读路径 | 1 天 | +| P0 | 只读性写成测试 + 工具注册表单点真相源 | `handlers_mcp.go` | 2 天 | +| P1 | 概念层与物理层解耦(REPRESENTS 多对多) | 新增 link_type 族 | 3-5 天 | +| P1 | 「认证」维度并入 axioms 第 6 类 | `ontology_axioms.go` | 1 天 | +| P1 | 跨版本结构 diff(机器事实 vs 人工策展) | `handlers_versions.go` | 2 天 | + +### 本仓领先(不必抄,且可反向输出) + +- 字段级审计 diff + 快照回滚(`object_changes` + `restore_object`)——NVIDIA **完全没有** +- schema 层审计(`ontology_audit_log`)——NVIDIA 只有 `created_by/modified_by` 两列 +- 快照路由(`X-Snapshot-Id` / `X-Snapshot-Ts`)——NVIDIA 无 +- append-only 版本流水 + 按版本读回旧定义——NVIDIA 无 +- GB/T 48000.3-2026 兼容层(IRI / 多语 / 继承 / 公理 / Turtle 导出)——NVIDIA 无 +- 实例治理三件套:merge / 软删 / `source_ts` 乱序丢弃 / 血统传播 / `same_as` 归并——NVIDIA 无 +- **分级驱动的数据可见性**(类型默认级 + 实例覆盖 + 字段策略)——NVIDIA **零行级、零列级**(全仓 `mask|redact` grep 0 命中) + +--- + +## 1. 双方定位对比 + +| 维度 | Auto Ontology | 本仓(SSW) | 判断 | +|---|---|---|---| +| 本体形态 | 物理目录层(db→schema→table→column)+ 语义层(term→column_attribute/sql_attribute),两层多对多 | `object_types`/`properties`/`link_types` 三表 + 实例 + 边 | 本仓**单层**,NVIDIA **双层** | +| 标准兼容 | Apache Ossie YAML 双向 | GB/T 48000.3-2026(IRI/多语/继承/公理)+ Turtle 导出 + **Turtle 导入(2026-11-06 落地)** | 本仓标准维度更强,导入的 fail-fast 纪律比 NVIDIA 更严(多一道逐实体校验) | +| 模型版本 | **无**(只有 Alembic 物理 DDL 线) | `schema_versions` append-only + 按版本读回 | **本仓领先** | +| 审计 | 无字段级 diff、无回滚 | `object_changes` 字段级 diff + snapshot + `ontology_audit_log` | **本仓领先** | +| 数据安全 | 无行级、无列级、无 RLS | Principal+Grant+Marking+FieldPolicy,clearance L0-L3 | **本仓领先** | +| MCP | **9 工具,只读**,OpenAPI 驱动 + 白名单 | **40 工具,读写混合**,硬编码 | NVIDIA 面窄但纪律强 | +| 生成式查询 | LangGraph 流水线 + 就绪校验 + 空结果修复 | 无生成式查询链路(本仓是元数据平台) | 场景不同,但校验纪律可借 | +| 权限模型 | 路由级 `resource:action`,admin/viewer 两角色 | clearance 分级(可见性轴) | 正交,可叠加但要防双过滤器 | + +--- + +## 2. P0 —— 值得借鉴(低成本高收益) + +### 2.1 新增 `check_readiness` 探针工具 + +**NVIDIA 机制**:`check_readiness` 把三个互不相关的端点折成**一个 verdict**,输出 +`{ready, semantic_layer_built, can_execute_sql, catalog_present, databases[], blockers[], unverified[]}`。 +关键细节:**403(无权限探查)记入 `unverified` 而不是 `blockers`**——「看不到」不等于「坏了」 +(`mcp/auto_ontology_mcp/readiness.py:104-143, 145-245`)。 + +**本仓落点**:新增 MCP 工具 `check_readiness`,一次性探: +本体类型是否非空 → 实例数是否 > 0 → 快照路由是否可用 → 分级引擎是否已配(`get_classification_config` 口径)→ Turtle 导出是否可生成 → 当前主体 clearance 覆盖到几级。 +输出 `{ready, blockers[], unverified[]}`,`unverified` 专收「因权限看不到」项。 + +**取舍**:本仓已有 `whoami`/`get_server_info`/`get_usage_guide`,但**没有**一个「这台本体现在能不能用」的合并判定。agent 第一次接入本仓时只能逐个试工具——这是 40 工具带来的真实成本。 + +### 2.2 新增 `check_answerable`(实体覆盖判定) + +**NVIDIA 机制**:`POST /api/question-entity-coverage` → `EntityCoverageResult{coverage 0..1, candidates[], uncovered_entities[]}`。 +覆盖度是**确定性算的**(`auto_ontology/retrieval/entity_coverage/agents/coverage.py`),不是 LLM 评分。 +它在 README 的实际对话里直接变成 agent 的回答依据:`Agent: check_answerable -> coverage 0.5; no term covers "ad spend"`。 + +**本仓落点**:新增 MCP 工具 `check_answerable(question)`,输出 +`{answerable, coverage, covered[], uncovered[], candidates[]}`。判定输入应来自本仓已有的 +`search_ontology` + `get_facets` + 类型/属性注册表——**完全确定性**,不调 LLM。 + +**取舍**:本仓 `search_ontology` 是「按名搜」,回答不了「这个问题的实体有没有被覆盖」。这是本仓从「本体浏览器」升级到「agent 语义层」的最小一步。 + +### 2.3 导入的 fail-fast 三重校验(已落地 2026-11-06) + +**NVIDIA 机制**(`server/model_interchange/service.py:82-92`): + +> Only a root holding Auto Ontology's own keys is read as native. Anything else goes to the Ossie converter, which rejects what it cannot read; read as native, it would validate as an empty document, and an import with `replace` would then wipe the catalog. + +配套四条: +- **整事务导入**:「The whole import is one transaction, so a failure part-way leaves nothing behind rather than a catalog with half its semantics on top」(`dal/model_interchange.py:1-15`, `:946`) +- **幂等**:`coalesce(imported_id, id)` 作载荷身份,同一文档导入两次不新建(`dal/model_interchange.py:903-909`) +- **范围对账删除**:范围内但载荷里没有的语义要删;跨范围共享的实体**不删**(`dal/model_interchange.py:1291-1380`) +- **id 双空间映射**:文档键 `column_id` ↔ 库内 `column_live_id` 必须翻译,否则 `sql_column_is` 回来是空的(`dal/model_interchange.py:~590-650`) + +**本仓落点**:`server/handlers_export.go` 的 `format=turtle` 导出(对称的导入见 `server/ontology_import.go`)。导入**必须**(已全部落地): +1. 文档根键必须匹配 + **文档非空** + 作用域内必须有实体——三重校验,任一不过直接拒绝 +2. 整事务(复用本仓 `a.pool` 事务视图,注意别绕过 `a.pool`,否则快照路由失效) +3. 导入**产生一个新的 `schema_versions` 行**而非就地覆盖(见 2.11 冲突点) +4. IRI(对外稳定)与内部 pk(本次导入内)双列 + 映射表,否则「导出→导入」后 IRI 会漂移 + +**取舍**:这是「将来要做的功能」而不是「现在能改的 bug」,但**现在写进设计约束**成本最低——因为 GB/T 48000.3 兼容层若要支持互操作,导入早晚要做。 + +**落地结果(2026-11-06)**:四道闸门(多一道「逐实体校验 G4」)→ 整事务 → `(source, external_id)` 幂等 → 一条汇总版本 + 逐实体审计 → IRI↔api_name 映射表 `import_identities`。**NVIDIA 的「范围对账删除」本仓明确不做**(与 append-only 版本流水 + 软删回滚方向相反,见 `docs/ONTOLOGY_IMPORT.md` §7),`mode=replace` 直接拒绝。 + +### 2.4 `None` vs `[]` 语义分离 + +**NVIDIA 机制**:`zone_ids=None` → **不加任何过滤**(全量);`zone_ids=[]` → **谓词匹配不到任何东西**(拒绝)。 +代码注释反复强调「Conflating the two is how an access-control bug gets written」 +(`auto_ontology/dal/users.py:105-146`),并有专门单测 `test_no_zone_ids_means_unscoped_not_empty`(`dal/tests/test_terms.py:279-280` 等三处)。 + +**本仓落点**:Dynamic Security 的读路径要钉死三条: +- 「某 principal 无 clearance 记录」= **什么都看不到**,不是「看到全部」 +- 「过滤条件算出空集合」= **拒绝**,不是放行 +- `object_markings` 为空 = 继承类型默认级,**不是**「无限制」 + +建议在 Go 侧引入显式类型而不是裸 `[]string`(如 `Scope{Unscoped|DenyAll|Tables(ids)}`),从类型上消除歧义。 + +**取舍**:改动面在所有读路径,属于「不改会出事、改了要回归」的类别。建议先加断言/单测把语义钉住,再逐步类型化。 + +### 2.5 只读性写成测试 + 工具注册表单点真相源 + +**NVIDIA 机制**: +- MCP 工具**从 OpenAPI spec 反生成**,再用手写白名单裁剪;白名单尾部 `EXCLUDE` 兜底使其成为真 allow-list;路径用 `^…$` 精确匹配防误选(`mcp/auto_ontology_mcp/tools.py:60-166`) +- 只读性是**测试**不是注释:`test_no_curated_operation_mutates_state` / `test_nothing_walks_the_physical_catalog`(`mcp/tests/test_tools.py:42-65`) +- 启动期**漂移 fail-fast**:白名单里的 operation 不在 spec 里 → 直接 `ConfigError` 拒启动(`tools.py:169-187`;`server.py:87-110`) +- 工具描述是**给 agent 的 prompt**,不是给维护者的文档(`tools.py:26-31`) + +**本仓落点**:本仓 MCP 是 40 工具**读写混合**、硬编码在 `server/handlers_mcp.go`。两条路可选: +- **路线 A(保守)**:注册表加 `read_only bool` 字段,CI 断言「对外只读的 MCP 端点里所有工具 `read_only=true`」;写工具走独立端点/独立 principal +- **路线 B(彻底)**:工具从 Gin 路由表**双向生成**(路由生成工具 + 工具生成路由),入参 schema 从 handler 结构产出;启动时校验「注册表每个工具都能在路由表找到 handler」 + +**顺带解决本仓已知待办**:`docs/PLAN.md` §5.3「Function 自动注册为 MCP 工具」——OpenAPI 驱动生成正是这条路。 + +**取舍**:路线 B 改动大,但能根治「REST 与 MCP 两套授权逻辑漂移」这个本仓 CLAUDE.md 已经点名的隐患。 + +### 2.6 长任务要吐进度 + +**NVIDIA 机制**:`ctx.report_progress()` 把 SSE step 事件转成 MCP progress notification(`mcp/auto_ontology_mcp/chat.py:218-227`),理由是「一次 run 常要几十秒,不吐进度会像卡死」(`chat.py:12-17`)。 + +**本仓落点**:`km_extract`(AI 抽取)、`recompute_classification`、`backup_create`、批量写入——这四类加进度回报(阶段名 + 已处理/总数)。 + +**取舍**:MCP 客户端(Claude Code 等)有自己的超时,无进度时会被当挂死而重试,重试又叠加负载。 + +**已落地(2026-11-06,v1.7.2)**: + +1. **客户端显式要才给**:客户端在 `tools/call` 的 `_meta` 里带 `progressToken`、且 `Accept` 里有 `text/event-stream`,服务端才进 SSE 进度模式。不带 → 走原来那条单响应路径,**行为与从前完全一致**(不给老客户端引入任何回归,也不给每个请求都套一层流)。 +2. **帧格式按 MCP 规范**:`event: message` + `data: {"jsonrpc":"2.0","method":"notifications/progress","params":{progressToken,progress,total,message}}`,`progressToken` 原样回带,客户端据此对应到具体请求;最后照常补一条 `message` 帧承载最终结果(进度不能顶掉结果)。 +3. **四类长任务都接上了**:`km_extract`(逐份文档)、`backup_create`(逐张表)、`recompute_classification`(逐实例,试算与落库两轮都报)、`batch_create_objects`(逐条)。 +4. **进度回调挂在 request context 上**(`server/mcp_progress.go`):MCP 层的进程内子请求(`mcpCall` / `callHandler` / `callConn`)继承同一个 ctx,handler 里 `reportProgress(ctx, done, total, msg)` 上报即可。没有回调时是空操作 → REST 直连路径完全不受影响。 +5. **节流 + 补发**:进度帧最小间隔 200ms——全库重算上万实例逐条发会把 SSE 刷爆;间隔内的上报只记最新一条(pending),由下一次到期或 `finish()` 发出,**终态一定送达**。 +6. **`total` 能给就给**:分母明确的场景(按文档 / 按表 / 按条目)带 `total`;`recompute_classification` 的实例总数事先不可知,就只报 `progress` 不报 `total`——宁可少给一个字段,也不给一个猜出来的数。 + +**与 NVIDIA 的差异**:NVIDIA 的 `report_progress` 是无条件上报(它的传输层本来就是 SSE);本仓做成「客户端要才给」,是因为本仓 MCP 同时服务 REST 直连与 MCP 两类调用方,而绝大多数 MCP 客户端并不消费进度通知——无条件 SSE 化会给每个请求都增加一次传输层变更,收益为零、风险不小。 + +--- + +## 3. P1 —— 结构性借鉴 + +### 3.1 概念层与物理层解耦(REPRESENTS 多对多) + +**NVIDIA**:一个 Term(业务概念)可被**多张表**代表,一张表也可有**多个 Term**(junction table 场景),关系在 `table__term`(`dal/schema.py:456-485`)。导出时一个 Term 会**导出它代表的全部表**(不论是否在范围内),理由是「keeps a partial export honest about a term it only partly owns」。 + +**本仓冲突点**:GB/T 兼容层把「类」直接映射到 `object_type`(单继承树),物理表这个概念目前**不在本体里**。 + +**取舍建议**:**保留双层**。GB/T 层继续用 `object_type` 表达概念;另加一类 link_type 表达「概念 ↔ 数据资产」的多对多关系,而不是把物理表也做成 object_type。这样不破坏 GB/T 映射,又能表达「一张表多视角」。 + +### 3.2 「认证」维度并入 axioms 第 6 类 + +**NVIDIA**:每个语义对象都有 `certified` / `name_certified` / `description_certified` 人工确认位,注释明写「nothing in the ingest ever writes it — it only appears once a human certifies a description」(`dal/schema.py:121-129`)。机器建议与已生效描述**分开存**(`description_suggestion`,`dal/schema.py:487-530`)。 + +**本仓现状**:`object_types.axioms` JSONB 五类 —— `disjointWith` / `equivalentTo` / `functionalLinks` / `inverseOf` / `dateOrder`(`server/ontology_axioms.go:20-24`),**没有「这条是人确认的还是机器生成的」这一维**。 + +**建议**:加第 6 类公理(如 `certification`),用公理机制承载而不是散落的布尔列——这正是本仓相对 NVIDIA 可以做得更好的地方(用标准兼容层而不是新列)。 + +### 3.3 资源 owner:行级写权限(我们完全没有) + +**NVIDIA**:owner 可为账号或 group;**两段式模型**——database/schema/table/term 读本行 owner(`_OWNED`),column/attribute 属 `_EDITABLE`(页面显示父级 owner,但判定不读本行 owner)(`dal/owners.py:26-47`);group 成员获得的权限**只对该行生效**,不扩大全局权限(`server/owners.py:52-75`);指派前校验该 owner 确有该权限(`server/owners.py:78-93`)。 + +**本仓现状**:确认 `grep -rn "object_owner\|owner_id" server/*.go` **零命中**。我们有 clearance(可见性轴),没有「谁能改这一条」这一维。 + +**建议**:加 `object_owner`(用户或组),与 clearance **正交**:clearance 决定「看不看得到」,owner 决定「能不能改」。比在 clearance 上加维度清晰。 + +### 3.4 zone:目录分区 + 授权边界 + +**NVIDIA**:zone 可指向 database/schema/table 三层(`dal/schema.py:729-790`),且是**授权边界不是相关度过滤**——「A term represented by any table outside table_ids is hidden entirely. **Not a relevance filter — an authorization boundary.**」(`dal/terms.py:82-104`)。 + +**本仓现状**:有 Marking(分级可见性),**没有分区**。(2026-11-06 已落地,见 §7 落地记录 S4.3。) + +**建议**:zone 落在「数据资产/连接」层,Marking 继续留在「本体对象」层,**两者叠加而非互斥**。 + +**反面教材(要避开的)**:NVIDIA 的 zone 当前**已被全局关闭**——所有 router 传 `zone_ids=None`,前端代理注释明说「zone membership stopped being an authorization boundary」(`frontend/auth/proxy-backend.ts:11-17`),`dal/search.py:33-35` 干脆没有 `zone_ids` 参数。**本仓若做实例级可见性,必须开箱即启用**,并加 CI 断言「每个读路径都带 scope 参数」。 + +### 3.5 跨版本结构 diff:机器事实 vs 人工策展 + +**NVIDIA 的短板正是我们的机会**:全仓无 `schema_versions`、无语义 diff、无旧版本回读。 + +**但 NVIDIA 的 diff 原则值得抄**(`catalog/diff.py:130-150`):增量 diff **只比源拥有的事实**——表比 `table_type`/`pk`,列比 `data_type`/`is_nullable`,**明确排除 `description`**(「it is curated in the UI and must survive a re-ingest」)。 + +**本仓落点**:`schema_versions` 已有 append-only 流水 + 按版本读回旧定义 JSON,但**没有「任意两版本结构 diff」**。建议补:type/property/link_type 的增删改 + axioms 变更 + IRI 变更,并**明确区分机器事实与人工策展**——否则重算会冲掉人工编辑。 + +### 3.6 三态存在性探针:Exists / NotExists / Invisible + +**这是本仓独有的高价值点**(NVIDIA 没有行级权限,做不到)。 + +问题:生成式回答引用了一个**真实存在但该主体无权看到**的实例;或 **FieldPolicy 把某列抹掉后,LLM 以为那列不存在而编了一个替代列**。 + +**建议**: +- 所有存在性探针返回**三态**而非两态 +- `Invisible` **不喂给 LLM**(否则它会编「不存在」的结论误导用户),而是作为 provenance 标记 +- 生成后校验时,若结果引用了**被 policy 抹掉的列名** ⇒ 判为**安全事件**,不是质量问题 + +**取舍**:需要把 Marking/FieldPolicy 的求值结果在生成管线里显式传下去,**不能只靠 Postgres RLS 行过滤**(RLS 管不了「列被替换成聚合值」这种语义)。 + +(2026-11-06 已落地管理面探针部分:见落地记录 S5。生成管线内的 provenance 传递待生成式问答。) + +### 3.7 证明式替换门:实体名 → pk 的带证据解析 + +**NVIDIA**(`sql_value_validation.py:330` `_apply_proven_substitutions`):「原值查不到」+「新值查得到」两条探针齐备才允许改;改完还要验证「只改了值、骨架不变、数量不变、改的正好是被批准的那些」,任一不满足 ⇒ **整批拒绝**。 + +**本仓落法**:实体名解析规则—— +- 精确命中 1 条 ⇒ 直接用 +- 精确命中 0 条,但大小写/空白归一后命中 1 条 ⇒ 允许替换,**并在返回里标注「已按实际存储拼写规范化」** +- 归一后命中 > 1 条 ⇒ **不替换**,返回歧义,要求澄清 +- 模糊多候选 ⇒ **不替换** + +**取舍**:多一次库查询。本体库在本地 Postgres,成本极低,**值得无条件做**。且替换动作本身是一次带 `source` 的写,可进 `object_changes` 审计。 + +### 3.8 指纹必须含 snapshot_id 与 principal(我们的差异化) + +**NVIDIA 的 `CacheKey`** 只有 connector/database/tables/schema/join/prompt/engine(`retrieval/kumo/graph_cache.py:100`)——**没有权限维度,也没有快照维度**。 + +**本仓必须带上**:`问题规范化 + 检索到的本体节点 id + 提示词版本 + 模型标识 + **snapshot_id** + **principal**`。 +理由:本仓有快照路由 + Dynamic Security,**同样的问题在不同快照/不同主体下答案不同**,指纹不带这两项就会串答案。 + +**可观测性同理**(照抄 `kumo/telemetry.py:4-8` 的理由):「Predictions are not deterministic and the data underneath them moves, so re-running the question is not a way of finding out what happened the first time.」——本仓的软删除、`source_ts`、分级抬升都会让同一问题的答案随时间变,所以每次生成式回答必须记录完整链路。 + +### 3.9 空结果的确定性预检查(我们的独有优势) + +**NVIDIA 的做法**:空结果时靠 LLM 重新推导(`agents/empty_result_value_repair.py:51`),并强调「An empty result can legitimately be the correct answer, so the retry is one-shot」。 + +**本仓可以做得更确定**——空结果的常见原因在我们这里是**可确定性判定**的三类,不该让 LLM 猜: +- 快照(`X-Snapshot-Id`)里该类型实例数为 0 ⇒ 直接说「该快照下无此数据」 +- 该主体 clearance 过滤后为 0 ⇒ 明确说「**无可见数据**」而不是「不存在」 +- Materialization 尚未完成 ⇒ 说「尚未物化」 + +**取舍**:这是「不可见 vs 不存在」问题在查询侧的落地,比 NVIDIA 的 LLM 重推确定得多。 + +(2026-11-06 已落地:见落地记录 S5。) + +### 3.10 澄清=MCP 场景要「一问一答」的结构化输出 + +**NVIDIA** 的澄清是多路确定性信号汇聚(未解析实体 / 不完整公式 / 输出不明确 / 历史未答),且有**歧义双阈值**(`_AMBIGUITY_MAX_GAP = 0.25`:best 0.10 / second 0.64 不算歧义,0.30 / 0.32 才算)(`interactive/entity_resolution.py:41, 68`)。 + +**本仓落点**:MCP 客户端往往一次调用,没有多轮澄清机会。所以澄清应表现为**结构化返回**而非交互循环: +`{needs_clarification: true, items: [{term, candidates[], suggested_question}]}`,并提供「按最可能解释直接回答」的降级路径 + 标注「本次基于假设 X,请确认」。 + +(2026-11-06 已落地:可答性报告新增 `needs_clarification` + `items`,见落地记录 S5。) + +### 3.11 导入语义与 append-only 版本流水的冲突(须由我们定义) + +NVIDIA 的导入是「replace 语义 + 幂等 upsert」,**不产生版本历史**。本仓的 `schema_versions` 是 append-only。 + +**必须定义**:导入应**产生一个新版本**而非就地覆盖,否则「导入即破坏版本流水」。同时把 NVIDIA 的「范围对账删除」逻辑接到**新版本 diff** 上(物理上不要 DELETE)。 + +### 3.12 规则(rule)的两阶段重放 + 禁止自指筛选 + +**NVIDIA**:rule = 「保存的全局搜索 + 要打的标签」,**软规则不阻断**(`dal/rules.py:1-30`)。重放**必须两阶段**:所有规则先移除失配标签,再统一应用新匹配——因为 `tag_target` 每 (tag,object) 一行,逐条循环会让「拥有者规则」的移除误删另一条规则还在用的标签(`server/rules/service.py:258-330`)。另有硬约束:**不允许规则以「未打标签」为筛选条件**(会自我失效 + 每夜 churn)。 + +**本仓落点**:若做「自动分级规则 / 自动加 marking」的常驻指令,同一坑会踩到。 + +--- + +## 4. P2 —— 可延后 + +| # | 机制 | 出处 | 本仓落点 | +|---|---|---|---| +| P2-1 | tag 带来源(人/规则),先写者胜;受保护系统标签 | `dal/tags.py:1-33, 74-79` | 分类打标区分「人工/自动」,自动重跑不夺人工标签 | +| P2-2 | 派生对象继承源标记 + 源改密级时重算派生物 | `dal/pii.py:220-250` | `recompute_classification` 可加第三维:类型默认 → 实例覆盖 → 派生继承 | +| P2-3 | 值锚点:区分「活库观测值」与「schema 猜测」 | `text_to_sql/value_anchors.py` | 生成式回答引用实例名/枚举字面拼写前先做活库观测 | +| P2-4 | 统一分页/信封 `{data,count,total}` + `MAX_PAGE_SIZE` 单点常量 | `server/pagination.py:16-32` | ✅ 已落地(2026-11-06):`server/pagination.go` 的 `pageEnvelope` 统一 `count`/`total`/`limit`/`offset`/`has_more`/`truncated`;检索与图式查询补 `total`/`truncated` 并支持 `offset`(见下文「P2-4 的实现取舍」) | +| P2-5 | `extra="allow"` 教训:响应模型不许丢未声明字段 | `server/responses.py:12-16` | Go 侧若用 `DisallowUnknownFields`,**新增响应字段会直接 400**,务必允许未知字段 | +| P2-6 | 能力位模式(`supports_statement_timeout`)而非每连接器都实现 | `connectors/base.py:114-123` | 将来做数据源连接器时按能力位设计 | +| P2-7 | graph 检索三纪律:深度按**边**算不按跳、反向边仅当目标是主键、跨库直接拒绝 | `dal/attributes.py:36-46, 797-820, 1058-1064` | 本仓知识图谱检索的正确性提升项 | +| P2-8 | 统一边集视图(把多类边 UNION 成可遍历集) | `alembic/.../c778a7d94c20:63-88` | 本仓若做统一边遍历,可照此建视图 | +| P2-9 | 召回配额(按 label 分别截断:Column 10 / Analysis 3 / SqlAttribute 3) | `retrieval/data_access/semantic_search.py:53-61` | 本仓做语义检索时的配额参考 | +| P2-10 | skills 层形态:`SKILL.md` + `assets/runtime-contract.yaml`(带类型 artifact / statuses / gates / fail_closed_when / handoffs) | `skills/nvidia-ontology-query/assets/runtime-contract.yaml` | 本仓 `server/mcp_guide.go`(`get_usage_guide`)+ `server/reviewkit/` 已是同源形态,可往 runtime-contract 的「receipt 化」演进 | + +--- + +## 5. 明确**不要**照搬 + +| # | NVIDIA 做法 | 为什么不能抄 | +|---|---|---| +| N1 | **「可信内部身份头」**:后端完全不认证,只读 `x-auto-ontology-user-id`,缺头 = 不检查(`server/identity.py:6-38`、`server/owners.py:100-102`) | 本仓的 `principals` **就是安全边界本身**,后端必须自证身份。若本仓前后端分层,内部头必须带签名且**缺头默认拒绝**。
⚠️ 注:本仓 `X-Principal` 越权洞已于 `25bbd15` 修复(外部一律不认该头,主体只来自真实凭据),**该 P0 已闭环**,无需再动 | +| N2 | **PII 只做标签不做脱敏**:retrieval 路径完全不感知 PII(`retrieval/` 下 grep `pii` 零命中) | 本仓有 L0-L3 + `object_markings` + `FieldPolicy`,**不需要第二套分类体系**。抄它的「检测机制」(规则优先→LLM兜底→仅元数据→不确定取最严→阈值自动标记)接到现有 `FieldPolicy`/`classification` 通道即可 | +| N3 | **只有 admin/viewer 两角色 + 扁平 resource×action** | 本仓已有 clearance,再叠一套角色矩阵会出现**两个正交过滤器叠加**,403 原因难表达。建议:clearance 保持为**唯一数据可见性轴**;resource×action 只承载粗粒度管理能力,且**永不作为数据可见性判据** | +| N4 | **Vault 部分配置 → 警告 → 明文回落**(`connectors/vault.py:34-47`) | 有 L0-L3 分级的平台里,降级到明文存凭据是错的默认。本仓应 **fail-fast**:区分「Vault 未启用(显式选择明文)」与「Vault 配坏了(必须报错)」 | +| N5 | **跨 schema 无外键成员表**,账号删除留孤儿 membership(`dal/schema.py:1163-1180`) | 本仓 `principals`/`object_markings` 应保留真实外键或显式墓碑语义 | +| N6 | **`limit` 省略 = 返回全部匹配行** | 与「agent 上下文有限」冲突。本仓 MCP 层应给保守默认,导出类接口显式绕过 | +| N7 | **「A rule that labelled more than the dialog showed is a rule they did not agree to」**(创建路径有上限、重放路径无上限) | 这条本身是好设计,但要连同「规则是软的不阻断」的定位一起理解,本仓若做硬校验须另设一档 | +| N8 | 迁移里 **import 应用代码常量** | NVIDIA 自己已经反向采纳(内联常量,「A migration is a record of what ran; it should not be able to change afterwards」,`alembic/.../c778a7d94c20:33-56`)——本仓照抄它的**最终形态**即可 | + +--- + +## 6. 本仓已领先(可反向输出给外部/开源社区) + +这三条是本仓相对 NVIDIA 的**结构性优势**,做对外方案时应主动讲: + +1. **字段级审计 diff + 可回滚**:`object_changes` 存 added/removed/changed + snapshot + links_snapshot,`restore_object` 可回滚(issue #4 修的洞)。NVIDIA 无。 +2. **schema 层审计**:`ontology_audit_log` 记对象类型/属性/链接类型的增删改,create 落 after、update/delete 落 before。NVIDIA 只有 `created_by/modified_by`。 +3. **快照路由**:任意 GET 带 `X-Snapshot-Id` / `X-Snapshot-Ts` 命中历史快照库,写请求带快照头 403。NVIDIA 无等效机制。 +4. **append-only 版本流水 + 按版本读回**(`schema_versions`):NVIDIA 完全无语义模型版本。 +5. **GB/T 48000.3-2026 兼容层**:IRI 固化 + 多语 `@lang` + 单亲继承闭包 + 五类公理 + Turtle 导出。NVIDIA 只有 Ossie YAML 一条路,且无公理表达。 + +--- + +## 7. 建议落地路线 + +| 阶段 | 内容 | 影响面 | 前置 | +|---|---|---|---| +| **S1 · 探针** | 加 `check_readiness` + `check_answerable` 两个 MCP 工具 | MCP 工具层,无 schema 变更 | 无 | +| **S2 · 语义钉死** | `None`/`[]` 语义分离 + 加单测;只读性写成测试;工具注册表单点化 | 读路径 + MCP 层 | 无 | +| **S3 · 导入前置** | 写下导入的三重校验 / 整事务 / 幂等 / 产生新版本 的设计约束(文档先行,不实现) | 设计文档 | 无 | +| **S4 · 结构扩展** | axioms 第 6 类(认证);`object_owner`;zone 分区;版本 diff | schema 变更 | S3 定稿 | +| **S5 · 生成式链路** | 三态存在性探针 / 证明式替换 / 空结果确定性预检 / 指纹含 snapshot+principal | 仅当本仓引入生成式问答 | 需要先有 IR 设计(**空结果预检 / 三态探针 / 结构化澄清 / 报告带 principal+snapshot 不依赖生成式问答,已先行落地 2026-11-06**) | + +**明确不做**:不引入 RDF/OWL 双存储;不引入 admin/viewer 角色矩阵;不引入可信内部头;不新建 PII 式平行分类体系。 + +### 落地记录 + +| 阶段 | 状态 | 落点 | +|---|---|---| +| S1 · 探针 | ✅ 已落地(2026-11-06) | `server/readiness.go`(核心逻辑)、`server/readiness_words.go`(停用词表)、`server/readiness_test.go`(纯函数单测)、`server/readiness_integration_test.go`(端到端);MCP 工具 `check_readiness` / `check_answerable`;REST `GET /api/v1/connector/readiness` + `POST /api/v1/connector/answerable` | +| S2 · 语义钉死 | ✅ 已落地(2026-11-06) | `server/scope.go`(Scope 类型 + 标记/分级两个维度的可见范围)、`server/scope_test.go`(纯函数单测)、`server/scope_integration_test.go`(分级语义端到端)、`server/mcp_registry.go`(MCP 工具单一注册表)、`server/mcp_drift_test.go`(注册表 ⇄ dispatch 双向漂移)、`server/mcp_registry_integration_test.go`(可分发性 + 只读纯度);读路径改造见 `server/handlers_objects.go` / `server/classification.go` / `server/access_control.go` | +| S3 · 导入前置 | ✅ 已落地(2026-11-06,文档先行 → 实现落地) | `docs/ONTOLOGY_IMPORT.md`:四道 fail-fast 闸门(根键匹配 G1 / 文档非空 G2 / 作用域内必须有实体 G3 / 逐实体校验 G4)、整事务导入(走 `a.pool` 不绕快照路由)、`(source, external_id)` 幂等、导入必产新的 `schema_versions`、IRI↔内部 pk 双空间映射;含 10 条实现前必写的测试清单。
**实现(2026-11-06)**:`server/ontology_import.go` + `server/ontology_import_turtle.go`(自研最小 Turtle 解析器)、`server/ontology_import_test.go`(单测)、`server/ontology_import_integration_test.go`(§10 十条全覆盖);端点 `POST /api/v1/ontology/import`(merge 模式 + dry_run,`replace` 明确拒绝)+ MCP 工具 `ontology_import`;幂等映射落 `import_identities`(DDL 在 `server/db.go::migrate()`);版本策略「一次导入一条汇总版本 + 逐实体审计明细」。**偏差与实现期修掉的缺陷见 `docs/ONTOLOGY_IMPORT.md` §12**(含 RDF Schema 命名空间年份不一致这个真 bug) | +| S4 · 结构扩展 | ✅ 已落地(2026-11-06) | **S4.1 公理第 6 类(认证位)已落地**:`server/ontology_axioms.go`(`certificationRule`)、`server/ontology_axioms_check.go`(`validateCertification`)、`server/ontology_export.go`(Turtle `sswo:certified*` 注解)、`server/ai/ai.go`(重摄取不冲掉已认证条目)、`server/ontology_certification_test.go` + `server/ontology_certification_integration_test.go`。
**S4.2 行级可改性轴已落地**:`server/object_owner.go`(判定核心)、`server/handlers_object_owner.go`(REST)、`server/access_control.go`(`object_owners` / `principal_groups` DDL)、`server/object_owner_test.go` + `server/object_owner_integration_test.go`;写路径收敛到 `canWriteObject`(handlers_objects / instance_governance / handlers_action);MCP 新增 4 个工具。
**S4.4 跨版本结构 diff 已落地**:`server/schema_diff.go`(事实采集 + 纯函数比对)、`server/db.go`(`schema_snapshots` DDL)、`server/schema_audit.go`(变更同点落快照)、`server/handlers_versions.go`(`/ontology/schema/diff` `/schema/snapshots` `/schema/snapshot`)、`server/schema_diff_test.go` + `server/schema_diff_integration_test.go`;MCP 新增 3 个工具。
**S4.3 zone 分区已落地**:`server/zone.go`(判定核心:分区绑类型 + 命中任一即可见 + fail-closed)、`server/handlers_zone.go`(REST `/api/v1/access/zones`)、`server/access_control.go`(`zones` / `object_zones` / `principal_zones` DDL + `Authz.Zones`)、`server/zone_test.go` + `server/zone_integration_test.go`(含「每个读路径都带 scope」的行为级 CI 断言);读路径改造覆盖 connector objects/object/search/query/graph/facets + 对应 MCP 工具;MCP 新增 3 个工具(清单 52 个)。 | +| S5 · 生成式链路 | 🟡 部分落地(2026-11-06) | **不依赖生成式问答的部分已落地**:§3.9 空结果的确定性预检查(`server/empty_reason.go`:读路径回包带 `empty_reason`,区分 `no_data` / `not_visible` / `no_type` / `not_materialized` / `no_match`);§3.6 三态存在性探针(`server/existence.go`:`GET /api/v1/access/existence` + MCP `probe_existence`,返回 `exists` / `invisible` / `not_exists`,附 `blocked_by`);§3.10 澄清的结构化输出(可答性报告新增 `needs_clarification` + `items[{term, candidates, suggested_question}]`);§3.8 的两个维度(体检与可答性报告带 `principal` 与 `snapshot`);§3.11 已在 S3 落地(导入必产新 `schema_versions`)。
**仍待生成式问答/IR 设计**:§3.6 把 Invisible 作为 provenance 传进生成管线、§3.7 证明式替换门(实体名→pk 带证据解析)、§3.8 完整生成指纹(问题规范化+节点 id+提示词版本+模型标识)、§3.12 规则两阶段重放(本仓无「自动加 marking/分级」的常驻指令机制) | + +**S1 的实现取舍(与 §2.1/§2.2 的原始设想有出入的地方,以实现为准)**: + +1. **分档口径**:`blockers` = 确定坏了(无对象类型 / 无实例 / 当前主体一条都看不到); + `unverified` = 因权限判不了(快照能力需 manager 验证);`warnings` = 能用但有缺口 + (未启用分级引擎 / 实例分级游离在引擎之外 / 类型缺 IRI / 类型注册了 `data_level` 属性却没配引擎)。 + NVIDIA 只有两档,本仓多一档 `warnings`,因为本仓的分级/标准兼容层缺口比它多,硬塞进 blockers 会让告警失真。 +2. **「当前主体一条都看不到」算 blocker 而不是 unverified**:这不是「判不了」,而是「判定结果就是 0」—— + Dynamic Security 过滤生效的直接证据,必须可执行(正解是降低类型默认级,不是抬高主体)。 +3. **覆盖率口径是自研的确定性算法**,不是照抄 NVIDIA 的 entity-coverage: + ① 已注册的类型名/属性名/关系名 → 最长匹配; + ② 实例名出现在问题里 → 命中(SQL 反向包含 `strpos(lower(question), lower(name))`,长名优先占位); + ③ 剩下的实义片段若是某个已注册名字的子串(「数据空间」⊂「可信数据空间」)→ **部分命中**(score < 1); + ④ 仍没落地的片段 → 去实例表找近似名作为 `candidates` 供消歧。 + 覆盖率 = 已覆盖字符 / 全部实义字符,阈值 0.5。**无 LLM、无随机**,同问题同输出。 +4. **停用词表分两档,刻意保守**:硬停用词(的了吗是在和与或及为把被从到就都也还很更最只这那些什么怎样多少几哪有谁否请问帮查看列吗呢吧呀个张)永远断句; + 软停用词(出所并含带且等内外中里上下于向则)**只有与相邻停用词成串时才断**—— + 否则「出口数量」「数据中枢」「所属机构」这类实词会被拆残。 + 纯度量词(数量/总数/数据/信息…)整词丢弃:不计入分母,也不该出现在 `uncovered` 里让人去补建模。 +5. **真实语料回归**:拿生产库(49 类型 / 3580 实例)实跑, + 「有哪些可信数据空间」→ 覆盖率 1.00;「广州数据集团运营了哪些数据空间」→ 命中实例 `MemberOrg:m_guangzhou` + 部分命中 `运营方`/`可信数据空间`,覆盖率 0.67; + 「火星基地的氧气含量是多少」→ 覆盖率 0.00,uncovered 列出两个未落地实体。 +6. **走 `a.pool`(dbRunner 接口)**,快照路由(`X-Snapshot-Id`)自动生效; + 实例相关查询按调用主体的 `visibilityCond` + `classificationCond` 过滤,不泄露越权实例的存在性。 +7. **MCP 侧直调核心逻辑**(不经 HTTP 往返),因此不受 `connectorAuth` 的 key 校验限制, + 但鉴权仍按当前主体的真实 clearance 走。REST 侧走 connector 组,供外部消费方复用同一套逻辑。 + +**S2 的实现取舍(与 §2.4/§2.5 的原始设想有出入的地方,以实现为准)**: + +1. **Scope 是三档而不是两档**:`ScopeUnscoped`(不施加过滤)/ `ScopeDenyAll`(过滤生效且拒绝全部)/ + `ScopeAllow`(只放行可见取值)。NVIDIA 侧只有「有白名单 / 无白名单」两种, + 但本仓的分级维度天然存在「未启用分级」这一档——把它塞进 `Unscoped` 会让「该维度不适用」 + 与「该维度无人有权限」混为一谈。 +2. **ScopeAllow 的 Values 恒表示「可见集合」**,不表示「被拒集合」——SQL 用的屏蔽表由 + `deniedLevels` 从可见集合反推,避免两套方向相反的清单同时存在而产生矛盾。 +3. **分级收紧为 fail-closed**:实例分级为空 ⇒ 继承类型默认级(不是「无限制」); + 主体与某类型级别完全无交集 ⇒ 该类型实例一律不可见(连「级别未定义」的存量实例也不放行)。 + 这是本仓**唯一一处收紧既有行为**的地方:原语义下「先灌数据、后配分级引擎」的存量数据 + 对所有主体无条件可见。配套修掉一个实现坑:`objects.classification` 存的是空串而不是 NULL + (列默认 `''`),故回落到默认级必须写 `COALESCE(NULLIF(col, ''), default)`, + 否则空串不会触发回落。 +4. **「无 clearance 记录 = 什么都看不到」是收紧**(原先等同「只放行公开对象」)。 + 口径依据:主体既然一条 clearance 都没有,就没有任何可看的分级;且平台给每个对象默认打 L0 + 标记,清空 clearance 应当等于「彻底失明」而不是「只看公开」。 +5. **只读性测试用「平台状态指纹」而非逐表断言**:对 `objects` / `links` / `object_types` / + `properties` / `link_types` / `object_markings` / `principal_clearances` / `grants` / + `field_policies` / `object_changes` / `schema_versions` / `ontology_audit_log` / `km_files` + 逐表算 `count + md5(string_agg(row_to_json))`,调用前后必须一字不差。 + **排除 `access_log`**——它是访问审计流水,每个请求都写,不是「平台状态」。 +6. **注册表 ⇄ dispatch 的双向漂移由 AST 解析拦截**(`server/mcp_drift_test.go`), + 而非启动期 fail-fast:本仓是单体二进制,没有独立的 spec 装载期可挂检查点, + 放进单测反而能覆盖 CI 与本地两种运行方式。双向检查能同时挡住 + 「注册表声明了却调不通」与「能调却不声明(被准入拦成未知工具)」两种漂移。 +7. **注册表只做「单一事实来源」,不自动生成工具**:路线 B(从 Gin 路由表双向生成工具) + 本仓未采纳——MCP 工具的参数模型与 REST 路由参数并不同构(如 `update_object_type` + 的 `api_name` 既是 MCP 参数又是路由参数),强行生成会把 REST 的多态参数摊平成工具 schema。 + 现阶段收益(防漂移)已由注册表 + 双向测试拿到,生成化的成本留给「Function 自动注册为 + MCP 工具」那条待办一起做(届时需要先统一参数模型)。 +8. **`update_enum` 的写闸门此前已有 `canWrite` 检查**(`handlers_mcp.go`), + 本轮复核确认无需补;MCP 写闸门统一读 `grants` 表(`authz.CanWrite("write","*","*")`), + 不再写死 `manager`/`ingest` 两个主体名——给其他主体授 `manage` 后 MCP 与 REST 口径一致。 + +**S3 的实现取舍(与 §2.3 的原始设想有出入的地方,以 `docs/ONTOLOGY_IMPORT.md` 为准)**: + +1. **闸门从三重扩到四道**:原设想是「根键匹配 + 文档非空 + 作用域内必须有实体」三重, + 本仓再加一道 **G4 逐实体校验失败即整体拒绝**——因为本仓有公理声明(GB/T 48000.3 兼容层), + 公理自相矛盾的类型一旦落库就是脏数据,且没有实例层的「部分成功」退路。 +2. **幂等键从 `coalesce(imported_id, id)` 改为 `(source, external_id)`**:NVIDIA 的 `imported_id` + 是导入方写进文档的字段,本仓没有这个概念;改用「来源命名空间 + 来源侧稳定 id」, + 语义更清楚,且能支持「同一实体来自多个来源」的场景。 +3. **范围对账删除明确不做**(NVIDIA 有):本仓没有「范围」概念(多本体仍是「仅规划,不执行」), + 且删除语义与本仓的 append-only 版本流水 + 软删除/`restore_object` 回滚方向相反。 + 硬做会产出「历史版本说它存在、现在说它没了且无法回滚」的状态。 +4. **「导入产生新版本」的具体形态**:不是「一次导入 = 一条版本行」, + 而是**一条汇总行(`action='import'`)+ 每个受影响实体的明细行**(沿用现有 create/update 词表), + 后者由既有的 `schemaAudit` 同点写出——**导入不得绕过 `schemaAudit`**,绕过即版本流水断点。 +5. **审计失败不阻断、回滚不假账**:公理 / URI 校验失败必须阻断回滚, + 但 `schemaAudit` / `object_changes` 写入失败只记日志(既有约定:审计不该让业务写失败)。 + 实现时审计**必须走 `a.pool`**,否则事务回滚后审计会留下「记录了但其实没导入」的假账。 +6. **IRI 不是主键**:`properties.iri` 按属性名全局拼接,同名属性跨类型共享同一 IRI, + 故属性的主键仍是 `(object_type_id, api_name)`;IRI 只作跨系统对应,不作导入去重键。 +7. **首版只支持 Turtle**(与现有导出对称),不做 RDF/OWL 双存储、不做推理。 +8. **文档先行,不实现**:本阶段只交付约束文档 + 10 条实现前必写的测试清单, + 端点与载荷形态在文档里占位(`POST /api/v1/ontology/import`,带 `mode` / `source` / `dry_run`), + 实现时定稿。 + +**S4.1(认证位)的实现取舍(与 §3.2 的原始设想有出入的地方,以实现为准)**: + +1. **认证位是公理机制的第 6 类,不是散落的布尔列**:沿用 `object_types.axioms` JSONB, + 与 disjointWith / equivalentTo / functionalLinks / inverseOf / dateOrder 同体, + 随 Turtle 导出为 `sswo:certified*` 注解——公理是「类型属主自己声明的关系」, + 认证正是这种关系(属主声明「这一条我确认过了」)。 +2. **认证位必须自洽**:`certified=true` 必须同时给出 `certifiedBy` 与 `certifiedAt` + (RFC3339),否则 400;`certified=false` 时不得残留认证人/时间,也不得单独标 + `nameCertified` / `descriptionCertified`。说「已认证」却说不清谁在何时认证 = 不可追溯 = 拒绝。 +3. **字段级粒度**:`certified` 管全部,`nameCertified` / `descriptionCertified` 可单独管一个字段—— + 「显示名我认了,描述还要再看看」是常见状态,硬做成全有全无会逼用户过度声明。 +4. **它真正改变的是 AI 重摄取的行为**(这是认证位存在的全部意义):已认证的显示名与描述 + 在 `ai.ApplySuggestion` 重抽取时**不被覆盖**,未认证的照常覆盖。认证位因此是 + NVIDIA「机器事实 vs 人工策展」那条原则在本仓的第一个落地实现点。 + 实现坑:PostgreSQL 的 `ON CONFLICT DO UPDATE` 只能看到目标表与 `EXCLUDED`, + 看不到 `INSERT ... SELECT` 的来源表,故认证标志要在属性 upsert 之前单独查一次, + 再作为 SQL 参数传进去(`$13`)。 +5. **未覆盖的旁路**:AI ApplySuggestion / KM import / restore / seed 这几条旁路不守公理校验 + (既有局限,与 schemaAudit 覆盖范围一致),认证位在这几条路径上同样不生效。 + +**S4.2(行级可改性轴)的实现取舍(与 §3.3 的原始设想有出入的地方,以实现为准)**: + +1. **归属只收窄、不放宽**:`grants` 表仍是「能做什么动作」的唯一真源,归属是在 grant 之上 + 的一层收窄——对象设有归属时,非归属方即便持有该类型的写授权也不能改这一行。 + 若反过来让归属本身授予写权限,「谁拥有写权限」就散落在 grants 之外, + 管理界面看到的授权清单将不等于实际权限。 +2. **未设归属 = 不限制**:存量库零影响,不需要任何迁移脚本或批量回填; + 归属是逐行 opt-in 的。「先设归属、后发授权」的编排也常见,故归属方未持有 write 授权时 + **只提示不阻断**(NVIDIA 是硬校验,本仓改成提示)。 +3. **不引入两段式模型**:NVIDIA 的 column/attribute 属 `_EDITABLE`(页面显示父 owner, + 判定不读本行 owner)是因为它的层级是 database/schema/table/column; + 本仓的实例没有这条层级链,「显示父级归属、判定读子级」那套没有对应物—— + 归属直接落在 `(type, pk)` 一层。 +4. **组的权限只对该行生效**:组只作为归属的载体存在,**本身不携带任何全局权限** + (`principal_groups` 不参与 grant 匹配)。与 NVIDIA「group 成员获得的权限只对该行生效」一致。 +5. **删组连带解除引用该组的归属行**:否则组没了、归属行还在,那些行会变成 + 「谁都改不了」的静默死锁(只有 manager 能动)。响应里回报解除了多少行。 +6. **归属方可转交行,解除归属仅 manager**:转交是行内事务(谁能管这行由当前归属方决定), + 解除是撤掉整道限制(比设置更强),故要求 manager。 +7. **写路径只有一个收敛点**:所有对象写路径(create / update / delete / restore / batch / + action / 链接两端)统一走 `canWriteObject`,归属查询失败即拒绝(fail-closed)。 + manager 豁免(与 `CanRead` / `CanWrite` 的 manager 特例一致)。 +8. **新增的表是纯 opt-in 的两张**:`object_owners` 与 `principal_groups`, + DDL 幂等写在 `server/access_control.go::ensureAccessControlSchema`(与既有 5 张访问控制表同处); + 集成测试环境也调同一入口补建(共享测试库是存量库,新表不会因为「跑过一次老版本」而存在)。 +9. **MCP 侧刻意不过粗粒度写关卡**:`set_object_owners` 的授权是「manager 或该行归属方」, + 由 handler 按行判定——归属方未必持有全局写授权,硬套 `canWrite("write","*","*")` 会误杀。 + +**S4.4(跨版本结构 diff)的实现取舍(与 §3.5 的原始设想有出入的地方,以实现为准)**: + +1. **用全量快照,不回放版本流水**:`schema_versions` 是一次变更一行,且更新走部分更新语义 + (`COALESCE(NULLIF(...))`),流水里的 `after` **不是完整状态**——回放重建的历史状态必然掺假。 + 故每次 schema 变更后另落一份全量结构快照(`schema_snapshots`),「任意两版本」退化成 + 两次读文件的比较。代价是每次变更多几次查询,换来 diff 结果可信。 +2. **机器事实 / 人工策展是两组字段,不是一个标记**:每条结构事实(类型 / 属性 / 链接类型 / + 链接属性 / 动作类型)的字段被拆成 `machine_fact`(结构与配置)与 `curated`(显示名、描述、 + 多语标签、`certification` 认证记录)。这正是 NVIDIA「只比源拥有的事实、排除 description」 + 的做法在本仓的落法——不是排除某个字段,而是**声明每个字段归谁所有**。 +3. **认证位是「人工策展」的标记位**:带 `certification` 的条目在 diff 里额外标 `certified=true`。 + 改动这类条目 = 改人工确认过的东西,值得人工确认——与 S4.1「重摄取不冲掉已认证条目」同源。 +4. **基线不是历史真值**:本仓的版本流水自 2026-09-11 起才有,更早的结构无法重建。 + 故 `version=0` 落的是「快照机制启用那一刻的实时结构」,`label` 里写明来源—— + 不能让它冒充「版本 0 时刻的结构」。 +5. **只能比有快照的版本**:请求一个没有快照的版本 → 400 并提示查快照清单,不静默返回空差异 + (空差异会被读成「没变化」,是最坏的失败方式)。 +6. **读路径不受影响**:diff 读的是结构元数据,不涉及实例,故连接器侧(`/connector/schema/diff`) + 与管理侧同口径开放;实例可见性仍走 Dynamic Security 那条线,两件事不混。 +7. **未做**:不做「diff 结果直接回滚」(回滚走既有的 `restore_object` / 快照路由); + 不做跨库 diff(只比本库版本)。 + +**S4.3(zone 分区)的实现取舍(与 §3.4 的原始设想有出入的地方,以实现为准)**: + +1. **分区绑在对象类型上,不绑实例**:NVIDIA 的 zone 指向 database/schema/table 三层, + 对应到本仓最接近的落点是「数据资产层」——本仓没有独立的物理表层,只有对象类型这一层 + 资产边界。绑在类型上还有一个决定性的好处:**一条条件能覆盖全部读路径**。 + §3.4 的反面教材正是 NVIDIA 自己的 zone 被全局关闭——没有一条断言守着, + 新加的 router 忘了传 `zone_ids` 就会静默越权。绑在类型上时, + 每个列表类读路径只需一个 `NOT (type = ANY(denied))` 条件,详情类只需一次 `zoneAllowed`。 + 代价:分区粒度到类型为止,做不到「同一类型里只划一部分实例进分区」—— + 要这个粒度得另设实例级分区机制(当前**不做**,见第 7 条)。 +2. **判定口径是「命中任一即可见」,不是「必须全部命中」**:类型同时属于两个分区时, + 持有任一分区的主体都看得见。选 AND 语义的话,给一个类型追加第二个分区会 + **静默收回**现有持有者的可见性——这种「加配置反而掉数据」是最难排查的一类事故。 + OR 语义下新增分区只会**放宽**可见性,方向上更安全。 +3. **fail-closed 的方向是「主体零分区 → 什么都看不见」**:主体一个分区都不持有时, + 所有被分区的类型都不可见;只有**未入任何分区的类型**(公共区)才对全体可见。 + 这与 clearance 语义一致(无 clearance 记录 = 看不到实例),不给主体默认放行。 + manager 豁免。分区表加载失败 → fail-closed(宁可看不见,不可越权)。 +4. **分区只收窄可见性,不改可改性**:分区是「读轴」,不是「写轴」。 + 可改性仍由 grants + 行级归属(S4.2 的 `canWriteObject`)决定。 + 这样分区不会与既有写路径的语义打架,也不用改动摄取/批量写链路。 +5. **未配置分区 = 零影响**:分区表默认为空 → 条件恒为 `TRUE` → 行为与从前完全一致, + 存量库零迁移成本。「开箱即启用」在这里成立:不需要任何配置就有分区语义, + 需要的是**一旦配置就立刻全面生效**——分区表在每次请求实时读取, + 只有主体侧的分区归属进鉴权缓存,写分区后失效缓存即可。 +6. **不藏 schema,只藏实例**:分区内类型的**类型定义、属性、关系结构照常可见**, + 越权的是**实例内容**(列表里不出现、详情 404、检索不命中、图谱里不出现该节点)。 + NVIDIA 的 zone 隐藏的是物理表,恰好连带隐藏了结构;本仓的物理层是共享的 + (类型定义对所有主体是同一份),强行按主体裁剪 schema 会让「同一类型在不同主体眼里形状不同」, + 反而更难推理。实例级的授权边界才是 zone 的本意("an authorization boundary")。 +7. **未做**:不做实例级分区;不做分区的继承/嵌套(分区是平铺的); + 不做按分区自动推导 clearance(两轴独立配置,叠加生效)。 +8. **CI 断言是行为级的,不是代码扫描**:`TestIntegration_ZoneEveryReadPathCarriesScope` + 造一个只在受限分区里的探针实例,逐条请求 11 条读路径(connector 的 + objects/object/search/query/graph/facets + 对应的 6 个 MCP 工具), + 回包里出现探针 token 即判定越权;随后给主体授分区,断言实例**变得可见**—— + 证明「看不到」不是因为别的条件挡的(否则断言会空转)。 + 判据用实例主键与维度取值,**不用实例名**:检索接口会原样回显查询参数,用名字会误报。 + 代码扫描式的断言(grep 某个函数名)挡不住「条件写错了」, + 行为断言能同时挡住漏加条件、加错列、加了但被后续逻辑绕过三种情况。 +9. **顺带补上一个既有缺口**:维度取值接口(`connector/facets` / `get_facets`) + 此前**完全不过滤授权**——受限实例的维度取值会从维度列表里漏出去。 + 本次一并补上标记 / 分级 / 分区三个条件(这是分区能成立的前提: + 维度接口也是读路径,同样要带 scope)。 +10. **管理面接口仅 manager**:`GET/POST /api/v1/access/zones`、`DELETE /api/v1/access/zones/:name` + 与 principals/grants 同级。`set_zone` 是全量替换语义(types 与 principals 都整体覆盖), + 引用不存在的对象类型或主体一律 400——**配错名字时静默失效**是最难查的一类问题。 + +**S5 的实现取舍(生成式链路:先落地不依赖生成式问答的那一半)**: + +S5 的前提是「本仓引入生成式问答」,而本仓目前只有查询能力、没有生成管线。 +把整段 S5 判成「不适用」会丢掉其中**已经可以确定的部分**——生成式链路要解决的 +问题,有一半在查询侧就能解,而且**现在就能解**: + +1. **空结果的确定性预检查(§3.9)先行落地**:NVIDIA 的空结果处置是「让 LLM 重新推导一次」 + (one-shot retry),因为在它那边空结果的原因本来就是概率性的(检索没召回 / 表达式写错)。 + 本仓的空结果原因**大部分是确定性可判定的**,所以不必退化成一次 LLM 猜谜: + `no_data`(真没数据)/ `not_visible`(有数据但当前主体看不到)/ `no_type`(类型没注册)/ + `not_materialized`(物化还没跑)。四者的处置完全不同,混成一句「查不到」会让调用方 + (以及读它的 LLM)把「不可见」当成「不存在」——用户被告知一条真实存在的数据不存在。 + 落法:`server/empty_reason.go`,读路径空回包带 `empty_reason`(连接器实例列表 + 检索)。 +2. **原因不报条数**:判定「不可见」时只说被哪一维挡住(标记 / 分级 / 分区), + **不给条数**。条数本身就是存在性泄漏——把它加进「可解释性」等于换个口子在泄密。 + 集成测试直接断言 `empty_reason` 里不出现被挡住实例的主键。 +3. **三态存在性探针(§3.6)走管理面,不改读路径**:读路径对越权实例一律 404(不泄漏存在性), + 这是对的,**不能为了三态把 404 改成 403/200**。所以三态单独做一条探针 + (`GET /api/v1/access/existence?type=&pk=&principal=` + MCP `probe_existence`), + **仅 manager 可用**——它能回答「某主体看不看得见这条实例」,等于把越权实例的存在性 + 抖给调用方,非 manager 调一律拒绝。返回 `exists` / `invisible`(附 `blocked_by`: + grant / marking / classification / zone)/ `not_exists`。 +4. **「Invisible 不喂给 LLM」落成显式约束,而不是靠自觉**:探针回包带 `note` 字段写明 + 「invisible 是溯源标记:据此要说『当前主体无可见数据』,不要据此说『不存在』」。 + §3.6 强调的正是这点——把 Invisible 当成「查不到」的结论喂给用户,会得到一个 + 「本体里没有这条数据」的错误断言。 +5. **澄清的结构化输出(§3.10)**:MCP 客户端往往一次调用,没有多轮澄清的机会, + 所以澄清必须表现为**结构化返回**而不是交互循环。可答性报告新增 + `needs_clarification` + `items[{term, candidates, suggested_question}]`—— + 直接照 `suggested_question` 追问即可,不需要客户端自己拼提示词。 +6. **指纹的两个维度现在就带上(§3.8 的可落地部分)**:体检与可答性报告带 `principal` 与 + `snapshot`——同样一个问题,在活库与在某个历史快照下答案不同,同一主体的答案也不同; + 报告不带这两项,两次看起来一样的报告可能查的根本不是同一批数据。 + §3.8 要求的**完整**生成指纹(问题规范化 + 检索到的节点 id + 提示词版本 + 模型标识) + 要等真有生成管线时才有对象可挂,**本次不做**(做了也没有消费方)。 +7. **未做(等生成式问答)**:把 Invisible 作为 provenance 传进生成管线(§3.6 后半); + 证明式替换门「实体名 → pk 的带证据解析」(§3.7);规则两阶段重放与禁止自指筛选(§3.12)—— + 本仓目前没有「自动加 marking / 自动分级」的常驻指令机制,§3.12 描述的坑要等那类机制 + 出现时才有对应物。**不做占位实现**:没有生成管线的三态传递、证据化替换都是空转代码。 + +**P2-4(统一分页信封)的实现取舍**: + +NVIDIA 的 `{data,count,total}` 是「响应模型里固定三个字段」,本仓是 Go + `map[string]any`, +字段名不受模型约束——所以「统一」在这里不是加字段,而是**约定同一套字段名与同一套语义**, +并让所有列表读路径都带上。 + +1. **信封字段:`count` / `total` / `limit` / `offset` / `has_more` / `truncated`** + (`server/pagination.go::pageEnvelope`)。`truncated` 与 `has_more` 同值—— + 前者是「结果被 limit 截断了」的直白说法,后者是给程序看的;跨实现比对时 `truncated` 更好认。 +2. **`total` 用独立的一条 `COUNT`,不用 `count(*) OVER ()`**:窗口函数在「本页为空」时 + 没有行可返回,`total` 会跟着丢成 0——翻过头一页就会被误读成「这个类型没有数据」。 + `COUNT` 是标量聚合,空页也有值。代价是多一次往返,换来 `total` 永远是真的。 +3. **`total` 与 `items` 必须同源**:同一 WHERE(授权 / 分级 / 分区过滤都在内), + 先过滤再截断。反过来(先截断再过滤)会让 `total` 偏小,调用方以为翻完了其实后面还有。 + 集成测试直接断言「看不到的主体 total=0」——`total` 不得泄漏当前主体看不到的行。 +4. **`has_more` 改由 `total` 推导**:此前图式查询按「本页条数 == limit」猜, + 总数正好是 limit 整数倍时会误报「还有下一页」(翻到最后一页还得再翻一次空页)。 +5. **检索补上 `offset`(真实的既有缺口)**:`search_ontology` 此前只有 `limit`(上限 200), + 匹配数超过 200 就**取不全**且无从判断取全了没有。现在检索与图式查询都能翻页, + MCP 工具 `search_ontology` / `query_related` 同步暴露 `offset`。 +6. **`MAX_PAGE_SIZE` 单点常量没有统一**:各端点的 limit 上限不同 + (检索 200 / 查询 500 / 列表 1000),这是既有 API 行为——统一会改变现有调用方的行为, + 收益只在文档层。**记为待办**,本次只在信封注释里写明现状。 +7. **回包里的数字是 JSON number**:Go 侧 `map[string]any` 解出来是 `float64`, + 断言时别拿 `int64` 比(我们自己的集成测试在这上面绊过一次)。 + +--- + +## 8. 出处索引(NVIDIA 侧) + +| 主题 | 文件 | +|---|---| +| MCP 工具白名单与只读测试 | `mcp/auto_ontology_mcp/tools.py`、`mcp/tests/test_tools.py` | +| MCP 鉴权与身份透传 | `mcp/auto_ontology_mcp/auto_ontology_auth.py`、`server.py:140-190` | +| readiness 探针 | `mcp/auto_ontology_mcp/readiness.py` | +| 技能契约 | `skills/nvidia-ontology-query/assets/runtime-contract.yaml`、`AGENTS.md` | +| 权限词表 | `auto_ontology/server/users/access.json`、`users/permissions.py` | +| 导入导出 | `server/model_interchange/{service,schemas,embed}.py`、`dal/model_interchange.py` | +| 语义模型 schema | `auto_ontology/dal/schema.py`(1431 行,唯一真源) | +| 版本(仅物理 DDL) | `auto_ontology/dal/schema_version.py`、`alembic/versions/` | +| 就绪校验与空结果修复 | `retrieval/text_to_sql/db_probe/`、`agents/sql_value_validation.py`、`agents/empty_result_value_repair.py` | +| 澄清与实体消解 | `retrieval/interactive/{clarify,entity_resolution}.py` | +| 分区 / 责任人 / 标签 / 规则 | `dal/{zones,owners,tags,rules}.py` | +| 检索与配额 | `retrieval/data_access/semantic_search.py`、`utils/{retriever,rerank}.py` | +| 缓存与可观测性 | `retrieval/kumo/{graph_cache,telemetry,budget}.py` | + +--- + +*本文只做机制对照与建议,未对本仓做任何代码或数据改动。NVIDIA Auto Ontology 为 Apache-2.0 且官方声明暂不接受外部贡献——本文引用其公开源码行为作为对标依据。* diff --git a/docs/ontology-audit-20261001.md b/docs/ontology-audit-20261001.md new file mode 100644 index 0000000..ec95e03 --- /dev/null +++ b/docs/ontology-audit-20261001.md @@ -0,0 +1,168 @@ +# 尚数网本体核心建模逻辑审查报告(schema 层只读审计) + +- **日期**:2026-10-01 +- **方式**:通过本体 MCP / REST 以 `manager` 主体**只读**拉取全量 object-types(59)、link-types(74)、图谱(2,409 节点 / 427 边)与 KM 目录树,脚本化交叉分析。全程未调用任何写接口。 +- **范围**:本体元逻辑(类型体系、链接体系、类型-实例一致性),知识内容仅做结构统计。 +- **结论先行**:类型体系**整体框架与 GB/T / TC609 可信数据空间概念贴合度尚可**(空间/产品/资源/需求/主体/评价/使用控制均有落点),但存在一次明显的"大爆炸式扩容"漂移(2026-09-22 一天新增 20 个空类型 + 50 条零使用链接类型),以及多组同义类型并存、硬件设备多重建模、14 处链接类型指向已不存在的类型等结构性问题。**约 1/3 的 schema 处于"僵尸"状态。** + +--- + +## 1. 本体建模总体评估 + +| 维度 | 现状 | 评价 | +|---|---|---| +| 类型规模 | 59 个对象类型,仅 39 个有实例 | **34% 空类型**,扩容超前于数据沉淀 | +| 链接规模 | 74 个链接类型,仅 24 个被使用 | **68% 死边**,关系建模明显冗余 | +| 图谱密度 | 2,409 节点仅 427 条边 | 实例"存而未联",本体优势未发挥;大量关系以字符串属性(owner/operator/parent_group)承载而非边 | +| 业务闭环 | 合约→交付→计量→账单→审计全链路**有边无类型**(DigitalContract 等类型已删,21 条链接类型成孤儿) | 核心交易闭环 schema 不自洽 | +| 与 GB/T 贴合度 | 空间/接入主体/功能节点/使用控制/评价体系贴合 TC609 系列;BusinessFlow 4 流程与 48000 系列流程语义一致 | 贴合,但"数字合约"层缺失(详见 §2.5) | + +--- + +## 2. 类型层问题清单(59 个对象类型) + +### 2.1 语义重复 / 同义类型(建议合并) + +| # | 类型组(api_name) | 证据 | 判断 | 建议 | +|---|---|---|---|---| +| T1 | `ControlPolicy`(使用控制策略, 2 实例) vs `UsageControlPolicy`(使用控制策略, 34 实例) | **display_name 完全相同**;属性语义重叠(policy_id/version 双方都有);ControlPolicy 存的是 ABAC/PBAC 策略模板 | 建模漂移,非刻意细分 | 合并:ControlPolicy 的 2 个模板迁入 UsageControlPolicy(policy_type=模板),废弃 ControlPolicy | +| T2 | `Connector`(接入连接器, 3) vs `DataAccessConnector`(数据接入连接器·硬件版, 3) vs `DataConnector`(数据接入连接器, 1) | Connector 是软件连接器(平台代理/提供方/使用方模板);DataAccessConnector 与 DataConnector **display_name 仅差"(硬件版)"后缀**,属性高度重合(form_factor/supported_sources/features 三字段完全一致) | DataConnector 是 DataAccessConnector 的早期残本 | `DataConnector`(1 实例) 并入 `DataAccessConnector`;Connector 保留(软件形态),但 display_name 建议改为"软件连接器"以消歧 | +| T3 | `TechnicalStandard`(技术标准, 2) vs `AccessStandard`(接入管理标准, 8) vs `Standard`(技术标准/文件, 10) vs `ComplianceStandard`(合规标准, 261) | 四个"标准"类型并存;属性几乎同构(编号/名称/发布机构/日期/scope 各起一套字段名:code vs doc_no vs standard_code,issuer vs publisher vs issuing_body) | 建模漂移。AccessStandard/TechnicalStandard 是 Standard 的子集场景 | 短期:TechnicalStandard(2) 并入 Standard;AccessStandard(8) 并入 Standard(doc_type 区分"接入管理规范")。中期:评估 ComplianceStandard 拆分(见 T4) | +| T4 | `ComplianceStandard`(261) vs `PolicyDocument`(政策法规文件, 0) | ComplianceStandard 的 desc 明确写"**规范性文件、政策文件**及技术文件",实例中确有浙政办发等政府文件;而专门的 PolicyDocument 空置 | 同一批政府文件被塞进"合规标准" | 二选一:政府类文件迁入 PolicyDocument(保持"标准"与"政策"分离,符合国标体系直觉);或废弃 PolicyDocument、把 ComplianceStandard 更名为"标准与政策文件"。**倾向前者** | +| T5 | `Appliance`(密算一体机, 15) vs `DataSecurityCard`(数据安全卡, 1) vs `TrustedCryptographyCard`(可信密码卡, 2) | Appliance 的 desc 自称"包括可信密码卡、数据接入连接器、密算一体机等"——**同一张卡被建了两遍**:Appliance 实例 `crypto_card`/`trusted_crypto_card`/`trusted_crypto_card_ant_shu` 与 DataSecurityCard/TrustedCryptographyCard 类型实例是同一硬件;且 Appliance 里还混有"数据接入连接器"实例 `appliance_44cf50443e10c881`(与 DataAccessConnector 类型重复)和噪音实例(§4.1) | 三重建模漂移 | 收敛 Appliance 语义为**仅密算一体机**(含密态计算服务器);密码卡只保留 TrustedCryptographyCard(废弃 DataSecurityCard,desc 与 TrustedCryptographyCard 几乎逐字相同);接入连接器硬件归 DataAccessConnector。Appliance 中 5 张卡/网关实例删除或迁移 | +| T6 | `DataAccessConnector` vs `DataSecurityCard` 属性冗余 | 两者均以 json `features` + `form_factor` + `interface` 为主干 | 属 T5 的伴随现象 | 随 T5 一并收敛 | +| T7 | `AppScenario`(应用场景, 17) vs `DeliveryScenario`(交付场景, 0) | 两条平行的"场景"边也存在(ResourceForScenario vs ResourceUsesScenario);DeliveryScenario 无实例无数据 | 空壳 | 废弃 DeliveryScenario + ResourceUsesScenario 边 | + +### 2.2 空类型 / 僵尸类型(0 实例,共 20 个,全部创建于 2026-09-22 同日) + +| 分组 | 类型 | 建议 | +|---|---|---| +| 运营/内容类(与本体核心无关) | `BusinessLine`、`ContentAsset`、`ContentChannel`、`PromotionCampaign`、`AuditLog` | **废弃**。这些是运营素材建模,不是可信数据空间本体原语;新闻已由 NewsArticle 承载 | +| AI 产品线(宁檬数科) | `AIProduct`、`AIPlatformComponent` | 空置但 desc 明确(宁檬 AI 产品线),配套边 AIProductContainsComponent/MemberOrgOperatesProduct 也为零使用。**决策点**:若宁檬产品线确要入本体则保留并灌数;否则整族废弃 | +| 业务闭环占位 | `DeliveryTask`、`MeteringBill`、`DataPropertyRegistration`、`DataRightsConfirmation`、`DataLineage`、`DataAsset`、`VerificationItem`、`TrustCredential`、`TDSInterconnection`、`HighQualityDataset` | 属数字合约/确权/计量生态的**预留壳**。GB/T 中确为核心概念,但当前一笔数据都没有。建议:保留 `DeliveryTask`/`MeteringBill`/`DataRightsConfirmation`/`HighQualityDataset`(业务闭环必要位)+ 随 DigitalContract 生态一起规划;废弃 `AuditLog`、`DataAsset`(与 DataResource/DataProduct 语义重叠,desc 自称"涵盖数据资源、数据集、数据产品"——一个类型覆盖三个已有类型,职责错位) | +| 政策 | `PolicyDocument` | 见 T4,建议启用而非废弃 | +| 评测 | `ShuXiaoGuEval` | desc="数小估/数小规产品族",空置。评价体系已由 EvaluationModule/Criterion/Level(106 实例) 承载。废弃,数小估作为产品实体用 MemberOrg 或 DataProduct 表达 | + +### 2.3 职责错位 + +| # | 类型 | 证据 | 建议 | +|---|---|---|---| +| T8 | `MemberOrg`(26 个属性,全库最重) | desc 自认"**亦承载产业集团及其控股子公司画像**";混入港口专属字段 `berths`/`throughput_capacity_yi_ton`/`throughput_asof`(96 实例中仅 1 家北部湾港务使用);`parent_group` 字符串字段(37 实例使用)与已有的 `OrgBelongsToGroup` 边(37 条)**双轨重复** | 港口/财务字段属个别画像,建议下沉为可选画像 JSON 字段或拆出"企业画像"附属类型;`parent_group` 字符串以边为准,做一次回填后弃用 | +| T9 | `DataAsset` | 见 §2.2——desc 与 DataResource/DataProduct/HighQualityDataset 三类型语义重叠 | 废弃 | +| T10 | `AccessEntity` | required 同时含 `entity_name` 和 `name`,两套主名;实例 `access_entity_general` 只填了 entity_name | 统一为 name,entity_name 弃用 | +| T11 | `TrustCredential`/`ContentAsset` 等 desc 为空 | 空类型且无描述,无法判断建模意图 | 随 §2.2 处置 | + +### 2.4 命名混乱 + +| # | 问题 | 证据 | +|---|---|---| +| T12 | display_name 相同、api_name 不同 | `ControlPolicy` 与 `UsageControlPolicy` 均叫"使用控制策略"(T1) | +| T13 | api_name 与 display_name 语义脱节 | `Appliance` 显示为"密算一体机"但 desc 声称覆盖三类硬件;`ComplianceStandard` 叫"合规标准"实际装了政府政策文件 | +| T14 | 实例命名规范缺失导致 label 退化为 pk | 全库 **407/2,409(17%)实例 label=pk**(ComplianceStandard 256、EvaluationCriterion 70、EvaluationModule 20 等);根因之一是多数类型 `title_property=""` 且无 name 属性,实例用 `display_name`/`title` 等各自为政的字段(DataSecurityCard 用 display_name,DataAccessConnector 实例用 connector_name/name 混用) | +| T15 | 类型内部属性重名 | `TechnicalStandard`:`title` 与 `standard_name` 同为 required"标准名称"、`issue_date`/`effective_date`、`issuer`/`issuing_body` 三对重复字段 | + +### 2.5 缺失的核心类型(对照 GB/T 可信数据空间参考架构) + +- **数字合约(DigitalContract)族整体缺位**:21 条链接类型引用的 `DigitalContract`/`ContractPolicy`/`LogicalSpace`/`ServiceNode`/`ManagementEntity`/`BillingRecord`/`UsageConstraint`/`UsageLog`/`DataAssetCapitalization`/`IndustryKnowledgeHub`/`IndustryMasterData`/`SemanticModel` **在对象类型表中均不存在**——类型被删但链接类型未级联清理,schema 层留下 21 条悬空边定义。数字合约是可信数据空间"可控可计量"的核心载体,建议**重建 DigitalContract(精简版)**而非放任边定义悬空。 +- **空间↔运营机构关系无类型承载**:TrustedDataSpace.operator 是字符串属性(9 个取值),MemberOrg 与 TDS 之间没有"运营"边(见 §3.3)。 + +--- + +## 3. 链接层问题清单(74 个链接类型,仅 24 个有边) + +### 3.1 悬空链接类型(source/target 类型不存在,共 21 个) + +`CapitalizationTargetsProduct`、`ConnectorProducesContract`、`ContractAppliesPolicy`、`ContractContainsPolicy`、`ContractCoversProduct`、`ContractGeneratesLog`、`ContractGovernsProduct`、`ContractGovernsTask`、`ContractOperatedInSpace`、`ContractSignedByParty`、`EntityManagesNode`、`IndustryNodeProvidesKnowledge`、`IndustryNodeProvidesMasterData`、`IndustryNodeProvidesSemanticModel`、`LogicalSpaceContainsSubject`、`LogicalSpaceHostsContract`、`NodeRegisteredAt`、`PolicyHasAction`、`PolicyHasConstraint`、`PolicyExecutedByAppliance`、`ProductBilledByRecord` + +**建议**:随 DigitalContract 生态重建一并恢复;IndustryNodeProvides* / LogicalSpace* / EntityManagesNode 若无重建计划则直接清理(均为 0 使用)。 + +### 3.2 死边(类型存在、0 使用,共 50 个,摘重点) + +- **同义重复导致的死边**(合并后自然消亡):`StdDraftedBy`(0) vs `StandardDraftedBy`(6);`DataProductComposedOf`(0)/`ResourceBuiltIntoProduct`(0) vs `ProductBuiltOnResource`(6);`ResourceUsesScenario`(0) vs `ResourceForScenario`(5);`SpaceUsesDataAccessConnector`(0) vs `SpaceRegistersConnector`(1)+`NodeUsesConnector`(2);`SubjectDeploysConnector`(0);`TDSInterconnectsWith`(0,且与空类型 TDSInterconnection 配套——互联互通是 GB/T 重点,**建议保留此边并灌数**) +- **实例侧无数据的生态边**:`PolicyDeployedIn`、`ApplianceFollowsStandard`、`CatalogIndexesResource`、`MemberOrgAuthorizesDataResource`、`MemberOrgSupervises`、`NewsArticleCitesStandard`、`ComponentBelongsToLayer`、`NodeManagesService/Dataset` 等 +- **建议立即清理**:所有"伴随空类型"的死边(ContentAssetPublishedOn、TrustCredentialIncludesItem、TaskProducesAudit 等);"待业务闭环重建"的死边(Contract* 族) + +### 3.3 明显缺失的关系(有数据、有需求,但没有边) + +| # | 缺失关系 | 现状 | 建议 | +|---|---|---|---| +| L1 | **MemberOrg → TrustedDataSpace(运营/入驻)** | TDS.operator 是字符串;"惠阳城投运营具身智能空间"这类关系无法表达,也是 §4 中"XX作为运营方"噪音实例的直接诱因 | 新建 `SpaceOperatedByOrg`(TDS→MemberOrg, many_to_one),把 operator 字符串边化 | +| L2 | **MemberOrg → DataProduct(开发商)** | DataProduct.owner 是 30 个取值的字符串 | 新建 `ProductDevelopedByOrg`,与 L1 同理边化 | +| L3 | **DataDemand → DataProduct(需求对接)** | 351 条需求悬空,无法表达"某需求由某产品/资源满足" | 新建 `DemandSatisfiedByProduct` | +| L4 | **MemberOrg ↔ IPAsset(知识产权归属)** | 71 条 IPAsset 无归属边 | 新建 `IPOwnedByOrg` | +| L5 | **NewsArticle ↔ 任意业务实体** | 405 条推文只进不出 | 视运营需要,低优先 | +| L6 | 集团-子公司 | `OrgBelongsToGroup` 已存在且健康使用(37 条,含持股比例边属性),**此前"缺集团-子公司边"的问题已解决**,无需再建 ParentOwnsSubsidiary | 保持现状 | + +### 3.4 cardinality 规范问题 + +同一系统里出现 **8 种写法**:`many_to_many`(52)、`one_to_many`(11)、`many_to_one`(4)、`1:N`(2)、`many-to-many`(2)、`N:M`(1)、`N:N`(1)、`one-to-many`(1)。连字符/下划线、数字/字母混用,说明录入未走统一校验。建议后端归一化为 `one_to_one/one_to_many/many_to_many` 三值枚举并存量清洗。 + +--- + +## 4. 实例层问题清单(抽查) + +### 4.1 抽取噪音(句子片段被建成实体,约 30 个) + +| 类型 | 数量 | 样例 pk / label | +|---|---|---| +| TrustedDataSpace | 25 实例中约 **11 个噪音** | `trusteddataspace_59aff4307ec75159`"江西司法厅作为运营方"、`trusteddataspace_7095db5aaccee8e5`"惠阳城投作为运营方"、`trusteddataspace_5c04e7aeaffcd664`"吉利汽车作为运营方"等 8 条"XX作为运营方"(与真实空间 tds_geely/tds_tea/tds_ecoenv **一一对应重复**);`trusteddataspace_07c439761f4e46fe`"可用不可见、可控可计量";`trusteddataspace_d41810191a8dd347`"物流、公证等";`trusteddataspace_d0249243468c03a4`"支持多种部署模式" | +| DataExchange | 10 实例中 **3 个噪音** | `dataexchange_fecdb94ea73cf01d`"交易所定规则,尚数网供技术";`dataexchange_26618819065b6c72`"广州数据交易所+光信深圳作为运营方";`dataexchange_de8bcfa4615862cb`"部分已经实现" | +| Appliance | 15 实例中 **3 个噪音** | `appliance_abe8947aee6a31f5`"数据要素x"、`appliance_ed0946bfc287a54b`"授权"、`appliance_dd2d388943edae7b`"软硬一体,开箱即用" | +| IPAsset | 1 | `ipasset_a62f135b8a463401`"如深圳标准院、江西司法厅" | +| TrustedDataSpace(概念混入) | 2~3 | `tds_tech_architecture_2025`"可信数据空间技术架构"、`national_trusted_data_space`"国家可信数据空间管理服务平台"——是架构概念/平台而非某空间实例,宜用独立"参考架构"类型或文档承载 | + +### 4.2 测试数据 + +- `TrustedDataSpace/mcp_test_medical_tds`"MCP测试医疗可信数据空间"(pk 即自证测试)。 + +### 4.3 同名重复 + +- 按(类型, 名称)全库查重:**0 组重复**。存在的是"同一事物多类型重复建模"(如同一张数据安全卡 = Appliance 实例 `crypto_card` + DataSecurityCard 实例 `shangshu_data_security_card` + TrustedCryptographyCard 实例 `shangshu_trusted_crypto_card`),属 §2.1 T5 范畴。 + +### 4.4 数据质量面 + +- 407 实例(17%)无显示名(label=pk),重灾区:ComplianceStandard 256/261、EvaluationCriterion 70/76——大概率是 title_property 未配置 + 抽取时未回填 name。 +- ComplianceStandard 5 条既无 title 也无 standard_code(`cs_tds_capability_building`、`yubanfa_2025_8` 等)。 +- NewsArticle 405 条的 content 字段存原始 HTML(截图编辑器标签),单条数 KB,属内容层问题仅记录不深查。 + +### 4.5 KM 目录与本体对齐度 + +- KM 顶层 24 个目录中与本体强对齐的有:可信数据空间、密算硬件、数据产品、标准/评测、政策、宁檬数科AI产品、产品手册。 +- 弱对齐/噪音:`x`、`yinmai70`、`工作日志`、`情报`、`友商信息`、`会议纪要`——运营私有素材,与本体类型无映射(这也解释了为何 ContentAsset/PromotionCampaign 等运营类型被凭空建出)。建议 KM 与类型体系建立"目录→类型"映射约定,未映射目录不作为抽取源。 + +--- + +## 5. 重构路线建议(分阶段,仅建议、未执行) + +### 阶段 0:止血(影响面:无业务影响,纯 schema 清理) +1. **清理 21 条悬空链接类型**(§3.1)中确认不重建的部分(IndustryNodeProvides*、LogicalSpace*、EntityManagesNode、NodeRegisteredAt、PolicyHasAction/Constraint、PolicyExecutedByAppliance、ProductBilledByRecord、CapitalizationTargetsProduct)。 +2. 废弃确认不要的空类型及其配套死边:`DataAsset`、`AuditLog`、`BusinessLine`、`ContentAsset`、`ContentChannel`、`PromotionCampaign`、`ShuXiaoGuEval`、`DeliveryScenario`(+ResourceUsesScenario)。 +3. 统一 cardinality 存量写法(8 种 → 3 种)。 + +### 阶段 1:合并重复类型(影响面:中,需迁移实例 + 改连接器查询) +1. `DataConnector`→`DataAccessConnector`(1 实例);`DataSecurityCard`→`TrustedCryptographyCard`(1 实例)。 +2. `ControlPolicy`→`UsageControlPolicy`(2 个模板实例,加 policy_type=模板)。 +3. `TechnicalStandard`+`AccessStandard`→`Standard`(10 实例;注意 TechnicalStandard 类型内部字段去重后映射);`ComplianceStandard` 中政府文件(standard_type 判别)迁入启用的 `PolicyDocument`。 +4. 收敛 `Appliance` 为仅密算一体机:5 张卡/网关实例删除或迁移;同时清理 3 条噪音 Appliance。 +5. 每次合并后跑 `/api/v1/ontology/types/merge-preview` 核对再执行(平台已内置合并工具)。 + +### 阶段 2:补关键缺失边(影响面:低,纯增量) +1. 新建 `SpaceOperatedByOrg`、`ProductDevelopedByOrg`、`DemandSatisfiedByProduct`、`IPOwnedByOrg`(§3.3 L1–L4),从既有字符串属性回填(operator/owner/org)。 +2. 回填后把字符串属性降级为冗余展示字段或删除,消除双轨。 +3. 为 NewsArticle 补 `NewsArticleCitesStandard` 的少量种子边或干脆清零该边定义。 + +### 阶段 3:业务闭环重建 + 噪音清洗(影响面:大,需产品决策) +1. 决策 DigitalContract 生态:重建精简版 `DigitalContract`(+ContractParty 或以 MemberOrg 代),恢复 Contract* 核心四边(CoversProduct/SignedByParty/GovernsTask/ProducesLog),联动启用 `DeliveryTask`/`MeteringBill`。 +2. 清理 §4.1 全部句子片段噪音(约 30 个 pk 已列出);处理 `mcp_test_medical_tds` 测试空间。 +3. 给 407 个 label=pk 实例回填显示名(title_property 配置 + backfillDisplayNames),重点是 ComplianceStandard(256)与 EvaluationCriterion(70)。 +4. 建立 schema 治理约定:新建类型必须当天有种子实例或写明启用计划;删除类型必须级联清理其链接类型(平台行为待加固)。 + +--- + +## 附:统计快照 + +- 对象类型 59(有实例 39 / 空 20);实例 2,409;边 427。 +- Top 实例类型:DataResource 630、NewsArticle 405、DataDemand 351、ComplianceStandard 261、DataProduct 266、MemberOrg 96。 +- Top 边:SpaceContainsResource 106、ModuleContainsCriterion 76、StandardDefinesCriterion 70、SpaceHasDemand 55、OrgBelongsToGroup 37。 +- 链接类型 74:有边 24 / 死边 50 / 悬空(类型不存在) 21(悬空与死边有交集)。 +- label=pk 实例:407(17%)。 diff --git a/docs/ontology-v2-framework.md b/docs/ontology-v2-framework.md new file mode 100644 index 0000000..fe7ccc4 --- /dev/null +++ b/docs/ontology-v2-framework.md @@ -0,0 +1,346 @@ +# 尚数网可信数据空间本体 · 梳理框架(v2 草案) + +> **定位**:本文是本体 schema 层的**设计蓝图**,面向评审与后续迁移执行,不是数据库 dump。 +> 它回答三件事:现在的本体有什么问题、我们希望它长什么样、怎么从旧的走到新的。 +> +> | 项 | 值 | +> |---|---| +> | 草案版本 | `v2-draft` | +> | 生成时间 | 2026-10-01 | +> | 数据来源 | 生产本体 `r.mayishangshu.cn:18081` **只读快照**(59 类型 / 2409 实例 / 74 链接类型 / 427 边) | +> | 配套产物 | `ontology-v2.db`(SQLite 结构化库)+ `scripts/build_ontology_v2.py`(可重跑,`--fetch` 重新拉快照) | +> | 上游依据 | `docs/ontology-audit-20261001.md`(只读审计报告) | +> | **状态** | **仅本地梳理,未导入生产;本文只提建议,不执行任何清理或写入** | + +--- + +## 一、为什么要梳理 + +审计报告对生产本体做了一遍"只读体检",结论很直接:**类型体系膨胀且自洽性差,关系层大量悬空,实例层混入抽取噪音。** 典型症状: + +- **类型重复**:同一张密码卡被建成 3 个类型实例;"四套标准"字段各起一套命名;`ControlPolicy` 与 `UsageControlPolicy` 显示名完全相同。 +- **僵尸类型**:59 个类型中约 20 个零实例,且集中创建于同一天(一次性扩容漂移)。 +- **关系悬空**:74 个链接类型中 50 个从未使用,21 个还指向**已被删除的类型**(数字合约族被删,边定义没跟着清)。 +- **字符串关系**:运营方、开发商、资源提供方等关键关系仍以 `operator` / `owner` 等**字符串字段**存在,这是"江西司法厅作为运营方"等 8 条句子片段噪音实例的直接诱因。 +- **属性失范**:17% 实例 `label` 退化为 `pk`;`ApplianceSKU.name` 缺失必填约束导致空名。 + +梳理目标:**对照 GB/T 48000.3《可信数据空间 第 3 部分:接入认证与管理》等标准,把 59 个类型收敛到 45 个活跃类型、42 条活跃关系,并补上缺失的关键边、清理噪音实例。** + +--- + +## 二、设计原则 + +1. **贴标准**:以 GB/T 48000 系列"可信数据空间 / 使用控制 / 数字合约"概念为骨架,类型 `gb_ref` 字段标注对应标准概念。 +2. **去重不丢语义**:同义类型合并(如四套标准 → `Standard`),刻意细分的保留(如卡/网关/一体机各立类型)。 +3. **关系优先于字符串**:凡是"谁运营 / 谁开发 / 谁提供 / 谁拥有"这类主体关系,**一律建模为边**,不再用字符串字段承载。 +4. **闭环完整**:数字合约是"可控可计量"的核心载体——重建精简版合约生态(合约→交付任务→计量账单),把之前悬空的 21 条边救回来。 +5. **可审计、可逆**:所有合并/废弃/清理都记录在 `type_migration` / `cleanup_instances` 表,执行前需人工确认。 + +--- + +## 三、本体元模型总览(分组树) + +v2 把全部类型归入 **8 个业务域分组**,让"这是哪一类东西"一眼可辨: + +``` +尚数网本体 v2 +├── 空间与治理 (可信数据空间、功能节点、数字合约、管理员、互联互通、可信凭证…) +├── 主体 (会员机构、分支机构、接入主体) +├── 数据资产 (数据资源、数据产品、数据需求、数据确权、知识产权、高质量数据集…) +├── 技术与硬件 (连接器、密算一体机、可信密码卡、使用控制策略/接口、服务、安全要求…) +├── 标准与评测 (标准、政策法规、评价模块/条款/等级、术语) +├── 业务与应用 (应用场景、数据交易所、应用商店、业务流程) +├── 内容与运营 (新闻动态) +└── (待决策) (AIProduct / AIPlatformComponent 产品族,整族待定) +``` + +| 分组 | 活跃类型数 | 职责一句话 | +|---|---:|---| +| 空间与治理 | 10 | 可信数据空间的本体、节点、合约履约与治理角色 | +| 主体 | 2 | 参与方(会员单位 / 分支机构 / 接入主体) | +| 数据资产 | 9 | 数据从资源→产品→需求→确权→知识产权的全生命周期 | +| 技术与硬件 | 13 | 连接器、密码卡、一体机、使用控制策略等技术底座 | +| 标准与评测 | 6 | 标准、政策法规、能力评价条款与等级 | +| 业务与应用 | 4 | 场景、交易所、应用商店、业务流程 | +| 内容与运营 | 1 | 官网资讯(内容域,与本体实体解耦) | +| 待决策 | 2 | AI 产品线(保留或废弃待拍板) | + +--- + +## 四、对象类型详解(活跃 45 个) + +> 下表为每类给出**中文名 / 近似实例数 / 在本体中的职责 / 对应 GB/T 概念**。实例数为快照近似值,反映数据分布,不用于精确计量。 + +### 4.1 空间与治理(10) + +| 类型 (api_name) | 中文 | 实例≈ | 职责 | GB 概念 | +|---|---|---:|---|---| +| `TrustedDataSpace` | 可信数据空间 | 25 | 数据要素流通的核心空间实体(清理 11 噪音 + 1 测试实例后) | 可信数据空间 | +| `FunctionalNode` | 功能节点 | 7 | 区域/行业/业务/全域功能节点 | 功能节点 | +| `SpaceManager` | 空间管理员角色 | 3 | 具空间创建/删除/用户管理权限的角色 | 空间运营方 | +| `DigitalContract` | 数字合约 | 0 | 可控可计量的核心闭环载体(重建精简版) | 数字合约 | +| `DeliveryTask` | 数据交付任务 | 0 | 合约唯一履约载体,强绑 contractId,终结销毁临时数据 | 数据交付 | +| `MeteringBill` | 计量账单 | 0 | 基于连接器计量+合约规则的永久存证账单 | 计量计费 | +| `TDSInterconnection` | 空间互联互通 | 0 | 互联空间、技术接口、互联协议 | 空间互联互通 | +| `TrustCredential` | 可信凭证 | 0 | 与核验项配套的可信度凭证 | 可信凭证 | +| `VerificationItem` | 核验项 | 0 | 凭证包含的可独立验真核验项 | 核验/验证 | +| `AccessEntity` | 接入主体 | 2 | 提供方/使用方等接入参与方的身份与认证 | 接入主体 | + +### 4.2 主体(2 + 1 相关) + +| 类型 | 中文 | 实例≈ | 职责 | GB 概念 | +|---|---|---:|---|---| +| `MemberOrg` | 会员单位/机构 | 96 | 会员单位、数据集团、登记/中央机构、生态伙伴;承载产业集团及其控股子公司画像(港口/财务专属字段将下沉) | 参与方/主体 | +| `Branch` | 分支机构 | 7 | 尚数网的分支机构 | 组织分支 | + +> 注:`AccessEntity`(接入主体)归入"空间与治理"分组,是与 `MemberOrg`(合作机构)互补的另一类主体(接入认证视角)。 + +### 4.3 数据资产(9) + +| 类型 | 中文 | 实例≈ | 职责 | GB 概念 | +|---|---|---:|---|---| +| `DataResource` | 数据资源 | 630 | 平台收录的数据资源(文本/图片/语音/视频/结构化);`owner` 边化为 `ResourceProvidedByOrg` | 数据资源 | +| `DataProduct` | 数据产品 | 266 | 经合规授权、安全使用、按量结算的可消费产品;`owner` 边化为 `ProductDevelopedByOrg` | 数据产品 | +| `DataDemand` | 数据需求 | 351 | 谁要什么数据、何场景、何期限的需求撮合 | 数据需求 | +| `IPAsset` | 知识产权 | 71 | 专利/软著/商标/标准/证书 | 知识产权 | +| `DataCatalog` | 数据目录 | 5 | 产品/服务/提供方/使用方/试用等目录集合 | 数据目录 | +| `DataRightsConfirmation` | 数据确权 | 0 | 三权分置、确权机构、登记证书 | 数据确权 | +| `DataPropertyRegistration` | 数据产权登记 | 0 | 登记事项、权利类型、登记机构、凭证效力 | 数据产权登记 | +| `HighQualityDataset` | 高质量数据集 | 0 | 建设标准/行业/场景建模 | 高质量数据集 | +| `DataLineage` | 数据血缘 | 0 | 资源-合约-任务-交付-结果的血缘链路(治理核心) | 数据血缘 | + +### 4.4 技术与硬件(13) + +| 类型 | 中文 | 实例≈ | 职责 | GB 概念 | +|---|---|---:|---|---| +| `Service` | 核心服务 | 22 | 密码学/数据接入/密态计算等核心能力服务 | 服务 | +| `UsageControlPolicy` | 使用控制策略 | 36 | 数据使用行为的细粒度控制规则(吸收 `ControlPolicy`) | 使用控制策略 | +| `Connector` | 软件连接器 | 3 | 部署在提供方/使用方侧的连接节点(本地使用控制/环境隔离/存证上报) | 连接器 | +| `DataAccessConnector` | 数据接入连接器 | 4 | 最后一公里微型网关,吸收 `DataConnector` 残本 | 接入连接器 | +| `Appliance` | 密算一体机 | 16 | 收敛为仅密算一体机/密态服务器(吸收 `HomomorphicComputePlatform`) | 可信管控设备 | +| `TrustedCryptographyCard` | 可信密码卡 | 3 | 自研 PCIe 国密底座(吸收 `DataSecurityCard`) | 密码学底座 | +| `UsageControlInterface` | 使用控制接口 | 4 | 使用控制模块对外标准化接口 | 使用控制接口 | +| `ArchitectureComponent` | 技术架构组件 | 14 | 技术架构中的功能模块 | 技术架构 | +| `InterfaceSpec` | 接口规范 | 3 | 组件间系统接口规范 | 接口 | +| `SecurityRequirement` | 安全要求 | 3 | 安全保障要求 | 安全要求 | +| `ApplianceSKU` | 密算一体机版本 | 3 | 一体机版本配置(`name` 需补必填) | 设备型号 | +| `UsageAction` | 操作行为 | 0 | 策略五元组之一(操作行为) | 操作行为 | +| `UsageConstraint` | 约束条件 | 0 | 策略五元组之一(约束条件) | 约束条件 | + +### 4.5 标准与评测(6) + +| 类型 | 中文 | 实例≈ | 职责 | GB 概念 | +|---|---|---:|---|---| +| `Standard` | 标准/技术文件 | 20 | 四套标准类型归一(字段名统一 `standard_code/title/issuer/...`) | 标准/技术文件 | +| `ComplianceStandard` 拆分 → `Standard` + `PolicyDocument` | —— | 261 | 原 261 实例按 `standard_type` 拆:标准入 `Standard`,政府规范性文件入 `PolicyDocument` | 标准/政策法规 | +| `PolicyDocument` | 政策法规文件 | 0 | 承接 `ComplianceStandard` 中的政策文件,与标准分离 | 政策法规 | +| `EvaluationModule` | 评价模块 | 28 | 技术能力评价的模块划分 | 评价/测评 | +| `EvaluationCriterion` | 评价条款 | 76 | 评价规范具体项(基础级/扩展级) | 评价条款 | +| `EvaluationLevel` | 评价等级 | 2 | 评价分级 | 评价等级 | +| `TechnicalTerm` | 术语定义 | 11 | 标准中的术语及定义 | 术语 | + +### 4.6 业务与应用(4) + +| 类型 | 中文 | 实例≈ | 职责 | GB 概念 | +|---|---|---:|---|---| +| `DataExchange` | 数据交易所 | 10 | 合作的数据交易机构(清理 3 句子片段噪音) | 数据交易机构 | +| `AppScenario` | 应用场景 | 17 | 资源与产品落地的场景域(吸收 `DeliveryScenario`) | 应用场景 | +| `BusinessFlow` | 业务流程 | 4 | 主要业务流程 | 业务流程 | +| `AppStore` | 应用商店 | 1 | 应用注册/审核/部署/评价的生态 | 应用生态 | + +### 4.7 内容与运营(1) + +| 类型 | 中文 | 实例≈ | 职责 | GB 概念 | +|---|---|---:|---|---| +| `NewsArticle` | 新闻动态 | 405 | 官网行业动态/产品发布/合作资讯(`content` 存原始 HTML 待清洗) | 资讯 | + +--- + +## 五、关系网(链接类型) + +v2 的关系层按"动作"分为五类,清晰区分**保留 / 启用 / 修复 / 新增 / 恢复**: + +| 动作 | 含义 | 条数 | +|---|---|---:| +| `keep` | 生产已用、继续保留 | 19 | +| `enable` | 定义存在、补数据启用 | 5 | +| `fix` | 端点指向已删类型,修复后启用 | 3 | +| `new` | 新增,把字符串关系边化 | 6 | +| `restore` | 随数字合约重建恢复 | 6 | +| **活跃合计** | | **42** | + +### 5.1 已使用并保留的核心关系(节选) + +| 关系 (api_name) | 连接 | 基数 | 已用 | 语义 | +|---|---|---|---:|---| +| `SpaceContainsResource` | 空间 → 资源 | 1:N | 106 | 空间包含数据资源 | +| `SpaceHasDemand` | 空间 → 需求 | 1:N | 55 | 空间包含需求 | +| `ModuleContainsCriterion` | 评价模块 → 条款 | M:N | 76 | 模块包含评价条款 | +| `StandardDefinesCriterion` | 标准 → 条款 | M:N | 70 | 标准定义评价条款 | +| `SpaceContainsProduct` | 空间 → 产品 | 1:N | 26 | 空间包含产品 | +| `OrgBelongsToGroup` | 机构 → 机构 | M:N | 37 | 隶属集团(含持股比例,替代 `parent_group` 字符串) | +| `ProductBuiltOnResource` | 产品 → 资源 | M:N | 6 | 产品基于资源 | + +### 5.2 新增的 6 条关键边(把字符串关系"边化") + +这是本次梳理最重要的修复——把散落在 `operator`/`owner`/`org` 等字符串字段里的主体关系,提升为显式边: + +| 新增关系 | 连接 | 解决的原问题 | +|---|---|---| +| `SpaceOperatedByOrg` | 空间 → 机构(1:N) | 取代 `TrustedDataSpace.operator` 字符串 → 消除"XX作为运营方"噪音实例 | +| `ProductDevelopedByOrg` | 产品 → 机构(1:N) | 取代 `DataProduct.owner` 字符串 | +| `ResourceProvidedByOrg` | 资源 → 机构(1:N) | 取代 `DataResource.owner` 字符串 | +| `IPOwnedByOrg` | 知识产权 → 机构(1:N) | 明确 IP 归属机构 | +| `ProductListedOnExchange` | 产品 → 交易所(M:N) | 产品挂牌交易所 | +| `DemandSatisfiedByProduct` | 需求 → 产品(M:N) | 需求由产品满足 | + +### 5.3 随数字合约恢复的 6 条边 + +`DigitalContract` 重建后,原先悬空的合约关系归位: + +``` +DigitalContract ──ContractCoversProduct──▶ DataProduct +DigitalContract ──ContractAppliesPolicy──▶ UsageControlPolicy +DigitalContract ──ContractSignedByParty──▶ MemberOrg +DigitalContract ──ContractOperatedInSpace─▶ TrustedDataSpace +DigitalContract ──ContractGovernsTask────▶ DeliveryTask +DeliveryTask ──TaskProducesBill───────▶ MeteringBill +``` + +### 5.4 修复的 3 条边 + +| 关系 | 修复前端点 | 修复后端点 | 说明 | +|---|---|---|---| +| `PolicyExecutedByAppliance` | 指向已删 `ControlPolicy` | `UsageControlPolicy → Appliance` | 策略执行节点 | +| `PolicyHasAction` | 同上 | `UsageControlPolicy → UsageAction` | 策略含操作行为 | +| `PolicyHasConstraint` | 同上 | `UsageControlPolicy → UsageConstraint` | 策略含约束 | + +### 5.5 概念关系图(核心实体) + +```mermaid +graph LR + TDS[可信数据空间] -->|SpaceContainsResource| DR[数据资源] + TDS -->|SpaceContainsProduct| DP[数据产品] + TDS -->|SpaceHasDemand| DD[数据需求] + TDS -->|SpaceOperatedByOrg| MO[会员机构] + TDS -->|SpaceRegistersConnector| CONN[连接器] + TDS -->|SpaceUsesAppliance| APP[密算一体机] + DP -->|ProductBuiltOnResource| DR + DP -->|ProductDevelopedByOrg| MO + DD -->|DemandSatisfiedByProduct| DP + DC[数字合约] -->|ContractCoversProduct| DP + DC -->|ContractGovernsTask| DT[交付任务] + DT -->|TaskProducesBill| MB[计量账单] + DC -->|ContractAppliesPolicy| UCP[使用控制策略] + MO -->|OrgBelongsToGroup| MO + FN[功能节点] -->|NodeFollowsStandard| ST[标准] + ST -->|StandardDefinesCriterion| EC[评价条款] +``` + +--- + +## 六、从旧本体到 v2 的迁移映射 + +### 6.1 合并(语义重复 → 单一权威类型) + +| 旧类型 | → 新类型 | 实例≈ | 理由 | +|---|---|---:|---| +| `ControlPolicy` | `UsageControlPolicy` | 2 | 显示名完全相同,同义 | +| `TechnicalStandard` | `Standard` | 2 | 四套标准归一 | +| `AccessStandard` | `Standard` | 8 | 同上 | +| `ComplianceStandard` | `Standard` + `PolicyDocument` | 261 | 标准与政策分离 | +| `DataConnector` | `DataAccessConnector` | 1 | 同义残本 | +| `DataSecurityCard` | `TrustedCryptographyCard` | 1 | 字段近乎重复 | +| `HomomorphicComputePlatform` | `Appliance` | 1 | 一体机语义收敛 | +| `DeliveryScenario` | `AppScenario` | 0 | 空壳场景类型 | + +### 6.2 直接废弃(无数据或重叠空壳) + +| 类型 | 实例≈ | 处置 | +|---|---:|---| +| `DataAsset` | 0 | 职责与资源/产品/数据集重叠,删除 | +| `AuditLog` | 0 | 日志走审计系统,删除 | +| `BusinessLine` | 0 | 运营类空壳,删除 | +| `ContentAsset` | 0 | 内容类空壳,删除 | +| `ContentChannel` | 0 | 同上,删除 | +| `PromotionCampaign` | 0 | 推广类空壳,删除 | +| `ShuXiaoGuEval` | 0 | 评测空壳,删除 | + +> 另有 38 条链接类型被标记 `deprecated`:其中 6 条(如 `MemberOrgAuthorizesDataResource` 公共数据授权运营、`NewsArticleCitesStandard` 推文引用标准、`MemberOrgSupervises` 监管考核、`NodeManagesService` 节点管理业务节点、`ApplianceFollowsStandard` 设备合规、`TrustCredentialIncludesItem` 凭证含核验项)**确有业务价值,建议在迁移时恢复**而非永久删除。 + +--- + +## 七、待你拍板的 5 件事(open_decisions) + +| # | 议题 | 现状 | 我的建议 | 影响 | +|---|---|---|---|---| +| 1 | `AIProduct` 产品线是否入本体 | 0 实例,配套 3 边 0 使用 | **B:整族废弃**,宁檬 AI 产品用 `DataProduct`/`MemberOrg` 表达 | 低 | +| 2 | `DigitalContract` 生态重建范围 | 类型被删、21 边悬空 | **A:精简版**(合约+任务+账单) | 中 | +| 3 | `ComplianceStandard` 拆分口径 | 261 实例混装标准与政策 | **A:按 `standard_type` 拆** | 中 | +| 4 | `NewsArticle` 是否留在本体 | 405 实例,content 存 HTML | **A:保留并清洗 HTML** | 中 | +| 5 | 硬件设备建模口径 | 同一张卡被建 3 遍 | **A:类型收敛**(卡/网关/一体机各立类型) | 中 | + +--- + +## 八、实例清理清单 + +审计发现三类需清理的实例,已逐条登记在 `cleanup_instances` 表(已排除误伤的真实证书 `ip_cert_top50`): + +| 类别 | 数量 | 说明 | 样例 | +|---|---:|---|---| +| `noise` 抽取噪音 | 17 | 大模型抽取把句子片段建成实体 | "惠阳城投作为运营方"、"可用不可见、可控可计量"、"交易所定规则,尚数网供技术"、"物流、公证等" | +| `concept` 概念实体 | 3 | 把标准/架构概念建成空间实例 | "可信数据空间技术架构"、"国家可信数据空间管理服务平台" | +| `test` 测试数据 | 1 | MCP 联调残留 | `mcp_test_medical_tds`(MCP测试医疗可信数据空间) | +| **合计** | **21** | | | + +> 这些实例多集中在 `TrustedDataSpace` / `DataExchange` / `Appliance` 三个类型,与真实空间一一重复(例如 8 条"XX作为运营方"本应只是 `operator` 字段值)。清理后才算"本体干净"。 + +--- + +## 九、属性质量与统一规范 + +梳理中暴露的属性层问题,v2 给出统一口径: + +1. **`label` 退化**:约 407/2409(17%)实例 `label` 退化为 `pk`。重灾类型 `EvaluationCriterion`(70 条)、`EvaluationModule`(20 条)、`ComplianceStandard`(256 条)——迁移时需回填显示名。 +2. **必填缺失**:`ApplianceSKU.name` 无 `required`,导致空名 → v2 标记为 `[new]` 补必填。 +3. **枚举归一**:`DeliveryTask.status`、`MeteringBill.status`、`DigitalContract.status`、`UsageAction.risk_level`、`UsageConstraint.constraint_type` 等给出统一枚举值(见库内 `properties` 表)。 +4. **字段名统一**:四套标准合并后字段统一为 `standard_code / title / issuer / issue_date / effective_date / scope / doc_type`,消除 `standard_name / code / issuing_body` 等重复命名。 +5. **cardinality 归一**:原生产出现 8 种写法(`many_to_many` / `N:M` / `1:N` / `one-to-many` 混用),v2 统一为 `one_to_one / one_to_many / many_to_many` 三种。 + +--- + +## 十、落地路线(分阶段,仅建议不执行) + +| 阶段 | 内容 | 影响面 | 前置 | +|---|---|---|---| +| **P0 止血** | 清理 21 个噪音/概念/测试实例;回填 407 个 `label=pk` | 实例层,无类型/关系变更 | 人工确认清理名单 | +| **P1 合并类型** | 执行 8 条合并 + 7 条废弃;迁移约 275 实例到新类型 | 类型层 + 实例归属 | 待决策 #3(拆分口径)先定 | +| **P2 补关键边** | 新增 6 条边 + 修复 3 条边;把 `operator`/`owner`/`org` 字符串关系改写为边;回填边数据 | 关系层 + 部分实例属性 | P1 完成后 | +| **P3 闭环重建** | 重建 `DigitalContract`/`DeliveryTask`/`MeteringBill` + 恢复 6 合约边;恢复 6 条建议保留边;灌入待补数据(数据确权/血缘/高质量数据集等 0 实例类型) | 类型层 + 关系层 | 待决策 #2 先定 | +| **收尾** | cardinality 归一、枚举审核、`NewsArticle` HTML 清洗 | 属性层 + 内容域 | 全程 | + +> 每一步都需在 `ontology-v2.db` 的 `type_migration` / `cleanup_instances` 表中核对范围后再执行;本文与数据库均为**评审与执行依据**,未对生产做任何改动。 + +--- + +## 附:核心属性速查(按类型,仅列关键字段) + +> 完整字段见 `ontology-v2.db` 的 `properties` 表。`*` 表示必填。 + +- **TrustedDataSpace**:name*、operator、industry、deploy_mode、region +- **DataResource**:name*、category、scenario、owner(→边)、format、source、registered_at +- **DataProduct**:name*、owner(→边)、desc、price_model、status、source +- **DataDemand**:name*、desc、scene、deadline、org、status、jurisdiction +- **MemberOrg**:name*、type、role、region、parent_group(→`OrgBelongsToGroup` 边)、group_shareholding_pct、unified_social_credit_code +- **UsageControlPolicy**:policy_id*、version、name、policy_type、dimension、priority(吸收原 `ControlPolicy` 字段) +- **DigitalContract**(新建):contract_id*、name*、status、space、signed_at、effective_at、expires_at +- **DeliveryTask**(新建):task_id*、contract_id*、space_id、task_type、status、result_hash、destroy_proof +- **MeteringBill**(新建):bill_id*、space_id、contract_id、task_id、metric_dimension、total_amount、status +- **Standard**(归一后):standard_code*、title_cn*、issue_date、implement_date、publisher、doc_type、scope +- **PolicyDocument**(新建):title*、doc_no、doc_type、issuer、issue_date、effective_date、hierarchy +- **EvaluationModule / EvaluationCriterion**:module_name* / check_content*、basic_level、extended_level +- **IPAsset**:name*、type、authority、cert_no、grant_date、valid_until + +--- + +*文档生成方式:`python3 scripts/build_ontology_v2.py`(不加 `--fetch` 则直接基于已落盘的快照重建 SQLite;加 `--fetch` 重新只读拉取生产并刷新)。所有结论均来自只读快照,未对生产本体写入任何数据。* diff --git a/docs/ontology_v2_audit.md b/docs/ontology_v2_audit.md new file mode 100644 index 0000000..d120eac --- /dev/null +++ b/docs/ontology_v2_audit.md @@ -0,0 +1,240 @@ +# 尚数网本体 v2(修订后版本)审计报告 + +> 审计对象:生产环境本体平台(v1.5.1,commit `8a72cb2`),v2 蓝图导入后状态。 +> 审计时间:2026-10-12。数据来源:MCP `get_object_types` + `get_classification_config` + `list_principals` + REST `/objects`、`/ontology/link-types`(同源)。 +> 基线对照:导入前 `backups_1` 快照(59 类型 / 74 链接)→ 导入后 47 类型 / 77 链接。 + +--- + +## 一、总体结论 + +v2 导入在**结构层面是成功且干净的**:类型从 59 收敛到 47,合并/拆分事务完整,link_types 对已删类型**零悬空引用**,分级词汇统一为 L0–L4。但审计发现若干**数据质量、分级治理、可见性**问题,需在后续版本修订。 + +--- + +## 二、需修订的问题(按优先级) + +### P0 · 高(影响数据正确性与合规) + +**① Standard / PolicyDocument 实例存在大面积「超纲属性」(schema 脱节)** +- 现象:P4 拆分时把原 `ComplianceStandard` 实例的字段**整体复制**进目标类型,但目标类型未定义这些属性(平台对未定义属性宽松接受)。抽样确认: + - `Standard`(抽样 3/3 实例)均含:`standard_type / issuing_body / standard_code / related_space / english_title / effective_date / title / migrated_from`(8 个超纲); + - `PolicyDocument`(抽样 3/3 实例)均含:`issuing_body / standard_code / standard_type / related_space / migrated_from`(超纲)。 +- 影响:超纲字段无类型约束、无 enum 校验、不纳入检索/脱敏 schema、导出不一致;`standard_type` 对 `Standard` 实例已无语义。 +- 修订建议:给 `Standard`/`PolicyDocument` **正式补定义**高频公共字段(`issuing_body`、`standard_code`、`related_space`、`migrated_from` 作溯源保留),并对 261 条实例回填 schema 约束;或拆分时改为**字段映射**(丢弃无语义字段、把 `title` 映射到 `title_cn` 等)。 + +**② 高分级类型的实例对绝大多数主体不可见(可见性缺口)** +- 现象:75 个普通员工主体 clearance 仅到 **L2**;但 `PolicyDocument`(223 实例, 默认 **L3**)、`UsageControlPolicy`(36, L3)、`TrustedCryptographyCard`(3, L3)、`SecurityRequirement`(3, L3)、`SpaceManager`(3, L3) 默认分级均为 L3。这些实例对 75 员工 + `connector`/`public`/`TradingAssistant` 均不可见,仅 `manager`/`ingest`(L0–L4) 可见。 +- 影响:PolicyDocument 的 223 条政策/法规文件对业务一线几乎不可见,若其本意是「对内政策依据」则业务价值落空。 +- 修订建议:复核 PolicyDocument 等是否应降级到 **L2**(使相关业务可见);或显式给需访问的员工主体提升 clearance。见存疑 Q1。 + +### P1 · 中 + +**③ P1 新建的 3 个类型未启用分级治理** +- 现象:`DigitalContract` / `UsageAction` / `UsageConstraint` 分级配置 `enabled=False`、`levels=None`、`default=None`。 +- 影响:这三类(数字合约/使用动作/使用约束,属合规核心)完全脱离 L0–L4 分级体系,任何主体按其公开默认处理,存在合规盲区。 +- 修订建议:启用分级(`enabled=True` + 设 `levels=[L0..L4]` + 合理 `default`,建议 L3)。 + +**④ 实例级细粒度分级未落地** +- 现象:全 47 个类型中,实例级分布(distribution)**全部等于类型 default**,无任何实例被显式定到非默认级(非默认分布类型数 = 0)。 +- 影响:分级治理停留在「类型默认级」,无法对单条敏感实例(如涉密国标、敏感政策)做精细化升降级。 +- 修订建议:对高敏感实例(涉密 Standard、内部 PolicyDocument)做实例级显式定级。 + +**⑤ 历史实例超纲属性 / 字段命名不一致(存量治理)** +- 现象:`DataProduct` 实例 `anon_emr_query_service` 含 `billing_model`/`description`,但类型定义为 `price_model`/`desc`;`yiliao_shujt_...` 含 `industry`/`supports_inference`/`supports_training`/`tech_stack` 超纲。说明实例由多连接器写入、schema 未统一。 +- 修订建议:统一字段命名(description↔desc、billing_model↔price_model),补齐 `DataProduct`/`DataResource` 等类型的 AI/行业扩展属性定义。 + +### P2 · 低 / 规划 + +**⑥ 14 个零实例类型待分类处置** +- 新建未接入(保留 + 接分级):`DigitalContract` / `UsageAction` / `UsageConstraint`(P1 新建,业务尚未写入)。 +- 缺失元原语 / 规划占位(需确认是否保留或补示例):`AIProduct` / `AIPlatformComponent` / `TrustCredential` / `TDSInterconnection` / `DataLineage` / `DataRightsConfirmation` / `HighQualityDataset` / `VerificationItem` / `MeteringBill` / `DeliveryTask` / `DataPropertyRegistration`。 +- 修订建议:明确每类「保留待接入 / 补示例数据 / 删除」策略,避免本体成「空壳陈列」。 + +--- + +## 三、结构一致性(已确认良好,无需修订) + +- ✅ link_types 对已删类型(AccessStandard/TechnicalStandard/ControlPolicy/DataConnector/DataSecurityCard/HomomorphicComputePlatform/DeliveryScenario/DataAsset/AuditLog/BusinessLine/ContentAsset/ContentChannel/PromotionCampaign/ShuXiaoGuEval/ComplianceStandard)**零悬空引用**(13 条端点改写 + 3 条删除完整)。 +- ✅ 6 组类型合并事务完整,源类型均 `deleted_type`;ComplianceStandard 261 实例拆分到 Standard(58) + PolicyDocument(223) 数量闭合。 +- ✅ 分级词汇全 47 类型统一为 L0–L4,无异常取值。 +- ✅ principals 81 个(4 内置 + 1 TradingAssistant + 75 员工),访问控制与类型解耦,未因导入损坏。 + +--- + +## 四、关键信息存疑项(需人工确认,勿自行修订) + +| # | 存疑点 | 现状 | 需确认 | +|---|--------|------|--------| +| Q1 | PolicyDocument 默认分级 L3 是否合理 | 223 条政策文件对 75 员工不可见 | 政策文件是否应对业务一线可见(降到 L2)? | +| Q2 | Standard 默认分级 L0(公开)是否合理 | 含国家标准/技术文件 | 是否含涉密国标,需升到 L2/L3? | +| Q3 | `yubanfa_2025_8` 归 PolicyDocument | 空 standard_type 按 pk 语义兜底归入 | 是否确为政策文件而非标准? | +| Q4 | 4 条 `cs_tds_*` 软删是否彻底 | 已软删(墓碑可恢复) | 还是应保留为「TDS 技术规范」类实例? | +| Q5 | Standard/PolicyDocument 超纲字段是否转正 | 261 条游离字段 | 是否正式定义为类型属性? | +| Q6 | 75 员工 clearance 是否都该 L2 | 均 L0–L2 | 部分角色是否需 L3 访问政策/合规文件? | +| Q7 | 3 个新建类型业务接入时点 | 0 实例 + 无分级 | 数字合约/使用控制业务何时上线写入? | + +--- + +## 五、修订建议清单(行动优先级) + +1. **[P0-①]** 治理 Standard/PolicyDocument 超纲属性:补定义公共字段 + 回填 schema 约束(或拆分字段映射)。影响 261 条。 +2. **[P0-②]** 复核高分级类型可见性:PolicyDocument 等是否降级到 L2,或提升相关员工 clearance(对齐 Q1/Q6)。 +3. **[P1-③]** 启用 DigitalContract/UsageAction/UsageConstraint 分级(enabled + levels + default)。 +4. **[P1-④]** 落地实例级细粒度分级(敏感实例显式定级)。 +5. **[P1-⑤]** 统一 DataProduct/DataResource 历史超纲属性命名,补齐 AI/行业扩展 schema。 +6. **[P2-⑥]** 14 个零实例类型分类处置(保留/补数据/删)。 +7. **[存疑]** 逐项人工确认 Q1–Q7 后再执行对应修订。 + +--- + +## 六、附:本次审计使用的交付物 + +- `docs/ontology_v2_snapshot.json`:提炼后的本体快照(47 类型含属性/分级/实例数 + 77 链接),供材料撰写与审计复用。 +- `scripts/ontology_snapshot.py`:快照生成脚本(可复跑)。 +- `docs/尚数网介绍材料.md`:基于本快照撰写的对外介绍材料(子 agent 产出)。 +- 所有破坏性历史操作原始数据均保留于 `backups_1` 快照(450358 行),可恢复。 + +--- + +## 七、优化执行记录(2026-10-12 续,按用户授权执行) + +用户确认「按建议去优化」。区分「可安全机械执行的技术修复」与「需业务决策的存疑项」,后者未擅自改动。 + +### 已执行(技术修复,全部可逆 / 可恢复) + +- **[P0-①] Standard/PolicyDocument 超纲属性治理** + - 补定义 17 个高频公共属性:Standard(+5: `migrated_from`/`standard_code`/`related_space`/`standard_type`/`status`)、PolicyDocument(+6: `scope`/`standard_code`/`standard_type`/`related_space`/`migrated_from`/`english_title`)、DataProduct(+6: `jurisdiction`/`scene`/`industry`/`supports_inference`/`supports_training`/`tech_stack`)。 + - 实例值映射归一(merge 模式,原值迁至定义字段而非销毁):`title→title_cn`、`english_title→title_en`、`effective_date→implement_date`、`issuing_body/issued_by/issuer→publisher/issuer`、`code→doc_no`、`name→title`、`validity_period→valid_period`、`billing_model→price_model`、`description→desc`;冗余超纲 key 置 null 清除。 + - 覆盖 Standard(52) + PolicyDocument(223) + DataProduct(1) 共 276 实例。 + - **结果:三类型实例超纲属性全部清零**(验证 `props - 定义属性 = 空集`)。 + - 坑:`yubanfa_2025_8` 在批内被单事务跳过(batch 单事务,个别实例校验失败整批回滚/跳过),已定向单条重提交修复。 + +- **[P1-③] 启用 3 类型分级** + - 先给 DigitalContract/UsageAction/UsageConstraint 补 `classification` 属性(其它类型 migrate 自动带、新建时漏)。 + - `PUT /object-types/:name/classification` 正确 body:`classification_property`/`classification_levels`/`classification_default`(带前缀;且 `classification_property` 必须指向已存在属性,否则走「关闭分级」分支)。已启用 L0–L4、default=L3。 + +- **[P1-⑤] DataProduct 历史超纲**:补定义 AI/行业/管辖扩展属性 + `billing_model`/`description` 命名归一(见 P0-① 映射)。 + +- **[D] 分级重算**:`POST /ontology/classification/recompute` (dry_run) 200,各类型实例级分布物化一致。 + +### 留待确认(业务决策,未自动修订) + +- **[P0-②] 可见性缺口**:PolicyDocument(223)/UsageControlPolicy(36) 等默认 L3,对 75 名员工(clearance≤L2)不可见。未改默认分级、未改员工 clearance —— 需确认政策文件是否应对业务一线可见(降到 L2)或提升相关角色 clearance(对齐 Q1/Q6)。 +- **[P1-④] 实例级细粒度分级**:全 47 类型实例级分布仍等于类型 default,未对单条敏感实例(涉密国标、内部政策)显式定级。 +- **[P2-⑥] 14 零实例类型**:未分类处置(保留待接入 / 补示例 / 删)。 +- **[Q1–Q7] 存疑项**:原样保留,待人工确认。 + +--- + +## 八、P0-② 执行记录(2026-10-12 续二,用户确认「员工可见提高到 L3」) + +用户决策:**保留高分级类型默认 L3 不变,把 75 个员工主体 clearance 提升到 L3**(而非把 PolicyDocument 降级)。 + +- 脚本 `scripts/raise_employee_clearance.py`:筛选 `is_builtin=false` 且非 `TradingAssistant`/`analyst` 的 75 个「尚数网-XXX」员工主体,`PUT /api/v1/access/principals/:name/clearances` 设为 `["L0","L1","L2","L3"]`。 +- **坑(已修复)**:REST `putClearances` 仅读取请求体字段 `markings`(`handlers_access.go:318`,`json:"markings"`),传 `clearances` 会被忽略且执行 `DELETE` 把 clearance **清空成空集**——首跑 75/75 返回 200 但实为清空。已改为传 `markings` 重跑,核验全 75 人均为 `['L0','L1','L2','L3']`。 +- **结果**:75 名员工现在可见 L0–L3 全部对象(含 PolicyDocument/UsageControlPolicy 等),P0-② 类型默认级不动、员工侧解决。 +- **未动**:`connector`(L0–L2)、`analyst`(L0–L1)、`TradingAssistant`(L0–L1)、`public`(L0) 仍维持原级——如需外部连接器/分析角色读 L3 文档另行确认。 +- 对应存疑项:**Q1(PolicyDocument 是否该 L2)按保留 L3 结案;Q6(员工是否都该 L3)按用户确认结案**。Q2/Q3/Q4/Q5/Q7 仍待确认(Q5 已由 P0-① 执行)。 + +--- + +## 九、P2-⑥ 占位类型合并(2026-10-13,用户确认「去合并吧」) + +用户决策:把 5 个占位/重叠类型**合并**进既有类型(非删除),保留结构关系。 + +- 合并映射(官方 `POST /ontology/types/merge-execute`,自动迁移实例+改写 links/link_types+合并属性+删源类型): + | 源类型 | 目标类型 | 端点 link_type 改写结果 | + |---|---|---| + | AIProduct | DataProduct | AIProductDeliveredViaAppliance→DataProduct→Appliance;MemberOrgOperatesProduct→MemberOrg→DataProduct | + | AIPlatformComponent | DataResource | AIProductContainsComponent→DataProduct→DataResource | + | VerificationItem | TrustCredential | TrustCredentialIncludesItem→TrustCredential→TrustCredential(自环,保留);VerificationItemBackedByResource→TrustCredential→DataResource | + | DataRightsConfirmation | TrustCredential | (用户注「可由 Grant/Marking 表达」,并入凭证类) | + | DataPropertyRegistration | DataResource | — | +- **零实例确认**:脚本初版误把响应 dict 键数当实例数(响应数组在 `items`/`total`,非 `objects`),报「各 8 实例」假阳性;修正后确认 5 类均为 `total=0`,合并无数据风险。 +- **结果**:object-types 47 → **42**;5 个源类型已删;指向被并类型的 link_type **零悬空**(已改写)。 +- **坑(重要,历史债务,非本次产生)**:系统现仍有 **11 个悬空 link_type 定义**,端点指向 `BillingRecord`/`UsageLog`/`ContractPolicy`/`LogicalSpace`/`AccessEntity`/`ManagementEntity`/`ServiceNode`/`FunctionalNode`/`IndustryMasterData`/`IndustryKnowledgeHub`/`SemanticModel` 等**从未进入 47 类型清单**的类型(v2 蓝图早期遗留)。它们与本次合并无关,未擅动;建议另立任务清理(按目标类型改写端点或删除定义)。 +- 交付:`scripts/consolidate_placeholder_types.py`(merge-preview 预演 + 执行 + 校验,可复跑)。 + +### 交付物 +- `scripts/optimize_ontology_v2.py`:四阶段优化脚本(A 补定义 / B 启用分级 / C 实例映射 / D 重算),可复跑;C 已修正为逐条提交避免 batch 单事务回滚。 +- 数据可恢复性:所有修改作用于生产库;原始对照 `backups_1`(450358 行)保留,超纲清理为「值映射」而非销毁。 + +--- + +## 十、P1-④ 实例级分级 + 历史悬空 link_type 清理(2026-10-13 续,用户确认「把几个代办处理吧」) + +### 1) [P1-④] 实例级细粒度分级落地 + +可见性为**两层**模型(`server/classification.go` + `handlers_objects.go:118`): +- `objects.classification` 列 = 类型默认级(recompute 物化),由 `classificationCond` 强制; +- `object_markings` 表 = 实例级**覆盖层**,由 `visibilityCond`(CanRead) 强制(两者都要过)。 +- 接口:`PUT /access/objects/:type/:pk/markings`(`handlers_access.go:432`,整替换;`[]` 即移除覆盖层、回落列默认级)。 + +脚本 `scripts/apply_instance_classification.py`(两路分级 + 「非」前缀排除 + 自愈,可复跑): +- **Standard(58 条,列默认 L0)**:敏感词扫描 0 命中 → 全部保持 L0 公开(即 Q2 结论:数据中国标均为公开,无涉密子集)。 +- **PolicyDocument(223 条,列默认 L3)**:正向命中敏感词 1 条 `cs_20260918_124`(含「国家秘密」)→ 打 `["L4"]`(仅 manager/ingest 可见);其余 222 条保持列默认 L3。 +- **UsageControlPolicy(36 条,列默认 L3)**:按既定建议全部打 `["L4"]`(访问控制策略,默认受限)。 + +**⚠️ 执行中踩坑(重要,已修复)**:首版关键词把「非涉密」里的「涉密」误判为敏感词,将 6 条明确为「非涉密政务数据」的文件(`cs_20260918_44/61/71/205/232`)错升 L4。修正:敏感词命中排除「非」前缀否定语境(如 `非涉密` 不计为正向命中),并对「未命中但被误升到目标级」的覆盖层执行 `PUT []` 自愈回落。最终 5 条误标已回落(由列 L3 治理),1 条真涉密(`cs_20260918_124`)保留 L4。 + +**结果核验**:`GET /access/markings` → L0 标记 2381(recompute 物化,含 Standard 等公开类)、**L4 标记 37**(36 UsageControlPolicy + 1 PolicyDocument 国家秘密);悬空/误标清零。 + +**可逆性**:L4 覆盖层均可 `PUT []` 回落到列默认级;UsageControlPolicy 若需恢复对员工可见,逐条/批量 `PUT ["L3"]` 即可(属判断项,已与用户说明)。 + +### 2) [历史债务] 11 个悬空 link_type 清理 + +脚本 `scripts/cleanup_dangling_linktypes.py`(含 `GET /graph` 运行期兜底:确认无 link 实例引用这些 link_type 名)。 +- 删除 11 个端点指向「幽灵类型」(BillingRecord/UsageLog/ContractPolicy/LogicalSpace/AccessEntity/ManagementEntity/ServiceNode/FunctionalNode/IndustryMasterData/IndustryKnowledgeHub/SemanticModel——均从未进入类型清单)的 link_type 定义。 +- **结果**:link_types 77 → **66**;删除后复核「悬空 link_type:无 ✅」。 +- 安全依据:悬空定义端点类型不存在 → 不可能有 link 实例;且 `deleteLinkType` 执行前 `schemaAudit(before 快照)` 可审计/可恢复。 + +### 3) 存疑项结案(均为「保持现状」决策) + +| 项 | 结论 | +|---|------| +| Q2 | Standard 默认 L0 合理:扫描 58 条国标 0 涉密子集,保持公开 L0(已在 P1-④ 验证)。 | +| Q3 | `yubanfa_2025_8` 归 PolicyDocument:保持(P2-⑥ 合并时已确认)。 | +| Q4 | 4 条 `cs_tds_*` 软删墓碑:保持(可恢复,不恢复)。 | +| Q7 | 3 个新建类型(DigitalContract/UsageAction/UsageConstraint)零实例 + 已启用分级:保持,等业务上线写入。 | + +> 至此审计报告全部待办(P0-①/P0-②/P1-③/P1-④/P1-⑤/P2-⑥ + Q1–Q7 + 历史悬空 link_type)均已处理或确认结案。本体当前状态:**42 object-types / 66 link_types**,全类型启用 L0–L4 分级,实例级敏感覆盖层 37 条(L4),无悬空引用,无超纲属性。 + +--- + +## 十一、员工分级模型校正(2026-10-13 续,用户纠正「员工应 L0–L2」) + +**用户纠正**:规划的分级模型为 **L0 公众 / L1 客户 / L2 员工 / L3 经理以上 / L4 公司管理层**。第八节把 75 名员工误提到 L3 是错的——正确做法是**员工停在 L2,把本该员工可见的数据降到 L2**,而非靠提权让员工够到 L3 数据。 + +**执行(`scripts/fix_clearance_and_classification.py`,幂等、可复跑)**: + +1. **员工 clearance 回落 L0–L2**:75 个员工主体 `PUT /access/principals/:name/clearances` `{"markings":["L0","L1","L2"]}`。 +2. **八类型默认级 L3→L2(员工可见类)**:先 `POST /ontology/object-types/:name/properties` 补建 `classification` 属性(枚举 L0–L4,**否则 setObjectTypeClassification 校验 400「类型没有属性 classification」**),再 `PUT .../classification` 设 `classification_default:"L2"`,最后 `POST /ontology/classification/recompute`(`apply=true`)。 + - 受影响实例(recompute `applied=232`):PolicyDocument 223、SecurityRequirement 3、SpaceManager 3、TrustedCryptographyCard 3(其余 4 类零实例,仅改默认级)。 +3. **保留经理以上 / 管理层级**:`UsageControlPolicy` 类型默认 L3(经理以上),其 36 条实例**保持 L4 覆盖层**(仅 `ingest`/管理层可见,员工本就不该看访问控制策略);`DigitalContract`/`MeteringBill` 保持 L3;`PolicyDocument.cs_20260918_124`(国家秘密)保持 L4 覆盖层。 +4. `recompute` 仅写 `objects.classification` 列、**不碰 `object_markings` 实例覆盖层**,故 L4 国家秘密覆盖层完好保留。 + +**校正后状态**: +- 员工(75):L0–L2;`connector` L0–L2、`analyst`/`TradingAssistant` L0–L1、`public` L0、`ingest` L0–L4(公司管理层)、`manager` 硬编码读全量。 +- 类型默认级:L0=4、L1=8、L2=27(含 PolicyDocument 等)、L3=3(DigitalContract/MeteringBill/UsageControlPolicy)。 +- PolicyDocument 223 条全部 L2(员工可见),仅 `cs_20260918_124` 因 L4 覆盖层对管理层专属;UsageControlPolicy 36 条 L4(管理层专属)。 +- L4 实例覆盖层共 37 条(36 UsageControlPolicy + 1 国家秘密 PolicyDocument),无悬空、无超纲。 + +**待用户拍板(未动)**: +- `UsageControlPolicy` 36 条维持 L4(仅管理层)还是降到 L3(经理以上也可治理)?当前按「公司管理层专属」保留。 +- `manager` 主体 clearance 仍为 L0–L4(按模型应为 L3),但 `principalMaxIndex` 对 `manager` 硬编码返回最高级,其 clearance 不影响读,仅命名不一致,未擅改。 + +--- + +## 十二、UsageControlPolicy 36 条回落 L3(2026-10-13,用户确认「经理以上也可治理」) + +- 用户决策:UsageControlPolicy 36 条实例级 `object_markings=['L4']` 覆盖层移除,回落类型默认 L3(经理以上可见),不再专属管理层。 +- 脚本 `scripts/revert_ucp_level.py`(幂等):`PUT /access/objects/UsageControlPolicy/:pk/markings {"markings": []}` 批量移除覆盖层。36/36 成功,抽样 `policy_access/policy_trade/policy_template_abac` 返回 `None`(落类型默认 L3)。 +- 终态核验 `GET /access/markings`:L4 覆盖层仅剩 **1 条**(PolicyDocument 国家秘密 `cs_20260918_124`);L0 覆盖层 2381 条(recompute 物化的公开类默认级)。 +- 同步修正 `scripts/apply_instance_classification.py`:从 CONFIG 移除 UsageControlPolicy(不再复跑时误升 L4),维护职责转交 `revert_ucp_level.py`。 +- **最终分级映射(完整)**: + - L0 公众:Standard(58) 等公开类。 + - L1 客户:8 个类型默认 L1。 + - L2 员工:PolicyDocument(223) + SecurityRequirement/SpaceManager/TrustedCryptographyCard 等 27 类型。 + - L3 经理以上:DigitalContract/MeteringBill/UsageControlPolicy(36 实例) + 类型默认 L3 部分。 + - L4 公司管理层:仅 PolicyDocument `cs_20260918_124`(国家秘密)1 条实例覆盖层。 diff --git a/docs/ontology_v2_snapshot.json b/docs/ontology_v2_snapshot.json new file mode 100644 index 0000000..ca92b7e --- /dev/null +++ b/docs/ontology_v2_snapshot.json @@ -0,0 +1,4162 @@ +{ + "generated_from": "MCP get_object_types + REST /ontology/classification/config + 实例数 + REST link-types", + "object_types": [ + { + "api_name": "BusinessFlow", + "display_name": "业务流程", + "description": "可信数据空间的主要业务流程", + "iri": "http://example.org/standard-ontology#BusinessFlow", + "instance_count": 4, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 4 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "流程名称", + "data_type": "string", + "required": true, + "description": "业务流程名称" + }, + { + "api_name": "description", + "display_name": "流程说明", + "data_type": "text", + "required": false, + "description": "业务流程详细说明" + } + ] + }, + { + "api_name": "SecurityRequirement", + "display_name": "安全要求", + "description": "可信数据空间的安全保障要求", + "iri": "http://example.org/standard-ontology#SecurityRequirement", + "instance_count": 3, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L3", + "distribution": { + "L3": 3 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "安全要求名称", + "data_type": "string", + "required": true, + "description": "安全要求名称" + }, + { + "api_name": "category", + "display_name": "安全类别", + "data_type": "enum", + "required": true, + "description": "安全类别" + }, + { + "api_name": "description", + "display_name": "要求说明", + "data_type": "text", + "required": false, + "description": "安全要求详细说明" + } + ] + }, + { + "api_name": "AppStore", + "display_name": "应用商店", + "description": "可信数据空间内支持应用注册、审核、部署、版本管理与评价的应用生态", + "iri": "http://example.org/standard-ontology#AppStore", + "instance_count": 1, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L0", + "distribution": { + "L0": 1 + } + }, + "properties": [ + { + "api_name": "app_id", + "display_name": "应用标识", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "version", + "display_name": "版本号", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "status", + "display_name": "应用状态", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "rating", + "display_name": "评价均分", + "data_type": "number", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "UsageAction", + "display_name": "操作行为", + "description": "GB/T 使用控制策略五元组之一:操作行为。", + "iri": "http://example.org/standard-ontology#UsageAction", + "instance_count": 0, + "classification": { + "enabled": false, + "property": "", + "levels": null, + "default": "", + "distribution": {} + }, + "properties": [ + { + "api_name": "action_code", + "display_name": "行为编码", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "name", + "display_name": "行为名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "risk_level", + "display_name": "风险等级", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "desc", + "display_name": "说明", + "data_type": "text", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "UsageConstraint", + "display_name": "约束条件", + "description": "GB/T 使用控制策略五元组之一:约束条件(次数/期限/地域/用途/环境/销毁)。", + "iri": "http://example.org/standard-ontology#UsageConstraint", + "instance_count": 0, + "classification": { + "enabled": false, + "property": "", + "levels": null, + "default": "", + "distribution": {} + }, + "properties": [ + { + "api_name": "constraint_code", + "display_name": "约束编码", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "name", + "display_name": "约束名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "constraint_type", + "display_name": "约束类型", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "value", + "display_name": "约束取值", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "desc", + "display_name": "说明", + "data_type": "text", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "ArchitectureComponent", + "display_name": "技术架构组件", + "description": "可信数据空间技术架构中的功能组件,涵盖服务平台与接入连接器的各类功能模块", + "iri": "http://example.org/standard-ontology#ArchitectureComponent", + "instance_count": 14, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 14 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "组件名称", + "data_type": "string", + "required": true, + "description": "组件的名称" + }, + { + "api_name": "layer", + "display_name": "所属层级", + "data_type": "enum", + "required": true, + "description": "组件所属架构层级" + }, + { + "api_name": "category", + "display_name": "类别", + "data_type": "enum", + "required": false, + "description": "功能类别" + }, + { + "api_name": "is_required", + "display_name": "是否必备", + "data_type": "boolean", + "required": false, + "description": "是否为必备功能" + }, + { + "api_name": "description", + "display_name": "功能描述", + "data_type": "text", + "required": false, + "description": "组件的详细功能说明" + } + ] + }, + { + "api_name": "InterfaceSpec", + "display_name": "接口规范", + "description": "可信数据空间各组件之间的系统接口规范", + "iri": "http://example.org/standard-ontology#InterfaceSpec", + "instance_count": 3, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 3 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "接口名称", + "data_type": "string", + "required": true, + "description": "接口名称" + }, + { + "api_name": "direction", + "display_name": "接口方向", + "data_type": "enum", + "required": true, + "description": "南北向或东西向" + }, + { + "api_name": "from_component", + "display_name": "源组件", + "data_type": "string", + "required": false, + "description": "接口源端" + }, + { + "api_name": "to_component", + "display_name": "目标组件", + "data_type": "string", + "required": false, + "description": "接口目标端" + }, + { + "api_name": "description", + "display_name": "接口说明", + "data_type": "text", + "required": false, + "description": "接口详细说明" + } + ] + }, + { + "api_name": "FunctionalNode", + "display_name": "功能节点", + "description": "数据基础设施中的功能节点,包括区域功能节点、行业功能节点、业务节点和全域功能节点", + "iri": "http://example.org/standard-ontology#FunctionalNode", + "instance_count": 7, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 7 + } + }, + "properties": [ + { + "api_name": "node_code", + "display_name": "节点编码", + "data_type": "string", + "required": true, + "description": "区域/行业功能节点唯一标识" + }, + { + "api_name": "node_type", + "display_name": "节点类型", + "data_type": "enum", + "required": true, + "description": "区域/行业/业务/全域" + }, + { + "api_name": "scope", + "display_name": "覆盖范围", + "data_type": "string", + "required": false, + "description": "区域名称或行业名称" + }, + { + "api_name": "functions", + "display_name": "核心能力", + "data_type": "json", + "required": false, + "description": "节点具备的核心能力列表" + }, + { + "api_name": "security_level", + "display_name": "安全等级", + "data_type": "string", + "required": false, + "description": "网络安全等级保护级别" + } + ] + }, + { + "api_name": "UsageControlInterface", + "display_name": "使用控制接口", + "description": "可信数据空间使用控制功能模块对外提供的标准化接口", + "iri": "http://example.org/standard-ontology#UsageControlInterface", + "instance_count": 4, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 4 + } + }, + "properties": [ + { + "api_name": "interface_code", + "display_name": "接口编码", + "data_type": "string", + "required": true, + "description": "接口英文路径编码" + }, + { + "api_name": "name", + "display_name": "接口名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "http_method", + "display_name": "HTTP方法", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "caller", + "display_name": "调用方", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "provider", + "display_name": "提供方", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "data_format", + "display_name": "数据格式", + "data_type": "enum", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "UsageControlPolicy", + "display_name": "使用控制策略", + "description": "可信数据空间中对数据使用行为进行细粒度控制的策略规则,包括约束类与行为类策略", + "iri": "http://example.org/standard-ontology#UsageControlPolicy", + "instance_count": 36, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L3", + "distribution": { + "L3": 36 + } + }, + "properties": [ + { + "api_name": "policy_id", + "display_name": "策略ID", + "data_type": "string", + "required": true, + "description": "策略实例唯一标识(36位)" + }, + { + "api_name": "version", + "display_name": "策略版本", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "name", + "display_name": "策略名称", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "policy_type", + "display_name": "策略类型", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "dimension", + "display_name": "策略维度", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "description", + "display_name": "策略说明", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "priority", + "display_name": "优先级", + "data_type": "integer", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "Connector", + "display_name": "接入连接器", + "description": "可信数据空间中部署在数据提供方、使用方侧的连接节点,承担本地使用控制、环境隔离与存证上报等职能", + "iri": "http://example.org/standard-ontology#Connector", + "instance_count": 3, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 3 + } + }, + "properties": [ + { + "api_name": "connector_id", + "display_name": "连接器ID", + "data_type": "string", + "required": true, + "description": "唯一标识(32位)" + }, + { + "api_name": "public_key", + "display_name": "公钥", + "data_type": "string", + "required": false, + "description": "用于身份认证与合约签名的公钥" + }, + { + "api_name": "capabilities", + "display_name": "能力清单", + "data_type": "text", + "required": false, + "description": "连接器支持的数据接入、产品封装、使用控制等能力说明" + }, + { + "api_name": "status", + "display_name": "运行状态", + "data_type": "enum", + "required": false, + "description": "由平台监测的运行状态" + }, + { + "api_name": "role", + "display_name": "角色", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "usage_control_module", + "display_name": "使用控制模块", + "data_type": "boolean", + "required": false, + "description": "是否内置使用控制策略引擎" + } + ] + }, + { + "api_name": "AccessEntity", + "display_name": "接入主体", + "description": "可信数据空间中接入的数据提供方、数据使用方等参与主体的身份与认证信息", + "iri": "http://example.org/standard-ontology#AccessEntity", + "instance_count": 2, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 2 + } + }, + "properties": [ + { + "api_name": "entity_type", + "display_name": "主体类型", + "data_type": "enum", + "required": true, + "description": "" + }, + { + "api_name": "identity_credential", + "display_name": "身份凭证", + "data_type": "string", + "required": false, + "description": "由区域/行业功能节点颁发的身份凭证" + }, + { + "api_name": "auth_method", + "display_name": "认证方式", + "data_type": "enum", + "required": false, + "description": "身份认证方式" + }, + { + "api_name": "subject_type", + "display_name": "主体类型", + "data_type": "enum", + "required": true, + "description": "接入主体在数据空间中的角色" + }, + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "主体机构名称" + }, + { + "api_name": "did", + "display_name": "DID标识", + "data_type": "string", + "required": false, + "description": "去中心化标识符" + }, + { + "api_name": "cert_no", + "display_name": "证书编号", + "data_type": "string", + "required": false, + "description": "数字证书编号" + } + ] + }, + { + "api_name": "Service", + "display_name": "核心服务", + "description": "可信数据空间提供的核心能力服务,如密码学服务、数据接入服务、密态计算服务等。", + "iri": "http://example.org/standard-ontology#Service", + "instance_count": 22, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 22 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "desc", + "display_name": "说明", + "data_type": "text", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "PolicyDocument", + "display_name": "政策法规文件", + "description": "数据要素领域法律法规、规范性文件、实施方案、政策解读、公示公告等政策文件的元数据与结构化摘要。", + "iri": "http://example.org/standard-ontology#PolicyDocument", + "instance_count": 223, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L3", + "distribution": { + "L3": 223 + } + }, + "properties": [ + { + "api_name": "title", + "display_name": "文件标题", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "doc_no", + "display_name": "文号", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "doc_type", + "display_name": "文件类型", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "issuer", + "display_name": "发布机关", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "issue_date", + "display_name": "发布日期", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "effective_date", + "display_name": "施行日期", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "valid_period", + "display_name": "有效期", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "hierarchy", + "display_name": "效力层级", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "key_points", + "display_name": "核心要点", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "status", + "display_name": "效力状态", + "data_type": "string", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "Standard", + "display_name": "技术标准/文件", + "description": "全国数据标准化技术委员会或其他机构发布的技术文件、参考标准", + "iri": "http://example.org/standard-ontology#Standard", + "instance_count": 58, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L0", + "distribution": { + "L0": 58 + } + }, + "properties": [ + { + "api_name": "doc_no", + "display_name": "文件编号", + "data_type": "string", + "required": true, + "description": "标准/文件唯一编号" + }, + { + "api_name": "title_cn", + "display_name": "中文标题", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "title_en", + "display_name": "英文标题", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "issue_date", + "display_name": "发布日期", + "data_type": "date", + "required": false, + "description": "" + }, + { + "api_name": "implement_date", + "display_name": "实施日期", + "data_type": "date", + "required": false, + "description": "" + }, + { + "api_name": "publisher", + "display_name": "发布机构", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "proposer", + "display_name": "提出归口单位", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "doc_type", + "display_name": "文件类型", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "scope", + "display_name": "适用范围", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "page_count", + "display_name": "页数", + "data_type": "integer", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "TechnicalTerm", + "display_name": "术语定义", + "description": "技术标准中规范的术语及其定义", + "iri": "http://example.org/standard-ontology#TechnicalTerm", + "instance_count": 11, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L0", + "distribution": { + "L0": 11 + } + }, + "properties": [ + { + "api_name": "term_cn", + "display_name": "中文术语", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "term_en", + "display_name": "英文术语", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "definition", + "display_name": "定义", + "data_type": "text", + "required": true, + "description": "" + }, + { + "api_name": "source", + "display_name": "来源", + "data_type": "string", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "DataProduct", + "display_name": "数据产品", + "description": "经合规授权、安全使用、按量结算的可消费数据产品。", + "iri": "http://example.org/standard-ontology#DataProduct", + "instance_count": 266, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": { + "L1": 266 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "owner", + "display_name": "开发商", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "desc", + "display_name": "说明", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "price_model", + "display_name": "计费方式", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "status", + "display_name": "状态", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "source", + "display_name": "来源", + "data_type": "enum", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "DataResource", + "display_name": "数据资源", + "description": "尚数网平台收录的数据资源,涵盖文本/图片/语音/视频/结构化数据等。", + "iri": "http://example.org/standard-ontology#DataResource", + "instance_count": 630, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 630 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "category", + "display_name": "类别", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "scenario", + "display_name": "应用场景", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "owner", + "display_name": "提供方", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "format", + "display_name": "格式", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "scale", + "display_name": "规模", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "source", + "display_name": "来源", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "registered_at", + "display_name": "登记时间", + "data_type": "date", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "DataDemand", + "display_name": "数据需求", + "description": "平台上的数据需求撮合信息(谁要什么数据、何场景、何期限)。", + "iri": "http://example.org/standard-ontology#DataDemand", + "instance_count": 351, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": { + "L1": 351 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "desc", + "display_name": "说明", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "scene", + "display_name": "场景", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "deadline", + "display_name": "截止时间", + "data_type": "date", + "required": false, + "description": "" + }, + { + "api_name": "org", + "display_name": "需求方", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "status", + "display_name": "状态", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "jurisdiction", + "display_name": "区域", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "data_space", + "display_name": "所属空间", + "data_type": "string", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "MemberOrg", + "display_name": "会员单位", + "description": "与尚数网建立合作关系的会员单位、数据集团、登记机构、中央数据机构与生态合作伙伴;亦承载产业集团及其控股子公司画像。", + "iri": "http://example.org/standard-ontology#MemberOrg", + "instance_count": 96, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": { + "L1": 96 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "type", + "display_name": "类型", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "role", + "display_name": "角色", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "region", + "display_name": "区域", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "full_name", + "display_name": "机构全称", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "short_name", + "display_name": "简称", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "parent_group", + "display_name": "所属集团", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "business_sector", + "display_name": "业务板块", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "registered_capital_wan", + "display_name": "注册资本(万元)", + "data_type": "number", + "required": false, + "description": "" + }, + { + "api_name": "registered_capital_note", + "display_name": "注册资本备注", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "total_assets_yi", + "display_name": "总资产(亿元)", + "data_type": "number", + "required": false, + "description": "" + }, + { + "api_name": "total_assets_asof", + "display_name": "总资产数据时点", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "total_assets_note", + "display_name": "总资产备注", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "net_assets_wan", + "display_name": "净资产(万元)", + "data_type": "number", + "required": false, + "description": "" + }, + { + "api_name": "net_assets_asof", + "display_name": "净资产数据时点", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "core_asset", + "display_name": "核心资产与规模", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "group_shareholding_pct", + "display_name": "集团持股比例(%)", + "data_type": "number", + "required": false, + "description": "" + }, + { + "api_name": "stock_code", + "display_name": "证券代码", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "unified_social_credit_code", + "display_name": "统一社会信用代码", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "revenue_2024_yi", + "display_name": "2024年营业收入(亿元)", + "data_type": "number", + "required": false, + "description": "" + }, + { + "api_name": "net_profit_yi", + "display_name": "净利润(亿元)", + "data_type": "number", + "required": false, + "description": "" + }, + { + "api_name": "net_profit_asof", + "display_name": "净利润数据时点", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "berths", + "display_name": "泊位数", + "data_type": "number", + "required": false, + "description": "" + }, + { + "api_name": "throughput_capacity_yi_ton", + "display_name": "吞吐能力(亿吨)", + "data_type": "number", + "required": false, + "description": "" + }, + { + "api_name": "throughput_asof", + "display_name": "吞吐数据时点", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "fortune500_china_2024_rank", + "display_name": "2024中国500强排名", + "data_type": "number", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "DataExchange", + "display_name": "数据交易所", + "description": "合作的数据交易机构。", + "iri": "http://example.org/standard-ontology#DataExchange", + "instance_count": 10, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": { + "L1": 10 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "region", + "display_name": "区域", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "relation", + "display_name": "合作方式", + "data_type": "string", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "DataCatalog", + "display_name": "数据目录", + "description": "可信数据空间内的产品、服务、提供方、使用方及试用等目录集合", + "iri": "http://example.org/standard-ontology#DataCatalog", + "instance_count": 5, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": { + "L1": 5 + } + }, + "properties": [ + { + "api_name": "catalog_type", + "display_name": "目录类型", + "data_type": "enum", + "required": true, + "description": "" + }, + { + "api_name": "scope", + "display_name": "范围", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "query_supported", + "display_name": "是否支持检索", + "data_type": "boolean", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "DataAccessConnector", + "display_name": "数据接入连接器(硬件版)", + "description": "可信数据空间最后一公里的微型数据接入网关,企业数据快速接入可信数据空间的轻量硬件,开箱即用", + "iri": "http://example.org/standard-ontology#DataAccessConnector", + "instance_count": 4, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 4 + } + }, + "properties": [ + { + "api_name": "form_factor", + "display_name": "形态", + "data_type": "string", + "required": false, + "description": "微型数据接入网关硬件版" + }, + { + "api_name": "supported_sources", + "display_name": "接入数据源类型", + "data_type": "json", + "required": false, + "description": "支持接入的数据源类型" + }, + { + "api_name": "features", + "display_name": "核心特性", + "data_type": "json", + "required": false, + "description": "多源安全接入、标识认证、自动编目、自组网传输" + }, + { + "api_name": "capabilities", + "display_name": "核心能力", + "data_type": "json", + "required": false, + "description": "多源安全接入、标识认证、自动编目、自组网传输" + }, + { + "api_name": "multi_source_access", + "display_name": "多源安全接入", + "data_type": "boolean", + "required": false, + "description": "安全接入数据库、文件、接口等多源异构数据,原始数据不出域" + }, + { + "api_name": "identity_authentication", + "display_name": "标识认证", + "data_type": "string", + "required": false, + "description": "为数据源与设备分配唯一可信身份,建立数据空间信任基础" + }, + { + "api_name": "auto_cataloging", + "display_name": "自动编目", + "data_type": "boolean", + "required": false, + "description": "自动生成标准化数据目录,便于检索发现" + }, + { + "api_name": "ad_hoc_network", + "display_name": "自组网传输", + "data_type": "string", + "required": false, + "description": "与管理平台自动建立虚拟专用加密通道" + }, + { + "api_name": "role_in_space", + "display_name": "在数据空间中角色", + "data_type": "text", + "required": false, + "description": "数据供得出、流得动的关键入口" + } + ] + }, + { + "api_name": "Appliance", + "display_name": "密算一体机", + "description": "可信数据空间的硬件/软硬一体设施,包括可信密码卡、数据接入连接器、密算一体机等。", + "iri": "http://example.org/standard-ontology#Appliance", + "instance_count": 16, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 16 + } + }, + "properties": [ + { + "api_name": "version", + "display_name": "版本", + "data_type": "enum", + "required": true, + "description": "" + }, + { + "api_name": "cpu", + "display_name": "CPU", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "features", + "display_name": "核心能力", + "data_type": "text", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "TrustedCryptographyCard", + "display_name": "可信密码卡", + "description": "尚数网自主研发的可信密码卡,标准PCIe接口,作为可信数据空间的密码学底座", + "iri": "http://example.org/standard-ontology#TrustedCryptographyCard", + "instance_count": 3, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L3", + "distribution": { + "L3": 3 + } + }, + "properties": [ + { + "api_name": "interface", + "display_name": "接口形态", + "data_type": "string", + "required": false, + "description": "标准PCIe即插即用" + }, + { + "api_name": "supported_algorithms", + "display_name": "支持算法", + "data_type": "json", + "required": false, + "description": "SM1/SM2/SM3/SM4/SM9等国密算法" + }, + { + "api_name": "features", + "display_name": "核心特性", + "data_type": "json", + "required": false, + "description": "根密钥烧录、安全隧道、安全启动" + } + ] + }, + { + "api_name": "TrustedDataSpace", + "display_name": "可信数据空间", + "description": "数据要素流通的可信数据空间。", + "iri": "http://example.org/standard-ontology#TrustedDataSpace", + "instance_count": 25, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 25 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "operator", + "display_name": "运营方", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "industry", + "display_name": "行业", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "deploy_mode", + "display_name": "部署方式", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "region", + "display_name": "区域", + "data_type": "string", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "DigitalContract", + "display_name": "数字合约", + "description": "GB/T 48000.3 核心闭环载体:数字合约,串联交付任务、计量账单与控制策略。", + "iri": "http://example.org/standard-ontology#DigitalContract", + "instance_count": 0, + "classification": { + "enabled": false, + "property": "", + "levels": null, + "default": "", + "distribution": {} + }, + "properties": [ + { + "api_name": "contract_id", + "display_name": "合约编号", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "name", + "display_name": "合约名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "status", + "display_name": "合约状态", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "space", + "display_name": "所属空间", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "signed_at", + "display_name": "签署时间", + "data_type": "datetime", + "required": false, + "description": "" + }, + { + "api_name": "effective_at", + "display_name": "生效时间", + "data_type": "datetime", + "required": false, + "description": "" + }, + { + "api_name": "expires_at", + "display_name": "到期时间", + "data_type": "datetime", + "required": false, + "description": "" + }, + { + "api_name": "desc", + "display_name": "合约说明", + "data_type": "text", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "Branch", + "display_name": "分支机构", + "description": "尚数网的分支机构。", + "iri": "http://example.org/standard-ontology#Branch", + "instance_count": 7, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 7 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "city", + "display_name": "城市", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "role", + "display_name": "职能", + "data_type": "string", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "AIProduct", + "display_name": "AI产品/平台", + "description": "宁檬数科的 AI 产品线主体,含 AI 平台(训练推理/智能体开发/数据标注)与智能体应用(公文写作/合同审核/供需撮合),以及硬件交付载体一体机。", + "iri": "http://example.org/standard-ontology#AIProduct", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": {} + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "产品全称,如 AI训练推理平台" + }, + { + "api_name": "product_type", + "display_name": "产品类型", + "data_type": "enum", + "required": true, + "description": "平台类与智能体应用类在此区分" + }, + { + "api_name": "positioning", + "display_name": "产品定位", + "data_type": "text", + "required": false, + "description": "一句话定位与核心价值主张" + }, + { + "api_name": "target_users", + "display_name": "目标用户", + "data_type": "json", + "required": false, + "description": "如 政府与事业单位/高校/医疗企业/金融银行/产业客户" + }, + { + "api_name": "core_capabilities", + "display_name": "核心能力", + "data_type": "json", + "required": false, + "description": "能力清单,如 可视化工作流编排/知识库RAG/多级质检" + }, + { + "api_name": "deploy_mode", + "display_name": "部署方式", + "data_type": "json", + "required": false, + "description": "如 公有云SaaS/私有化部署/混合云/密算一体机" + }, + { + "api_name": "tech_stack", + "display_name": "技术栈", + "data_type": "json", + "required": false, + "description": "如 PyTorch/TensorFlow/DeepSeek/Qwen/GLM/昇腾NPU/海光DCU" + }, + { + "api_name": "domain", + "display_name": "适用领域", + "data_type": "json", + "required": false, + "description": "行业与业务领域,如 政务/金融/医疗/教育/具身智能" + }, + { + "api_name": "maturity", + "display_name": "成熟度", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "operator", + "display_name": "运营方", + "data_type": "string", + "required": false, + "description": "如 南宁市宁檬数据科技有限公司" + }, + { + "api_name": "release_date", + "display_name": "发布日期", + "data_type": "date", + "required": false, + "description": "" + }, + { + "api_name": "source", + "display_name": "来源", + "data_type": "enum", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "AIPlatformComponent", + "display_name": "AI平台组件", + "description": "AI 产品内部的功能模块、算法资产、模板与技能包、标注工具、基础设施组件。", + "iri": "http://example.org/standard-ontology#AIPlatformComponent", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": {} + }, + "properties": [ + { + "api_name": "name", + "display_name": "组件名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "parent_product", + "display_name": "所属产品", + "data_type": "string", + "required": false, + "description": "所属 AIProduct 名称" + }, + { + "api_name": "layer", + "display_name": "所属层级", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "component_type", + "display_name": "组件类别", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "capability_desc", + "display_name": "能力说明", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "is_required", + "display_name": "是否必备", + "data_type": "boolean", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "TrustCredential", + "display_name": "可信凭证", + "description": "", + "iri": "http://example.org/standard-ontology#TrustCredential", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L3", + "distribution": {} + }, + "properties": [ + { + "api_name": "name", + "display_name": "凭证名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "credential_id", + "display_name": "凭证编号", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "business_line", + "display_name": "所属业务线", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "subject_type", + "display_name": "主体类型", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "verified_items", + "display_name": "包含核验项", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "grade", + "display_name": "可信度档", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "disclosure_rule", + "display_name": "披露与解锁规则", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "issued_at", + "display_name": "签发时间", + "data_type": "date", + "required": false, + "description": "" + }, + { + "api_name": "valid_until", + "display_name": "有效期至", + "data_type": "date", + "required": false, + "description": "" + }, + { + "api_name": "verifiable_by", + "display_name": "可独立验真的第三方", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "signature_tech", + "display_name": "签名与存证技术", + "data_type": "string", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "TDSInterconnection", + "display_name": "可信数据空间互联互通", + "description": "可信数据空间互联互通:互联空间、技术接口、互联协议。", + "iri": "http://example.org/standard-ontology#TDSInterconnection", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L3", + "distribution": {} + }, + "properties": [ + { + "api_name": "peer_space", + "display_name": "互联空间", + "data_type": "string", + "required": false, + "description": "对端可信数据空间" + }, + { + "api_name": "tech_interface", + "display_name": "技术接口", + "data_type": "string", + "required": false, + "description": "互联互通技术接口" + }, + { + "api_name": "protocol", + "display_name": "互联协议", + "data_type": "string", + "required": false, + "description": "互联协议" + } + ] + }, + { + "api_name": "DeliveryTask", + "display_name": "数据交付任务", + "description": "数字合约的唯一履约载体:发起任务强制绑定已生效合约(contractId),生成唯一 taskId;任务全生命周期受连接器本地策略管控(频次/参数/算法/组网/输出),终结后自动销毁临时数据并固化血缘。", + "iri": "http://example.org/standard-ontology#DeliveryTask", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": {} + }, + "properties": [ + { + "api_name": "task_id", + "display_name": "任务标识", + "data_type": "string", + "required": true, + "description": "全局唯一 taskId" + }, + { + "api_name": "contract_id", + "display_name": "合约标识", + "data_type": "string", + "required": true, + "description": "强绑定已生效 contractId" + }, + { + "api_name": "space_id", + "display_name": "所属逻辑空间", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "task_type", + "display_name": "任务类型", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "status", + "display_name": "任务状态", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "provider_subject", + "display_name": "提供方", + "data_type": "string", + "required": false, + "description": "主体ID/连接器节点" + }, + { + "api_name": "consumer_subject", + "display_name": "使用方", + "data_type": "string", + "required": false, + "description": "主体ID/连接器节点" + }, + { + "api_name": "result_hash", + "display_name": "交付结果哈希", + "data_type": "string", + "required": false, + "description": "结果文件哈希,供验收/销毁核对" + }, + { + "api_name": "started_at", + "display_name": "开始时间", + "data_type": "datetime", + "required": false, + "description": "" + }, + { + "api_name": "ended_at", + "display_name": "结束时间", + "data_type": "datetime", + "required": false, + "description": "" + }, + { + "api_name": "destroy_proof", + "display_name": "销毁证明", + "data_type": "string", + "required": false, + "description": "终结/到期后各参与方本地数据销毁凭证" + }, + { + "api_name": "finished_at", + "display_name": "结束时间", + "data_type": "datetime", + "required": false, + "description": "" + }, + { + "api_name": "data_volume", + "display_name": "数据量", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "desc", + "display_name": "说明", + "data_type": "text", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "DataPropertyRegistration", + "display_name": "数据产权登记", + "description": "", + "iri": "http://example.org/standard-ontology#DataPropertyRegistration", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": {} + }, + "properties": [ + { + "api_name": "name", + "display_name": "登记事项名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "registration_system", + "display_name": "登记系统", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "registration_no", + "display_name": "登记编号", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "right_type", + "display_name": "权利类型", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "authority", + "display_name": "登记机构", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "subject", + "display_name": "登记主体", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "issued_at", + "display_name": "发证日期", + "data_type": "date", + "required": false, + "description": "" + }, + { + "api_name": "valid_until", + "display_name": "有效期至", + "data_type": "date", + "required": false, + "description": "" + }, + { + "api_name": "renewal_window", + "display_name": "续期窗口", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "certificate_effect", + "display_name": "凭证效力", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "basis_policy", + "display_name": "依据政策文件", + "data_type": "string", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "DataRightsConfirmation", + "display_name": "数据确权", + "description": "数据确权:三权、确权机构、登记证书。", + "iri": "http://example.org/standard-ontology#DataRightsConfirmation", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": {} + }, + "properties": [ + { + "api_name": "three_rights", + "display_name": "数据三权", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "authority", + "display_name": "确权机构", + "data_type": "string", + "required": false, + "description": "数据交易中心等" + }, + { + "api_name": "cert", + "display_name": "登记证书", + "data_type": "string", + "required": false, + "description": "数据资产登记证书" + } + ] + }, + { + "api_name": "DataLineage", + "display_name": "数据血缘", + "description": "", + "iri": "http://example.org/standard-ontology#DataLineage", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": {} + }, + "properties": [ + { + "api_name": "resourceId", + "display_name": "资源", + "data_type": "object", + "required": false, + "description": "" + }, + { + "api_name": "contractId", + "display_name": "合约", + "data_type": "object", + "required": false, + "description": "" + }, + { + "api_name": "taskId", + "display_name": "任务", + "data_type": "object", + "required": false, + "description": "" + }, + { + "api_name": "result", + "display_name": "结果", + "data_type": "object", + "required": false, + "description": "" + }, + { + "api_name": "delivery", + "display_name": "交付", + "data_type": "object", + "required": false, + "description": "" + }, + { + "api_name": "is_locked", + "display_name": "是否锁定", + "data_type": "boolean", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "VerificationItem", + "display_name": "核验项", + "description": "", + "iri": "http://example.org/standard-ontology#VerificationItem", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": {} + }, + "properties": [ + { + "api_name": "name", + "display_name": "核验项名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "data_source", + "display_name": "数据来源", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "verify_method", + "display_name": "核验方式", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "mark_type", + "display_name": "卡上标记", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "legal_constraint", + "display_name": "合规红线", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "authorization_required", + "display_name": "是否需本人授权", + "data_type": "boolean", + "required": false, + "description": "" + }, + { + "api_name": "risk_note", + "display_name": "风险提示", + "data_type": "text", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "MeteringBill", + "display_name": "计量账单", + "description": "基于连接器本地采集上报的原始计量与合约计费规则生成的账单:区分正常/超额用量、支持对账确认与计量异议修正,绑定 billId/spaceId/contractId/taskId 永久存证。", + "iri": "http://example.org/standard-ontology#MeteringBill", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L3", + "distribution": {} + }, + "properties": [ + { + "api_name": "bill_id", + "display_name": "账单标识", + "data_type": "string", + "required": true, + "description": "全局唯一 billId" + }, + { + "api_name": "space_id", + "display_name": "所属逻辑空间", + "data_type": "string", + "required": false, + "description": "计量账单按 spaceId 隔离归集" + }, + { + "api_name": "contract_id", + "display_name": "合约标识", + "data_type": "string", + "required": false, + "description": "计费规则取自合约生效版本" + }, + { + "api_name": "task_id", + "display_name": "任务标识", + "data_type": "string", + "required": false, + "description": "每条明细可溯源到 taskId" + }, + { + "api_name": "provider_subject", + "display_name": "提供方", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "consumer_subject", + "display_name": "使用方", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "metric_dimension", + "display_name": "计量维度", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "metric_value", + "display_name": "计量原始值", + "data_type": "number", + "required": false, + "description": "连接器上报原始计量快照汇总" + }, + { + "api_name": "total_amount", + "display_name": "计算金额", + "data_type": "number", + "required": false, + "description": "正常用量×单价+超额用量×超额单价" + }, + { + "api_name": "status", + "display_name": "账单状态", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "settle_period", + "display_name": "对账周期", + "data_type": "string", + "required": false, + "description": "按次/按日/按月" + }, + { + "api_name": "period", + "display_name": "计费周期", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "amount", + "display_name": "金额", + "data_type": "number", + "required": false, + "description": "" + }, + { + "api_name": "unit", + "display_name": "计量单位", + "data_type": "string", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "HighQualityDataset", + "display_name": "高质量数据集", + "description": "高质量数据集:建设标准、所属行业、应用场景建模。", + "iri": "http://example.org/standard-ontology#HighQualityDataset", + "instance_count": 0, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": {} + }, + "properties": [ + { + "api_name": "standard", + "display_name": "建设标准", + "data_type": "string", + "required": false, + "description": "数据集质量/标注标准" + }, + { + "api_name": "industry", + "display_name": "行业", + "data_type": "string", + "required": false, + "description": "生态环保/低空/医疗等" + }, + { + "api_name": "scenario", + "display_name": "应用场景", + "data_type": "string", + "required": false, + "description": "模型训练/分析等" + } + ] + }, + { + "api_name": "AppScenario", + "display_name": "应用场景", + "description": "数据资源与产品落地的应用场景域。", + "iri": "http://example.org/standard-ontology#AppScenario", + "instance_count": 17, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": { + "L1": 17 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "domain", + "display_name": "领域", + "data_type": "enum", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "EvaluationCriterion", + "display_name": "评价条款", + "description": "可信数据空间技术能力评价规范中的具体评价项(含基础级/扩展级要求)", + "iri": "http://example.org/standard-ontology#EvaluationCriterion", + "instance_count": 76, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 76 + } + }, + "properties": [ + { + "api_name": "criterion_code", + "display_name": "条款编号", + "data_type": "string", + "required": false, + "description": "如 6.1.a、7.3.b 等" + }, + { + "api_name": "check_content", + "display_name": "检查内容", + "data_type": "string", + "required": true, + "description": "评价项的名称" + }, + { + "api_name": "basic_level", + "display_name": "基础级要求", + "data_type": "boolean", + "required": false, + "description": "是否为基础级必备" + }, + { + "api_name": "extended_level", + "display_name": "扩展级要求", + "data_type": "boolean", + "required": false, + "description": "是否为扩展级必备" + }, + { + "api_name": "module", + "display_name": "所属模块", + "data_type": "string", + "required": false, + "description": "所属评价模块,如身份管理、目录管理" + }, + { + "api_name": "target_component", + "display_name": "评价对象", + "data_type": "enum", + "required": false, + "description": "所属章节大类" + }, + { + "api_name": "description", + "display_name": "条款说明", + "data_type": "text", + "required": false, + "description": "条款的详细要求描述" + } + ] + }, + { + "api_name": "EvaluationModule", + "display_name": "评价模块", + "description": "可信数据空间技术能力评价的模块划分", + "iri": "http://example.org/standard-ontology#EvaluationModule", + "instance_count": 28, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 28 + } + }, + "properties": [ + { + "api_name": "module_name", + "display_name": "模块名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "module_code", + "display_name": "模块编号", + "data_type": "string", + "required": false, + "description": "如 6.1、7.2 等" + }, + { + "api_name": "target_component", + "display_name": "所属评价对象", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "description", + "display_name": "模块说明", + "data_type": "text", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "EvaluationLevel", + "display_name": "评价等级", + "description": "可信数据空间技术能力评价的分级", + "iri": "http://example.org/standard-ontology#EvaluationLevel", + "instance_count": 2, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 2 + } + }, + "properties": [ + { + "api_name": "level_name", + "display_name": "等级名称", + "data_type": "string", + "required": true, + "description": "基础级/扩展级" + }, + { + "api_name": "description", + "display_name": "等级说明", + "data_type": "text", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "IPAsset", + "display_name": "知识产权", + "description": "尚数网的专利/软著/商标/标准/证书等。", + "iri": "http://example.org/standard-ontology#IPAsset", + "instance_count": 71, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L1", + "distribution": { + "L1": 71 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "type", + "display_name": "类型", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "status", + "display_name": "状态", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "authority", + "display_name": "发证机构", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "cert_no", + "display_name": "证书编号", + "data_type": "string", + "required": false, + "description": "登记号/注册号/备案号/证书编号等唯一编号" + }, + { + "api_name": "grant_date", + "display_name": "发证日期", + "data_type": "string", + "required": false, + "description": "发证日期 YYYY-MM-DD" + }, + { + "api_name": "valid_from", + "display_name": "有效期起", + "data_type": "string", + "required": false, + "description": "有效期起始 YYYY-MM-DD" + }, + { + "api_name": "valid_until", + "display_name": "有效期至", + "data_type": "string", + "required": false, + "description": "有效期截止 YYYY-MM-DD" + }, + { + "api_name": "reg_no", + "display_name": "登记号", + "data_type": "string", + "required": false, + "description": "登记号:软著登记号/商标注册号" + }, + { + "api_name": "patent_no", + "display_name": "专利号", + "data_type": "string", + "required": false, + "description": "专利号(授权后)" + }, + { + "api_name": "application_no", + "display_name": "申请号", + "data_type": "string", + "required": false, + "description": "申请号" + } + ] + }, + { + "api_name": "NewsArticle", + "display_name": "新闻动态", + "description": "尚数网官网发布的行业动态、产品发布、合作资讯等。", + "iri": "http://example.org/standard-ontology#NewsArticle", + "instance_count": 405, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L0", + "distribution": { + "L0": 405 + } + }, + "properties": [ + { + "api_name": "name", + "display_name": "标题", + "data_type": "string", + "required": true, + "description": "" + }, + { + "api_name": "content", + "display_name": "正文", + "data_type": "text", + "required": false, + "description": "" + }, + { + "api_name": "date", + "display_name": "发布日期", + "data_type": "date", + "required": false, + "description": "" + }, + { + "api_name": "source", + "display_name": "来源", + "data_type": "string", + "required": false, + "description": "" + }, + { + "api_name": "category", + "display_name": "分类", + "data_type": "string", + "required": false, + "description": "" + } + ] + }, + { + "api_name": "SpaceManager", + "display_name": "空间管理员角色", + "description": "可信数据空间中具备空间创建、删除与用户管理能力的管理员角色", + "iri": "http://example.org/standard-ontology#SpaceManager", + "instance_count": 3, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L3", + "distribution": { + "L3": 3 + } + }, + "properties": [ + { + "api_name": "role_name", + "display_name": "角色名", + "data_type": "enum", + "required": true, + "description": "" + }, + { + "api_name": "permissions", + "display_name": "权限列表", + "data_type": "json", + "required": false, + "description": "对应角色的差异化能力" + } + ] + }, + { + "api_name": "ApplianceSKU", + "display_name": "密算一体机版本", + "description": "密算一体机的版本配置", + "iri": "http://example.org/standard-ontology#ApplianceSKU", + "instance_count": 3, + "classification": { + "enabled": true, + "property": "classification", + "levels": [ + "L0", + "L1", + "L2", + "L3", + "L4" + ], + "default": "L2", + "distribution": { + "L2": 3 + } + }, + "properties": [ + { + "api_name": "sku_name", + "display_name": "版本名称", + "data_type": "enum", + "required": false, + "description": "" + }, + { + "api_name": "configurable_options", + "display_name": "可选配置", + "data_type": "json", + "required": false, + "description": "可按场景选配国密卡、GPU、低代码与智能体" + }, + { + "api_name": "name", + "display_name": "名称", + "data_type": "string", + "required": true, + "description": "" + } + ] + } + ], + "link_types": [ + { + "id": 109, + "api_name": "ResourceUsesScenario", + "display_name": "ResourceUsesScenario", + "source_type": "DataResource", + "target_type": "AppScenario", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ResourceUsesScenario" + }, + { + "id": 107, + "api_name": "SubjectDeploysConnector", + "display_name": "SubjectDeploysConnector", + "source_type": "AccessEntity", + "target_type": "Connector", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SubjectDeploysConnector" + }, + { + "id": 98, + "api_name": "AIProductDeliveredViaAppliance", + "display_name": "产品交付载体", + "source_type": "AIProduct", + "target_type": "Appliance", + "cardinality": "N:M", + "description": "AIProduct 与已有 Appliance(密算一体机)的交付关系:智能体开发平台等产品以密算一体机为交付形态,本地部署国产大模型,数据不出域。", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#AIProductDeliveredViaAppliance" + }, + { + "id": 97, + "api_name": "AIProductContainsComponent", + "display_name": "产品包含组件", + "source_type": "AIProduct", + "target_type": "AIPlatformComponent", + "cardinality": "1:N", + "description": "AIProduct 与 AIPlatformComponent 的组成关系:一个产品包含多个功能模块/算法资产/标注工具。", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#AIProductContainsComponent" + }, + { + "id": 124, + "api_name": "ProductListedOnExchange", + "display_name": "产品在交易所挂牌", + "source_type": "DataProduct", + "target_type": "DataExchange", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ProductListedOnExchange" + }, + { + "id": 120, + "api_name": "ProductDevelopedByOrg", + "display_name": "产品由机构开发", + "source_type": "DataProduct", + "target_type": "MemberOrg", + "cardinality": "many_to_one", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ProductDevelopedByOrg" + }, + { + "id": 60, + "api_name": "ProductBilledByRecord", + "display_name": "产品被计费", + "source_type": "DataProduct", + "target_type": "BillingRecord", + "cardinality": "one_to_many", + "description": "数据产品使用对应的计量计费记录", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ProductBilledByRecord" + }, + { + "id": 94, + "api_name": "TaskProducesBill", + "display_name": "任务产生账单", + "source_type": "DeliveryTask", + "target_type": "MeteringBill", + "cardinality": "one_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#TaskProducesBill" + }, + { + "id": 2, + "api_name": "MemberJoinsExchange", + "display_name": "入驻", + "source_type": "MemberOrg", + "target_type": "DataExchange", + "cardinality": "many_to_many", + "description": "会员单位入驻的数据交易所", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#MemberJoinsExchange" + }, + { + "id": 7, + "api_name": "SpaceContainsResource", + "display_name": "包含", + "source_type": "TrustedDataSpace", + "target_type": "DataResource", + "cardinality": "one_to_many", + "description": "可信数据空间内收录的数据资源/样本", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceContainsResource" + }, + { + "id": 1, + "api_name": "SpaceContainsProduct", + "display_name": "包含", + "source_type": "TrustedDataSpace", + "target_type": "DataProduct", + "cardinality": "one_to_many", + "description": "可信数据空间内运行/包含的数据产品", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceContainsProduct" + }, + { + "id": 8, + "api_name": "SpaceHasDemand", + "display_name": "包含需求", + "source_type": "TrustedDataSpace", + "target_type": "DataDemand", + "cardinality": "one_to_many", + "description": "可信数据空间内的数据需求", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceHasDemand" + }, + { + "id": 101, + "api_name": "TrustCredentialIncludesItem", + "display_name": "可信凭证包含核验项", + "source_type": "TrustCredential", + "target_type": "VerificationItem", + "cardinality": "many_to_many", + "description": "TrustCredential 的 verified_items 字段所述的核验项,对应到 VerificationItem 实例", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#TrustCredentialIncludesItem" + }, + { + "id": 42, + "api_name": "SpaceUsesDataAccessConnector", + "display_name": "可信数据空间-接入连接器", + "source_type": "TrustedDataSpace", + "target_type": "DataAccessConnector", + "cardinality": "many_to_many", + "description": "可信数据空间通过数据接入连接器接入多源数据", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceUsesDataAccessConnector" + }, + { + "id": 41, + "api_name": "SpaceUsesTrustedCryptoCard", + "display_name": "可信数据空间-部署可信密码卡", + "source_type": "TrustedDataSpace", + "target_type": "TrustedCryptographyCard", + "cardinality": "many_to_many", + "description": "可信数据空间部署可信密码卡作为密码学底座", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceUsesTrustedCryptoCard" + }, + { + "id": 91, + "api_name": "TDSInterconnectsWith", + "display_name": "可信数据空间互联互通", + "source_type": "TrustedDataSpace", + "target_type": "TrustedDataSpace", + "cardinality": "many-to-many", + "description": "可信数据空间之间的互联互通。", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#TDSInterconnectsWith" + }, + { + "id": 58, + "api_name": "ContractGeneratesLog", + "display_name": "合约产生日志", + "source_type": "DigitalContract", + "target_type": "UsageLog", + "cardinality": "one_to_many", + "description": "合约履行过程中产生的使用/交付/审计日志", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ContractGeneratesLog" + }, + { + "id": 76, + "api_name": "ContractContainsPolicy", + "display_name": "合约包含策略", + "source_type": "DigitalContract", + "target_type": "ContractPolicy", + "cardinality": "one_to_many", + "description": "一个数字合约中可包含多条合约策略", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ContractContainsPolicy" + }, + { + "id": 53, + "api_name": "ContractAppliesPolicy", + "display_name": "合约应用控制策略", + "source_type": "DigitalContract", + "target_type": "UsageControlPolicy", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ContractAppliesPolicy" + }, + { + "id": 74, + "api_name": "ContractCoversProduct", + "display_name": "合约标的为数据产品", + "source_type": "DigitalContract", + "target_type": "DataProduct", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ContractCoversProduct" + }, + { + "id": 75, + "api_name": "ContractSignedByParty", + "display_name": "合约签署主体", + "source_type": "DigitalContract", + "target_type": "MemberOrg", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ContractSignedByParty" + }, + { + "id": 93, + "api_name": "ContractGovernsTask", + "display_name": "合约管控交付任务", + "source_type": "DigitalContract", + "target_type": "DeliveryTask", + "cardinality": "one_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ContractGovernsTask" + }, + { + "id": 52, + "api_name": "ContractGovernsProduct", + "display_name": "合约管控数据产品", + "source_type": "DigitalContract", + "target_type": "DataProduct", + "cardinality": "many_to_many", + "description": "数字合约对数据产品使用行为进行控制", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ContractGovernsProduct" + }, + { + "id": 80, + "api_name": "ContractOperatedInSpace", + "display_name": "合约运行于空间", + "source_type": "DigitalContract", + "target_type": "TrustedDataSpace", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ContractOperatedInSpace" + }, + { + "id": 5, + "api_name": "ProductBuiltOnResource", + "display_name": "基于", + "source_type": "DataProduct", + "target_type": "DataResource", + "cardinality": "many_to_many", + "description": "数据产品所基于的数据资源", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ProductBuiltOnResource" + }, + { + "id": 43, + "api_name": "ApplianceHasSKU", + "display_name": "密算一体机-包含版本", + "source_type": "Appliance", + "target_type": "ApplianceSKU", + "cardinality": "many_to_many", + "description": "密算一体机提供多个版本配置供选配", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ApplianceHasSKU" + }, + { + "id": 88, + "api_name": "MemberOrgAuthorizesDataResource", + "display_name": "授权运营数据资源", + "source_type": "MemberOrg", + "target_type": "DataResource", + "cardinality": "many_to_many", + "description": "运营机构/实施机构对公共数据资源在授权范围、期限(如省本级整体授权 3 年)内开展开发运营的关系,可携带授权模式(整体/分领域/场景)、期限、协议编号", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#MemberOrgAuthorizesDataResource" + }, + { + "id": 125, + "api_name": "NewsArticleCitesStandard", + "display_name": "推文引用标准", + "source_type": "NewsArticle", + "target_type": "Standard", + "cardinality": "N:N", + "description": "推文解读或引用的政策/标准文件", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#NewsArticleCitesStandard" + }, + { + "id": 86, + "api_name": "ProductPublishedInSpace", + "display_name": "数据产品在空间中发布", + "source_type": "DataProduct", + "target_type": "TrustedDataSpace", + "cardinality": "many_to_many", + "description": "数据产品发布于某可信数据空间", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ProductPublishedInSpace" + }, + { + "id": 90, + "api_name": "DataProductComposedOf", + "display_name": "数据产品由数据资源组成", + "source_type": "DataProduct", + "target_type": "DataResource", + "cardinality": "many-to-many", + "description": "数据产品由若干数据资源组合而成。", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#DataProductComposedOf" + }, + { + "id": 85, + "api_name": "SpaceHasAccessEntity", + "display_name": "数据空间接入主体", + "source_type": "TrustedDataSpace", + "target_type": "AccessEntity", + "cardinality": "many_to_many", + "description": "可信数据空间接入的参与主体(提供方/使用方/服务方)", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceHasAccessEntity" + }, + { + "id": 48, + "api_name": "SpaceEvaluatedByCriterion", + "display_name": "数据空间适用评价条款", + "source_type": "TrustedDataSpace", + "target_type": "EvaluationCriterion", + "cardinality": "many_to_many", + "description": "可信数据空间与适用评价条款的关联", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceEvaluatedByCriterion" + }, + { + "id": 92, + "api_name": "CapitalizationTargetsProduct", + "display_name": "数据资产入表针对数据产品", + "source_type": "DataAssetCapitalization", + "target_type": "DataProduct", + "cardinality": "one-to-many", + "description": "数据资产入表所针对的数据产品。", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#CapitalizationTargetsProduct" + }, + { + "id": 106, + "api_name": "DataResourceProvidedBy", + "display_name": "数据资源由……提供", + "source_type": "DataResource", + "target_type": "MemberOrg", + "cardinality": "many_to_one", + "description": "DataResource.owner 字符串字段的关系化建模:一条数据资源由一个会员单位/组织提供", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#DataResourceProvidedBy" + }, + { + "id": 105, + "api_name": "DataDemandFiledBy", + "display_name": "数据需求由……提交", + "source_type": "DataDemand", + "target_type": "MemberOrg", + "cardinality": "many_to_one", + "description": "DataDemand.org 字符串字段的关系化建模:一条数据需求由一个会员单位/组织提交", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#DataDemandFiledBy" + }, + { + "id": 3, + "api_name": "ResourceForScenario", + "display_name": "服务于", + "source_type": "DataResource", + "target_type": "AppScenario", + "cardinality": "many_to_many", + "description": "数据资源落地的应用场景", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ResourceForScenario" + }, + { + "id": 99, + "api_name": "MemberOrgOperatesProduct", + "display_name": "机构运营产品", + "source_type": "MemberOrg", + "target_type": "AIProduct", + "cardinality": "1:N", + "description": "MemberOrg(会员单位/机构)与 AIProduct 的运营关系:南宁市宁檬数据科技有限公司运营其 AI 产品线。", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#MemberOrgOperatesProduct" + }, + { + "id": 46, + "api_name": "StandardDefinesCriterion", + "display_name": "标准定义评价条款", + "source_type": "Standard", + "target_type": "EvaluationCriterion", + "cardinality": "many_to_many", + "description": "技术标准文件中包含的评价条款", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#StandardDefinesCriterion" + }, + { + "id": 82, + "api_name": "StandardReferences", + "display_name": "标准引用", + "source_type": "Standard", + "target_type": "Standard", + "cardinality": "many_to_many", + "description": "标准之间规范性引用关系", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#StandardReferences" + }, + { + "id": 73, + "api_name": "StandardReferencesStandard", + "display_name": "标准引用标准", + "source_type": "Standard", + "target_type": "Standard", + "cardinality": "many_to_many", + "description": "接入管理标准规范性引用的其他技术文件", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#StandardReferencesStandard" + }, + { + "id": 81, + "api_name": "StandardDraftedBy", + "display_name": "标准起草单位", + "source_type": "Standard", + "target_type": "MemberOrg", + "cardinality": "many_to_many", + "description": "技术文件的起草/参与制定单位", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#StandardDraftedBy" + }, + { + "id": 65, + "api_name": "StdDraftedBy", + "display_name": "标准起草单位", + "source_type": "Standard", + "target_type": "MemberOrg", + "cardinality": "many_to_many", + "description": "技术标准的起草单位", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#StdDraftedBy" + }, + { + "id": 70, + "api_name": "StandardAppliesToNode", + "display_name": "标准适用于节点", + "source_type": "Standard", + "target_type": "FunctionalNode", + "cardinality": "many_to_many", + "description": "接入管理标准适用于功能节点的接入活动", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#StandardAppliesToNode" + }, + { + "id": 102, + "api_name": "VerificationItemBackedByResource", + "display_name": "核验项由数据资源支撑", + "source_type": "VerificationItem", + "target_type": "DataResource", + "cardinality": "many_to_many", + "description": "VerificationItem.data_source 对应的数据资源/接口实例", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#VerificationItemBackedByResource" + }, + { + "id": 47, + "api_name": "ModuleContainsCriterion", + "display_name": "模块包含评价条款", + "source_type": "EvaluationModule", + "target_type": "EvaluationCriterion", + "cardinality": "many_to_many", + "description": "评价模块与评价条款的归属关系", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ModuleContainsCriterion" + }, + { + "id": 89, + "api_name": "MemberOrgSupervises", + "display_name": "监督评价", + "source_type": "MemberOrg", + "target_type": "MemberOrg", + "cardinality": "many_to_many", + "description": "数据管理部门/实施机构对下级实施机构、运营机构的监督检查、考核评价、安全审查关系", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#MemberOrgSupervises" + }, + { + "id": 55, + "api_name": "CatalogIndexesResource", + "display_name": "目录索引资源", + "source_type": "DataCatalog", + "target_type": "DataResource", + "cardinality": "many_to_many", + "description": "数据目录对数据资源/产品进行登记与检索", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#CatalogIndexesResource" + }, + { + "id": 122, + "api_name": "IPOwnedByOrg", + "display_name": "知识产权归属机构", + "source_type": "IPAsset", + "target_type": "MemberOrg", + "cardinality": "many_to_one", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#IPOwnedByOrg" + }, + { + "id": 4, + "api_name": "SpaceUsesAppliance", + "display_name": "空间使用设备", + "source_type": "TrustedDataSpace", + "target_type": "Appliance", + "cardinality": "many_to_many", + "description": "可信数据空间使用各类硬件设备构建其底层基础设施。", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceUsesAppliance" + }, + { + "id": 96, + "api_name": "LogicalSpaceContainsSubject", + "display_name": "空间包含主体", + "source_type": "LogicalSpace", + "target_type": "AccessEntity", + "cardinality": "one_to_many", + "description": "一个逻辑空间可入驻多个主体(机构/企业/组织),同一主体可入驻多个空间且各空间角色权限独立隔离。", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#LogicalSpaceContainsSubject" + }, + { + "id": 95, + "api_name": "LogicalSpaceHostsContract", + "display_name": "空间承载合约", + "source_type": "LogicalSpace", + "target_type": "DigitalContract", + "cardinality": "one_to_many", + "description": "逻辑空间内初始化独立合约池;空间冻结/注销时校验未到期合约,空间注销前须处理全部合约。", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#LogicalSpaceHostsContract" + }, + { + "id": 57, + "api_name": "SpaceHostsStore", + "display_name": "空间承载应用商店", + "source_type": "TrustedDataSpace", + "target_type": "AppStore", + "cardinality": "one_to_many", + "description": "空间内运行的应用商店与生态", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceHostsStore" + }, + { + "id": 50, + "api_name": "SpaceRegistersConnector", + "display_name": "空间注册连接器", + "source_type": "TrustedDataSpace", + "target_type": "Connector", + "cardinality": "many_to_many", + "description": "可信数据空间对连接器进行注册、注销与认证管理", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceRegistersConnector" + }, + { + "id": 119, + "api_name": "SpaceOperatedByOrg", + "display_name": "空间由机构运营", + "source_type": "TrustedDataSpace", + "target_type": "MemberOrg", + "cardinality": "many_to_one", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceOperatedByOrg" + }, + { + "id": 6, + "api_name": "SpaceFollowsStandard", + "display_name": "空间遵循标准", + "source_type": "TrustedDataSpace", + "target_type": "Standard", + "cardinality": "many_to_many", + "description": "可信数据空间遵循的技术标准(已存在链接类型的复用)", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#SpaceFollowsStandard" + }, + { + "id": 78, + "api_name": "PolicyHasAction", + "display_name": "策略包含操作行为", + "source_type": "UsageControlPolicy", + "target_type": "UsageAction", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#PolicyHasAction" + }, + { + "id": 77, + "api_name": "PolicyHasConstraint", + "display_name": "策略包含约束", + "source_type": "UsageControlPolicy", + "target_type": "UsageConstraint", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#PolicyHasConstraint" + }, + { + "id": 79, + "api_name": "PolicyExecutedByAppliance", + "display_name": "策略执行节点", + "source_type": "UsageControlPolicy", + "target_type": "Appliance", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#PolicyExecutedByAppliance" + }, + { + "id": 83, + "api_name": "PolicyDeployedIn", + "display_name": "策略部署于", + "source_type": "UsageControlPolicy", + "target_type": "TrustedDataSpace", + "cardinality": "many_to_many", + "description": "使用控制策略在可信数据空间或接入连接器内执行", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#PolicyDeployedIn" + }, + { + "id": 72, + "api_name": "EntityManagesNode", + "display_name": "管理主体管理节点", + "source_type": "ManagementEntity", + "target_type": "ServiceNode", + "cardinality": "many_to_many", + "description": "管理主体对业务节点、接入连接器开展接入管理与常态化管理", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#EntityManagesNode" + }, + { + "id": 56, + "api_name": "ManagerAdministersSpace", + "display_name": "管理员管理空间", + "source_type": "SpaceManager", + "target_type": "TrustedDataSpace", + "cardinality": "many_to_one", + "description": "管理员对空间进行创建、删除与用户管理", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ManagerAdministersSpace" + }, + { + "id": 49, + "api_name": "ComponentBelongsToLayer", + "display_name": "组件所属层级", + "source_type": "ArchitectureComponent", + "target_type": "TrustedDataSpace", + "cardinality": "many_to_many", + "description": "技术组件归属于某一可信数据空间层级(服务平台或接入连接器)", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ComponentBelongsToLayer" + }, + { + "id": 61, + "api_name": "NodeUsesConnector", + "display_name": "节点接入连接器", + "source_type": "FunctionalNode", + "target_type": "DataAccessConnector", + "cardinality": "many_to_many", + "description": "区域/行业功能节点接入连接器管理", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#NodeUsesConnector" + }, + { + "id": 71, + "api_name": "NodeRegisteredAt", + "display_name": "节点注册于", + "source_type": "ServiceNode", + "target_type": "FunctionalNode", + "cardinality": "many_to_many", + "description": "业务节点/接入连接器选择某功能节点作为注册地", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#NodeRegisteredAt" + }, + { + "id": 63, + "api_name": "NodeManagesService", + "display_name": "节点管理业务节点", + "source_type": "FunctionalNode", + "target_type": "FunctionalNode", + "cardinality": "many_to_many", + "description": "区域/行业功能节点管理其下业务节点", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#NodeManagesService" + }, + { + "id": 69, + "api_name": "NodeManagesDataset", + "display_name": "节点管理数据集", + "source_type": "FunctionalNode", + "target_type": "HighQualityDataset", + "cardinality": "many_to_many", + "description": "区域/行业功能节点管理高质量数据集", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#NodeManagesDataset" + }, + { + "id": 62, + "api_name": "NodeAuthenticatesEntity", + "display_name": "节点认证主体", + "source_type": "FunctionalNode", + "target_type": "AccessEntity", + "cardinality": "many_to_many", + "description": "区域/行业功能节点对接入主体进行身份注册与核验", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#NodeAuthenticatesEntity" + }, + { + "id": 64, + "api_name": "NodeFollowsStandard", + "display_name": "节点遵循标准", + "source_type": "FunctionalNode", + "target_type": "Standard", + "cardinality": "many_to_many", + "description": "区域/行业功能节点遵循相关技术标准", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#NodeFollowsStandard" + }, + { + "id": 66, + "api_name": "IndustryNodeProvidesMasterData", + "display_name": "行业节点提供主数据", + "source_type": "FunctionalNode", + "target_type": "IndustryMasterData", + "cardinality": "many_to_many", + "description": "行业功能节点提供行业主数据服务", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#IndustryNodeProvidesMasterData" + }, + { + "id": 68, + "api_name": "IndustryNodeProvidesKnowledge", + "display_name": "行业节点提供知识中枢", + "source_type": "FunctionalNode", + "target_type": "IndustryKnowledgeHub", + "cardinality": "many_to_many", + "description": "行业功能节点提供行业知识中枢服务", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#IndustryNodeProvidesKnowledge" + }, + { + "id": 67, + "api_name": "IndustryNodeProvidesSemanticModel", + "display_name": "行业节点提供语义模型", + "source_type": "FunctionalNode", + "target_type": "SemanticModel", + "cardinality": "many_to_many", + "description": "行业功能节点提供行业语义模型服务", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#IndustryNodeProvidesSemanticModel" + }, + { + "id": 126, + "api_name": "ApplianceFollowsStandard", + "display_name": "设备遵循标准", + "source_type": "Appliance", + "target_type": "Standard", + "cardinality": "many_to_many", + "description": "密算一体机等设备需遵循的标准", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ApplianceFollowsStandard" + }, + { + "id": 59, + "api_name": "ResourceBuiltIntoProduct", + "display_name": "资源封装为产品", + "source_type": "Connector", + "target_type": "DataProduct", + "cardinality": "many_to_many", + "description": "连接器基于接入的数据资源封装数据产品", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ResourceBuiltIntoProduct" + }, + { + "id": 123, + "api_name": "ResourceProvidedByOrg", + "display_name": "资源由机构提供", + "source_type": "DataResource", + "target_type": "MemberOrg", + "cardinality": "many_to_one", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ResourceProvidedByOrg" + }, + { + "id": 54, + "api_name": "ConnectorProducesContract", + "display_name": "连接器发起合约", + "source_type": "Connector", + "target_type": "DigitalContract", + "cardinality": "many_to_one", + "description": "由接入连接器创建与协商的数字合约", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#ConnectorProducesContract" + }, + { + "id": 87, + "api_name": "OrgBelongsToGroup", + "display_name": "隶属集团", + "source_type": "MemberOrg", + "target_type": "MemberOrg", + "cardinality": "many_to_many", + "description": "机构隶属/控股关系:源=成员机构(子公司),目标=所属集团(母公司)。边属性 group_shareholding_pct 记录集团持股比例。", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#OrgBelongsToGroup" + }, + { + "id": 121, + "api_name": "DemandSatisfiedByProduct", + "display_name": "需求由产品满足", + "source_type": "DataDemand", + "target_type": "DataProduct", + "cardinality": "many_to_many", + "description": "", + "directional": false, + "source_property": "", + "target_property": "", + "iri": "http://example.org/standard-ontology#DemandSatisfiedByProduct" + } + ] +} \ No newline at end of file diff --git a/docs/尚数网介绍材料.md b/docs/尚数网介绍材料.md new file mode 100644 index 0000000..d793af3 --- /dev/null +++ b/docs/尚数网介绍材料.md @@ -0,0 +1,262 @@ +# 尚数网介绍材料 + +> 面向外部合作方 / 客户 +> 文档依据:尚数网本体数据快照 `ontology_v2_snapshot.json` +> 数据来源说明:`generated_from` = MCP `get_object_types` + REST `/ontology/classification/config` + 实例数 + REST link-types + +--- + +## 一、概述 + +尚数网(ShangShu Network)是以**可信数据空间(TrustedDataSpace)**为核心底座、面向数据要素流通的可信数据基础设施平台。平台围绕"数据供得出、流得动、用得好、保安全"的目标,构建了一套覆盖**数据资源(DataResource)→数据产品(DataProduct)→数据需求(DataDemand)→数据交易(DataExchange)**全链路的本体化数据模型,并以**数字合约(DigitalContract)+ 使用控制策略(UsageControlPolicy)+ 计量账单(MeteringBill)** 实现流通全过程的可控、可计量、可追溯。 + +基于快照中的核心对象类型,尚数网的定位可概括如下: + +- **可信数据空间(TrustedDataSpace,实例数 25)**:数据要素流通的逻辑载体,由运营机构构建,承载数据资源、数据产品、数据需求、连接器与应用生态。 +- **数据交易所(DataExchange,实例数 10)**:平台合作的场外交易机构,数据产品可在其上挂牌,会员单位可入驻。 +- **数据资源(DataResource,实例数 630)**:平台收录的数据资产,涵盖文本 / 图片 / 语音 / 视频 / 结构化数据等形态,是数据产品的原料。 +- **数据产品(DataProduct,实例数 266)**:经合规授权、安全使用、按量结算的可消费数据产品。 +- **数据需求(DataDemand,实例数 351)**:平台上撮合的数据需求信息,记录"谁要什么数据、何场景、何期限"。 + +平台同时具备国密自主可控的硬件底座(可信密码卡、密算一体机、数据接入连接器)、标准与政策合规库(技术标准 58 项、政策法规文件 223 项)、以及覆盖"身份—目录—合约—计量—存证"的治理体系。 + +--- + +## 二、本体体系架构 + +尚数网本体采用**对象类型(Object Type)/ 连接类型(Link Type)/ 属性(Property)**三层建模,整体规模如下: + +| 层级 | 规模 | 说明 | +| --- | --- | --- | +| 对象类型(Object Type) | **47 个** | 含 api_name / display_name / description / iri / instance_count / classification / properties | +| 连接类型(Link Type) | **77 条** | 描述对象类型之间的语义关系(source_type → target_type),含基数(cardinality) | +| 属性(Property) | 随对象类型挂载 | 每个对象类型含一组属性(api_name / data_type / required 等) | + +### 2.1 对象类型实例规模分布(含分级状态) + +- 已启用分级(classification.enabled = true)的类型:45 个 +- 未启用分级(classification.enabled = false)的类型:2 个 —— **UsageAction(操作行为,0 实例)**、**UsageConstraint(约束条件,0 实例)**(GB/T 使用控制策略五元组的组成部分,当前尚未分级建模);以及 **DigitalContract(数字合约,0 实例)**、**AIProduct(0 实例)**、**AIPlatformComponent(0 实例)** 等处于数据待补充状态的类型(其 classification 已启用但分布为空)。 + +### 2.2 实例数规模概览(Top 类型) + +快照中实例数较多的对象类型依次为:数据资源(630)、新闻动态(405)、数据需求(351)、数据产品(266)、政策法规文件(223)、会员单位(96)、知识产权(71)、评价条款(76)、技术标准(58)、可信数据空间(25)。 + +--- + +## 三、核心实体详解 + +以下挑选快照中实例数最多的关键类型,给出其展示名、说明、实例规模与关键属性。 + +### 3.1 数据资源(DataResource) +- **instance_count:630** | **默认分级:L2** +- 说明:尚数网平台收录的数据资源,涵盖文本 / 图片 / 语音 / 视频 / 结构化数据等。 +- 关键属性:`name`(名称)、`category`(类别)、`scenario`(应用场景)、`owner`(提供方)、`format`(格式)、`scale`(规模)、`source`(来源)、`registered_at`(登记时间)。 + +### 3.2 数据产品(DataProduct) +- **instance_count:266** | **默认分级:L1** +- 说明:经合规授权、安全使用、按量结算的可消费数据产品。 +- 关键属性:`name`、`owner`(开发商)、`desc`(说明)、`price_model`(计费方式)、`status`(状态)、`source`(来源)。 +- 关联:基于数据资源封装(`ProductBuiltOnResource` / `DataProductComposedOf`),可在数据交易所挂牌(`ProductListedOnExchange`),由会员单位开发(`ProductDevelopedByOrg`)。 + +### 3.3 数据需求(DataDemand) +- **instance_count:351** | **默认分级:L1** +- 说明:平台上的数据需求撮合信息(谁要什么数据、何场景、何期限)。 +- 关键属性:`name`、`desc`、`scene`(场景)、`deadline`(截止时间)、`org`(需求方)、`status`、`jurisdiction`(区域)、`data_space`(所属空间)。 +- 关联:需求可由会员单位提交(`DataDemandFiledBy`),并由数据产品满足(`DemandSatisfiedByProduct`)。 + +### 3.4 可信数据空间(TrustedDataSpace) +- **instance_count:25** | **默认分级:L2** +- 说明:数据要素流通的可信数据空间。 +- 关键属性:`name`、`operator`(运营方)、`industry`(行业)、`deploy_mode`(部署方式)、`region`(区域)。 +- 关联:包含数据资源 / 数据产品 / 数据需求(`SpaceContainsResource` / `SpaceContainsProduct` / `SpaceHasDemand`),由会员单位运营(`SpaceOperatedByOrg`),遵循技术标准(`SpaceFollowsStandard`),可互联互通(`TDSInterconnectsWith`)。 + +### 3.5 数据交易所(DataExchange) +- **instance_count:10** | **默认分级:L1** +- 说明:合作的数据交易机构。 +- 关键属性:`name`、`region`(区域)、`relation`(合作方式)。 +- 关联:会员单位入驻(`MemberJoinsExchange`),数据产品挂牌(`ProductListedOnExchange`)。 + +### 3.6 会员单位(MemberOrg) +- **instance_count:96** | **默认分级:L1** +- 说明:与尚数网建立合作关系的会员单位、数据集团、登记机构、中央数据机构与生态合作伙伴;亦承载产业集团及其控股子公司画像。 +- 关键属性:`name`、`type`(类型)、`role`(角色)、`region`(区域)、`parent_group`(所属集团)、`business_sector`(业务板块)、`registered_capital_wan`(注册资本,万元)、`revenue_2024_yi`(2024 年营业收入,亿元)、`unified_social_credit_code`(统一社会信用代码)等。 +- 关联:授权运营数据资源(`MemberOrgAuthorizesDataResource`)、开发数据产品(`ProductDevelopedByOrg`)、隶属集团(`OrgBelongsToGroup`)、相互监督评价(`MemberOrgSupervises`)。 + +### 3.7 技术标准 / 文件(Standard) +- **instance_count:58** | **默认分级:L0** +- 说明:全国数据标准化技术委员会或其他机构发布的技术文件、参考标准。 +- 关键属性:`doc_no`(文件编号)、`title_cn`(中文标题)、`title_en`、`issue_date`、`implement_date`、`publisher`(发布机构)、`proposer`(提出归口单位)、`doc_type`、`scope`(适用范围)、`page_count`。 + +### 3.8 政策法规文件(PolicyDocument) +- **instance_count:223** | **默认分级:L3** +- 说明:数据要素领域法律法规、规范性文件、实施方案、政策解读、公示公告等政策文件的元数据与结构化摘要。 +- 关键属性:`title`(文件标题)、`doc_no`(文号)、`doc_type`、`issuer`(发布机关)、`issue_date`、`effective_date`、`valid_period`、`hierarchy`(效力层级)、`key_points`(核心要点)、`status`(效力状态)。 + +### 3.9 其他重要类型速览 + +| 对象类型 | 展示名 | 实例数 | 默认分级 | 说明 | +| --- | --- | --- | --- | --- | +| Service | 核心服务 | 22 | L2 | 密码学服务、数据接入服务、密态计算服务等 | +| IPAsset | 知识产权 | 71 | L1 | 专利/软著/商标/标准/证书等 | +| NewsArticle | 新闻动态 | 405 | L0 | 官网发布的行业动态、产品发布、合作资讯 | +| EvaluationCriterion | 评价条款 | 76 | L2 | 技术能力评价规范的具体评价项 | +| EvaluationModule | 评价模块 | 28 | L2 | 技术能力评价的模块划分 | +| AppScenario | 应用场景 | 17 | L1 | 数据资源与产品落地的应用场景域 | +| ArchitectureComponent | 技术架构组件 | 14 | L2 | 服务平台与接入连接器的功能模块 | +| Appliance | 密算一体机 | 16 | L2 | 软硬一体设施(含可信密码卡、数据接入连接器) | +| FunctionalNode | 功能节点 | 7 | L2 | 区域/行业/业务/全域功能节点 | +| UsageControlPolicy | 使用控制策略 | 36 | L3 | 对数据使用行为细粒度控制的策略规则 | +| AccessEntity | 接入主体 | 2 | L2 | 数据提供方/使用方等参与主体的身份与认证 | +| Connector | 接入连接器 | 3 | L2 | 部署在提供方/使用方侧的连接节点 | +| TrustedCryptographyCard | 可信密码卡 | 3 | L3 | 国密算法 PCIe 密码学底座 | +| Branch | 分支机构 | 7 | L2 | 尚数网分支机构 | +| DataCatalog | 数据目录 | 5 | L1 | 产品/服务/提供方/使用方/试用目录集合 | +| SpaceManager | 空间管理员角色 | 3 | L3 | 空间创建/删除/用户管理权限 | +| ApplianceSKU | 密算一体机版本 | 3 | L2 | 密算一体机版本配置 | +| DataAccessConnector | 数据接入连接器(硬件版) | 4 | L2 | 微型数据接入网关,开箱即用 | +| BusinessFlow | 业务流程 | 4 | L2 | 可信数据空间主要业务流程 | +| InterfaceSpec | 接口规范 | 3 | L2 | 组件间系统接口规范 | +| UsageControlInterface | 使用控制接口 | 4 | L2 | 使用控制模块对外标准化接口 | +| SecurityRequirement | 安全要求 | 3 | L3 | 安全保障要求 | +| TechnicalTerm | 术语定义 | 11 | L0 | 标准中的术语及定义 | +| EvaluationLevel | 评价等级 | 2 | L2 | 基础级/扩展级 | +| AppStore | 应用商店 | 1 | L0 | 应用注册/审核/部署/评价生态 | +| TrustCredential | 可信凭证 | 0 | L3 | (待补充) | +| TDSInterconnection | 可信数据空间互联互通 | 0 | L3 | (待补充) | +| DeliveryTask | 数据交付任务 | 0 | L2 | 数字合约履约载体(待补充实例) | +| MeteringBill | 计量账单 | 0 | L3 | 计量计费账单(待补充实例) | +| DataLineage | 数据血缘 | 0 | L2 | (待补充) | +| VerificationItem | 核验项 | 0 | L2 | (待补充) | +| DataPropertyRegistration | 数据产权登记 | 0 | L1 | (待补充) | +| DataRightsConfirmation | 数据确权 | 0 | L1 | (待补充) | +| HighQualityDataset | 高质量数据集 | 0 | L1 | (待补充) | +| DigitalContract | 数字合约 | 0 | 未启用 | GB/T 48000.3 核心闭环载体(待补充实例) | +| AIProduct | AI 产品/平台 | 0 | L1 | 宁檬数科 AI 产品线(待补充实例) | +| AIPlatformComponent | AI 平台组件 | 0 | L2 | (待补充) | +| UsageAction | 操作行为 | 0 | 未启用 | 使用控制策略五元组之一(待补充) | +| UsageConstraint | 约束条件 | 0 | 未启用 | 使用控制策略五元组之一(待补充) | + +> 说明:实例数为 0 的类型,快照中已有属性定义但尚未录入实例(或分级暂未启用),属"模型已建、数据待补充"状态,本文不编造任何具体实例数字。 + +--- + +## 四、关系网络 + +平台 77 条连接类型(Link Type)将 47 个对象类型编织为一张"数据要素流通与治理"语义网络。按语义可归为以下几类: + +### 4.1 数据供应链(资源 → 产品 → 需求 → 交易) +- `DataProductComposedOf` / `ProductBuiltOnResource`:**数据产品**由**数据资源**组成 / 基于资源(many-to-many)。 +- `SpaceContainsResource` / `SpaceContainsProduct` / `SpaceHasDemand`:**可信数据空间**包含资源 / 产品 / 需求(one-to-many)。 +- `ProductListedOnExchange`:**数据产品**在**数据交易所**挂牌(many-to-many)。 +- `MemberJoinsExchange`:**会员单位**入驻**数据交易所**(many-to-many)。 +- `DemandSatisfiedByProduct`:**数据需求**由**数据产品**满足(many-to-many)。 +- `DataResourceProvidedBy` / `DataDemandFiledBy`:资源由机构提供 / 需求由机构提交(many-to-one)。 + +### 4.2 合约与治理闭环 +- `DigitalContract` 为核心闭环载体,串联: + - `ContractCoversProduct` / `ContractGovernsProduct`:合约标的 / 管控数据产品; + - `ContractSignedByParty`:合约由会员单位签署; + - `ContractAppliesPolicy`:合约应用使用控制策略; + - `ContractGovernsTask`:合约管控交付任务; + - `TaskProducesBill`:交付任务产生计量账单; + - `ContractOperatedInSpace`:合约运行于可信数据空间。 +- `ConnectorProducesContract`:接入连接器发起数字合约(many-to-one)。 + +### 4.3 使用控制与合规 +- `PolicyHasAction` / `PolicyHasConstraint`:使用控制策略包含操作行为 / 约束条件; +- `PolicyDeployedIn`:策略部署于可信数据空间或连接器; +- `PolicyExecutedByAppliance`:策略由密算一体机执行; +- `StandardDefinesCriterion` / `ModuleContainsCriterion`:标准定义评价条款 / 模块包含评价条款; +- `SpaceEvaluatedByCriterion`:可信数据空间适用评价条款。 + +### 4.4 主体、节点与基础设施 +- `SubjectDeploysConnector`:**接入主体**部署**接入连接器**; +- `SpaceRegistersConnector`:**可信数据空间**注册连接器; +- `SpaceHasAccessEntity`:空间接入参与主体; +- `NodeAuthenticatesEntity`:功能节点对接入主体身份注册与核验; +- `SpaceUsesAppliance` / `SpaceUsesTrustedCryptoCard` / `SpaceUsesDataAccessConnector`:空间使用密算一体机 / 可信密码卡 / 数据接入连接器; +- `OrgBelongsToGroup`:会员单位隶属集团(边属性 `group_shareholding_pct` 记录持股比例); +- `MemberOrgSupervises`:会员单位间监督评价 / 安全审查; +- `StandardDraftedBy` / `StdDraftedBy`:标准由会员单位起草。 + +### 4.5 互联互通与生态 +- `TDSInterconnectsWith`:可信数据空间之间互联互通(many-to-many); +- `AIProductDeliveredViaAppliance`:AI 产品以密算一体机为交付载体; +- `AIProductContainsComponent`:AI 产品包含平台组件; +- `MemberOrgOperatesProduct`:机构运营 AI 产品; +- `NewsArticleCitesStandard`:新闻动态引用 / 解读政策标准。 + +--- + +## 五、数据分级与合规治理 + +### 5.1 分级体系(L0–L4) +尚数网对 45 个启用分级的对象类型采用五级数据分类分级模型,属性 `classification` 统一承载: + +| 分级 | 含义(概括) | 可见范围 | +| --- | --- | --- | +| **L0** | 公开级 | 最广,可公开披露 / 对外发布 | +| **L1** | 受限级 | 合作方可控范围,需基本授权 | +| **L2** | 内部级 | 空间内部 / 授权主体可见 | +| **L3** | 敏感级 | 缩小至特定角色 / 强合规审查 | +| **L4** | 机密级 | 最小可见范围,最高保密要求 | + +> **基本原则:分级越高,可见范围越小。** 默认分级越高(如 L3、L4)的类型,通常对应合规、安全、策略类敏感实体;默认分级越低(如 L0)的类型,对应公开资讯、标准术语等可对外内容。 + +### 5.2 各类型默认分级一览(节选) + +| 默认分级 | 代表类型(展示名 / api_name) | +| --- | --- | +| **L0** | 应用商店 / 技术标准 / 术语定义 / 新闻动态 | +| **L1** | 数据产品 / 数据需求 / 数据交易所 / 数据目录 / 会员单位 / 应用场景 / 高质量数据集 / 知识产权 / 数据产权登记 / 数据确权 / AI 产品 / 空间管理员角色… | +| **L2** | 数据资源 / 可信数据空间 / 核心服务 / 技术架构组件 / 接口规范 / 功能节点 / 使用控制接口 / 接入连接器 / 接入主体 / 密算一体机 / 评价条款 / 评价模块 / 评价等级 / 数据血缘 / 数据接入连接器 / 数据交付任务 / 逻辑空间… | +| **L3** | 安全要求 / 使用控制策略 / 政策法规文件 / 可信凭证 / 可信密码卡 / 计量账单 / 空间管理员角色 / 互联互通 / 可信数据空间互联互通 | +| **L4** | (快照中各类型默认分级均未设为 L4,L4 作为最高保密级别预留) | + +> 注:快照中所有已录入实例的类型,其 `distribution` 当前均集中于默认分级(例如数据资源 630 条全为 L2、数据产品 266 条全为 L1、政策法规文件 223 条全为 L3)。即各类型实例暂未跨级分布,分级可在后续运营中按需上调。 + +### 5.3 合规治理要点 +- **标准合规**:技术标准(Standard,58 项)与评价条款(EvaluationCriterion,76 项)、评价模块(EvaluationModule,28 项)共同构成平台能力评价与合规基线的本体检模。 +- **政策合规**:政策法规文件(PolicyDocument,223 项)提供法律法规与规范性文件的结构化摘要,新闻动态(NewsArticle)可引用 / 解读标准。 +- **使用控制**:使用控制策略(UsageControlPolicy,36 项,默认 L3)基于 GB/T 使用控制策略五元组(操作行为 / 约束条件),由密算一体机本地执行。 +- **可追溯**:数字合约 → 交付任务 → 计量账单 → 数据血缘形成全过程存证链(`result_hash`、`destroy_proof`、`billId` 永久存证)。 + +--- + +## 六、接入与生态 + +### 6.1 接入主体与连接器 +- **接入主体(AccessEntity,2 实例,默认 L2)**:数据提供方 / 使用方等参与主体的身份与认证信息,含 `entity_type`、`identity_credential`(功能节点颁发)、`did`(去中心化标识)、`cert_no`(数字证书编号)。 +- **接入连接器(Connector,3 实例,默认 L2)**:部署在提供方 / 使用方侧,承担本地使用控制、环境隔离与存证上报,含 `connector_id`(32 位)、`public_key`、`usage_control_module`(是否内置策略引擎)。 +- **数据接入连接器(硬件版,DataAccessConnector,4 实例)**:微型硬件网关,多源安全接入、标识认证、自动编目、自组网传输,实现"数据不出域"。 +- **可信密码卡(TrustedCryptographyCard,3 实例,默认 L3)**:标准 PCIe 国密底座,支持 SM1/SM2/SM3/SM4/SM9。 + +### 6.2 功能节点体系 +- **功能节点(FunctionalNode,7 实例)**:区域功能节点、行业功能节点、业务节点、全域功能节点,承担身份认证、节点管理、主数据 / 知识中枢 / 语义模型服务。 + +### 6.3 主体体系说明 +> 快照未包含 `principals`(主体/账号与访问控制主体)明细。本文所述"接入主体(AccessEntity)""空间管理员角色(SpaceManager)""管理主体(ManagementEntity)""逻辑空间(LogicalSpace)"等为本体对象类型层面的建模;**具体的平台账号、权限主体与访问控制清单见平台访问控制体系(待补充)**。 + +### 6.4 生态合作 +- 会员单位(MemberOrg,96 家)覆盖数据集团、登记机构、中央数据机构与生态伙伴,并可通过 `OrgBelongsToGroup` 表达集团—子公司控股关系。 +- 数据交易所(DataExchange,10 家)提供挂牌交易通道。 +- AI 产品体系(宁檬数科)以密算一体机为交付载体,可私有化部署国产大模型。 + +--- + +## 七、总结与展望 + +尚数网以**可信数据空间**为底座,借助一套由 47 个对象类型、77 条连接类型、数百项属性构成的本体体系,将"数据资源—数据产品—数据需求—数据交易—数字合约—使用控制—计量存证"的全流程要素化、关系化、可治理化。截至本快照: + +- **数据规模**:数据资源 630 项、数据产品 266 项、数据需求 351 项、政策法规文件 223 项、新闻动态 405 项,已形成较为丰富的内容资产。 +- **标准体系**:技术标准 58 项、评价条款 76 项、评价模块 28 项,构成合规与评价基线的本体基础。 +- **基础设施**:可信数据空间 25 个、功能节点 7 个、密算一体机 16 台、可信密码卡 3 张,形成国密自主可控的软硬一体底座。 +- **分级治理**:L0–L4 五级分类分级覆盖 45 个类型,分级越高、可见范围越小,为跨主体安全流通提供制度与技术双重保障。 + +### 展望方向(基于现有模型推断,非承诺) +1. **实例补全**:数字合约、AI 产品、数据确权、计量账单等模型已建但实例待补充的类型,将随业务落地逐步录入。 +2. **跨空间互联**:`TDSInterconnectsWith` 已建模可信数据空间互联互通,未来可支撑多空间联邦流通。 +3. **主体体系完善**:配合平台访问控制,补全 principals 与各角色权限映射。 +4. **分级精细化**:在默认分级基础上,按数据敏感度实施实例级动态上调,强化最小可见范围。 + +> 本材料所有数据均来源于 `ontology_v2_snapshot.json` 快照,未引用任何快照之外的数字、人名或案例。快照未含字段(如 principals、具体实例明细)均以「(待补充)」标注,未作任何编造。 diff --git a/scripts/apply_instance_classification.py b/scripts/apply_instance_classification.py new file mode 100644 index 0000000..2aea817 --- /dev/null +++ b/scripts/apply_instance_classification.py @@ -0,0 +1,139 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +P1-④ 实例级细粒度分级:敏感实例加 object_markings 覆盖层(自愈/幂等)。 + +两层分级模型(server/classification.go + handlers_objects.go): + 1) objects.classification 列 = 类型默认级(recompute 物化),由 classificationCond 强制。 + 2) object_markings 表 = 实例级「额外覆盖层」,由 visibilityCond(CanRead) 强制。 + 两者都要过:实例 marking 要求主体 clearance 包含其全部 marking。 + -> 给实例打 ["L4"] 即在列值之上再叠加一层「仅 L4+ 可见」限制。 + +规则: + - Standard (列默认 L0/公开) 正向命中敏感词 -> ["L3"] (员工可见, 公开/connector 不可见) + - PolicyDocument (列默认 L3) 正向命中敏感词 -> ["L4"] (仅 manager/ingest 可见) + - UsageControlPolicy(列默认 L3) 全部 -> ["L4"] (访问控制策略, 默认受限) + +敏感词排除「非」前缀否定语境(如「非涉密」不计为正向命中)。 + +自愈: + - 正向命中 -> 确保 object_markings = [目标级](已是则跳过)。 + - 未命中 -> 若当前有 object_markings(上一轮误标),PUT [] 移除覆盖层,回落到列默认级; + 当前本就无标记(由列默认级治理)则不动。 +""" +import sys, json, argparse +sys.path.insert(0, "scripts") +import raise_employee_clearance as r + +SENSITIVE = ["涉密", "机密", "秘密", "保密", "内部", "受限", "敏感", "军事", + "国防", "绝密", "商密", "密级", "secret", "internal", "confidential", + "restricted", "classified", "sensitive"] + +CONFIG = { + "Standard": {"scan": True, "level": "L3", "reason": "内部/涉密标准(实际扫描0命中, 保持L0公开)"}, + "PolicyDocument": {"scan": True, "level": "L4", "reason": "仅国家秘密等真涉密文件升L4; 含'非涉密'否定语境的不升"}, + # UsageControlPolicy 不在此处处理:用户确认降到 L3(经理以上也可治理), + # 由 scripts/revert_ucp_level.py 维护(实例级移除L4覆盖层, 回落类型默认L3)。 +} + +def list_instances(typ): + out, offset = [], 0 + while True: + code, data = r.api("GET", f"/objects?type={typ}&limit=1000&offset={offset}") + if code != 200 or not data: + break + arr = data.get("items", data) if isinstance(data, dict) else data + if not arr: + break + out.extend(arr) + if len(arr) < 1000: + break + offset += 1000 + return out + +def text_of(o): + parts = [str(o.get(k, "") or "") for k in + ("name", "title", "title_cn", "title_en", "standard_code", + "doc_no", "publisher", "issuer", "scope", "classification")] + pj = o.get("properties_json") or o.get("properties") + if isinstance(pj, dict): + parts += [str(v) for v in pj.values()] + elif isinstance(pj, str): + parts.append(pj) + return " ".join(parts).lower() + +def positive_hit(txt): + hits = [] + for kw in SENSITIVE: + k = kw.lower() + start = 0 + found = False + while True: + i = txt.find(k, start) + if i < 0: + break + if i > 0 and txt[i - 1] == "非": # 否定语境,不算正向命中 + start = i + len(k) + continue + found = True + start = i + len(k) + if found: + hits.append(kw) + return hits + +def get_current_markings(typ, pk): + code, data = r.api("GET", f"/access/objects/{typ}/{pk}/markings") + if code == 200 and isinstance(data, dict): + return data.get("markings", []) or [] + return [] + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--dry-run", action="store_true", help="只盘点不写入") + args = ap.parse_args() + + plan, applied, reverted = [], 0, 0 + for typ, cfg in CONFIG.items(): + insts = list_instances(typ) + for o in insts: + pk = o.get("pk") + name = o.get("name") or o.get("title_cn") or o.get("title") or pk + txt = text_of(o) + cur = get_current_markings(typ, pk) + hits = positive_hit(txt) if cfg["scan"] else ["(全部)"] + if hits: + desired = [cfg["level"]] + note = "升" + str(hits) + else: + # 未命中:仅当本就被误升到目标级(覆盖层)时才回落移除; + # 其余(如 recompute 物化的列默认级标记)保持原样不动。 + desired = [] if cur == [cfg["level"]] else cur + note = "回落(移除误标)" if desired == [] else "保持" + if cur == desired: + continue + plan.append((typ, pk, name, desired, cur, note)) + if args.dry_run: + continue + code, _ = r.api("PUT", f"/access/objects/{typ}/{pk}/markings", + {"markings": desired}) + if code == 200: + if desired: + applied += 1 + else: + reverted += 1 + else: + print(f" ✗ 写入失败 {typ}/{pk}: HTTP {code}", file=sys.stderr) + print(f"[{typ}] 实例总数={len(insts)} 目标级={cfg['level']} ({cfg['reason']})") + + print(f"\n=== 待处理 {len(plan)} 条(升={sum(1 for p in plan if p[3])} 移除误标={sum(1 for p in plan if not p[3])})===") + for typ, pk, name, desired, cur, note in plan[:60]: + print(f" {typ}/{pk} {cur} -> {desired or '[]'} {note} {name!r}") + if len(plan) > 60: + print(f" ... 其余 {len(plan)-60} 条省略") + if args.dry_run: + print("\n[DRY-RUN] 未写入。去掉 --dry-run 执行。") + else: + print(f"\n已写入:加覆盖层 {applied} 条,移除误标 {reverted} 条(幂等)。") + +if __name__ == "__main__": + main() diff --git a/scripts/build_ontology_v2.py b/scripts/build_ontology_v2.py new file mode 100644 index 0000000..51417d1 --- /dev/null +++ b/scripts/build_ontology_v2.py @@ -0,0 +1,639 @@ +#!/usr/bin/env python3 +""" +本体 v2 schema 梳理工具(本地 SQLite,只读生产、不导入生产)。 + +用途:依据 docs/ontology-audit-20261001.md 的审计结论,把「梳理后的本体(对象类型 / +属性 / 链接类型 / 迁移映射 / 清理清单 / 枚举候选)」落成一份可查询的 SQLite 库, +用于评审与后续执行迁移。全过程只做: + 1) 对生产本体 REST 的只读 GET(可选,--fetch) + 2) 本地 SQLite 写入 +绝不调用任何生产写接口(create_object / create_link / create_*_type / km_* 写)。 + +用法: + python3 scripts/build_ontology_v2.py # 用 /tmp/onto-audit 缓存 + python3 scripts/build_ontology_v2.py --fetch # 重新只读拉取生产数据 + python3 scripts/build_ontology_v2.py --db path.db +""" +import json, os, sqlite3, sys, argparse, urllib.request, collections + +API_KEY = "0e926a78570d51a6949c65ffec2b7be6aa43ff2b678019c75cc0d65005affe05" +BASE = "http://r.mayishangshu.cn:18081/api/v1" +CACHE = "/tmp/onto-audit" +DEFAULT_DB = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "ontology-v2.db") + +# ============================================================ +# 决策清单:对象类型 v2 +# action: keep | merge | create | enable | refactor | deprecate | pending +# keep 保留且已有实例 +# merge 吸收其它类型后保留(merges=被吸收类型) +# create 新建 +# enable 现有空类型,确认启用(需灌数) +# refactor 保留但收敛语义/精简属性 +# deprecate 废弃(merged_into 指向归宿,可为空表示直接删除) +# pending 待业务决策,暂不处理 +# ============================================================ +OBJECT_TYPES = [ + # ---- A 空间与治理 ---- + ("TrustedDataSpace", "可信数据空间", "空间与治理", "keep", "", "", + "核心实体;需清理 11 个句子片段噪音实例 + 1 个测试实例", "可信数据空间"), + ("SpaceManager", "空间管理员角色", "空间与治理", "keep", "", "", + "3 个角色实例,保留", "空间运营方/管理角色"), + ("FunctionalNode", "功能节点", "空间与治理", "keep", "", "", + "区域/行业功能节点,7 实例", "功能节点"), + ("AccessEntity", "接入主体", "空间与治理", "refactor", "", "", + "统一主名:弃用 entity_name,只保留 name;补边 NodeAuthenticatesEntity", "接入主体"), + ("DigitalContract", "数字合约", "空间与治理", "create", "", "", + "GB/T 48000.3 核心闭环载体;原类型被删而 21 条边悬空,重建精简版", "数字合约"), + ("DeliveryTask", "数据交付任务", "空间与治理", "enable", "", "", + "随 DigitalContract 启用;task 发起强制绑定 contractId", "数据交付/履约"), + ("MeteringBill", "计量账单", "空间与治理", "enable", "", "", + "随 DigitalContract 启用;账单明细溯源到 taskId", "计量计费"), + ("TDSInterconnection", "空间互联互通", "空间与治理", "enable", "", "", + "互联互通是 GB/T 重点,保留边 TDSInterconnectsWith 并灌数", "空间互联互通"), + ("TrustCredential", "可信凭证", "空间与治理", "enable", "", "", + "GB/T 概念,与 VerificationItem 配套保留,需灌数", "可信凭证"), + ("VerificationItem", "核验项", "空间与治理", "enable", "", "", + "随 TrustCredential 启用", "核验/验证"), + + # ---- B 主体 ---- + ("MemberOrg", "会员单位/机构", "主体", "refactor", "", "", + "精简:港口专属(berths/throughput)与财务字段下沉;parent_group 字符串由 OrgBelongsToGroup 边取代", "参与方/主体"), + ("Branch", "分支机构", "主体", "keep", "", "", "7 实例,保留", "组织分支"), + + # ---- C 数据资产 ---- + ("DataResource", "数据资源", "数据资产", "keep", "", "", "630 实例;owner 字符串边化为 ResourceProvidedByOrg", "数据资源"), + ("DataProduct", "数据产品", "数据资产", "keep", "", "", "266 实例;owner 边化为 ProductDevelopedByOrg", "数据产品"), + ("DataDemand", "数据需求", "数据资产", "keep", "", "", "351 实例;补 DemandSatisfiedByProduct 边", "数据需求"), + ("DataCatalog", "数据目录", "数据资产", "keep", "", "", "5 实例;启用 CatalogIndexesResource 边", "数据目录"), + ("HighQualityDataset", "高质量数据集", "数据资产", "enable", "", "", "保留并灌数", "高质量数据集"), + ("DataRightsConfirmation", "数据确权", "数据资产", "enable", "", "", "三权分置核心,保留灌数", "数据确权"), + ("DataPropertyRegistration", "数据产权登记", "数据资产", "enable", "", "", "KM 有「数据产权登记」目录对应,保留灌数", "数据产权登记"), + ("DataLineage", "数据血缘", "数据资产", "enable", "", "", "治理核心,保留灌数", "数据血缘"), + ("IPAsset", "知识产权", "数据资产", "keep", "", "", "71 实例;补 IPOwnedByOrg 边;清理 1 个噪音", "知识产权"), + + # ---- D 标准与评测 ---- + ("Standard", "标准/技术文件", "标准与评测", "merge", "", "TechnicalStandard,AccessStandard", + "四套标准类型归一;字段名统一为 standard_code/title/issuer/issue_date/effective_date/scope/doc_type", "标准/技术文件"), + ("PolicyDocument", "政策法规文件", "标准与评测", "enable", "", "", + "承接 ComplianceStandard 中的政府规范性文件,与标准分离", "政策法规"), + ("TechnicalTerm", "术语定义", "标准与评测", "keep", "", "", "11 实例,保留", "术语"), + ("EvaluationModule", "评价模块", "标准与评测", "keep", "", "", "28 实例(20 条 label=pk 需回填显示名)", "评价/测评"), + ("EvaluationCriterion", "评价条款", "标准与评测", "keep", "", "", "76 实例(70 条 label=pk 需回填)", "评价条款"), + ("EvaluationLevel", "评价等级", "标准与评测", "keep", "", "", "2 实例,保留", "评价等级"), + + # ---- E 技术与硬件 ---- + ("Appliance", "密算一体机", "技术与硬件", "refactor", "", "HomomorphicComputePlatform", + "语义收敛为仅密算一体机/密态服务器;吸收 HomomorphicComputePlatform;清理 3 噪音 + 5 条卡/网关实例迁出", "可信管控设备"), + ("ApplianceSKU", "密算一体机版本", "技术与硬件", "refactor", "", "", + "3 实例;补 name 为 required(当前无 required 字段导致 label=pk)", "设备型号"), + ("TrustedCryptographyCard", "可信密码卡", "技术与硬件", "merge", "", "DataSecurityCard", + "吸收 DataSecurityCard(两者 desc 与字段近乎重复)", "密码学底座"), + ("DataAccessConnector", "数据接入连接器", "技术与硬件", "merge", "", "DataConnector", + "吸收 DataConnector(同义残本)", "接入连接器"), + ("Connector", "软件连接器", "技术与硬件", "keep", "", "", + "display_name 由「接入连接器」改为「软件连接器」以与硬件版消歧", "连接器"), + ("ArchitectureComponent", "技术架构组件", "技术与硬件", "keep", "", "", "14 实例;启用 ComponentBelongsToLayer 边或废弃", "技术架构"), + ("InterfaceSpec", "接口规范", "技术与硬件", "keep", "", "", "3 实例,保留", "接口"), + ("UsageControlInterface", "使用控制接口", "技术与硬件", "keep", "", "", "4 实例,保留", "使用控制接口"), + ("UsageControlPolicy", "使用控制策略", "技术与硬件", "merge", "", "ControlPolicy", + "吸收 ControlPolicy(display_name 完全相同的同义类型),新增 policy_type=模板 承载两条策略模板", "使用控制策略"), + ("UsageAction", "操作行为", "技术与硬件", "create", "", "", + "GB/T 策略五元组之一(操作行为),配合恢复 PolicyHasAction 边", "操作行为"), + ("UsageConstraint", "约束条件", "技术与硬件", "create", "", "", + "GB/T 策略五元组之一(约束条件),配合恢复 PolicyHasConstraint 边", "约束条件"), + ("Service", "核心服务", "技术与硬件", "keep", "", "", "22 实例,保留", "服务"), + ("SecurityRequirement", "安全要求", "技术与硬件", "keep", "", "", "3 实例,保留", "安全要求"), + + # ---- F 业务与应用 ---- + ("BusinessFlow", "业务流程", "业务与应用", "keep", "", "", "4 实例,保留", "业务流程"), + ("AppScenario", "应用场景", "业务与应用", "merge", "", "DeliveryScenario", + "吸收 DeliveryScenario(0 实例的空壳场景类型)", "应用场景"), + ("AppStore", "应用商店", "业务与应用", "keep", "", "", "1 实例,保留", "应用生态"), + ("DataExchange", "数据交易所", "业务与应用", "keep", "", "", "10 实例;清理 3 个句子片段噪音", "数据交易机构"), + + # ---- G 内容与运营 ---- + ("NewsArticle", "新闻动态", "内容与运营", "keep", "", "", + "405 实例,保留但归入内容域;content 存原始 HTML 待清洗", "资讯"), +] + +DEPRECATED_TYPES = [ + ("ControlPolicy", "UsageControlPolicy", 2, "display_name 与 UsageControlPolicy 完全相同(均「使用控制策略」),实例为策略模板"), + ("DataConnector", "DataAccessConnector", 1, "与 DataAccessConnector 同义残本,字段为后者子集"), + ("DataSecurityCard", "TrustedCryptographyCard", 1, "desc 与字段与可信密码卡近乎逐字相同;且同一硬件在 Appliance 中又被建了一遍"), + ("TechnicalStandard", "Standard", 2, "第三套「标准」类型;类型内部还有 title/standard_name、issuer/issuing_body 重复字段"), + ("AccessStandard", "Standard", 8, "接入管理标准是技术标准的子集场景,用 doc_type 区分即可"), + ("ComplianceStandard", "Standard+PolicyDocument", 261, "混装标准与政府政策文件,按 standard_type 拆分:标准→Standard,政策→PolicyDocument"), + ("DeliveryScenario", "AppScenario", 0, "空壳且与 AppScenario 平行;配套边 ResourceUsesScenario 亦 0 使用"), + ("HomomorphicComputePlatform", "Appliance", 1, "与 Appliance 中的「密态计算服务器」实例重复"), + ("DataAsset", "", 0, "desc 自称涵盖数据资源/数据集/数据产品,与三个已有类型职责重叠,且 0 实例"), + ("AuditLog", "", 0, "运营审计日志,非本体原语;0 实例"), + ("BusinessLine", "", 0, "运营素材建模,非可信数据空间本体原语;0 实例"), + ("ContentAsset", "", 0, "运营内容建模;0 实例,内容由 KM 承载"), + ("ContentChannel", "", 0, "同上;0 实例"), + ("PromotionCampaign", "", 0, "运营活动建模;0 实例"), + ("ShuXiaoGuEval", "", 0, "数小估产品线,评价体系已由 EvaluationModule/Criterion 承载;0 实例"), + ("DataSecurityCard", "TrustedCryptographyCard", 1, "重复条目占位(见上)"), +] + +PENDING_TYPES = [ + ("AIProduct", 0, "宁檬数科 AI 产品线主体;若确认 AI 产品线入本体则保留并灌数,否则整族废弃(含 AIPlatformComponent、AIProductContainsComponent、MemberOrgOperatesProduct)"), + ("AIPlatformComponent", 0, "AI 产品内部模块;随 AIProduct 一并决策"), +] + +# 新建类型的属性(已有类型自动继承生产 schema 属性) +NEW_PROPERTIES = { + "DigitalContract": [ + ("contract_id", "合约编号", "string", 1, ""), + ("name", "合约名称", "string", 1, ""), + ("status", "合约状态", "enum", 0, "草稿|待签署|已生效|已终止|已到期"), + ("space", "所属空间", "string", 0, ""), + ("signed_at", "签署时间", "datetime", 0, ""), + ("effective_at", "生效时间", "datetime", 0, ""), + ("expires_at", "到期时间", "datetime", 0, ""), + ("desc", "合约说明", "text", 0, ""), + ], + "DeliveryTask": [ + ("task_id", "任务编号", "string", 1, ""), + ("contract_id", "合约编号", "string", 1, ""), + ("status", "任务状态", "enum", 0, "执行中|已完成|已终止|异常"), + ("started_at", "开始时间", "datetime", 0, ""), + ("finished_at", "结束时间", "datetime", 0, ""), + ("data_volume", "数据量", "string", 0, ""), + ("desc", "说明", "text", 0, ""), + ], + "MeteringBill": [ + ("bill_id", "账单编号", "string", 1, ""), + ("task_id", "关联任务", "string", 0, ""), + ("period", "计费周期", "string", 0, ""), + ("amount", "金额", "number", 0, ""), + ("unit", "计量单位", "string", 0, ""), + ("status", "账单状态", "enum", 0, "待确认|已确认|异议中|已结算"), + ], + "UsageAction": [ + ("action_code", "行为编码", "string", 1, ""), + ("name", "行为名称", "string", 1, ""), + ("risk_level", "风险等级", "enum", 0, "低|中|高"), + ("desc", "说明", "text", 0, ""), + ], + "UsageConstraint": [ + ("constraint_code", "约束编码", "string", 1, ""), + ("name", "约束名称", "string", 1, ""), + ("constraint_type", "约束类型", "enum", 0, "次数|期限|地域|用途|环境|销毁条件"), + ("value", "约束取值", "string", 0, ""), + ("desc", "说明", "text", 0, ""), + ], +} + +# ============================================================ +# 决策清单:链接类型 v2 +# 未在清单中出现、且当前 0 使用的链接类型 → 自动标 deprecated +# ============================================================ +LINK_KEEP = { + "ApplianceHasSKU": "keep", "ManagerAdministersSpace": "keep", "MemberJoinsExchange": "keep", + "ModuleContainsCriterion": "keep", "NodeAuthenticatesEntity": "keep", "NodeFollowsStandard": "keep", + "NodeUsesConnector": "keep", "OrgBelongsToGroup": "keep", "ProductBuiltOnResource": "keep", + "ResourceForScenario": "keep", "SpaceContainsProduct": "keep", "SpaceContainsResource": "keep", + "SpaceFollowsStandard": "keep", "SpaceHasAccessEntity": "keep", "SpaceHasDemand": "keep", + "SpaceHostsStore": "keep", "SpaceRegistersConnector": "keep", "SpaceUsesAppliance": "keep", + "StandardAppliesToNode": "keep", "StandardDefinesCriterion": "keep", "StandardDraftedBy": "keep", + "StandardReferences": "keep", + # 修复后启用(source/target 或语义调整) + "CatalogIndexesResource": "enable", "PolicyDeployedIn": "enable", + "TDSInterconnectsWith": "enable", "ComponentBelongsToLayer": "enable", + "NodeManagesDataset": "enable", "PolicyExecutedByAppliance": "fix", + "PolicyHasAction": "fix", "PolicyHasConstraint": "fix", +} +LINK_DEPRECATE_NOTE = { + "ProductPublishedInSpace": "与 SpaceContainsProduct 同义反向重复(used=1 vs 26)", + "StandardReferencesStandard": "AccessStandard 并入 Standard 后与 StandardReferences 自引用重复", + "StdDraftedBy": "与 StandardDraftedBy 同义重复(used=0 vs 6)", + "DataProductComposedOf": "与 ProductBuiltOnResource 同义重复(used=0 vs 6)", + "ResourceBuiltIntoProduct": "同上,且 source 误设为 Connector", + "ResourceUsesScenario": "DeliveryScenario 并入 AppScenario,与 ResourceForScenario 重复", + "SpaceUsesDataAccessConnector": "与 SpaceRegistersConnector / NodeUsesConnector 语义重合", + "SubjectDeploysConnector": "与 SubjectDeploys… 无对应数据,主体-连接器关系由 NodeUsesConnector 表达", + "ContractGovernsProduct": "与 ContractCoversProduct 语义重复,保留后者", + "ContractContainsPolicy": "与 ContractAppliesPolicy 语义重复,保留后者", + "ContractGeneratesLog": "UsageLog 类型不存在,且不重建(日志走审计系统)", + "ContractSignedByParty": "改为连 MemberOrg(不重建 ContractParty 类型)", + "EntityManagesNode": "ManagementEntity/ServiceNode 类型不存在且不重建", + "NodeRegisteredAt": "ServiceNode 类型不存在且不重建", + "IndustryNodeProvidesKnowledge": "IndustryKnowledgeHub 类型不存在且不重建", + "IndustryNodeProvidesMasterData": "IndustryMasterData 类型不存在且不重建", + "IndustryNodeProvidesSemanticModel": "SemanticModel 类型不存在且不重建", + "LogicalSpaceContainsSubject": "LogicalSpace 概念不重建(逻辑空间由空间内策略表达)", + "LogicalSpaceHostsContract": "同上", + "ProductBilledByRecord": "BillingRecord 类型不存在,计费账单由 MeteringBill 承接", + "CapitalizationTargetsProduct": "DataAssetCapitalization 类型不存在,且不重建(DataAsset 已废弃)", + "MemberOrgOperatesProduct": "随 AIProduct 决策,当前 0 使用", + "AIProductContainsComponent": "随 AIProduct 决策,当前 0 使用", + "AIProductDeliveredViaAppliance": "随 AIProduct 决策,当前 0 使用", + "BusinessLineOperatedBy": "BusinessLine 类型废弃", + "ContentAssetPublishedOn": "ContentAsset/ContentChannel 类型废弃", + "TrustCredentialIncludesItem": "TrustCredential 启用后重新启用此边", + "VerificationItemBackedByResource": "VerificationItem 启用后重新启用此边", + "TaskProducesAudit": "AuditLog 类型废弃", + "SpaceEvaluatedByCriterion": "0 使用;如需空间-条款适用关系可恢复", + "NewsArticleCitesStandard": "有数据价值(405 篇推文),建议恢复并灌少量种子边", + "MemberOrgAuthorizesDataResource": "公共数据授权运营场景确有需要,建议恢复", + "MemberOrgSupervises": "监管考核关系确有需要,建议恢复", + "NodeManagesService": "功能节点-业务节点管理关系,建议恢复", + "ApplianceFollowsStandard": "设备合规遵循关系,建议恢复", + "MemberOrgSupervises ": "", +} +LINK_NEW = [ + ("SpaceOperatedByOrg", "空间由机构运营", "TrustedDataSpace", "MemberOrg", "many_to_one", + "把 TrustedDataSpace.operator 字符串边化;也是「XX作为运营方」噪音实例的根治手段"), + ("ProductDevelopedByOrg", "产品由机构开发", "DataProduct", "MemberOrg", "many_to_one", + "把 DataProduct.owner 字符串边化(30 个取值)"), + ("DemandSatisfiedByProduct", "需求由产品满足", "DataDemand", "DataProduct", "many_to_many", + "351 条需求当前无法表达被哪个产品/资源满足"), + ("IPOwnedByOrg", "知识产权归属机构", "IPAsset", "MemberOrg", "many_to_one", + "71 条 IPAsset 当前无归属边"), + ("ResourceProvidedByOrg", "资源由机构提供", "DataResource", "MemberOrg", "many_to_one", + "把 DataResource.owner 字符串边化;复用原 DataResourceProvidedBy 定义"), + ("ProductListedOnExchange", "产品在交易所挂牌", "DataProduct", "DataExchange", "many_to_many", + "数据产品与交易所的挂牌关系(建议项)"), + ("ContractCoversProduct", "合约标的为数据产品", "DigitalContract", "DataProduct", "many_to_many", + "随 DigitalContract 重建恢复"), + ("ContractSignedByParty", "合约签署主体", "DigitalContract", "MemberOrg", "many_to_many", + "随 DigitalContract 重建恢复(不重建 ContractParty 类型,直接连 MemberOrg)"), + ("ContractGovernsTask", "合约管控交付任务", "DigitalContract", "DeliveryTask", "one_to_many", + "随 DigitalContract 重建恢复"), + ("ContractOperatedInSpace", "合约运行于空间", "DigitalContract", "TrustedDataSpace", "many_to_many", + "随 DigitalContract 重建恢复"), + ("ContractAppliesPolicy", "合约应用控制策略", "DigitalContract", "UsageControlPolicy", "many_to_many", + "随 DigitalContract 重建恢复"), + ("TaskProducesBill", "任务产生账单", "DeliveryTask", "MeteringBill", "one_to_many", + "随 DigitalContract 重建恢复"), +] + +# 端点修复:把指向已废弃类型的活跃边重定向到 v2 类型 +LINK_RETARGET = { + "StandardDefinesCriterion": ("Standard", None), # TechnicalStandard → Standard + "StandardAppliesToNode": ("Standard", None), # AccessStandard → Standard + "NodeFollowsStandard": (None, "Standard"), # target TechnicalStandard → Standard + "PolicyExecutedByAppliance": ("UsageControlPolicy", "Appliance"), + "PolicyHasAction": ("UsageControlPolicy", "UsageAction"), + "PolicyHasConstraint": ("UsageControlPolicy", "UsageConstraint"), +} + +NOISE_PATTERNS = [ + ("作为运营方", "句子片段:'XX作为运营方',与真实空间实例一一重复"), + ("可用不可见、可控可计量", "抽取噪音:能力口号被建成空间实例"), + ("物流、公证等", "抽取噪音:枚举片段"), + ("支持多种部署模式", "抽取噪音:描述性短语"), + ("部分已经实现", "抽取噪音:描述性短语"), + ("交易所定规则", "抽取噪音:口号式短语"), + ("数据要素x", "抽取噪音:词根片段"), + ("软硬一体,开箱即用", "抽取噪音:营销短语"), + ("如深圳标准院", "抽取噪音:举例片段"), +] +# 白名单:命中关键词但确为正常实例(人工复核后排除) +NOISE_WHITELIST = { + ("IPAsset", "ip_cert_top50"): "『2024数据要素x行业推进大会数商TOP50』为真实证书,非噪音", +} + +NOISE_EXACT = [ + ("Appliance", "appliance_ed0946bfc287a54b", "授权", "单词片段"), + ("TrustedDataSpace", "mcp_test_medical_tds", "MCP测试医疗可信数据空间", "测试数据"), +] +CONCEPT_AMBIGUOUS = [ + ("TrustedDataSpace", "tds_tech_architecture_2025", "可信数据空间技术架构", "架构概念而非空间实例"), + ("TrustedDataSpace", "national_trusted_data_space", "国家可信数据空间管理服务平台", "平台概念而非空间实例"), + ("TrustedDataSpace", "tds_tc609_6_2025_14", "可信数据空间(依据TC609-6-2025-14数字合约技术要求)", "标准派生概念"), +] + + +def load_data(fetch: bool): + os.makedirs(CACHE, exist_ok=True) + files = { + "object-types": "object-types.json", + "type-details": "type-details.json", + "link-types": "link-types.json", + "graph": "graph.json", + } + + def get(path, out): + req = urllib.request.Request(f"{BASE}/{path}", headers={"X-API-Key": API_KEY}) + with urllib.request.urlopen(req) as r: + data = json.load(r) + json.dump(data, open(f"{CACHE}/{out}", "w"), ensure_ascii=False) + return data + + if fetch: + types = get("ontology/object-types", "object-types.json") + details = [] + for t in types: + req = urllib.request.Request(f"{BASE}/ontology/object-types/{t['api_name']}", headers={"X-API-Key": API_KEY}) + details.append(json.load(urllib.request.urlopen(req))["object_type"]) + json.dump(details, open(f"{CACHE}/type-details.json", "w"), ensure_ascii=False) + links = get("ontology/link-types", "link-types.json") + graph = get("ontology/graph", "graph.json") + else: + types = json.load(open(f"{CACHE}/object-types.json")) + details = json.load(open(f"{CACHE}/type-details.json")) + links = json.load(open(f"{CACHE}/link-types.json")) + graph = json.load(open(f"{CACHE}/graph.json")) + return types, details, links, graph + + +def build(db_path, fetch): + types, details, links, graph = load_data(fetch) + det = {t["api_name"]: t for t in details} + nodes = graph["nodes"] + cnt = collections.Counter(n["type"] for n in nodes) + edge_cnt = collections.Counter(e["type"] for e in graph["edges"]) + + if os.path.exists(db_path): + os.remove(db_path) + con = sqlite3.connect(db_path) + c = con.cursor() + c.executescript(""" + CREATE TABLE meta(key TEXT PRIMARY KEY, value TEXT); + + CREATE TABLE object_types( + id INTEGER PRIMARY KEY, api_name TEXT UNIQUE, display_name TEXT, group_name TEXT, + description TEXT, status TEXT, action TEXT, merges TEXT, merged_into TEXT, + instance_count INTEGER, prop_count INTEGER, rationale TEXT, gb_ref TEXT); + + CREATE TABLE properties( + id INTEGER PRIMARY KEY, type_api_name TEXT, api_name TEXT, display_name TEXT, + data_type TEXT, required INTEGER, enum_values TEXT, action TEXT, note TEXT); + + CREATE TABLE link_types( + id INTEGER PRIMARY KEY, api_name TEXT UNIQUE, display_name TEXT, source_type TEXT, + target_type TEXT, cardinality TEXT, status TEXT, action TEXT, usage_count INTEGER, + note TEXT, prev_usage INTEGER); + + CREATE TABLE type_migration( + id INTEGER PRIMARY KEY, old_type TEXT, new_type TEXT, action TEXT, + instance_count INTEGER, note TEXT); + + CREATE TABLE cleanup_instances( + id INTEGER PRIMARY KEY, type TEXT, pk TEXT, label TEXT, reason TEXT, category TEXT); + + CREATE TABLE enum_candidates( + id INTEGER PRIMARY KEY, type_api_name TEXT, prop_api_name TEXT, value TEXT, freq INTEGER); + + CREATE TABLE open_decisions( + id INTEGER PRIMARY KEY, topic TEXT, current TEXT, options TEXT, recommendation TEXT, + impact TEXT, related TEXT); + """) + + # ---- meta ---- + total_nodes = len(nodes) + for k, v in [ + ("schema_version", "v2-draft"), + ("generated_at", "2026-10-01"), + ("source", "production ontology r.mayishangshu.cn:18081 (read-only snapshot)"), + ("audit_report", "docs/ontology-audit-20261001.md"), + ("note", "本地梳理产物,未导入生产;仅供评审与后续迁移执行"), + ("prod_object_types", str(len(types))), + ("prod_instances", str(total_nodes)), + ("prod_link_types", str(len(links))), + ("prod_edges", str(len(graph['edges']))), + ]: + c.execute("INSERT INTO meta VALUES(?,?)", (k, v)) + + # ---- object_types + properties ---- + declared = {t[0] for t in OBJECT_TYPES} + oid = 0 + for (api, disp, grp, action, merged_into, merges, rationale, gb) in OBJECT_TYPES: + src = det.get(api) + desc = (src or {}).get("description", "") or "" + base_props = {p["api_name"]: p for p in ((src or {}).get("properties") or [])} + # 合并被吸收类型的属性 + merged_props = {} + for m in [x for x in merges.split(",") if x]: + mt = m.split("(")[0] + for p in (det.get(mt, {}).get("properties") or []): + merged_props.setdefault(p["api_name"], p) + n = cnt.get(api, 0) + for m in [x for x in merges.split(",") if x]: + n += cnt.get(m.split("(")[0], 0) + oid += 1 + c.execute("""INSERT INTO object_types + (id,api_name,display_name,group_name,description,status,action,merges,merged_into, + instance_count,prop_count,rationale,gb_ref) + VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)""", + (oid, api, disp, grp, desc, "active", action, merges, merged_into, + n, len(base_props) + len(merged_props), rationale, gb)) + # 属性写入 + for name, p in base_props.items(): + note = "" + act = "keep" + if api == "MemberOrg" and name in ("berths", "throughput_capacity_yi_ton", "throughput_asof"): + act, note = "review", "港口专属字段(96 实例中 1 家使用),建议下沉为 profile_json" + if api == "MemberOrg" and name == "parent_group": + act, note = "review", "与 OrgBelongsToGroup 边(37 条)双轨,建议回填后弃用字符串" + if api == "AccessEntity" and name == "entity_name": + act, note = "drop", "与 name 双主名,统一为 name" + if api == "TechnicalStandard" and name in ("standard_name", "effective_date", "issuing_body"): + act, note = "drop", "与 title/implementation_date/issuer 重复" + c.execute("INSERT INTO properties(type_api_name,api_name,display_name,data_type,required,enum_values,action,note)" + " VALUES(?,?,?,?,?,?,?,?)", + (api, name, p.get("display_name", ""), p.get("data_type", ""), + int(bool(p.get("required"))), "", act, note)) + for name, p in merged_props.items(): + if name in base_props: + continue + c.execute("INSERT INTO properties(type_api_name,api_name,display_name,data_type,required,enum_values,action,note)" + " VALUES(?,?,?,?,?,?,?,?)", + (api, name, p.get("display_name", ""), p.get("data_type", ""), + int(bool(p.get("required"))), "", "inherit_merge", + f"来自被吸收类型 {p.get('object_type_id','')}")) + for (pn, pd, dt, req, ev) in NEW_PROPERTIES.get(api, []): + c.execute("INSERT INTO properties(type_api_name,api_name,display_name,data_type,required,enum_values,action,note)" + " VALUES(?,?,?,?,?,?,?,?)", (api, pn, pd, dt, req, ev, "new", "新建类型属性")) + # 补 required 建议 + if api == "ApplianceSKU": + c.execute("INSERT INTO properties(type_api_name,api_name,display_name,data_type,required,enum_values,action,note)" + " VALUES(?,?,?,?,?,?,?,?)", + ("ApplianceSKU", "name", "名称", "string", 1, "", "new", + "当前无 required 且无 name,导致 3 个实例 label=pk")) + + # 废弃 / 待定类型 + seen = set() + for (old, into, ic, note) in DEPRECATED_TYPES: + if old in seen: + continue + seen.add(old) + oid += 1 + d = det.get(old, {}) + c.execute("""INSERT INTO object_types + (id,api_name,display_name,group_name,description,status,action,merges,merged_into, + instance_count,prop_count,rationale,gb_ref) + VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)""", + (oid, old, d.get("display_name", ""), "(废弃)", d.get("description", ""), + "deprecated", "deprecate", "", into, ic, len(d.get("properties") or []), note, "")) + c.execute("INSERT INTO type_migration(old_type,new_type,action,instance_count,note) VALUES(?,?,?,?,?)", + (old, into or "(删除)", "merge" if into else "delete", ic, note)) + for (api, ic, note) in PENDING_TYPES: + oid += 1 + d = det.get(api, {}) + c.execute("""INSERT INTO object_types + (id,api_name,display_name,group_name,description,status,action,merges,merged_into, + instance_count,prop_count,rationale,gb_ref) + VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)""", + (oid, api, d.get("display_name", ""), "(待定)", d.get("description", ""), + "pending_decision", "pending", "", "", ic, len(d.get("properties") or []), note, "")) + + # ---- link_types ---- + lid = 0 + for l in links: + api = l["api_name"] + used = edge_cnt.get(api, 0) + act = LINK_KEEP.get(api) + if act in ("keep", "enable", "fix"): + status, action = ("active", act) + note = {"keep": "有边使用,保留", + "enable": "当前 0 使用,但业务上需要,建议启用并灌数", + "fix": "source/target 指向已删除类型,修复端点后启用"}[act] + st, tt = l["source_type"], l["target_type"] + # 统一端点重定向(被合并/重建类型) + if api in LINK_RETARGET: + ns, nt = LINK_RETARGET[api] + if ns: + st = ns + if nt: + tt = nt + else: + status, action = "deprecated", "deprecate" + st, tt = l["source_type"], l["target_type"] + note = LINK_DEPRECATE_NOTE.get(api, "审计:0 使用且无启用计划") + if act == "fix": + note += f"(原定义 {l['source_type']}→{l['target_type']})" + lid += 1 + c.execute("""INSERT INTO link_types + (id,api_name,display_name,source_type,target_type,cardinality,status,action,usage_count,note,prev_usage) + VALUES(?,?,?,?,?,?,?,?,?,?,?)""", + (lid, api, l.get("display_name", ""), st, tt, l.get("cardinality", ""), + status, action, used, note, used)) + existing_link_apis = {l["api_name"] for l in links} + for (api, disp, s, t, card, note) in LINK_NEW: + used = edge_cnt.get(api, 0) + if api in existing_link_apis: + # 已有定义(多为指向已删类型的悬空边)→ 原地修复并置为 active + c.execute("""UPDATE link_types SET display_name=?, source_type=?, target_type=?, + cardinality=?, status='active', action='restore', note=? + WHERE api_name=?""", (disp, s, t, card, note, api)) + else: + lid += 1 + c.execute("""INSERT INTO link_types + (id,api_name,display_name,source_type,target_type,cardinality,status,action,usage_count,note,prev_usage) + VALUES(?,?,?,?,?,?,?,?,?,?,?)""", + (lid, api, disp, s, t, card, "active", "new", used, note, used)) + + # ---- cleanup_instances ---- + cid = 0 + for n in nodes: + lb = (n.get("label") or "").strip() + hit = None + if (n["type"], n["pk"]) in NOISE_WHITELIST: + continue + for pat, reason in NOISE_PATTERNS: + if pat in lb: + hit = (reason, "noise") + break + for (tp, pk, lab, reason) in NOISE_EXACT: + if n["type"] == tp and n["pk"] == pk: + hit = (reason, "test" if "测试" in reason else "noise") + if not hit: + for (tp, pk, lab, reason) in CONCEPT_AMBIGUOUS: + if n["type"] == tp and n["pk"] == pk: + hit = (reason, "concept") + if hit: + cid += 1 + c.execute("INSERT INTO cleanup_instances(type,pk,label,reason,category) VALUES(?,?,?,?,?)", + (n["type"], n["pk"], lb, hit[0], hit[1])) + + # ---- enum_candidates(从实例实际取值统计 top20)---- + vals = collections.defaultdict(collections.Counter) + for n in nodes: + for k, v in (n.get("props") or {}).items(): + if isinstance(v, str) and 0 < len(v) <= 30: + vals[(n["type"], k)][v] += 1 + eid = 0 + for (t, k), counter in vals.items(): + if counter.most_common(1)[0][1] < 2: + continue + if len(counter) > 30: # 高基数,非枚举 + continue + for v, f in counter.most_common(20): + eid += 1 + c.execute("INSERT INTO enum_candidates(type_api_name,prop_api_name,value,freq) VALUES(?,?,?,?)", (t, k, v, f)) + + # ---- open_decisions ---- + for (topic, cur, opts, rec, impact, rel) in [ + ("AIProduct 产品线是否入本体", "AIProduct/AIPlatformComponent 均 0 实例,配套 3 条边 0 使用", + "A 保留并灌数 | B 整族废弃,宁檬 AI 产品用 DataProduct/MemberOrg 表达", "B", + "低(无实例)", "AIProduct, AIPlatformComponent, AIProductContainsComponent, MemberOrgOperatesProduct"), + ("DigitalContract 生态重建范围", "类型已删,21 条边悬空", "A 精简版(合约+任务+账单)| B 完整版(+合约策略/签署主体/日志)| C 全部清理", + "A", "中(需新建 3 类 + 恢复 6 边)", "DigitalContract, DeliveryTask, MeteringBill, Contract*"), + ("ComplianceStandard 拆分口径", "261 实例混装标准与政策", "A 按 standard_type 拆 | B 现状不变仅更名", "A", + "中(261 实例需判定)", "ComplianceStandard, Standard, PolicyDocument"), + ("NewsArticle 是否留在本体", "405 实例,content 存原始 HTML", "A 保留并清洗 HTML | B 移出本体仅留 KM", "A", + "中(405 实例)", "NewsArticle"), + ("硬件设备建模口径", "同一张卡被建成 Appliance 实例 + DataSecurityCard + TrustedCryptographyCard", + "A 类型收敛(卡/网关独立类型,Appliance 只管一体机)| B 全部并入 Appliance 用 category 区分", "A", + "中(15+3 实例需迁移)", "Appliance, TrustedCryptographyCard, DataSecurityCard, DataAccessConnector"), + ]: + c.execute("INSERT INTO open_decisions(topic,current,options,recommendation,impact,related) VALUES(?,?,?,?,?,?)", + (topic, cur, opts, rec, impact, rel)) + + # ---- 视图 ---- + c.executescript(""" + CREATE VIEW v_type_summary AS + SELECT group_name, status, count(*) AS types, sum(instance_count) AS instances + FROM object_types GROUP BY group_name, status ORDER BY group_name; + CREATE VIEW v_link_summary AS + SELECT status, action, count(*) AS links, sum(prev_usage) AS current_edges + FROM link_types GROUP BY status, action ORDER BY status; + CREATE VIEW v_cleanup_summary AS + SELECT type, category, count(*) AS n FROM cleanup_instances GROUP BY type, category ORDER BY n DESC; + CREATE VIEW v_pending_actions AS + SELECT 'type' AS kind, api_name AS name, action, rationale AS note FROM object_types WHERE action IN ('merge','create','enable','refactor','deprecate','pending') + UNION ALL + SELECT 'link', api_name, action, note FROM link_types WHERE action IN ('new','restore','fix','enable'); + """) + con.commit() + + # ---- 自检 ---- + print("=" * 66) + print(f"SQLite: {db_path}") + for row in c.execute("SELECT value FROM meta WHERE key IN ('prod_object_types','prod_instances','prod_link_types','prod_edges')"): + pass + print("-- 对象类型 --") + for r in c.execute("SELECT group_name, status, types, instances FROM v_type_summary"): + print(f" {r[0] or '(未分组)':10s} {r[1]:16s} 类型={r[2]:3d} 实例={r[3]}") + print("-- 链接类型 --") + for r in c.execute("SELECT status, action, links, current_edges FROM v_link_summary"): + print(f" {r[0]:10s} {r[1]:10s} 边类型={r[2]:3d} 现有边={r[3]}") + print("-- 待清理实例 --") + for r in c.execute("SELECT type, category, n FROM v_cleanup_summary"): + print(f" {r[0]:22s} {r[1]:8s} {r[2]}") + tot = c.execute("SELECT count(*) FROM object_types WHERE status='active'").fetchone()[0] + dep = c.execute("SELECT count(*) FROM object_types WHERE status='deprecated'").fetchone()[0] + lk = c.execute("SELECT count(*) FROM link_types WHERE status='active'").fetchone()[0] + ld = c.execute("SELECT count(*) FROM link_types WHERE status='deprecated'").fetchone()[0] + props = c.execute("SELECT count(*) FROM properties").fetchone()[0] + print(f"\n合计: 活跃类型 {tot} / 废弃 {dep} / 待定 2 ; 活跃边 {lk} / 废弃 {ld} ; 属性定义 {props}") + # display_name 唯一性校验 + dup = c.execute("""SELECT display_name, count(*) c FROM object_types WHERE status='active' + GROUP BY display_name HAVING c>1""").fetchall() + print("display_name 冲突(活跃类型):", dup or "无") + # 悬空边校验 + names = {r[0] for r in c.execute("SELECT api_name FROM object_types WHERE status IN ('active','pending_decision')")} + dangling = c.execute("SELECT api_name, source_type, target_type FROM link_types WHERE status='active'").fetchall() + bad = [d for d in dangling if d[1] not in names or d[2] not in names] + print("活跃边指向不存在类型:", bad or "无") + con.close() + + +if __name__ == "__main__": + ap = argparse.ArgumentParser() + ap.add_argument("--db", default=DEFAULT_DB) + ap.add_argument("--fetch", action="store_true", help="重新只读拉取生产快照") + a = ap.parse_args() + build(a.db, a.fetch) diff --git a/scripts/cleanup_dangling_linktypes.py b/scripts/cleanup_dangling_linktypes.py new file mode 100644 index 0000000..43311ed --- /dev/null +++ b/scripts/cleanup_dangling_linktypes.py @@ -0,0 +1,68 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +清理 11 个历史遗留悬空 link_type 定义(指向从未进入类型清单的「幽灵类型」)。 + +安全依据: + - 悬空 link_type 的 source_type/target_type 指向不存在的 object-type + (BillingRecord/UsageLog/ContractPolicy/LogicalSpace/AccessEntity/ + ManagementEntity/ServiceNode/FunctionalNode/IndustryMasterData/ + IndustryKnowledgeHub/SemanticModel),故不可能存在引用它们的 link 实例。 + - 运行期兜底:GET /graph(manager 可见全部边)校核这些 link_type 名未出现在任何边。 + - deleteLinkType 执行前有 schemaAudit(before 快照),可审计/可恢复。 + +删除端点:DELETE /ontology/link-types/:name +""" +import sys, json, argparse +sys.path.insert(0, "scripts") +import raise_employee_clearance as r + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--dry-run", action="store_true", help="只盘点不删除") + args = ap.parse_args() + + code, ltd = r.api("GET", "/ontology/link-types") + lts = ltd if isinstance(ltd, list) else ltd.get("link_types", ltd) + _, ty = r.api("GET", "/ontology/object-types") + ts = ty if isinstance(ty, list) else ty.get("object_types", ty) + types = {t["api_name"] for t in ts} + + dangling = [(l["api_name"], l["source_type"], l["target_type"]) + for l in lts + if l["source_type"] not in types or l["target_type"] not in types] + print(f"当前类型 {len(types)} 个,link_types {len(lts)} 个") + print(f"悬空 link_type(端点指向不存在类型): {len(dangling)} 个") + + # 运行期兜底:确认当前图谱里没有这些 link_type 的边(manager 可见全部) + print("== 运行期校验:GET /graph 校核无 link 实例引用 ==") + gc, gd = r.api("GET", "/graph") + edge_types = set() + if gc == 200 and isinstance(gd, dict): + for e in gd.get("edges", []): + edge_types.add(e.get("type")) + used = [n for n, _, _ in dangling if n in edge_types] + if used: + print(" ✗ 发现这些悬空 link_type 仍有 link 实例引用,中止:", used) + sys.exit(1) + print(" ✅ 无 link 实例引用这些悬空 link_type(图谱边类型不含其名)") + + for n, s, t in dangling: + print(f" - {n}: {s} -> {t}") + if args.dry_run: + continue + dc, _ = r.api("DELETE", f"/ontology/link-types/{n}") + print(f" DELETE -> HTTP {dc}") + + if args.dry_run: + print(f"\n[DRY-RUN] 未删除。去掉 --dry-run 执行(共 {len(dangling)} 个)。") + else: + # 复核 + code2, ltd2 = r.api("GET", "/ontology/link-types") + lts2 = ltd2 if isinstance(ltd2, list) else ltd2.get("link_types", ltd2) + remain = [l["api_name"] for l in lts2 + if l["source_type"] not in types or l["target_type"] not in types] + print(f"\n删除后剩余悬空 link_type: {remain or '无 ✅'}(link_types 总数 {len(lts2)})") + +if __name__ == "__main__": + main() diff --git a/scripts/compare_versions.py b/scripts/compare_versions.py new file mode 100644 index 0000000..23faaea --- /dev/null +++ b/scripts/compare_versions.py @@ -0,0 +1,116 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +对比两个版本(导入前 vs 导入后)的数据与表现。 +- 导入前:backups_1 快照(X-Snapshot-Id:1),v1.5.1 部署后、v2 蓝图落地前的全库态 +- 导入后:当前生产(/api/v1/... manager 主体) +维度:object-types / link-types / 实例分布 / 数据分级 / principals / 版本与可用端点 +""" +import json +import scripts.import_ontology_v2 as m # 复用其清代理 env 的 api() + + +def get_types(kind, snap=False): + headers = {"X-Snapshot-Id": "1"} if snap else None + code, resp = m.api("GET", f"/ontology/{kind}", headers=headers) + assert code == 200, f"{kind} {code}: {resp}" + return resp if isinstance(resp, list) else [] + + +def get(path, snap=False): + headers = {"X-Snapshot-Id": "1"} if snap else None + code, resp = m.api("GET", path, headers=headers) + return code, resp + + +def main(): + print("=" * 70) + print("版本对比:导入前(backups_1 快照) vs 导入后(当前生产)") + print("=" * 70) + + # ---- 0. 版本与可用端点 ---- + c_v, v = get("/version") + print(f"\n[0] 服务端版本 (导入后): {v.get('version')} / commit {v.get('commit')} / {v.get('build_time')}") + + # ---- 1. object-types ---- + cur_ot = {t["api_name"]: t for t in get_types("object-types", snap=False)} + snap_ot = {t["api_name"]: t for t in get_types("object-types", snap=True)} + cur_names, snap_names = set(cur_ot), set(snap_ot) + added = sorted(cur_names - snap_names) + removed = sorted(snap_names - cur_names) + kept = sorted(cur_names & snap_names) + print(f"\n[1] OBJECT-TYPES 导入前={len(snap_ot)} 导入后={len(cur_ot)}") + print(f" 新增({len(added)}): {added}") + print(f" 移除({len(removed)}): {removed}") + print(f" 保留({len(kept)})") + + # ---- 2. link-types ---- + cur_lt = {l["api_name"]: l for l in get_types("link-types", snap=False)} + snap_lt = {l["api_name"]: l for l in get_types("link-types", snap=True)} + cur_ln, snap_ln = set(cur_lt), set(snap_lt) + added_l = sorted(cur_ln - snap_ln) + removed_l = sorted(snap_ln - cur_ln) + retargeted = [n for n in (cur_ln & snap_ln) + if (cur_lt[n].get("source_type"), cur_lt[n].get("target_type")) + != (snap_lt[n].get("source_type"), snap_lt[n].get("target_type"))] + print(f"\n[2] LINK-TYPES 导入前={len(snap_lt)} 导入后={len(cur_lt)}") + print(f" 新增({len(added_l)}): {added_l}") + print(f" 移除({len(removed_l)}): {removed_l}") + print(f" 同名但端点改写({len(retargeted)}): {retargeted}") + for n in retargeted: + print(f" {n}: {snap_lt[n].get('source_type')}->{snap_lt[n].get('target_type')}" + f" => {cur_lt[n].get('source_type')}->{cur_lt[n].get('target_type')}") + + # ---- 3. 实例分布与总量 ---- + def inst_total(tbl): + return sum(int(t.get("instance_count", 0) or 0) for t in tbl.values()) + print(f"\n[3] 实例总量(按 object-types.instance_count 求和)") + print(f" 导入前={inst_total(snap_ot)} 导入后={inst_total(cur_ot)}") + + # ComplianceStandard 拆分专项 + c_c, r_c = get("/objects?type=ComplianceStandard&limit=1") + c_s, r_s = get("/objects?type=Standard&limit=1") + c_p, r_p = get("/objects?type=PolicyDocument&limit=1") + cs_now = r_c.get("total") if isinstance(r_c, dict) else "?" + st_now = r_s.get("total") if isinstance(r_s, dict) else "?" + pd_now = r_p.get("total") if isinstance(r_p, dict) else "?" + print(f" ComplianceStandard: 原261(全墓碑) -> 现{cs_now}(类型已删)") + print(f" Standard: 现{st_now} (原10 + 合并10 + 新建38)") + print(f" PolicyDocument: 现{pd_now} (新建223)") + + # ---- 4. 数据分级 L0-L4 表现 ---- + c_cf, cfg = get("/ontology/classification/config") + levels = set() + n_types = 0 + items = cfg.get("items", []) if isinstance(cfg, dict) else (cfg if isinstance(cfg, list) else []) + for it in items: + n_types += 1 + for lv in (it.get("classification_levels") or []): + levels.add(lv) + print(f"\n[4] 数据分级 L0-L4 配置覆盖类型数={n_types} 实际出现的层级={sorted(levels)}") + print(f" 统一词汇={ 'OK' if levels == {'L0','L1','L2','L3','L4'} else '不一致' }") + + # ---- 5. principals 用户 ---- + c_p, pr = get("/access/principals") + prs = pr.get("principals", []) if isinstance(pr, dict) else [] + names = [p.get("name") for p in prs] + print(f"\n[5] principals(用户主体) 总数={len(names)}") + print(f" 含 manager={ 'manager' in names } 含 rong={ 'rong' in names }") + # 角色分布 + from collections import Counter + roles = Counter() + for p in prs: + r = p.get("roles") or p.get("role") + if isinstance(r, list): + for x in r: + roles[x] += 1 + elif r: + roles[r] += 1 + print(f" 角色分布(前8): {roles.most_common(8)}") + + print("\n" + "=" * 70) + print("对比完成。") + + +if __name__ == "__main__": + main() diff --git a/scripts/consolidate_placeholder_types.py b/scripts/consolidate_placeholder_types.py new file mode 100644 index 0000000..f0ceab7 --- /dev/null +++ b/scripts/consolidate_placeholder_types.py @@ -0,0 +1,145 @@ +#!/usr/bin/env python3 +""" +合并 5 个零实例占位类型(P2-⑥ 用户确认「去合并吧」,2026-10-13)。 + +全部用官方 merge-execute:自动迁移实例(0) + 改写 links/link_types 引用 + 合并属性 + 删源类型。 +合并目标(语义最贴,保留 link 关系): + - AIProduct -> DataProduct (用户指定:并入 DataProduct+AI 扩展属性) + - AIPlatformComponent -> DataResource (平台组件≈数据/软件资源; + AIProductContainsComponent => DataProduct→DataResource) + - VerificationItem -> TrustCredential (TrustCredential 包含 VerificationItem) + - DataRightsConfirmation -> TrustCredential (用户注「可由 Grant/Marking 表达」;并入凭证类) + - DataPropertyRegistration -> DataResource (数据要素登记≈资源) + +link_type 结局(merge 自动改写,无悬空): + - AIProductDeliveredViaAppliance -> DataProduct→Appliance + - MemberOrgOperatesProduct -> MemberOrg→DataProduct + - AIProductContainsComponent -> DataProduct→DataResource + - TrustCredentialIncludesItem -> TrustCredential→TrustCredential(自环,保留) + - VerificationItemBackedByResource-> TrustCredential→DataResource + +复用 raise_employee_clearance 的 KEY/BASE/_clean_env(curl 子进程直连,清代理变量)。 + +用法: + python3 scripts/consolidate_placeholder_types.py --dry-run + python3 scripts/consolidate_placeholder_types.py +""" +import argparse, json, subprocess, sys, os + +KEY = "0e926a78570d51a6949c65ffec2b7be6aa43ff2b678019c75cc0d65005affe05" +BASE = "http://r.mayishangshu.cn:18081/api/v1" + +# (source, target) +MERGES = [ + ("AIProduct", "DataProduct"), + ("AIPlatformComponent", "DataResource"), + ("VerificationItem", "TrustCredential"), + ("DataRightsConfirmation", "TrustCredential"), + ("DataPropertyRegistration", "DataResource"), +] + + +def _clean_env(): + env = dict(os.environ) + for k in ("HTTP_PROXY", "HTTPS_PROXY", "https_proxy", "http_proxy", + "ALL_PROXY", "all_proxy", "NO_PROXY", "no_proxy"): + env.pop(k, None) + return env + + +def api(method, path, body=None): + url = f"{BASE}{path}" + cmd = ["curl", "-s", "--noproxy", "*", "-m", "120", "-X", method, url, + "-H", f"X-API-Key: {KEY}", "-H", "Content-Type: application/json", + "-w", "\n__STATUS__%{http_code}"] + if body is not None: + cmd += ["-d", json.dumps(body, ensure_ascii=False)] + out = subprocess.run(cmd, capture_output=True, text=True, timeout=140, env=_clean_env()) + raw = out.stdout + if "\n__STATUS__" in raw: + txt, _, code_s = raw.rpartition("\n__STATUS__") + code = int(code_s.strip() or -1) + else: + txt, code = raw, -1 + try: + data = json.loads(txt) if txt.strip() else None + except Exception: + data = txt + return code, data + + +def list_types(): + code, data = api("GET", "/ontology/object-types") + assert code == 200, f"list types {code}" + return data if isinstance(data, list) else data.get("object_types", data) + + +def list_linktypes(): + code, data = api("GET", "/ontology/link-types") + assert code == 200, f"list linktypes {code}" + return data if isinstance(data, list) else data.get("link_types", data) + + +def count_objects(t): + code, data = api("GET", f"/objects?type={t}&limit=1") + if code != 200 or not isinstance(data, dict): + return -1 + return data.get("total", len(data.get("items", []))) + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--dry-run", action="store_true") + args = ap.parse_args() + + types = {t["api_name"] for t in list_types()} + lts = list_linktypes() + + # 前置校验 + for s, t in MERGES: + assert s in types, f"源类型不存在: {s}" + assert t in types, f"目标类型不存在: {t}" + + # 实例计数(响应 items/total;merge 会迁移,这里仅报告) + print("== 实例计数(merge 会迁移,0 即无数据风险)==") + for s, t in MERGES: + print(f" {s}: total={count_objects(s)} -> {t}") + + # 预演 + print("\n== merge-preview ==") + for s, t in MERGES: + code, prev = api("POST", "/ontology/types/merge-preview", + {"sources": [s], "target": t}) + print(f" {s}->{t}: {code} {prev}") + assert code == 200, f"preview {s} 失败" + + if args.dry_run: + print("\n[dry-run] 校验通过,未执行任何写操作。") + return + + # 执行合并 + print("\n== merge-execute ==") + for s, t in MERGES: + code, resp = api("POST", "/ontology/types/merge-execute", + {"sources": [s], "target": t}) + print(f" {s}->{t}: {code} {resp}") + assert code == 200, f"merge {s} 失败: {resp}" + + # 校验 + print("\n== 校验 ==") + after_types = {t["api_name"] for t in list_types()} + after_lts = list_linktypes() + src_set = {s for s, _ in MERGES} + gone = [x for x in src_set if x in after_types] + dangling = [l["api_name"] for l in after_lts + if l["source_type"] not in after_types or l["target_type"] not in after_types] + print(f" 类型总数: {len(after_types)} (原 47,应 42)") + print(f" 仍残留的源类型: {gone or '无'}") + print(f" 悬空 link_type (端点类型不存在): {dangling or '无'}") + assert not gone, f"有类型未合并成功: {gone}" + assert not dangling, f"存在悬空 link_type: {dangling}" + print("\n✅ 5 个占位类型合并完成,无悬空引用。") + + +if __name__ == "__main__": + main() diff --git a/scripts/fix_clearance_and_classification.py b/scripts/fix_clearance_and_classification.py new file mode 100644 index 0000000..6adc025 --- /dev/null +++ b/scripts/fix_clearance_and_classification.py @@ -0,0 +1,147 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +按规划修正本体分级与主体 clearance(2026-10-13 续): + 规划:L0 公众 / L1 客户 / L2 员工 / L3 经理以上 / L4 公司管理层 + +问题:上一轮误把 75 名员工 clearance 提到 L0-L3,且把本该员工可见的数据定在 L3, + 导致"员工该看到的很多数据反而靠提权才看得到"。正确做法: + ① 员工 clearance 回落 L0-L2; + ② 把本该员工可见的数据类型默认级从 L3 降到 L2; + ③ UsageControlPolicy 等经理级数据保持 L3(员工不可见,正确); + ④ 仅「国家秘密」等真正涉密实例保留 L4 覆盖层。 + +幂等、可复跑;默认 dry-run 仅预览,--apply 才落库。 +""" +import sys, json, argparse +sys.path.insert(0, 'scripts') +import raise_employee_clearance as r + +BUILTIN = {'public', 'analyst', 'connector', 'TradingAssistant', 'manager', 'ingest'} +EMP_LEVELS = ['L0', 'L1', 'L2'] +LEVELS = ['L0', 'L1', 'L2', 'L3', 'L4'] + +# 类型默认级重分类: +# L3 -> L2(员工可见的内部/运营/政策类,有实例的才是"员工访问不了"的根因) +TO_L2 = ['PolicyDocument', 'SecurityRequirement', 'SpaceManager', + 'TrustedCryptographyCard', 'TrustCredential', 'TDSInterconnection', + 'UsageAction', 'UsageConstraint'] +# 保持 L3(经理以上,含 UsageControlPolicy 36 实例 + 两个 0 实例契约/计费类) +KEEP_L3 = ['DigitalContract', 'MeteringBill', 'UsageControlPolicy'] + +# 实例覆盖层修正:UsageControlPolicy 是否从 L4 回落 L3 交由用户确认(默认保留 L4, +# 它属「公司管理层」治理范畴,且不影响员工可见性;员工本就不该看访问控制策略)。 +# PolicyDocument 的 cs_20260918_124(国家秘密)保持 L4 不动。 +REVERT_UCP_L4 = False + + +def ensure_classification_property(name): + # 补建 classification 属性(幂等 ON CONFLICT),否则 setObjectTypeClassification 校验会拒 + body = { + 'api_name': 'classification', + 'display_name': '数据分级', + 'data_type': 'string', + 'enum_values': LEVELS, + 'description': '数据分级 L0公众/L1客户/L2员工/L3经理以上/L4公司管理层', + 'indexable': False, + } + return r.api('POST', f'/ontology/object-types/{name}/properties', body) + + +def set_type_default(name, default): + # 先确保 classification 属性存在(校验依赖它) + ensure_classification_property(name) + body = {'classification_property': 'classification', + 'classification_levels': LEVELS, + 'classification_default': default} + return r.api('PUT', f'/ontology/object-types/{name}/classification', body) + + +def get_clearance(name): + code, data = r.api('GET', f'/access/principals/{name}/clearances') + if isinstance(data, dict): + return data.get('markings') or data.get('clearances') + return data + + +def set_clearance(name, levels): + # 关键:端点只认 markings 字段(handlers_access.go:318),传 clearances 会被清空 + return r.api('PUT', f'/access/principals/{name}/clearances', {'markings': levels}) + + +def get_markings(typ, pk): + code, data = r.api('GET', f'/access/objects/{typ}/{pk}/markings') + if isinstance(data, dict): + return data.get('markings') or [] + return [] + + +def set_markings(typ, pk, levels): + return r.api('PUT', f'/access/objects/{typ}/{pk}/markings', {'markings': levels}) + + +def list_instances(typ, limit=2000): + code, data = r.api('GET', f'/objects?type={typ}&limit={limit}') + if isinstance(data, dict): + return data.get('items', data.get('objects', [])) + return data or [] + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument('--apply', action='store_true', help='落库(默认 dry-run)') + args = ap.parse_args() + A = args.apply + print(f'== 模式: {"APPLY" if A else "DRY-RUN"} ==') + + # ---- Phase 1: 员工 clearance 回落 L0-L2 ---- + print('\n[Phase 1] 员工 clearance -> L0-L2') + code, pdata = r.api('GET', '/access/principals') + ps = pdata if isinstance(pdata, list) else pdata.get('principals', pdata) + emp = [p['name'] for p in ps if p['name'] not in BUILTIN] + print(f' 员工主体数: {len(emp)}') + for n in emp: + cur = get_clearance(n) + if cur == EMP_LEVELS: + continue + print(f' {n}: {cur} -> {EMP_LEVELS}') + if A: + set_clearance(n, EMP_LEVELS) + + # ---- Phase 2: 类型默认级重分类 ---- + print('\n[Phase 2] 类型默认级 L3->L2(员工可见类)') + for n in TO_L2: + print(f' {n}: default L3 -> L2') + if A: + set_type_default(n, 'L2') + for n in KEEP_L3: + print(f' {n}: 保持 L3(经理以上)') + + # ---- Phase 3: recompute(仅写 classification 列,不碰 object_markings)---- + if A: + print('\n[Phase 3] recompute classification(apply=true)') + code, data = r.api('POST', '/ontology/classification/recompute', + {'apply': True, 'dry_run': False, 'limit': 20000}) + print(' ', json.dumps(data, ensure_ascii=False)[:400]) + else: + print('\n[Phase 3] recompute 将在 --apply 时执行(materialize 类型默认级)') + + # ---- Phase 4: 实例覆盖层修正 ---- + print('\n[Phase 4] 实例覆盖层') + if REVERT_UCP_L4: + ucp = list_instances('UsageControlPolicy', 200) + print(f' UsageControlPolicy 实例 {len(ucp)} 条:回落被误标的 L4 -> (移除覆盖, 落类型默认 L3)') + for o in ucp: + pk = o.get('pk') + cur = get_markings('UsageControlPolicy', pk) + if cur == ['L4']: + print(f' {pk}: L4 -> [] (回落 L3)') + if A: + set_markings('UsageControlPolicy', pk, []) + print(' PolicyDocument.cs_20260918_124(国家秘密)保持 L4 覆盖层(不动)') + + print('\n== 完成 ==') + + +if __name__ == '__main__': + main() diff --git a/scripts/import_ontology_v2.py b/scripts/import_ontology_v2.py new file mode 100644 index 0000000..8266aff --- /dev/null +++ b/scripts/import_ontology_v2.py @@ -0,0 +1,335 @@ +#!/usr/bin/env python3 +""" +本体 v2 蓝图导入生产(manager 主体,REST 直写)。 + +阶段: + P1 新建 schema:3 新类型+属性、补属性、20 条链接、删 1 属性 (0 实例/无迁移) + P2 类型合并 merge-execute(事务) + P3 删除零实例废弃类型 + P4 ComplianceStandard 261 拆分(按 standard_type) + P5 三项校验:分级 L0-L4 / 用户信息 / 与 backups_1 一致 + +用法: + python3 scripts/import_ontology_v2.py --phase 1 # 执行某阶段 + python3 scripts/import_ontology_v2.py --phase 1 --dry-run # 只打印计划 + python3 scripts/import_ontology_v2.py --phase all # 1..5 顺序执行 +""" +import argparse, json, sqlite3, sys, urllib.request, urllib.error + +KEY = "0e926a78570d51a6949c65ffec2b7be6aa43ff2b678019c75cc0d65005affe05" +BASE = "http://r.mayishangshu.cn:18081/api/v1" +DB = "ontology-v2.db" + +NEW_TYPE_DESC = { + "DigitalContract": "GB/T 48000.3 核心闭环载体:数字合约,串联交付任务、计量账单与控制策略。", + "UsageAction": "GB/T 使用控制策略五元组之一:操作行为。", + "UsageConstraint": "GB/T 使用控制策略五元组之一:约束条件(次数/期限/地域/用途/环境/销毁)。", +} + + +def _clean_env(): + # Bash 沙箱会注入 HTTP_PROXY/HTTPS_PROXY/http_proxy/https_proxy, + # 代理中间件会剥掉自定义 X-API-Key 头导致 401。这里去掉代理变量,直连生产。 + import os + env = dict(os.environ) + for k in ("HTTP_PROXY", "HTTPS_PROXY", "https_proxy", + "http_proxy", "ALL_PROXY", "all_proxy", "NO_PROXY", "no_proxy"): + env.pop(k, None) + return env + + +def api(method, path, body=None, headers=None): + # 用 curl 子进程:urllib 跟随重定向会丢弃自定义 X-API-Key 头导致 401,curl 会保留。 + import subprocess + url = f"{BASE}{path}" + cmd = ["curl", "-s", "--noproxy", "*", "-m", "120", "-X", method, url, + "-H", f"X-API-Key: {KEY}", "-H", "Content-Type: application/json", + "-w", "\n__STATUS__%{http_code}"] + for h, v in (headers or {}).items(): + cmd += ["-H", f"{h}: {v}"] + if body is not None: + cmd += ["-d", json.dumps(body, ensure_ascii=False)] + try: + out = subprocess.run(cmd, capture_output=True, text=True, timeout=140, env=_clean_env()) + raw = out.stdout + if "\n__STATUS__" in raw: + body_txt, _, code_s = raw.rpartition("\n__STATUS__") + code = int(code_s.strip() or -1) + else: + body_txt, code = raw, -1 + return code, _parse(body_txt) + except Exception as e: + return -1, str(e) + + +def _parse(txt): + try: + return json.loads(txt) + except Exception: + return txt + + +def db(): + return sqlite3.connect(DB) + + +def parse_enum(v): + if not v: + return [] + return [x for x in v.split("|") if x.strip()] + + +def p1(dry): + con = db(); c = con.cursor(); c2 = con.cursor() + log = [] + + # ---- 1a) 新建 3 类型(含内联属性)---- + create_types = [r[0] for r in c.execute("SELECT api_name FROM object_types WHERE action='create'")] + for api_name in create_types: + ot = c.execute("SELECT display_name,description,group_name FROM object_types WHERE api_name=?", (api_name,)).fetchone() + disp, desc, grp = ot + desc = desc or NEW_TYPE_DESC.get(api_name, "") + props = [] + for p in c2.execute("SELECT api_name,display_name,data_type,required,enum_values FROM properties WHERE type_api_name=? AND action='new'", (api_name,)): + enum = parse_enum(p[4]) + props.append({"api_name": p[0], "display_name": p[1], "data_type": p[2], + "required": bool(p[3]), "enum_values": enum}) + body = {"api_name": api_name, "display_name": disp, "description": desc, + "group": grp or "未分类", "properties": props} + log.append(("POST", "/ontology/object-types", body)) + if not dry: + code, resp = api("POST", "/ontology/object-types", body) + print(f" create type {api_name}: {code} {resp if code>=400 else 'ok'}") + + # ---- 1b) 给已存在类型补 new 属性(DeliveryTask/MeteringBill/ApplianceSKU)---- + for api_name in list(c.execute("SELECT DISTINCT type_api_name FROM properties WHERE action='new' AND type_api_name NOT IN (SELECT api_name FROM object_types WHERE action='create')")): + api_name = api_name[0] + for p in c2.execute("SELECT api_name,display_name,data_type,required,enum_values FROM properties WHERE type_api_name=? AND action='new'", (api_name,)): + enum = parse_enum(p[4]) + body = {"api_name": p[0], "display_name": p[1], "data_type": p[2], "required": bool(p[3]), "enum_values": enum} + log.append(("POST", f"/ontology/object-types/{api_name}/properties", body)) + if not dry: + code, resp = api("POST", f"/ontology/object-types/{api_name}/properties", body) + print(f" add prop {api_name}.{p[0]}: {code} {resp if code>=400 else 'ok'}") + + # ---- 1c) 新建/恢复/修复 链接类型(upsert)---- + for r in c.execute("SELECT api_name,display_name,source_type,target_type,cardinality FROM link_types WHERE action IN ('new','restore','fix')"): + body = {"api_name": r[0], "display_name": r[1], "source_type": r[2], "target_type": r[3], "cardinality": r[4] or "many_to_many"} + log.append(("POST", "/ontology/link-types", body)) + if not dry: + code, resp = api("POST", "/ontology/link-types", body) + print(f" link {r[0]} ({r[2]}->{r[3]}): {code} {resp if code>=400 else 'ok'}") + + # ---- 1d) 删除 AccessEntity.entity_name 属性 ---- + if not dry: + code, resp = api("GET", "/ontology/object-types/AccessEntity") + if code == 200: + for p in resp.get("object_type", {}).get("properties", []): + if p.get("api_name") == "entity_name": + dcode, dresp = api("DELETE", f"/ontology/properties/{p['id']}") + print(f" drop AccessEntity.entity_name (id={p['id']}): {dcode} {dresp if dcode>=400 else 'ok'}") + else: + log.append(("DELETE", "/properties/", None)) + + con.close() + if dry: + print(f"[dry-run] P1 计划 {len(log)} 个写调用:") + for m, p, b in log: + print(f" {m:5s} {p} {json.dumps(b, ensure_ascii=False)[:120] if b else ''}") + + +def p2(dry): + con = db(); c = con.cursor() + # merges 来自 v2.db object_types.merges 字段(逗号分隔多个源) + rows = c.execute("SELECT api_name,merges FROM object_types WHERE merges<>'' AND merges IS NOT NULL").fetchall() + for target, srcs in rows: + sources = [s.split("(")[0].strip() for s in srcs.split(",") if s.strip()] + if not sources: + continue + body = {"target": target, "sources": sources} + print(f"[P2] merge {sources} -> {target}") + if not dry: + code, resp = api("POST", "/ontology/types/merge-execute", body) + print(f" {code} {json.dumps(resp, ensure_ascii=False)[:300] if isinstance(resp,dict) else resp}") + con.close() + + +def p3(dry): + # 定向删除 v2.db 标记为 deprecate 且当前 0 实例的 7 个类型;其被引用的 3 条链接先删。 + drop_links = ["TaskProducesAudit", "BusinessLineOperatedBy", "ContentAssetPublishedOn"] + drop_types = ["DataAsset", "AuditLog", "BusinessLine", "ContentAsset", + "ContentChannel", "PromotionCampaign", "ShuXiaoGuEval"] + if dry: + print(f"[P3 dry-run] 将删 {len(drop_links)} 条链接 + {len(drop_types)} 个 deprecate 零实例类型") + return + for l in drop_links: + code, resp = api("DELETE", f"/ontology/link-types/{l}") + print(f" link {l}: {code} {'ok' if code < 400 else resp}") + for t in drop_types: + code, resp = api("DELETE", f"/ontology/object-types/{t}") + print(f" type {t}: {code} {'ok' if code < 400 else resp}") + + +POLICY_TYPES = {"政策文件", "法律法规", "政策法规", "行业监管"} +STANDARD_TYPES = {"技术文件", "国家标准"} + + +def classify_cs(inst): + """按 standard_type 归类;空值按 pk 语义兜底。返回 ('Standard'|'PolicyDocument', reason)。""" + st = (inst.get("properties", {}).get("standard_type") or "").strip() + if st in POLICY_TYPES: + return "PolicyDocument", f"standard_type={st}" + if st in STANDARD_TYPES: + return "Standard", f"standard_type={st}" + # 空值:按 pk 语义 + pk = inst.get("pk", "") + if pk.startswith("cs_tds_"): + return "Standard", "standard_type 空值,pk 属 TDS 技术/能力概念" + if pk.startswith("yubanfa"): + return "PolicyDocument", "standard_type 空值,pk 属政策办法文件" + return "Standard", "standard_type 空值,默认归入 Standard" + + +def _batch(path, items, stop_on_error=False): + body = {"items": items, "stop_on_error": stop_on_error} + code, resp = api("POST", path, body) + return code, resp + + +def p4(dry): + # 拉全部 ComplianceStandard 实例 + objs = [] + off = 0 + while True: + code, resp = api("GET", f"/objects?type=ComplianceStandard&limit=300&offset={off}") + if not isinstance(resp, dict): + print(f"[P4] 取数失败 {code} {resp}") + return + items = resp.get("items", []) + objs.extend(items) + if len(items) < 300: + break + off += 300 + print(f"[P4] 拉取 ComplianceStandard 实例 {len(objs)} 条") + + # 归类 + plan = [] # (inst, target) + none_log = [] + for o in objs: + tgt, reason = classify_cs(o) + plan.append((o, tgt)) + if "空值" in reason: + none_log.append((o.get("pk"), tgt, reason)) + from collections import Counter + cnt = Counter(t for _, t in plan) + print(f"[P4] 归类: Standard={cnt['Standard']} PolicyDocument={cnt['PolicyDocument']}") + for pk, tgt, reason in none_log: + print(f" 空值 pk={pk} -> {tgt} ({reason})") + + if dry: + print("[P4 dry-run] 以上为拆分计划,不写库") + return + + # 批量建目标类型实例(复制全部原字段,保留 standard_type 作溯源;豁免 enum/axiom) + created = {"Standard": 0, "PolicyDocument": 0} + failed = [] + for tgt in ("Standard", "PolicyDocument"): + batch_items = [] + for o, t in plan: + if t != tgt: + continue + props = dict(o.get("properties", {})) + # 溯源标记 + props.setdefault("migrated_from", "ComplianceStandard") + batch_items.append({ + "type": tgt, "pk": o.get("pk"), "properties": props, + "source": "v2_cs_split", "validate_enum": False, "validate_axioms": False, + }) + # 分块 200 + for i in range(0, len(batch_items), 200): + chunk = batch_items[i:i + 200] + code, resp = _batch("/objects/batch", chunk, stop_on_error=False) + if code == 200 and isinstance(resp, dict): + for r in resp.get("results", []): + if r.get("status") == "failed": + failed.append(r) + else: + created[tgt] += 1 + else: + print(f" [{tgt}] batch 失败 {code} {str(resp)[:200]}") + failed.extend([{"pk": it["pk"], "error": str(resp)[:120]} for it in chunk]) + print(f" [{tgt}] 已建 {created[tgt]} 条 (失败 {len([f for f in failed if f.get('type')==tgt])})") + + if failed: + print(f"[P4] 建实例失败 {len(failed)} 条: {failed[:10]}") + + # 校验:目标类型实例数 + for tgt in ("Standard", "PolicyDocument"): + code, resp = api("GET", f"/objects?type={tgt}&limit=1") + total = resp.get("total") if isinstance(resp, dict) else "?" + print(f" [{tgt}] 当前实例总数={total}") + + # 软删除原 ComplianceStandard 实例(可恢复,不硬删) + del_items = [{"type": "ComplianceStandard", "pk": o.get("pk"), + "properties": {}, "deleted": True, "source": "v2_cs_split"} for o, _ in plan] + d_failed = [] + for i in range(0, len(del_items), 200): + chunk = del_items[i:i + 200] + code, resp = _batch("/objects/batch", chunk, stop_on_error=False) + if code == 200 and isinstance(resp, dict): + for r in resp.get("results", []): + if r.get("status") == "failed": + d_failed.append(r) + else: + d_failed.extend([{"pk": it["pk"], "error": str(resp)[:120]} for it in chunk]) + print(f"[P4] 软删除原 ComplianceStandard 实例 {len(del_items)} 条 (失败 {len(d_failed)})") + if d_failed: + print(f" 删除失败样例: {d_failed[:5]}") + print("[P4] 完成。ComplianceStandard 类型保留为空壳(实例均为墓碑,可恢复);如需彻底移除类型请单独确认。") + + +def p5(dry): + # 1) 数据分级 L0-L4 + code, resp = api("GET", "/ontology/classification/config") + levels = set() + if isinstance(resp, dict): + for it in resp.get("items", []): + for lv in (it.get("classification_levels") or []): + levels.add(lv) + print(f"[P5-1 分级] status={code} 类型数={resp.get('count') if isinstance(resp,dict) else '?'} 分级词汇={sorted(levels)}") + ok1 = levels == {"L0", "L1", "L2", "L3", "L4"} + # 2) 用户信息(principals) —— 路由在 /access 组下 + code, resp = api("GET", "/access/principals") + names = [p.get("name") for p in (resp.get("principals", []) if isinstance(resp, dict) else [])] + print(f"[P5-2 用户] status={code} principals 数={len(names)} 含 manager={'manager' in names} 含 rong={'rong' in names}") + ok2 = "manager" in names and "rong" in names + # 3) 与 backups_1 快照对比(核心行为一致) + code, cur = api("GET", "/ontology/object-types") + cur_names = sorted(o["api_name"] for o in cur) if isinstance(cur, list) else [] + code_s, snap = api("GET", "/ontology/object-types", headers={"X-Snapshot-Id": "1"}) + snap_names = sorted(o["api_name"] for o in snap) if isinstance(snap, list) else [] + only_cur = [n for n in cur_names if n not in snap_names] + only_snap = [n for n in snap_names if n not in cur_names] + print(f"[P5-3 备份对比] 当前={len(cur_names)} 快照={len(snap_names)}") + print(f" 仅当前有(新建): {only_cur}") + print(f" 仅快照有(已移除): {only_snap}") + # 期望:新建=3(DigitalContract/UsageAction/UsageConstraint);移除=14(7合并源+7 deprecate删) + expected_new = {"DigitalContract", "UsageAction", "UsageConstraint"} + ok3 = set(only_cur) == expected_new and len(only_snap) == 14 + print(f"[P5 结论] 分级L0-L4={'OK' if ok1 else 'FAIL'} | principals={'OK' if ok2 else 'FAIL'} | 备份一致={'OK' if ok3 else 'CHECK'}") + + +if __name__ == "__main__": + ap = argparse.ArgumentParser() + ap.add_argument("--phase", default="1") + ap.add_argument("--dry-run", action="store_true") + a = ap.parse_args() + dry = a.dry_run + phases = {"1": p1, "2": p2, "3": p3, "4": p4, "5": p5} + if a.phase == "all": + for n in ["1", "2", "3", "4", "5"]: + print(f"\n===== Phase {n} =====") + phases[n](dry) + else: + print(f"\n===== Phase {a.phase} =====") + phases[a.phase](dry) diff --git a/scripts/ontology_snapshot.py b/scripts/ontology_snapshot.py new file mode 100644 index 0000000..2819f47 --- /dev/null +++ b/scripts/ontology_snapshot.py @@ -0,0 +1,113 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""从 MCP 拉取的本体数据提炼成子 agent / 审计友好的快照 JSON。 +合并来源:MCP get_object_types(类型+属性) + REST /ontology/classification/config(分级) + REST 实例数 + REST link-types。 +""" +import json +import os +import sys + +sys.path.insert(0, "/Users/xs/Desktop/workspace/ontology") +import scripts.import_ontology_v2 as m # 复用清代理 env 的 api() + +SRC = "/Users/xs/.workbuddy/projects/Users-xs-Desktop-workspace-ontology/eb60a04f-d93b-47ff-90cd-6a3803d86557/tool-results/mcp-shangshu-ontology-get_object_types-1791802900950-fbd57d.txt" +OUT = "/Users/xs/Desktop/workspace/ontology/docs/ontology_v2_snapshot.json" + +DELETED = { + "AccessStandard", "TechnicalStandard", "ControlPolicy", "DataConnector", + "DataSecurityCard", "HomomorphicComputePlatform", "DeliveryScenario", + "DataAsset", "AuditLog", "BusinessLine", "ContentAsset", "ContentChannel", + "PromotionCampaign", "ShuXiaoGuEval", "ComplianceStandard", +} + + +def main(): + data = json.loads(open(SRC).read()) + ots = data.get("object_types", []) + print(f"[1] object_types 数 = {len(ots)}") + + # 分级配置 + c, cls = m.api("GET", "/ontology/classification/config") + cls_items = cls.get("items", []) if isinstance(cls, dict) else (cls if isinstance(cls, list) else []) + cls_by = {it["api_name"]: it for it in cls_items} + print(f"[2] classification 配置数 = {len(cls_by)}") + + # 实例数(逐类型 limit=1 取 total) + inst = {} + for o in ots: + name = o["api_name"] + cc, r = m.api("GET", f"/objects?type={name}&limit=1") + inst[name] = r.get("total") if isinstance(r, dict) else None + print(f"[3] 实例数拉取完成") + + # link_types + lt_path = "/tmp/mcp_pull_linktypes.json" + lt = json.load(open(lt_path)) if os.path.exists(lt_path) else [] + print(f"[4] link_types 数 = {len(lt)}") + + snap = [] + for o in ots: + name = o["api_name"] + ci = cls_by.get(name, {}) + snap.append({ + "api_name": name, + "display_name": o.get("display_name"), + "description": o.get("description"), + "iri": o.get("iri"), + "instance_count": inst.get(name), + "classification": { + "enabled": ci.get("enabled"), + "property": ci.get("classification_property"), + "levels": ci.get("classification_levels"), + "default": ci.get("classification_default"), + "distribution": ci.get("distribution"), + }, + "properties": [ + { + "api_name": p.get("api_name"), + "display_name": p.get("display_name"), + "data_type": p.get("data_type"), + "required": p.get("required"), + "description": p.get("description"), + } + for p in o.get("properties", []) + ], + }) + + out = { + "generated_from": "MCP get_object_types + REST /ontology/classification/config + 实例数 + REST link-types", + "object_types": snap, + "link_types": lt, + } + json.dump(out, open(OUT, "w"), ensure_ascii=False, indent=1) + print(f"[OK] 快照已写 {OUT} ({len(snap)} 类型 / {len(lt)} 链接)") + + # ---- 审计预检 ---- + print("\n===== 审计预检 =====") + hits = [(l.get("api_name"), l.get("source_type"), l.get("target_type")) + for l in lt if l.get("source_type") in DELETED or l.get("target_type") in DELETED] + print(f"[A] link_types 仍引用已删类型: {len(hits)}") + for h in hits: + print(" ", h) + + print("[B] P1 新建类型分级状态:") + for s in snap: + if s["api_name"] in ("DigitalContract", "UsageAction", "UsageConstraint"): + print(f" {s['api_name']}: enabled={s['classification']['enabled']} default={s['classification']['default']} levels={s['classification']['levels']}") + + print("[C] 实例级分级是否全为类型 default(细粒度分级是否落地):") + nondefault = [(s["api_name"], s["classification"]["distribution"]) + for s in snap + if s["classification"]["distribution"] and s["classification"]["default"] is not None + and any(k != s["classification"]["default"] for k in s["classification"]["distribution"])] + print(f" 非默认分布的类型数 = {len(nondefault)} (0 表示实例级细粒度分级未落地)") + for x in nondefault[:10]: + print(" ", x) + + print("[D] 零实例类型(需判断是否应保留):") + zero = [s["api_name"] for s in snap if s["instance_count"] == 0] + print(f" {zero}") + + +if __name__ == "__main__": + main() diff --git a/scripts/optimize_ontology_v2.py b/scripts/optimize_ontology_v2.py new file mode 100644 index 0000000..2ea1168 --- /dev/null +++ b/scripts/optimize_ontology_v2.py @@ -0,0 +1,164 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +尚数网本体 v2 修订后优化脚本(基于 ontology_v2_audit.md 建议) + - 阶段 A (schema 补定义): 给 Standard/PolicyDocument/DataProduct 补定义高频公共属性, + 使 P4 拆分遗留的"超纲属性"合法化、纳入检索/脱敏 schema (P0-① / P1-⑤) + - 阶段 B (启用分级): DigitalContract/UsageAction/UsageConstraint 启用 L0-L4 分级 (P1-③) + - 阶段 C (实例值映射): 把 Standard/PolicyDocument/DataProduct 实例上的超纲字段 + 值归一到类型定义字段, 并清掉冗余超纲 key (P0-① / P1-⑤ 增强) + - 阶段 D (recompute): 跑分级重算(默认 dry_run, 无副作用)确认一致性 + +运行: python3 scripts/optimize_ontology_v2.py --phase A [--dry-run] + python3 scripts/optimize_ontology_v2.py --phase B + python3 scripts/optimize_ontology_v2.py --phase C [--dry-run] + python3 scripts/optimize_ontology_v2.py --phase D +REST 调用需 dangerouslyDisableSandbox (出口代理会剥 X-API-Key 头) +""" +import sys, json, argparse +sys.path.insert(0, "/Users/xs/Desktop/workspace/ontology") +import scripts.import_ontology_v2 as m # 复用 api() + +# ---------- 阶段 A: 补定义属性 ---------- +# (type, api_name, display_name, data_type, required, description) +ADD_PROPS = [ + # Standard: ComplianceStandard 原字段, 对标准有意义 + ("Standard", "migrated_from", "迁移溯源", "string", False, "源自 ComplianceStandard 拆分前的实例主键"), + ("Standard", "standard_code", "标准代号", "string", False, "标准编号/代号, 如 GB/T 19001"), + ("Standard", "related_space", "关联空间", "string", False, "所属可信数据空间标识"), + ("Standard", "standard_type", "原分类", "string", False, "拆分前 standard_type 取值(国家标准/行业标准/技术文件/政策文件/法律法规)"), + ("Standard", "status", "标准状态", "string", False, "现行/废止/征求意见稿等"), + # PolicyDocument + ("PolicyDocument", "scope", "适用范围", "string", False, "文件适用地域/行业范围"), + ("PolicyDocument", "standard_code", "文件号", "string", False, "文件编号/标准代号"), + ("PolicyDocument", "standard_type", "原分类", "string", False, "拆分前 standard_type 取值(溯源)"), + ("PolicyDocument", "related_space", "关联空间", "string", False, "所属可信数据空间标识"), + ("PolicyDocument", "migrated_from", "迁移溯源", "string", False, "源自 ComplianceStandard 拆分前的实例主键"), + ("PolicyDocument", "english_title", "英文标题", "string", False, "文件英文标题"), + # DataProduct: AI/行业/管辖扩展属性 + ("DataProduct", "jurisdiction", "管辖域", "string", False, "数据产品适用管辖地域"), + ("DataProduct", "scene", "应用场景", "string", False, "数据产品应用场景描述"), + ("DataProduct", "industry", "所属行业", "string", False, "数据产品所属行业"), + ("DataProduct", "supports_inference", "支持推理", "boolean", False, "是否可作为模型推理输入"), + ("DataProduct", "supports_training", "支持训练", "boolean", False, "是否可作为模型训练输入"), + ("DataProduct", "tech_stack", "技术栈", "string", False, "实现技术栈"), +] + +def _exists_prop(tname, api_name): + code, r = m.api("GET", f"/ontology/object-types/{tname}") + ot = r.get("object_type", r) if isinstance(r, dict) else {} + props = ot.get("properties", []) if isinstance(ot, dict) else [] + return any(p.get("api_name") == api_name for p in props) + +def phase_a(dry): + print("[A] 补定义高频公共属性 (P0-① / P1-⑤)") + for tname, api_name, disp, dt, req, desc in ADD_PROPS: + if _exists_prop(tname, api_name): + print(f" 跳过(已存在) {tname}.{api_name}") + continue + body = {"api_name": api_name, "display_name": disp, "data_type": dt, + "required": req, "description": desc} + if dry: + print(f" [dry] POST {tname}/properties {api_name}") + continue + code, r = m.api("POST", f"/ontology/object-types/{tname}/properties", body) + print(f" {tname}.{api_name}: {code} {'ok' if code < 400 else r}") + +# ---------- 阶段 B: 启用 3 类型分级 ---------- +def phase_b(dry): + print("[B] 启用 DigitalContract/UsageAction/UsageConstraint 分级 (P1-③)") + levels = ["L0", "L1", "L2", "L3", "L4"] + for tname in ("DigitalContract", "UsageAction", "UsageConstraint"): + body = {"classification_property": "classification", + "classification_levels": levels, "classification_default": "L3"} + if dry: + print(f" [dry] PUT {tname}/classification classification_property=classification default=L3") + continue + code, r = m.api("PUT", f"/ontology/object-types/{tname}/classification", body) + print(f" {tname}: {code} {'ok' if code < 400 else r}") + +# ---------- 阶段 C: 实例值映射 + 清冗余 ---------- +# Standard 映射: 超纲 -> 定义字段 +STD_MAP = [ + ("title", "title_cn"), ("english_title", "title_en"), + ("effective_date", "implement_date"), ("code", "doc_no"), + ("name", "title_cn"), ("implementation_date", "implement_date"), + ("issued_by", "publisher"), ("issuer", "publisher"), + ("issuing_body", "publisher"), ("standard_name", "title_cn"), +] +STD_CLEAR = ["title", "english_title", "effective_date", "code", "name", + "implementation_date", "issued_by", "issuer", "standard_name", + "issuing_body", "note", "reference_docs"] # 映射后仍残留就清 +# PolicyDocument 映射 +PD_MAP = [("validity_period", "valid_period"), ("name", "title"), + ("code", "doc_no"), ("issuing_org", "issuer"), + ("issuing_body", "issuer")] +PD_CLEAR = ["validity_period", "name", "code", "issuing_body", "issuing_org", + "level", "key_entities", "core_target_2027", "ai_scenarios", + "key_projects", "project_target", "scenario_target", "talent_target"] +# DataProduct 映射 +DP_MAP = [("billing_model", "price_model"), ("description", "desc")] +DP_CLEAR = ["billing_model", "description"] + +def _migrate_type(tname, mapping, clear, dry): + off = 0; n = 0; migrated = 0; batch = [] + dst_set = set(d for _, d in mapping) + def flush(batch): + if not batch: + return + body = {"items": batch, "stop_on_error": False, "validate_enum": False} + c2, r2 = m.api("POST", "/objects/batch", body) + if c2 >= 400: + print(f" ! {tname} batch 失败 {c2} {str(r2)[:200]}") + while True: + code, r = m.api("GET", f"/objects?type={tname}&limit=300&offset={off}") + if not isinstance(r, dict): + print(f" {tname} ERR {code} {r}"); break + items = r.get("items", []) + for o in items: + n += 1 + props = o.get("properties") or {} + new_props = dict(props) + changed = False + for src, dst in mapping: + if props.get(src) not in (None, ""): + if not new_props.get(dst): + new_props[dst] = props[src] + new_props[src] = None # merge 语义: null=删除字段 + changed = True + for k in clear: + if k in new_props and k not in dst_set: + new_props[k] = None # 标记删除 + changed = True + if changed: + migrated += 1 + if dry: + continue + batch.append({"type": tname, "pk": o.get("pk"), "properties": new_props}) + if len(batch) >= 100: + flush(batch); batch = [] + if len(items) < 300: + break + off += 300 + flush(batch) + print(f" {tname}: 扫描 {n} 实例, 需迁移 {migrated}") + +def phase_c(dry): + print("[C] 实例值映射 + 清冗余超纲 (P0-① / P1-⑤ 增强)") + _migrate_type("Standard", STD_MAP, STD_CLEAR, dry) + _migrate_type("PolicyDocument", PD_MAP, PD_CLEAR, dry) + _migrate_type("DataProduct", DP_MAP, DP_CLEAR, dry) + +# ---------- 阶段 D: recompute ---------- +def phase_d(dry): + print("[D] 分级重算 (默认 dry_run)") + code, r = m.api("POST", "/ontology/classification/recompute", {"dry_run": True}) + print(f" recompute: {code}") + print(" ", json.dumps(r, ensure_ascii=False)[:500] if isinstance(r, dict) else r) + +if __name__ == "__main__": + ap = argparse.ArgumentParser() + ap.add_argument("--phase", required=True, choices=["A", "B", "C", "D"]) + ap.add_argument("--dry-run", action="store_true") + a = ap.parse_args() + {"A": phase_a, "B": phase_b, "C": phase_c, "D": phase_d}[a.phase](a.dry_run) diff --git a/scripts/raise_employee_clearance.py b/scripts/raise_employee_clearance.py new file mode 100644 index 0000000..a442b8b --- /dev/null +++ b/scripts/raise_employee_clearance.py @@ -0,0 +1,99 @@ +#!/usr/bin/env python3 +""" +把 75 个员工主体(尚数网-XXX,is_builtin=false,非 TradingAssistant/analyst 角色) +的 clearance 从 [L0,L1,L2] 提升为 [L0,L1,L2,L3],解决 P0-② 可见性缺口。 + +复用 import_ontology_v2.py 的 BASE / KEY / _clean_env(curl 子进程直连,清代理变量)。 + +用法: + python3 scripts/raise_employee_clearance.py --dry-run # 只打印将改动的名单 + python3 scripts/raise_employee_clearance.py # 实际执行 +""" +import argparse, json, subprocess, sys, os + +KEY = "0e926a78570d51a6949c65ffec2b7be6aa43ff2b678019c75cc0d65005affe05" +BASE = "http://r.mayishangshu.cn:18081/api/v1" +TARGET = ["L0", "L1", "L2", "L3"] + +# 这些非内置主体不是「普通员工」,不在此脚本处理范围(按需另行确认) +EXCLUDE = {"TradingAssistant", "analyst"} + + +def _clean_env(): + env = dict(os.environ) + for k in ("HTTP_PROXY", "HTTPS_PROXY", "https_proxy", "http_proxy", + "ALL_PROXY", "all_proxy", "NO_PROXY", "no_proxy"): + env.pop(k, None) + return env + + +def api(method, path, body=None): + url = f"{BASE}{path}" + cmd = ["curl", "-s", "--noproxy", "*", "-m", "120", "-X", method, url, + "-H", f"X-API-Key: {KEY}", "-H", "Content-Type: application/json", + "-w", "\n__STATUS__%{http_code}"] + if body is not None: + cmd += ["-d", json.dumps(body, ensure_ascii=False)] + out = subprocess.run(cmd, capture_output=True, text=True, timeout=140, env=_clean_env()) + raw = out.stdout + if "\n__STATUS__" in raw: + txt, _, code_s = raw.rpartition("\n__STATUS__") + code = int(code_s.strip() or -1) + else: + txt, code = raw, -1 + try: + data = json.loads(txt) if txt.strip() else None + except Exception: + data = txt + return code, data + + +def list_principals(): + code, data = api("GET", "/access/principals") + if code != 200 or not isinstance(data, dict): + print(f"[ERR] GET /access/principals -> {code}: {data}", file=sys.stderr) + sys.exit(1) + return data.get("principals", data) if isinstance(data, dict) else data + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--dry-run", action="store_true") + args = ap.parse_args() + + principals = list_principals() + # 员工 = 非内置 且 不在 EXCLUDE 名单 + employees = [p for p in principals + if not p.get("is_builtin") and p.get("name") not in EXCLUDE] + already = [p for p in employees if "L3" in (p.get("clearances") or [])] + to_change = [p for p in employees if "L3" not in (p.get("clearances") or [])] + + print(f"员工主体总数: {len(employees)}") + print(f" 已是 L0-L3 : {len(already)}") + print(f" 待提升 L3 : {len(to_change)}") + if args.dry_run: + print("\n[dry-run] 将提升以下主体到", TARGET) + for p in to_change: + print(f" - {p['name']} (当前 {p.get('clearances')})") + return + + ok, fail = 0, [] + for p in to_change: + # 注意:REST putClearances 只认请求体字段 `markings`(handlers_access.go:318), + # 传 `clearances` 会被忽略并清空!必须用 markings。 + code, resp = api("PUT", f"/access/principals/{p['name']}/clearances", + {"markings": TARGET}) + if code in (200, 204): + ok += 1 + else: + fail.append((p["name"], code, resp)) + print(f"[FAIL] {p['name']} -> {code}: {resp}", file=sys.stderr) + + print(f"\n完成: 成功 {ok} / 失败 {len(fail)} / 跳过(已L3) {len(already)}") + if fail: + print("失败名单:", [f[0] for f in fail]) + sys.exit(2) + + +if __name__ == "__main__": + main() diff --git a/scripts/revert_ucp_level.py b/scripts/revert_ucp_level.py new file mode 100644 index 0000000..5a26a8e --- /dev/null +++ b/scripts/revert_ucp_level.py @@ -0,0 +1,58 @@ +#!/usr/bin/env python3 +# revert_ucp_level.py +# 把 UsageControlPolicy 的实例级 L4 覆盖层移除,回落到类型默认级 L3(经理以上可见)。 +# 依据:用户确认「UsageControlPolicy 36 条降到 L3(经理以上也可治理)」。 +# 机制:PUT /access/objects/UsageControlPolicy/:pk/markings {"markings": []} 移除覆盖层, +# 实例回落到 object_types 的 classification_default(当前 L3)。 +import sys, json +sys.path.insert(0, 'scripts') +import raise_employee_clearance as r + +TYPE = "UsageControlPolicy" +APPLY = "--apply" in sys.argv + +def err(msg): + print("❌", msg); sys.exit(1) + +def main(): + # 1) 确认类型默认级 + code, cfg = r.api("GET", "/ontology/classification/config") + if code != 200: + err(f"读 classification/config 失败 code={code}") + items = {c["api_name"]: c for c in cfg.get("items", [])} + default = items.get(TYPE, {}).get("classification_default") + print(f"类型 {TYPE} 当前默认级 = {default} (回落目标)") + + # 2) 列出该类型全部实例 pk + code, data = r.api("GET", f"/objects?type={TYPE}&limit=1000") + if code != 200: + err(f"读实例列表失败 code={code}") + arr = data.get("items", data) if isinstance(data, dict) else data + pks = [o.get("pk") for o in arr] + print(f"实例数: {len(pks)}") + + # 3) 逐个查看当前 markings 并回落到 [] + done = skip = 0 + for pk in pks: + c, d = r.api("GET", f"/access/objects/{TYPE}/{pk}/markings") + cur = (d.get("markings") or []) if isinstance(d, dict) else [] + if not cur: + skip += 1 + continue + if APPLY: + code, _ = r.api("PUT", f"/access/objects/{TYPE}/{pk}/markings", + {"markings": []}) + if code == 200: + done += 1 + print(f" ✅ {pk}: {cur} -> [](回落 L3)") + else: + print(f" ❌ {pk}: PUT 失败 code={code}") + else: + done += 1 + print(f" [dry-run] {pk}: 当前 {cur} -> 将回落 []") + print(f"\n{'执行' if APPLY else '预览'}完成:回落 {done} 条,原无覆盖层跳过 {skip} 条") + if not APPLY: + print("(干跑模式,未改动。加 --apply 执行)") + +if __name__ == "__main__": + main() diff --git a/尚数网最新介绍.md b/尚数网最新介绍.md new file mode 100644 index 0000000..345bc01 --- /dev/null +++ b/尚数网最新介绍.md @@ -0,0 +1,117 @@ +# 尚数网最新介绍 + +> 依据尚数网本体管理平台(shangshu-ontology)知识库与本体数据整理,数据截至 2026-09。 +> 覆盖 59 类本体对象:新闻动态、会员单位、数据产品/资源、可信数据空间、硬件设施、知识产权、分支机构等。 + +--- + +## 一、公司概况 + +**深圳市尚数网科技有限公司**(简称"尚数网")是数据要素流通领域的综合服务商,由光信数据技术(深圳)有限公司联合广州数据交易所打造,是**广州数据交易所认证的可信 AI 样本行业数据平台**。 + +- **使命**:构建可信数据流通交易生态,让数据更安全、让价值可看见 +- **运营架构**:深圳、北京**双总部**,业务辐射五大核心区域 +- **分支机构**(7 个):深圳总部 + 北京、赣州、东莞、南宁、南昌、南京分公司 +- **核心团队**:创始人/CEO 王蒙,副总经理兼 CTO 吴桂荣,运营总监周海涛 +- **官网**:https://shangshuwang.cn/ + +## 二、技术体系:"3+5+N" 全链路服务 + +尚数网以 **"3+5+N" 全链路服务体系**为核心: + +| 平台 | 能力 | +|---|---| +| **数据交易平台** | 数据产品挂牌、供需撮合、交易存证 | +| **数据交付平台** | 可信数据空间,"原始数据不出域、可用不可见、可控可计量" | +| **数据资产管理平台** | 数据资产梳理、合规确权、评估入表 | + +业务涵盖:数据合规确权、数据资产化(入表/质押融资)、数据供需撮合、数据运营、产教融合、API 应用超市等全链路服务。 + +## 三、可信数据空间(核心业务) + +可信数据空间以"可信管控、资源交互、价值共创"为三大核心能力,构建**企业级、行业级、城市级**三级体系,采用"服务平台 + 连接器"架构,支持自建、租赁、一体机多种部署模式。 + +**已落地的行业空间**(本体在册 8+ 个): + +| 行业空间 | 运营方 | 部署模式 | +|---|---|---| +| 物流行业(全国首个物流) | 深圳华储数据 | 一体机 | +| 茶行业(全国首个茶业) | 北京茶业交易中心 | 自建 | +| 数证通-赣江公证(司法) | 江西司法厅 | 租赁 | +| 吉利汽车(汽车) | 吉利汽车 | 一体机 | +| 资产评估 | 国誉评估 | 一体机 | +| 生态环保 | 内蒙应急飞行大队 | 租赁 | +| 具身智能 | 惠阳城投 | 一体机 | +| 医疗健康 | 尚数网自建 | 自建 | + +**标杆成效**(物流空间):高速病害识别率 99%、货车保险核保时间从 3 天压缩至 2 小时、新疆出疆运输空载率从 58% 降至 32%,方案已在多省推广。 + +服务对象:20 余家数据交易机构、多家央国企及上市公司。 + +## 四、自研硬件:密算基础设施 + +| 产品 | 说明 | +|---|---| +| **数据安全卡** | 自主研发,标准 PCIe 即插即用;全套国密算法(SM1/2/3/4/9),根密钥出厂烧录构建硬件级可信根,安全启动 + 端到端加密隧道,密钥不出卡 | +| **可信密码卡** | 可信数据空间的密码学底座,与密算一体机、连接器协同实现数据全链路密态流转 | +| **数据接入连接器(硬件版)** | 微型数据接入网关,"最后一公里"开箱即用;多源异构数据安全接入、原始数据不出域、自动生成标准化数据目录 | +| **密算一体机** | 机密计算底座 + 隐私计算集成;TEE 支持海光 CSV / AMD SNP;标准版 / AI 版 / 顶级版三档,可配置国密卡、GPU、低代码、智能体 | + +**信创认证**:密算一体机获信创工作委员会认证(DBRTA-XC-144,2026-07-15,有效期至 2031-07-14);亮相第二十八届北京科博会西城展区。 + +## 五、AI 产品矩阵(DeepSeek 底座) + +| 产品 | 定位 | +|---|---| +| **数小规** | 全国首个企业数据合规智能体:"四步体检法"输出合规体检报告与整改指引;已在深圳数据交易所上架并完成首笔场内交易;商标 + 作品登记证书双证 | +| **金臻估** | 企业数据资源潜在价值测算模型:联合国誉评估打造,"评估→规划→变现"三段式赋能,成本降低 90%+、效率提升 10 倍,联合颁发《数据资产潜在价值证书》;已获数据知识产权登记证书(深数所) | +| **数小估** | 企业数据资源潜在价值测算 / 数据资产评价 | +| **数小美** | 面向企业估值与合规的数据产品 | +| **数据流通交易助手(AI 供需撮合)** | 2025-12 于北京"中国数据街"合作发展联盟活动首发:自然语言解析、全源数据检索、智能用数推荐,破解供需撮合痛点 | + +## 六、生态与合作 + +- **会员规模**:优质会员单位 **1200+ 家**,平台沉淀 **20000+ 份高质量 AI 样本**(覆盖医疗健康、公共服务、地理遥感、智慧金融、通信运营商等行业) +- **交易所生态**: + - 广州数据交易所:可信 AI 样本行业数据平台共建 / 认证渠道商 / 交易合伙人 + - 深圳数据交易所:合规背书 + - 贵阳、北部湾、江苏、昆明、内蒙古等:会员互认 / 合作 +- **行业联盟**:率先加入可信数据空间发展联盟;受邀出席北京"中国数据街"合作发展联盟活动 +- **机构合作**:深圳市标准技术研究院(数据知识产权登记)、中安院(低空与无人系统数据空间)、江西财经大学等高校(产教融合) + +## 七、标准与知识产权 + +**标准参编**(代表性): +- 全国数标委《可信数据空间标准化研究报告》 +- 《数据资产全过程管理规范》T/TMAC 276-2025(核心参编) +- 《数据交易师职业技能评价标准》起草单位 +- 深圳市《数据知识产权价值评估指南》地方标准参编 +- 《高质量数据产品开发实践白皮书》(昆明国际数交所牵头) +- 《数据要素的标准化未来:数据零件化白皮书》 +- 《2025 跨境数据流通合规与技术应用白皮书》 +- 《人形机器人产业白皮书》 +- 江西省《数据资产质押公证登记规范》 + +**知识产权**(本体在册): +- 注册商标:**尚数网**(2024-05-28)、**数小规 / 数小估**(2025-10-14)、**金臻估**(2026-02-28)、数小美 等 +- 证书:密算一体机信创认证、数小规作品登记证书、金臻估数据知识产权登记证书 等 +- 自研软著:可信数据交付系统、可信数据空间平台、数据资产管理系统、可信模型训练交付系统 等 + +**荣誉**:2025 年"数据要素×"大赛广东分赛应用实践奖;广州数据交易所认证渠道商资质;深度赋能财政部资产评估中心研究课题顺利结题;国务院国资委首批央企高质量数据集优秀建设成果深度参与。 + +## 八、近期动态亮点(2025–2026) + +1. **2026-03** 江西财经大学副校长一行莅临指导,深化校企产教融合 +2. **2026-01** 成功举办"可信数据空间专区建设研讨会",发布轻量化专区产品矩阵 +3. **2025-12** 入驻北京("启新程·聚数势"),双总部格局成型;"中国数据街"首发数据流通交易助手 +4. **2025-12** 全国政协委员唐冬生一行调研,共探制造业数据资产化 +5. **2025-07** 赋能全国首个物流行业可信数据空间上线 +6. 持续开展供需撮合(已至第三十期)、深度赋能央企高质量数据集建设 + +--- + +### 数据说明 + +- 本文档由尚数网本体 MCP(manager 主体)检索整理:59 类对象类型、100+ 条新闻动态、8 个行业可信数据空间、7 个分支机构、10 家合作交易所及硬件/AI 产品/知识产权等实例。 +- 新闻动态的 `date` 字段多为批量导入时间(2026-07-22),事件实际发生时间以正文为准(2023-12 至 2026-03)。 +- 会员规模、样本数量等以官方新闻口径(1200+ 会员 / 20000+ AI 样本)为准;本体在册 MemberOrg 实例为治理中的结构化子集。