P2 Foundry

入门：从数据到本体

从接入数据源到对象建模，再到查询、Action 写回与版本合入，一条龙看懂 Foundry 的基础玩法。看完这 4 个故事，你就能自己动手把一张业务表变成"能查、能改、能管"的本体对象。

数据工程师业务分析师本体建模对象查询 Action 写回版本治理共 4 个故事

能 / 不能速览

✅ 这个主题能做

把数据源里的表建模成"对象"（Object），绑定主键与属性映射
用对象查询 / 语义检索按业务语言查数据，不用写 SQL
通过 Action 把订单状态等数据安全地写回源表，全程留痕
对对象定义做 draft → review → merged 受控变更，可对比、可回滚
用指标语义层统一 total_gmv / aov 等口径

⛔ 这个主题做不了

对象查询是"OOL 轻量版"：一次只查一个对象，最多 3 层深，禁点号引用
order_to_product 是 N:N 占位链接，暂查不到"订单里有哪些商品"明细
语义检索的向量增强默认关闭，口语化描述可能命中不了
Action 回写仅支持 SQL 类，对接外部系统的 HTTP/API 类回写未实现

适用角色

本主题面向两个角色：

数据工程师：配置数据源、做本体建模、走版本合入——是核心使用者，掌握对象 / 属性 / 链接 / Action 的定义。
业务分析师：消费对象与指标，用对象查询 / 语义检索自助取数，通过 Action 完成受控的数据变更。

平台管理员负责权限与审计；业务决策者通过指标口径（total_gmv / aov）消费结论，不直接操作。

能力速览（能做什么）

本体工作台

把表建模为 customer / order / product 对象，配置属性映射、主键、同义词、PII 标记与约束（enum / range / unique）。

对象查询 + 语义检索

按业务语言选对象、加过滤条件即可取数；语义检索帮你找到正确的对象、属性与指标口径。

Action 写路径

唯一的写入口：先 VALIDATE 预校验、再执行，带乐观锁防冲突、幂等防重放、强制审计留痕。

版本治理

任何本体改动走 draft → review → merged，保存版本快照与变更 diff，合入前做影响分析。

指标语义层

entity / dimension / measure / metric 四层结构，把 total_gmv、aov 等口径集中管理，避免"口径对不上"。

调整指南（怎么调整）

改属性口径：给 region 属性加同义词（"区域、大区"）提升语义检索命中率；给 name 加 PII 标记，列级安全会自动生效。
改查询范围：想按客户维度看订单，用 customer_to_order 链接 traverse 到客户再过滤；单对象内用 eq / gte / contains 等过滤算子。
改 Action 行为：执行时务必带上 expected_updated_at 乐观锁期望值，减少 409 冲突；批量改先 VALIDATE 再执行。
改版本流程：关键对象可配置审批策略（最少批准人数、指定评审人），未过审不得合入；大改动在草稿里分步提交，diff 更清晰。
改指标口径：到指标管理里维护 entity / measure / metric，口径变更走审批，不开放随意改。

做得好的场景

Foundry 把"数据 → 对象 → 查询 → 写回 → 治理"收进同一套系统，特别适合以下场景：

快速建模上线：数据工程师十几分钟走通"数据源 → 对象 → 查询"，替代以前 3~7 天的 SQL + 接口排期。
业务自助取数：分析师不写 SQL，用对象过滤 + 指标口径秒级取数，口径不再靠人对。
受控的数据变更：改订单状态走 Action 唯一写路径，RBAC + 乐观锁 + 幂等 + 审计全自动，改坏了查得到、退得回。
核心对象受控演进：版本快照 + 影响分析，改 order 这样的核心对象不用心惊胆战。

限制与不足

以下是明确的边界，使用前先知道：

查询能力受限：对象查询是 OOL 轻量版（单对象、≤3 层深、禁点号），跨对象复杂 join 要拆开分步查。
占位链接：order_to_product 的 join 表 order_items 只是占位映射，当前查不到"订单买了哪些商品"的明细。
语义检索无向量增强：默认靠元数据 / 同义词文本匹配，口语化或新词可能命中不了。
回写类型有限：Action 只支持 SQL 类回写，HTTP / API 类（对接外部系统）未实现。
demo 数据每次启动重建：回写到源表的改动重启后会被还原，但编辑态与审计记录保留在平台库。

