ontopoc

用数据回答一个业务问题：模型把问题写成查询，代码在数据上算答案。不给 question 就让模型出一组题。会调用模型，慢且花钱。每道题有 status：answered 答出来了；no_data 数据里没有满足条件的对象；query_limit 查询写不出来、ontology_gap 本体缺回答它要的东西（reason_from_model 为 true 时是模型的判断；否则是代码查出来的原因，照 reason 告诉人）；needs_derived 要一个派生指标，derive 里是公式和试算，人同意后才 confirm_derived。evidence 是代码给的核对依据：filters 是查询里的筛选条件（before、after 是筛前筛后的对象数，removed_measure 是筛掉的那部分的合计），其中 not_in_question 的是模型自己加的、题目没提，该不该加由人定，不加用 drop_filter 去掉重算；merged 是被算成同一个的对象组（同一个名字下有几个不同的识别值）；found_elsewhere 是 no_data 时，这个值在别的对象里能找到的地方。口径卡：refused_by_card 是被卡上的哪一格拒答的（status 是 query_limit，reason 是代码给的），照 reason 告诉人，不要换问法绕过；evidence.card 是答案用了哪张表、数据到哪天（tables）、按哪几条口径（lines），incomplete 是对象在数据里只有一部分，要转告人。

上传文件并建本体：模型提出、代码核验、数据体检、建三次比稳定性，并回答 purpose 里写的问题。给 previous 表示这是那次运行的新版本，沿用它的确认、验收问题和规则。会调用模型，等它跑完才返回；返回的概况同 run_overview，也带 open_items、answered_items、card。

拿一份人写的参考本体（JSON）和这次的本体对照：哪些对象、关系对上了，哪些多了、少了。

确认一个派生指标（例如 金额 = 单价 × 数量 ×（1 − 折扣））：服务再核一遍公式，存下后重算等它的题。只在人看过公式和试算结果、同意之后调用；derive 用那道题返回的 derive 原样传。

保存人对本体的逐项判断，成为这个文件的参考本体并马上对照。decisions 形如 {"types": {"<对象key>": {"verdict": "ok"|"wrong", "label": "改名（可选）"}}, "relations": {"<关系key>": {"verdict": "ok"|"wrong"}}, "added": ["漏掉的对象名"]}。

数据体检：七项检查是否通过，以及每类发现的数量和前几个例子。全部由代码算。

上传的每张表：行数、跳过的标题行、每列类型长度空值；表没连上时，能把它们连起来的列。

让字段释义员起草对象表单里只有人能写的列：每个对象和字段的中文名、一句话描述、展示字段。一次模型调用；人写过的不会被覆盖。

去掉模型自己加在一道题上的一个条件，用本机代码重算，不调模型；新答案作为这道题新的一次追加到记录里并返回，想固定它再用 fix_question。用在人同意去掉模型自己加的条件之后（evidence.filters 里 not_in_question 的那些）。field、equals 两种写法都认：照 evidence.filters 里那一条写（字段不带表名），或照这道题 query.where 里那一条原样写（字段带不带表名以查询为准）。

按对象表单导出：每个对象一张 CSV（主键、展示、中文名称、英文名称、描述、类型、长度、属性类型）和一份说明。导入契约还没实测，说明里写着导入前要测。文件写到本机的一个文件夹（out_dir，默认在下载文件夹里），同名覆盖，只返回文件的路径和字节数 {dir, files: [{name, path, bytes}], total_bytes, removed}，不返回文件内容。文件夹里会留一份清单 .ontopoc-export.json，记着这一类导出这次写了哪些文件；再导出到同一个文件夹时，上次清单里有、这次没有的文件会被删掉（removed 是删掉的文件名），清单以外的文件不碰。文件名必须是单纯的文件名，否则整次导出报错、一个文件也不写。

组织架构模式的运行导出组织图（Mermaid）：组织隶属.mmd（隶属、汇报、担任）和协作交接.mmd（协作、交接及交接内容）。years 写 2016-2022 只画这段时间的关系，没写时间的关系每段都画；判错的不画。文件写到本机的一个文件夹（out_dir，默认在下载文件夹里），同名覆盖，只返回文件的路径和字节数 {dir, files: [{name, path, bytes}], total_bytes, removed}，不返回文件内容。文件夹里会留一份清单 .ontopoc-export.json，记着这一类导出这次写了哪些文件；再导出到同一个文件夹时，上次清单里有、这次没有的文件会被删掉（removed 是删掉的文件名），清单以外的文件不碰。文件名必须是单纯的文件名，否则整次导出报错、一个文件也不写。

