Commit Graph
17 Commits
Author SHA1 Message Date
adminandClaude Opus 4.8 34933b7c53 docs(gb48000): 差距分析报告 + 标准 PDF + PLAN/README 同步 + 实施计划 + CLAUDE.md
Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-09-20 14:50:56 +08:00
admin d938462bd6 refactor(access): 完全移除 .env 显式密钥,密钥统一由 principals 表管理
理由:管理界面已就位,DB 中由 UI 设置或 seed 随机生成的 key 才是唯一权威来源,
不再需要在部署时手动配置 MANAGER_API_KEY/CONNECTOR_API_KEY/INGEST_API_KEY,
避免环境变量泄漏/不同环境不一致/容器重启覆盖等运维隐患。

### 设计
- 移除 Config 中的 ManagerAPIKey/ConnectorAPIKey/IngestAPIKey 字段及对应环境变量读取。
- principalFromRequest 仅查 principals 表 api_key;不再有 env 优先回退。
- loginRequired/connectorAuth 改为查询 'DB 是否已有密钥' 判定是否进入真实鉴权模式;
  manager 未配置 key 的全新库仍保留开放体验,便于首次引导(密码登录)。
- 首次启动时 seedAccessControlDefaults 为 4 个内置主体(manager/connector/public/ingest)
  随机生成 API Key 并打印到 stdout(幂等,已有 key 不覆盖)。
- handlers_mcp.callConn 内部派发改用 a.builtinKey('connector') 注入 X-API-Key,
  走 DB 查到的密钥而非 env。

### 加固
- 移除固定/空 key 漏洞:seed 写入前先 UPDATE...WHERE api_key IS NULL OR api_key='',
  重复启动幂等;首次启动日志里打印 4 个随机值,运维保存后可在 Access Control 页重置。

### 验证(localhost:8081 真实库,go test 全绿)
- mgr-key-2213 经纯 DB 解析回 manager(manage+L0-L4);密码登录仍可引导。
- connector 端点:无 key 401,带 DB key 200;authHint 切到 DB key 状态文案。
- public key 解析为 public(L0 only),匿名请求也回退 public,无升权。
- mgmt 端点:无 key / public key 均 401;manager key 200。
- 全部测试 green (server + ai)。

### 文档同步
- README.md / docs/README.md / docs/USAGE.md / docs/IMPORT.md /
  skills/ssw-ontology-reviewer/SKILL.md / web/src/views/ConnectorView.vue /
  server/CHANGELOG.md 同步去掉 .env 密钥说明,改为'首次启动日志 + Access Control 页管理'。
