Relqis

Appearance

CLI インターフェース ​

Relqis では CLI を、会計エンジンを安全に操作するためのアダプタとして扱います。ドメイン規則を迂回するための近道としては扱いません。

コマンド探索モデル ​

help は 2 段階で使います。

  1. グループ探索: rlq entry --help、rlq postreq --help、rlq close --help
  2. 実行単位の詳細確認: rlq entry create --help、rlq postreq validate --help、rlq close month --help

rlq --help では、全体の操作モデル、コマンド群、ワークフロー、出力契約、終了コードの分類を確認できます。

close 系の automation では、check close --json を structured blocker read model として扱います。close month、close year preview/run、carryforward preview/run の失敗は v1.0 では summary message を返し、close-specific detail payload までは持ちません。

基本安全ルール ​

  • ledger entry が会計上の唯一の真実です。
  • posted 済み仕訳は不変です。
  • 手入力仕訳や開始仕訳も PostingRequest の意味論を通ります。
  • 状態が重要な書き込みコマンドの前には、読み取り専用の確認を挟みます。
  • close、reopen、carryforward、void のような監査上重要な操作では理由が必須です。

入力規約 ​

安定した識別子 ​

CLI は ENTRY_ID、POSTING_REQUEST_ID、FISCAL_PERIOD_ID のようなアプリケーションレベルの ID を前提にしています。エージェントは、あとから再試行や照合に使える安定 ID を生成してください。

行を含む read response には、永続化済みの entry_line_id も含まれます。後続コマンドで必要になったら、接尾辞の規則を推測するのではなく、entry show、journal show、ledger show、または validation 済みの postreq show から読み取ってください。

整数 minor unit ​

金額はすべて整数の minor unit です。

  • 10000 は 10,000 minor units を意味します
  • 借方と貸方の向きは dc_type で表します
  • コマンドが明示対応していない限り、負数は渡しません

構造化 JSON 入力 ​

構造化 JSON 入力を受け付ける書き込み系コマンドでは、--input PATH または --input - による stdin JSON を使います。

主な対象コマンド:

  • entry create
  • entry update
  • opening create
  • opening update
  • postreq create
  • postreq preview
  • receivable create
  • payable create
  • receipt create
  • payment create
  • bank-statement create
  • export-profile create
  • export-profile update

payload が構造化されている場合、他ツールが生成した場合、optional な dimension が疎な場合は、このモードを使ってください。

入力形状の概要:

  • entry create、entry update、opening create、opening update: トップレベル項目と lines を持つ 1 つのドキュメント
  • postreq create: posting_request_id、origin_type、entry_type、entry_date、lines などを持つ 1 つの起票要求ドキュメント
  • postreq preview: { "requests": [ ...postreq create と同じ要求ドキュメント... ] } というバッチドキュメント

例:

bash
rlq entry create --input ./entry-create.json --json

postreq create の入力例:

json
{
  "posting_request_id": "pr-import-001",
  "origin_type": "import",
  "origin_id": "row-42",
  "entry_type": "normal",
  "entry_date": "2026-04-10",
  "posting_date": "2026-04-10",
  "lines": [
    { "line_no": 1, "dc_type": "debit", "account_id": "cash", "amount_minor": 10000 },
    { "line_no": 2, "dc_type": "credit", "account_id": "sales", "amount_minor": 10000 }
  ]
}

entry create / entry update / opening create / opening update / postreq create は strict JSON 前提です。

receivable create / payable create / receipt create / payment create / bank-statement create も同じく strict JSON 入力です。field 名や required 項目は各 --help が唯一の正本です。

重要事項:

  • amount_minor は正数の minor unit です。
  • 借方か貸方かは dc_type で表します。
  • unknown field は reject されるので、生成側は typo を早めに検出できます。
  • subledger 系 create command では、税付き line を渡す場合でも JSON field 名で明示します。placeholder 位置を推測する必要はありません。

インポート前の事前確認 ​

主なリスクが仕訳バランスそのものではなく、master 不足や policy 不一致にある場合は、バッチを stage する前に postreq preview を使います。

  • postreq preview は読み取り専用で、状態を永続化しません。
  • 正式な入力は JSON のバッチドキュメントです。
  • 結果では ready と blocked、missing_masters、blocking_issues、policy_suggestions が要約されます。
  • バッチの外形は { "requests": [ ... ] } で、requests の各要素は postreq create と同じ形です。

読み取りと書き込みの区別 ​

コマンドは read-side の確認と write-side の変更に分けて扱います。

読み取り専用コマンド:

  • show
  • list
  • postreq preview
  • journal show
  • ledger show
  • trial-balance show
  • check close
  • export validate
  • trace entry

状態変更コマンド:

  • entry create
  • entry update
  • entry post
  • entry reverse
  • entry void
  • postreq create
  • postreq validate
  • close month
  • close reopen-month
  • close year
  • close reopen-year
  • carryforward run
  • export run
  • master data の create、update、enable、disable command

並行実行と再試行 ​

既存 aggregate を変更するコマンドでは、--expected-version が必要になることがよくあります。直前の show や mutation 結果で返された最新 version を使ってください。

オーケストレータがワークフローを再試行する可能性があるなら、使える箇所では idempotency 入力を優先します。

  • entry create --idempotency-key
  • entry copy --idempotency-key
  • entry reverse --idempotency-key
  • postreq create --idempotency-key

再試行の意味論は意図的に厳格です。

  • UUIDv7 方針は engine-owned な run/batch/system ID に適用します。manual/import の posting_request_id と validate-time entry_id は v1.0 では caller-managed boundary ID のままです。
  • master data や policy を修正した後で rejected な postreq validate、entry create、opening create をやり直す場合は、同じ posting_request_id を使います。
  • 同じ論理 request に対する postreq validate の再試行では、同じ entry_id を使います。
  • 異なる payload で同じ idempotency key を再利用すると、2 件目を作る代わりに conflict になります。
  • rejected な再試行でも、同じ論理 entry id に結び付いたままでなければなりません。

ファイルベースの SQLite 接続には短い busy timeout も設定しています。これは一時的な lock 競合を和らげますが、writer を直列化する代替にはなりません。

推奨探索パターン ​

  1. show または list で master data を確認します。
  2. 使えるなら、特に import 前の postreq preview のような読み取り専用 preflight を挟みます。
  3. mutation は --json 付きで実行します。
  4. 結果の aggregate を show で確認します。
  5. 状態と version を確認してから、次のライフサイクル段階へ進みます。