生成编排需求单，交给搭管道的人：把体检、要确认的事、口径卡、派生指标和采纳的规则里已经说了的“这份数据要怎么加工才能算对”合成一份清单——每张表要做的清洗、表之间怎么关联、按期取数、计算列、编排后的校验、还没说清的；每条写明来源（代码查出、客户答复、人确认）。写出 编排需求单.md 和 编排需求单.json。只描述要做什么，不执行加工，不调用模型，没有模型 key 也能导出。文档运行和没通过核验的运行没有需求单，服务的说明作为工具错误原样返回。文件写到本机的一个文件夹（out_dir，默认在下载文件夹里），同名覆盖，只返回文件的路径和字节数 {dir, files: [{name, path, bytes}], total_bytes, removed}，不返回文件内容。文件夹里会留一份清单 .ontopoc-export.json，记着这一类导出这次写了哪些文件；再导出到同一个文件夹时，上次清单里有、这次没有的文件会被删掉（removed 是删掉的文件名），清单以外的文件不碰。文件名必须是单纯的文件名，否则整次导出报错、一个文件也不写。

按 W3C 标准导出 Turtle：ontology.ttl（OWL 类、字段、关系、识别键）、data.ttl（每个对象按识别值命名，同一对象跨表跨版本同名）、shapes.ttl（采纳的规则写成 SHACL，有规则时才有）。判错的对象和关系不导出。文件写到本机的一个文件夹（out_dir，默认在下载文件夹里），同名覆盖，只返回文件的路径和字节数 {dir, files: [{name, path, bytes}], total_bytes, removed}，不返回文件内容。文件夹里会留一份清单 .ontopoc-export.json，记着这一类导出这次写了哪些文件；再导出到同一个文件夹时，上次清单里有、这次没有的文件会被删掉（removed 是删掉的文件名），清单以外的文件不碰。文件名必须是单纯的文件名，否则整次导出报错、一个文件也不写。

按名称或编号找数据里的某个对象（实例图谱的起点），给出节点 id；对象类型没有名称字段时 name 就是识别值。

找出同一类对象里可能是同一个东西的不同写法，只给建议、不合并。会调用模型。

把问过的一道题固定为验收问题：以后重传同一份文件，用同一个查询再算一次。只在人明确说了之后调用。这道题的答案里有模型自己加的条件（evidence.filters 里 not_in_question、且筛掉了对象）时，note 不写就报错：先问人，不该加用 drop_filter 去掉重算，该加就在 note 里写明口径。

一次运行的口径卡（数据是什么意思）：每张表一行是什么、日期列的最早最晚和空值、数值列的类型，以及已答复的格（answer：value、says、by、basis、at）和对象全不全。代码能算的已经算好，只有人能答的留空；blank 是还没说清的格数。文档运行没有卡，返回空的 tables。格的 value 只能是下面的值，种类看 id 冒号前的那段，等号后是意思：grain（一行是什么）：one_object=一行就是一个对象、event=一行是一次事件或一次修改（同一个东西有多行）、period=一行是一段时期的汇总、unsure=说不清；date（日期列是什么时间）：business=业务发生的日期、system=系统录入或修改的时间、fetched=取数的时间、unsure=说不清；amount（数值列能不能加）：flow=每行是这一笔自己的数，可以跨行相加、running=每次事件后的累计值、latest=截至最近一次的值、period_to_date=期初到期末的累计值、not_amount=不是数量（编号或代码）、unsure=说不清；complete（对象全不全）：full=数据里是全的、partial=数据里只有一部分、unsure=说不清。日期范围格 range 的 value 写 {"from": "YYYY-MM-DD" 或 null, "to": "YYYY-MM-DD" 或 null}。

本机建模服务是否在跑、有没有模型凭据、是否在跑旧代码。

实例图谱：一个对象的字段，和数据里与它相连的对象；每条关系先给 20 个，其余计数。

本体里的对象：名称、说明、来自哪些表、识别字段、数据里有多少个、几条关系、人的判断。人判错的默认不给，列在 left_out 里；include_wrong=true 全给。

这次运行里模型出的题（model_round）、人问过的题（asked）和固定的验收问题（acceptance），带答案和查询路径。每道题有 status：answered 答出来了；no_data 数据里没有满足条件的对象；query_limit 查询写不出来、ontology_gap 本体缺回答它要的东西（reason_from_model 为 true 时是模型的判断；否则是代码查出来的原因，照 reason 告诉人）；needs_derived 要一个派生指标，derive 里是公式和试算，人同意后才 confirm_derived。evidence 是代码给的核对依据：filters 是查询里的筛选条件（before、after 是筛前筛后的对象数，removed_measure 是筛掉的那部分的合计），其中 not_in_question 的是模型自己加的、题目没提，该不该加由人定，不加用 drop_filter 去掉重算；merged 是被算成同一个的对象组（同一个名字下有几个不同的识别值）；found_elsewhere 是 no_data 时，这个值在别的对象里能找到的地方。口径卡：refused_by_card 是被卡上的哪一格拒答的（status 是 query_limit，reason 是代码给的），照 reason 告诉人，不要换问法绕过；evidence.card 是答案用了哪张表、数据到哪天（tables）、按哪几条口径（lines），incomplete 是对象在数据里只有一部分，要转告人。