场景故事

故事 1 数据工程师首次接入数据源，建出第一个客户对象

场景：数据接入角色：数据工程师耗时：约 10 分钟

背景: 张工是刚接手电商分析的"数据工程师"。订单、客户数据散落在演示数据源 foundry_demo_warehouse（SQLite）里，他希望把这些表变成"看得见、查得动"的业务对象，让不懂 SQL 的同事也能自助取数。今天的第一步：把 customers 表建成 customer 对象。

传统做法对比: 以前要人先看 ER 图、写建表 SQL 和一堆接口文档，再让 IT 排期开发查询接口，快则 3~7 天；中间任何字段口径变化都要重走一轮。现在在平台里十几分钟就能走通"数据源 → 对象 → 查询"。

角色: 数据工程师（拥有本体建模与数据源管理权限）；后续由业务分析师直接消费对象。

操作步骤

登录平台（admin / admin1，端口 18081 或经 5173 的 /api 前缀）
侧边栏"数据源"确认 foundry_demo_warehouse 已注册并导入元数据
进入"本体工作台"，点击"新建对象"
填写 api_name=customer、显示名=客户，选主表 customers、主键 customer_id
映射 customer_id / name / region 三个属性后保存

系统响应

POST /api/ontology/objects 创建成功返回 {"id": 1}，侧边栏对象列表立即出现 customer；对象详情返回其定义结构：

{
  "id": 1,
  "name": "customer",
  "display_name": "客户",
  "base_table": "customers",
  "pk_column": "customer_id",
  "status": "merged",
  "version": 1
}

属性（customer_id / name / region）挂在 properties 子资源上。

结果洞察: 对象就绪后，在"对象查询"选中 customer 即可查出 3 条客户记录（张三·华东、李四·华北、王五·华南）。属性级权限、同义词、PII 标记都可在属性上继续配置，为后续语义检索打底。

调整建议: 给 region 属性加同义词（如"区域、大区"）方便语义检索命中；给 name 打 PII 标记，列级安全会自动生效；映射列名与源表列核对一致，避免查询为空。

动手试一试: 登录：http://127.0.0.1:18081（或 Vite 5173），账号 admin / admin1。页面路径：数据源 → 本体工作台 → 新建对象。输入内容：api_name=customer、主表 customers、主键 customer_id、属性 customer_id/name/region。预期结果：创建成功，对象查询选 customer 返回 3 条客户记录。

限制提示: 对象查询是"OOL 轻量版"——单对象遍历、最多 3 层深、禁点号引用，跨对象复杂 join 要拆开分步查；demo 数据源每次启动重建，临时改动重启后会被还原。

故事 2 业务分析师按业务语言查"华东客户的待处理订单"

场景：自助查询角色：业务分析师耗时：约 3 分钟

背景: 王姐是业务分析师，被问到"华东客户的订单里，还有哪些没发货？金额大概多少？"她不会 SQL，但平台上已经有 customer / order 对象和 sales 指标口径（total_gmv、aov），可以完全自助回答。

传统做法对比: 以前要写工单给数据团队，等 1~2 天拿一张临时报表；口径对不对还要反复核对。现在直接在页面上选对象、加过滤，秒级出结果，还能用指标口径对答案。

角色: 业务分析师（只读查询权限即可，无需建模权限）。

操作步骤

登录平台后打开"对象查询"
选中 order 对象，添加过滤条件 status = pending
（可选）再到"语义检索"输入"华东客户待处理订单"，看平台推荐的对象 / 属性 / 指标
执行查询，查看结果

系统响应: 对象查询返回订单行列表（order_id、customer_id、amount、status、created_at）；语义检索返回结构化建议：对象 order、属性 status、指标 total_gmv / aov 及匹配说明。

结果洞察: 演示库里 pending 的订单是 order_id=2（李四，995 元）。结合指标 aov（客单价）可以快速判断订单量级；因为口径都在指标语义层统一管理，"口径对不上"的问题明显减少。

