Hane Platform

業務データ

型と項目の定義、値の状態と出典、レコードの読み書きと楽観的排他、絞込み、関係、CSV の取り込みを説明します。

このページでは、Hane の業務データ（Data サービス）の考え方と使い方を説明します。型をマニフェストで定義し、レコードを公開 API（/v1/data）で読み書きします。

型を定義する

業務データの型は、Schema と Ontology の 2 つのマニフェストで定義します。Schema は項目と値の形を、Ontology は型の意味と型どうしの関係を決めます。Schema を持つ型は、どれかの Ontology に載せる必要があります。

apiVersion: data/v1alpha1
kind: Schema
metadata:
  name: lease-contract
spec:
  type: LeaseContract
  key: contract_no            # 型の中で一意の業務上のキー
  display: contract_no        # 一覧で名前として出す項目
  fields:
    contract_no: { type: string, title: 契約番号 }
    start_date: { type: string, format: date, title: 開始日 }
    term_months: { type: integer, minimum: 1, maximum: 120, title: 契約月数 }
    end_date: { type: string, format: date, title: 満了日, computed: lease-end-date }
    monthly_fee: { $ref: provider:Money, title: 月額（税抜）, classification: confidential }
    status: { enum: [active, notice_sent, renewed, replaced, returned, terminated], title: 状態 }
  required: [contract_no, status]
  index: [end_date, status]

項目の指定	内容
`type`	`string`・`integer`・`number`・`boolean`
`format`	`date`（YYYY-MM-DD）・`date-time`・`email`
`enum`	選べる値の一覧
`$ref: provider:Money`	金額。値は `amount_minor`（通貨の最小単位の整数。円なら円）と `currency` を持つ
`computed`	計算の規則（`Rule`）の名前。値は規則が CEL で計算し、API からは書けない
`classification`	機密区分（`public`・`internal`・`confidential`・`restricted`）

型の関係は Ontology に書きます。temporal: valid-time の関係は有効期間を持ち、ある日にどの関係が有効だったかをたどれます。

apiVersion: data/v1alpha1
kind: Ontology
metadata:
  name: vehicle-lease
spec:
  types:
    LeaseContract: { label: リース契約, aliases: [契約, リース], schema: lease-contract }
    Vehicle: { label: 車両, aliases: [社用車], schema: vehicle }
  relations:
    covers: { from: LeaseContract, to: Vehicle, label: 対象の車両, cardinality: many-to-one, temporal: valid-time }

型を変えるときは、マニフェストを変えて新しい ReleaseBundle を有効にします。項目の名前や型を変えるときは Migration を書きます。詳しくは定義をコードで管理するを参照してください。

値の状態と出典

Hane の業務データは、値ごとに「どこまで確かめたか」と「どこから来たか」を持ちます。AI が読んだ値と人が確かめた値を区別するためです。

値の状態	意味
`confirmed`（確定）	書類か人の確認で裏付けた値
`estimated`（推定）	根拠はあるが確かめていない値。計算した値もここに入る
`pending_inquiry`（要照会）	書類から取れず、相手に問い合わせている値
`unknown`（不明）	取れておらず、問い合わせもしていない値

状態を指定せずに書いた値は推定になります。値が null なら不明です。
確定にできるのは、data:values.confirm のスコープを持つ人だけです。AI とサービスアカウントは確定にできません。
計算した値の状態は、入力の値のうち一番弱いものになります。
出典（source）は、取り込み・人・計算・文書・外部・Workflow のどれから来たかと、その詳細（文書のページと引用など）を持ちます。

レコードを読み書きする

レコードを作るときは、型と項目ごとの値を送ります。

POST /v1/data/records
Authorization: Bearer <API キー>
Idempotency-Key: 5c2a…
Content-Type: application/json

{
  "type": "LeaseContract",
  "values": {
    "contract_no": { "value": "C-1001" },
    "status": { "value": "active" },
    "start_date": { "value": "2024-04-01", "state": "estimated", "note": "車検証の初度登録から" },
    "monthly_fee": { "value": { "amount_minor": 52000, "currency": "JPY" } }
  }
}

応答はレコードで、ETag ヘッダーにレコードのバージョンが入ります。同じ型で同じキーのレコードがすでにあれば 409 です。

操作	API
取得（関係と変更の履歴を含む）	`GET /v1/data/records/{id}`
更新	`PATCH /v1/data/records/{id}`。`If-Match` と、任意で `reason`
項目の値の履歴	`GET /v1/data/records/{id}/values/{field}/history`
値を確定にする	`POST /v1/data/records/{id}/values/{field}/confirm`
有効な型と項目の一覧	`GET /v1/data/types`

楽観的排他

レコードは整数の version を持ち、更新のたびに上がります。更新には、取得したときの ETag を If-Match で送ります。

PATCH /v1/data/records/ent_01J…
Authorization: Bearer <API キー>
If-Match: "4"
Content-Type: application/json

{ "values": { "status": { "value": "returned" } }, "reason": "車両の返却を受けたため" }

If-Match がなければ 428 PRECONDITION_REQUIRED、ほかの人が先に更新していれば 412 PRECONDITION_FAILED です。412 のときは取得し直して、変更をもう一度当ててから送ります。SDK では ifMatch(version) でヘッダーの値を作れます。

一覧と絞込み

GET /v1/data/records は、1 つの型のレコードを一覧します。

パラメーター	内容
`type`	型（必須）
`where`	CEL の条件。変数は `record` と `states`（例: `record.status == "active"`）
`state`・`field`	`field` の値の状態が `state` のものに絞る
`include=relations`	各レコードに今の関係を含める
`limit`・`cursor`	1 ページの件数（最大 500）と、前のページの `next_cursor`

GET /v1/data/records?type=LeaseContract&where=record.status%20%3D%3D%20%22active%22&state=estimated&field=end_date
Authorization: Bearer <API キー>

関係をたどる読み取りには、型付きの問い合わせ（POST /v1/data/ontology/query）を使います。型と関係を定義と突き合わせてから、決まった段数（最大 3 段）だけたどります。自由な SQL やグラフの探索は受け付けません。

関係

関係は POST /v1/data/relations で、関係の型・元・先のレコードを指定して作ります。

多対一で有効期間を持つ関係は、新しい関係を作ると今の関係を valid_from（省くと今日）で閉じ、新しい関係をその日から始めます。
書いた関係は未確認（inferred）から始まります。POST /v1/data/relations/{id}/state で確定（confirmed）にするか、疑義（disputed）を記録します。確定にするには data:values.confirm を持つ人が要ります。

CSV の取り込み

既存の台帳は CSV で取り込めます。POST /v1/data/imports に型と CSV の本文を送ります。見出しは項目の名前で、<項目>@state の列で値の状態を、@rel:<関係> の列で関係の相手のキーを指定できます。状態を書かない値は、default_state（省くと推定）になります。hanectl では hanectl import <型> -f <ファイル> で取り込めます。

次に読む

Workflow と案件業務データのレコードを対象に案件を進める

文書書類から値を読み、確かめて確定にする

データと Workflow を使う業務アプリから使う手順

API リファレンス/v1/data の全要求