本体里的关系：两端、含义、来源表、基数、人的判断。cardinality 是 one_to_one / one_to_many / many_to_one / many_to_many，方向是 from 到 to；reads 用两端对象的名字把它读成一句中文，most_from 是一个 from 对象最多对应几个 to，most_to 是一个 to 对象最多对应几个 from。判错的、或一端对象判错的默认不给，列在 left_out 里；include_wrong=true 全给。

代码在数据里找到的规则（某字段每个对象都有值；两个日期总是先后有序）和人采纳的规则，采纳的带本次数据里的违反数和例子。

本机保存过的运行，新的在前。

一个对象的属性：每个字段的类型、长度、空值和来源表（交接到数据平台时要填的列）。

一个对象在数据里的每一个实例，一页 20 个；all=true 一次给全部。

不调用模型：看这几份文件会发给模型什么（字段名、示例值、代码在全部行上数出的计数、每行都不同的列和可能的连接）。

一次运行的概况：对象和关系数、体检通过几项、问答能答几道、稳定性、是否确认过；open_items 是要和客户确认的事（服务算好的清单，每项有 kind、ask、facts、from_model、target），先看它，是要带给人的事。answered_items 是已记下客户答复的事，card 是口径卡的格数 {cells, blank}（blank 是还没说清的格，看细节用 get_card）。服务是旧版本、没有这个清单时 open_items、answered_items 为 null，note 里说明；card 只有在旧版服务没有这条路由时才是 null，没有数据行的运行（文档、没通过核验）给 {cells:0, blank:0}。文档运行没有要和客户确认的事，也不会去请求这份清单和口径卡：open_items、answered_items 直接给 []。

记下客户对口径卡的答复，也可以记下“要确认的事”里能答复的事的答复。只记人说的客户答复：by（答复人）和 basis（出处）都来自人，不要自己填格，不要替客户答，不要按列名猜；只在人明确说了之后调用。校验不过整次不写，服务的说明原样返回。cells 每项 {id, value, note?, basis?}：id 来自 get_card，value 是那一格可选的值，null 表示清空。格的 value 只能是下面的值，种类看 id 冒号前的那段，等号后是意思：grain（一行是什么）：one_object=一行就是一个对象、event=一行是一次事件或一次修改（同一个东西有多行）、period=一行是一段时期的汇总、unsure=说不清；date（日期列是什么时间）：business=业务发生的日期、system=系统录入或修改的时间、fetched=取数的时间、unsure=说不清；amount（数值列能不能加）：flow=每行是这一笔自己的数，可以跨行相加、running=每次事件后的累计值、latest=截至最近一次的值、period_to_date=期初到期末的累计值、not_amount=不是数量（编号或代码）、unsure=说不清；complete（对象全不全）：full=数据里是全的、partial=数据里只有一部分、unsure=说不清。日期范围格 range 的 value 写 {"from": "YYYY-MM-DD" 或 null, "to": "YYYY-MM-DD" 或 null}。items 每项 {id, choice?, text?, basis?}：id 来自 run_overview 的 open_items，choice 的可选值看事的种类（unlinked：expected、incomplete；same_name、merged：distinct、same），没有 choice 时 text 必填。unlinked 答“数据没导全”（incomplete）时，服务会自动把另一端对象在卡上记成“只有一部分”，改答复时撤回，不用另发那一格。cells 和 items 至少给一样。写完返回 {card, items, answered}。

保存对象表单。form 形如 {"types": {"<对象key>": {"label": "中文名", "description": "描述", "display_field": "字段", "drafted": false, "fields": {"<字段>": {"label": "…", "description": "…", "drafted": false}}}}}；drafted=false 表示人写的。

采纳或不要规则：adopted、declined 各写完整的规则 id 列表（id 来自 list_rules）。采纳的规则以后每次重跑都会检查。

代码在数据里看到、本体里没有的关系，只作建议：同一行上的两个对象没连起来；某列写的是别的对象的名称（且指向的不是本行已连着的那个）；或某列按名字和取值指向别的对象的编号。