2026-09-07 15:29:20 +08:00
admin e7b39805fb feat(backup): 按 schema 镜像 + 请求级 search_path 切库 (issue #4 #5 后续)
「让客户端敢操作」的关键能力:写前/写后打一份快照 → 任意 GET 带 X-Snapshot-Id
 头即可命中 backups_<id> schema 的同名表(业务 SQL 不带 schema 前缀照样切)。

 设计要点:
   - 备份 = 独立 schema backups_<id>(真表,不是单存 JSONB)—— 查询性能与活库一致
   - snapshotRouter 中间件:BeginTx + SET LOCAL search_path → 把 a.pool 临时换
     为事务视图 txPool → handler 结束 commit + 还原 a.pool。业务代码一行不改。
   - a.pool 字段类型从 *pgxpool.Pool 升级为 dbRunner interface(中间件可换 txPool)。
   - 11 个 helper 函数签名同步改为 dbExec(与现有 dbExec 共存,无破坏性)。
   - 写方法(POST/PUT/PATCH/DELETE)带快照头 → 403 拒绝(mistake-safety)。

 接口:
   - POST /api/v1/backups 创建
   - GET /api/v1/backups 列表
   - GET /api/v1/backups/:id 元信息(含 schema_name)
   - GET /api/v1/backups/:id/switch 切库提示
   - DELETE /api/v1/backups/:id 级联删 schema
   - 支持 X-Snapshot-Id (直接 run id) + X-Snapshot-Ts (秒级时间戳) 两种切换入口

 MCP 工具 (5 个):backup_create / backup_list / backup_inspect / backup_switch / backup_delete

 测试 (22 个全绿,~5.5s 集成):
   - SnapshotRouter:改前建快照 → 改后读快照只见改前
   - SnapshotSearchPathPersist:不污染下一个请求
   - SnapshotByTimestamp:ts 头也能切库
   - SnapshotDeleteCleansSchema:delete 真 DROP schema
   - BackupLifecycle / BackupDiffAfterMutation:完整 create→list→inspect→switch→delete

 文档:docs/BACKUP.md 写清用法、机制、客户端工作流;CHANGELOG.md [1.3.0]。
2026-09-07 11:35:47 +08:00
admin ae9a1a69e2 test: 加 16 个回归测试 (11 纯函数 + 5 集成) + docs/TESTING.md
- 纯函数单测(go test -short)覆盖:
  classification (levelIndex/maxLevel/materializeClassification/principalMaxIndex/deniedLevelsFor)、
  display_name (propString/resolveDisplayName)、
  governance (diffProps/mergeProps/parseStringArray/similarity)
- 集成测试(-tags=integration,跑真实 PG)覆盖 issue #4 #5 端到端:
  enum_violation 拦截 + 友好错误;分级过滤 manager vs analyst(L0/L1) 越级 404;
  properties.sensitivity 越级 redact 为 ***;删→恢复关系边 (links_snapshot+edges_created=1);
  recompute dry_run 不落库 / apply=true 落库修正错误分级
- 集成测试踩坑:X-Principal 与 principal_clearances.principal 必须一致;每次新主体必须清
  authzCache(sync.Map 进程级),否则历史空 Authz 会让分级过滤假阴性
- docs/TESTING.md:测试分层 / 跑测命令 / 编写新测试的约定
- CHANGELOG [1.2.0] 加 测试 与 文档 段落
2026-09-07 10:11:39 +08:00
admin da73b1091f feat(governance): restore_object 恢复关系边 + 数据分级通用能力 (issue #4 #5)
- #4 restore_object 默认连同关系边恢复:删除级联存边快照(links_snapshot),回滚重建两端在的边、跳过悬空引用,分级从快照物化
- #5 数据分级(不硬编码字段名/级别名):
  - 类型级 classification_property/levels/default 配置 + objects.classification 物化列+索引
  - 读路径按 principal_clearances 下推过滤,越级默认屏蔽且不泄漏存在性(fail-closed)
  - 字段级 properties.sensitivity 越级脱敏为 ***
  - 枚举写入校验(修复变量遮蔽导致的永不拦截 bug):越界值 400 enum_violation
  - 批量重算 recompute(dry_run 默认/apply 落库) + KM 源文件级分级传导
  - MCP +3 工具(get_classification_config/recompute_classification/set_km_classification)
- 分级路由改挂 /ontology 避免与 /objects/:type/:pk 参数路由冲突
- 更新 CHANGELOG 与 INSTANCE_GOVERNANCE.md §15-§16
- 验证:localhost:8081 真实库跑通删→恢复边、分级过滤、枚举拦截、字段脱敏、重算落库
2026-09-07 09:45:02 +08:00
admin cf9e8a74a4 feat(instances): 实例治理 — 显示名物化/merge 语义/软删除/审计/批量/血统传播/source_ts
对标《本体改进需求》14 项按本库实情取舍落地 + Palantir 两机制:

- 显示名物化: title_property → name/title/real_name/display_name 回退链,
  启动回填存量 1235 个空 name(修复 45% 实例检索隐身)— server/display_name.go
- 写入语义: create/update 默认 merge(只改传入字段),replace=true 才全量替换,
  响应回显 added/changed/removed — server/object_upsert.go
- 软删除: objects.deleted/same_as 真实列,连接器默认排除墓碑,
  connObject 别名自动跳转 canonical,restore_object 恢复
- 删除闭环: delete_object 级联删边+幂等+快照进 object_changes;
  propagate=true 沿 source 血统清理该来源全部抽取产物+摄取记录
- 变更审计: object_changes 字段级 diff + get_object_history + restore
- 批量: POST /objects/batch /links/batch 单事务逐条 ok/fail
- 检索: search 多字段 + query filters ne/in/nin/contains/exists + fields 裁剪
- KM: km_list_files recursive + 文件级 excluded 标记 + 双向溯源
- source_ts 乱序丢弃: 旧于已有值直接 409 stale_write(批量 stale_skipped)
- MCP: 新增 batch_create_objects/batch_create_links/delete_object/
  restore_object/get_object_history/find_duplicates 等,共 24 工具
- 前端: api 封装 + InstanceView 删除/保存对话框治理提示
- 文档: docs/INSTANCE_GOVERNANCE.md 权威语义 + 6 份关键文档同步
2026-09-05 14:31:00 +08:00
admin 9298f58744 chore: 升级完成后清掉 docs/update/ 全部过渡文件
镜像启动自带 migrate + ensureBuiltin* + seedIfEmpty,
本次升级已全员跑完,docs/update/ 4 个过渡文件(升级说明 + runbook +
schema-migrate.sql + builtin-seed.sql)作为一次性引导物可以删。

历史保留:4 个文件均在 git log 里能找到,需要时 checkout 即可恢复。

3 处引用清理:
- README.md              4 行升级导航删除
- docs/PLAN.md           runbook 引用删除
- docs/README.md         update/ 目录说明 + 3 行升级指引删除
2026-09-03 15:57:24 +08:00
admin a73d865d8a docs: 删 2026-08-24.md 过渡文档,5 处引用改指新版本
旧 2026-08-24.md 是升级当时的临时大文档(11 节、P0/P1/P2 设计 +
迁移步骤 + 回滚),升级完成后已被拆成 4 个独立正式版:
- docs/update/升级说明.md        (同事操作版)
- docs/update/2026-08-24-runbook.md  (工程师技术细节)
- docs/update/2026-08-24-schema-migrate.sql  (DDL)
- docs/update/2026-08-24-builtin-seed.sql    (内置 seed)

旧文档作为唯一升级入口引用已被替代,删掉避免误引用。

5 处引用替换:
- README.md:17            → 4 行新文档导航
- docs/README.md:387       → update/ 目录说明改为'按日期分目录,每次含 4 件套'
- docs/README.md:406       → 分三层指向新文档
- runbook.md:183           → 指向同事版升级说明
- docs/PLAN.md:18          → 指向 runbook + PLAN.md 演进阶段
2026-09-03 15:37:15 +08:00
admin 1b677b8762 docs(update): 同事升级操作说明(面向操作员友好版)
跟 2026-08-24-runbook.md(面向工程师技术细节)的区别:
- 升级说明:3 步命令可复制粘贴、验证清单可逐项打勾、失败兜底列具体场景
- runbook:DDL 设计取舍、FK 顺序、事务行为细节

涵盖:
1. 一句话总结(3 段命令贴进终端跑完即可)
2. 适用场景表(哪些情况要做、哪些不用)
3. 前置要求(PG 版本 / pgcrypto 扩展 / 操作账号权限)
4. 三步执行(改连接变量 → 跑 schema → 跑 seed)
5. 验证清单(7 条 SQL 逐项打勾)
6. 失败兜底(schema / seed / 接口三类问题的修法)
7. 升级前后对比(22 张表 vs 17 张 / 新增哪些列)
8. 升级完后下一步 + 还要问老板的事
2026-08-24 17:56:15 +08:00
admin 81c4dcc5c4 docs(update): 独立 schema 迁移 + builtin seed 脚本 + runbook\n\n把 server/db.go migrate() + ensureAccessControlSchema() +\nensureBuiltinFunctions() + ensureBuiltinInterfaces() +\nseedAccessControlDefaults() + seedIfEmpty() 共 6 段拆成可手动跑的\nSQL 脚本,方便:\n- 手动部署到生产 PG(不让服务自己建表)\n- 调试 schema 演进(不启动服务即可单跑)\n- 离线环境无 server 二进制时也能升级\n\n3 个文件:\n- schema-migrate.sql DDL(事务,幂等):22张表 + 12个索引\n- builtin-seed.sql 数据:4 functions + 6 interfaces + 4 principals +\n clearances/grants + L0 默认标记 + demo 种子\n- runbook.md 执行顺序 + 验证清单 + 回滚 + 设计要点\n\n实测 (空库):\n- schema-migrate.sql 重复跑 2 次,全部 NOTICE/skipped,table_count=22 ✓\n- builtin-seed.sql 一次跑过,验证函数返回全部命中预期值 ✓\n- builtin-seed.sql 含 CREATE EXTENSION pgcrypto 自包含 2026-08-24 17:52:26 +08:00
admin 240dd2c31f docs(WORKBUDDY): WorkBuddy 接入 + 本体信息更新说明(连接器安装 / 三条更新路径 / 排错) 2026-08-24 14:53:07 +08:00
admin e5fc024217 chore: 删除 importer/import-from-xeo.js(尚数网业务专用)
沙数网 shangshuwang.cn mobileApi 专用 importer 不属于通用本体平台的一部分,
按业务专用代码剥离。

- 删除 importer/import-from-xeo.js(200 行, Node 脚本)
- 删除空目录 importer/

文档同步:
- docs/README.md 项目结构去掉 importer/ 行
- docs/IMPORT.md 删除"尚数网示例"整节,改为通用 Node 骨架

历史信息归档在 .workbuddy/memory/2026-08-24.md
(字段映射表 / 抓取器路径 / 重新启用方式)
2026-08-24 14:11:29 +08:00
admin 1e30d4c355 docs+code: 通用化平台叙事,去掉尚数网业务绑定
## 文档重构(5 个 md + 1 个 html)
- README.md: '尚数网本体管理平台' → '本体元数据平台 · Ontology Platform'
- docs/README.md: 通用化定位,补全 P0/P1/P2 (Palantir Ontology 对标) + Materialization/BackingSource/Suggestions 全清单
- docs/PLAN.md: 通用化设计目标,改为 'Palantir Ontology 对标' 路线图
- docs/USAGE.md: 用通用占位符(项目/空间/组织)替换尚数网具体业务举例
- docs/IMPORT.md: 把 shangshu 当成 '一个采用方示例' 展示通用模式
- docs/product-intro.html: title/brand/hero/场景/footer 全改通用,沙数只作典型场景之一

## 代码字符串同步去 shangshu
- server/main.go: '[boot] 尚数网本体管理平台监听' → '[boot] 本体平台监听'
- server/handlers_connector.go: manifest 'server' 字段 → 'ontology-platform'
- server/handlers_mcp.go: tool description + serverInfo → 通用
- server/handlers_functions.go: builtin interface description → 通用
- server/handlers_backing_source.go: 注释去 shangshuwang.cn 具体网址
- server/config.go + server/db.go: 注释/seed 数据改占位 (demo_self / demo_partner_a/b)
- server/ai/anthropic.go: fallback systemPrompt → '通用本体平台工程师'
- server/ai/heuristic.go: 未识别 summary → '本体概念'
- server/ai/prompt.go: 静态 systemPrompt 头部 + JSON 示例去 shangshu

## 前端文案同步
- web/src/App.vue: title 改 '本体元数据平台'
- web/src/views/LoginView.vue: 登录页 h1 改通用
- web/src/views/OntologyView.vue: backing source placeholder 改 example.com
- web/src/components/ReviewWorkbench.vue + useReviewWorkbench.js: '尚数网' → '本体平台'

## 验证
- go build ./server OK
- 剩余 '尚数网' / 'shangshu-ontology' 引用:
  - 文档 README/README/USAGE/PLAN/IMPORT 仅在 '采用方示例' 上下文出现
  - 代码注释 sswOntologySystemPrompt 等 identifier 保持不变(避免改动 API 表面)
  - skill 名 'ssw-ontology-reviewer' 保持不变(已发布技能)

Refs: docs/README.md (1.1 元数据组件表)、docs/PLAN.md (4 当前已完成能力)
2026-08-24 14:04:59 +08:00
admin 86730bd52d feat: 对标 Palantir Ontology + P0/P1/P2 全落地 + xeo 端到端导入
## Palantir Ontology 对标(10 项)

P0 核心契约:
- when_to_suggest JSONB + llm_tool_description TEXT 加到 function_types/action_types
- Action 完整契约: submission_criteria / side_effects / impl_function_id / return_type
- FBA (Function-backed Action) 执行链: /api/v1/objects/:type/:pk/actions/:action
- /api/v1/ontology/suggestions 提示调度端点

P1 元原语补全:
- Object Type UX: title_property / subtitle_property / color / primary_key
- Property 字段元数据: format / default_value / indexable / vector_index / backing_column
- Link Type: directional + 独立 link_properties 子表
- Interface Type: shared_properties + parent_interface_id 多态
- Property extended types: geoshape / geopoint / media / timeseries / timestamp

P2 数据管道层:
- materializations / materialization_rows 物化层 + 60s ticker scheduler
- backing_sources 同步源元数据 + 投影字段映射

AI 提示词升级:
- ai/prompt.go 抽出 250+ 行静态 systemPrompt
- 动态上下文注入: 每次 Suggest 前查 db 拉已注册类型清单
- Suggestion struct 扩展 22 字段

## ON CONFLICT 漏 source 修复(4 处)
- handlers_objects createObject/updateObject: COALESCE(NULLIF(EXCLUDED.source,''), objects.source)
- handlers_km upsertObject + ai.ApplySuggestion: SET source=EXCLUDED.source
- 表名必须限定 objects.source, 否则报 ambiguous

## xeo mobileApi 端到端导入
- /api/v1/ai/ingest raw_text 改用 json.dumps 转义, 修复 ingestion_id=56 failed
- 1179 实例 + 1672 links + 1806 物化行
- 占位: 5 TrustedDataSpace + 158 MemberOrg
- 5 类 Materialization 配好(mat_xeo_dataproduct 等)

## 文档
- docs/update/2026-08-24.md: 10 节迁移 + 增量 11 节
- .gitignore: 加 web/vite.config.js.timestamp-*.mjs

Refs: docs/update/2026-08-24.md
2026-08-24 13:54:49 +08:00
admin 993f74c2b2 feat: Docker 单镜像分发 + 默认端口统一 8081 + seed 极简化
新增 Dockerfile + docker/entrypoint.sh:
- 基础 crpi-.../ssw188/postgres:16-alpine + ontology 二进制,单镜像
- 默认端口 8081 / 库 ssw-ontology / 用户 ssw / 密码 ssw
- /data/pg 自动挂 PG 数据,/data/archive 挂文档根目录
- trap 收尸保证 PG + ontology 同生命周期

seed 极简化为 1 个对象类型「合作企业」+ 3 条示例
(尚数网/腾讯/阿里巴巴),便于演示也便于清理。

默认 HTTP_PORT 统一为 8081(覆盖 server/config.go、run.sh、
vite.config.js、importer/import-from-xeo.js、docs/README.md、
docs/USAGE.md、docs/IMPORT.md、.env.example 等所有文档/代码)。

docs/README.md / .env.example 默认 DATABASE_URL 改为
ssw/[email protected]:5432/ssw-ontology(与 Docker 镜像自带 PG 一致);
run.sh 删 dacli 硬编码 fallback,改从 .env 读(不存在则报错退出)。

README 重整:分「方式 A Docker 镜像 / 方式 B 本机 ./run.sh」,
新增 AI 智能导入(-e AI_*)与管理接口鉴权(-e MANAGER_API_KEY)说明。
2026-08-13 15:59:27 +08:00
admin e28c8add5f fix(ai): 修复 AI 摄取弹窗卡死 + 端口默认 8081→8082
- AIView.doExtract 改用 try/catch/finally, finally 必关弹窗 + 清 loading;
  Element Plus 新版 ElMessage(opts) 返回 MessageHandler 实例, 调 .close()
  才是正确用法 (旧 ElMessage.close(id) 静态方法在新版本里已移除).
- run.sh / README.md / docs/README.md 默认端口 8081 改为 8082,
  避免与 docker compose 里的 ontology 服务端口冲突.

测试: 浏览器实际点击开始提取, 弹窗完成后立刻关闭, 无 Console 报错.
2026-08-07 19:16:00 +08:00
ssw f1b687c2d2 目录扁平化:子目录内容提升至仓库根,文档归入 docs/
- 将 shangshu-ontology/ 子目录内容移至仓库根一级
- 修复 run.sh 的 REPO_ROOT 计算(扁平化后不再需要 cd ..),ARCHIVE_DIR 正确指向仓库根/archive
- 文档(README/PLAN/USAGE/IMPORT/product-intro)移至 docs/,同步更新结构树与导入命令中的旧路径
- 新增根 README.md 索引指向 docs/
- 新增 .gitignore:忽略 bin/、web/node_modules/、web/dist/、server/webroot/、.env、.workbuddy/ 等噪音
- main.go 的 ARCHIVE_DIR fallback 基于可执行文件相邻上级,扁平化后仍正确,无需改动
2026-08-07 14:21:34 +08:00