调整建议: 想按客户维度看，可先用 customer_to_order 链接 traverse 到客户再过滤；常用查询沉淀为团队习惯，让同事在"对象查询"直接复用；口径问题去指标管理核对 total_gmv / aov 定义。

动手试一试: 登录：admin / admin1。页面路径：侧边栏"对象查询"。输入内容：对象 order，过滤 status = pending。预期结果：返回 1 条 pending 订单（order_id=2、金额 995）；再到"语义检索"输入"销售额"，预期命中指标 total_gmv。

限制提示: 语义检索的向量增强默认关闭，主要靠元数据 / 同义词文本匹配，极端口语化描述可能命中不了；order_to_product 是 N:N 占位链接（join 表 order_items 仅为占位），当前查不到"某订单买了什么商品"的明细。

故事 3 运营用 Action 把 pending 订单改为 shipped（写回 + 乐观锁）

场景：数据变更角色：运营人员耗时：约 5 分钟

背景: 小陈是订单运营。演示库里 order_id=2 的订单状态还是 pending，但货已发出。她要在平台里把它改成 shipped——不能直接改库，必须走唯一写路径 Action（update_order_status）。

传统做法对比: 以前要么找 DBA 手写 UPDATE（无审计、无回滚，出了事查不到谁改的），要么走线下 OA 审批再人工同步，一次状态变更动辄半天。现在平台里先 VALIDATE 预校验、再执行，全程留痕。

角色: 运营人员（需有 update_order_status 动作的执行权限）。

操作步骤

在"对象查询"查 order，记下 order_id=2 及其 updated_at（乐观锁期望值）
打开"Action 测试"，选择 update_order_status
填写 order_id=2、status=shipped、expected_updated_at=刚查到的值
先点 VALIDATE 做预校验（不落盘）
再选 VALIDATE_AND_EXECUTE 正式执行

系统响应: VALIDATE（dry run）返回 {"mode":"VALIDATE","status":"success","validation":{}}，不落盘、不写幂等登记；正式执行（VALIDATE_AND_EXECUTE）返回 {"mode":"VALIDATE_AND_EXECUTE","status":"success","operation_id":"run_<id>","rows_affected":1}；再次查询 order_id=2 状态已变为 shipped。

结果洞察: 状态变更已写回源表（orders），编辑态写入 ontology_edits 可回溯修改前状态（prior state），审计日志与血缘 Action 边同步生成——"谁在何时改了什么"一查便知。平台还实现了编辑态读叠加：即使源表值被外部覆盖或还原，对象查询仍返回编辑后的值（编辑态永久优先），改完立即可查。若同一行已被别人改过，会返回 409 ACTION_CONFLICT（乐观锁：受影响行数为 0，不会静默覆盖），响应体附 latest_state，重新查询拿到最新 updated_at 作为新期望值重试即可。

调整建议: 批量改状态先 VALIDATE 跑一遍再批量执行，避免无效写；把 expected_updated_at 传对，减少 409 冲突；重复提交同一幂等键会返回首次结果（ACTION_IDEMPOTENT_REPLAY），不会重复执行。

动手试一试: 登录：admin / admin1。页面路径：对象查询 → Action 测试。输入内容：order_id=2、status=shipped、expected_updated_at=查询到的 updated_at。预期结果：VALIDATE 返回 status=success；执行后返回 operation_id 与 rows_affected=1，再查询可见订单状态变为 shipped。

限制提示: HTTP 200 不等于成功，必须看响应体的 status 与 validation_result（成功判定 result==VALID）；响应体含 validation / edits / latest_state 等字段，其中 edits 目前只返回变更行数、无逐记录明细。写路径支持 SQL 类回写的四种编辑类型（create / modify / delete / link），HTTP / API 类（对接外部系统）未实现；demo 数据源重启重建，回写到源表的改动会重置，但编辑态（ontology_edits）与审计记录保留在平台库中。

故事 4 给订单对象加"优先级"属性：draft → review → merge 受控变更

场景：版本治理角色：数据工程师 + 评审人耗时：约 8 分钟

背景: 张工要给 order 对象新增一个"优先级"属性（enum：高 / 中 / 低）。但 order 是被销售指标（total_gmv、aov）引用的核心对象，不能直接改线上定义。平台用"草稿 + 评审 + 合入"的浓缩版版本流程来治理这类变更。

传统做法对比: 以前改表 / 改模型往往直接线上改，没有评审、没有历史快照，改坏了只能靠记忆回滚。现在任何变更都有版本快照与 diff，可对比、可回滚、可审批。

角色: 数据工程师（改 draft）+ 评审人 / 管理员（提交 review、合入 merge）。

操作步骤

进入"版本历史"，找到 order 对象
新建草稿（draft），在草稿中添加属性 priority（enum 高 / 中 / 低）
提交评审（review），状态机 draft → review
查看影响分析，确认受影响的指标与对象
合入（merge），线上对象版本号 +1

系统响应: 草稿保存后返回 draft 版本与 change_diff（新增属性 priority）；提交评审后进入 review 状态（含 requires_approval 动作时自动要求至少 1 人审批且不可自我批准）；merge 前校验审批票数与聚合冲突检测，通过后返回影响分析结果——列出受影响的指标（total_gmv / aov 引用 order 对象）与建议；合入成功 status=merged。

结果洞察: 变更受控、全程留痕；对象查询里 order 现在多出 priority 字段，历史版本可随时查看 / 回滚。若与 main 上其他人对同一属性冲突，merge 会阻塞并提示人工解决。

调整建议: 大改动先在草稿里分步提交，diff 更清晰；被其他对象 / 指标引用的属性删除会被拒绝，先清理依赖再删；关键对象可配置审批策略（requires_approval 动作即自动要求审批），用版本页的 approve / reject 过审，未过审不得合入；merge 冲突检测为"聚合真冲突"——main 上多版本累计改过同一资源（modify/delete）才拦截，改别的资源会自动合并放行。

动手试一试: 登录：admin / admin1。页面路径：版本历史 → order → 新建草稿。输入内容：添加属性 priority（enum：高,中,低），提交评审后合入。预期结果：状态机 draft → review → merged 走通，order 对象 version 递增，对象查询出现 priority 字段。

限制提示: 这是"浓缩版"版本管理（版本快照 + 变更 diff），不是真正的全局分支，复杂多人并行场景能力有限；demo 默认审批策略宽松，审批强度需自行配置；草稿修改对线上查询不生效，必须合入后才可见。

常见问题

故事里的数据是真实的吗？

是演示数据源 foundry_demo_warehouse（SQLite）的真实数据：3 个客户、5 个订单（含 1 个 cancelled）、3 个商品。每次启动服务器会重建演示数据，方便反复练习；平台元数据与编辑态记录则持久保存在平台库。

故事里的"动手试一试"需要什么环境？

启动 Foundry 后端（端口 18081）后，用 admin / admin1 登录。也可以通过前端 Vite（5173）的 /api 前缀访问同一后端。全部功能都在侧边栏里：本体工作台、版本历史、Action 测试、指标管理、语义检索、对象查询、数据源等。

对象查询和语义检索有什么区别？

对象查询是"精确过滤"：明确选对象、加条件，适合已有明确目标；语义检索是"找口径"：输入业务语言，平台返回匹配的对象、属性与指标，适合不确定去哪查时先探路。

为什么说 demo 数据"每次启动重建"？

演示数据源是启动时现场生成的 SQLite 文件（customers / orders / products），重启会删掉重建。因此回写到源表的改动会被还原；但 Action 的编辑态（ontology_edits）、审计日志等平台数据不受影响，仍可回溯。

对象查询能像 SQL 那样随意 join 吗？

不能。它是 OOL 轻量版：一次只查一个对象，最多 3 层深，禁止点号引用（related.field 不允许）。跨对象用 traverse 进入相邻对象再过滤；复杂跨源 join 不在当前能力范围内。

主题小结

一句话：Foundry 的入门路径是"先建对象、再查对象、用 Action 改对象、靠版本护对象"。对象（Object）是数据的业务表达，查询用业务语言，写回走唯一受控入口，版本让一切变更可追溯。记住几个边界：查询是轻量 OOL、order_to_product 是占位链接、语义检索无向量增强、回写仅 SQL 类。