業務イベント仕様 作成ルール

Business Event Specification (BES) Documentation Rules

BES は、BEL（業務イベント一覧）の各イベントについて、重要/複雑なものだけ を詳細化するための仕様です。

1. 位置づけ

• BEL: イベントを網羅する一覧（表）
• BES: イベント1件の記述を 責務の範囲で 最小限に明確化（何が起きたか/いつ/誰が・何が/発生条件/事実データ）
• BPS: イベントを契機に動く業務プロセスの手順（詳細手順ガイドは BPS 側に寄せる）
• BR: 判断/計算ロジック（BES には直書きせず、必要なら implements で参照）

2. いつ BES を作るか

次のいずれかに当てはまる場合に作成します。

前提:

• BES の本文は「何が起きたか / いつ / 誰が／何が / 発生条件 / 事実データ」の 事実（観測） に限定します。
• それでも、BEL の 1 行だけでは 解釈が割れやすい（= 後工程が迷う）場合があり、そのとき BES を作成します。

判断基準（BEL 1 行では足りないサイン）:

• 何が起きたか の解釈が割れる（例: 「確定」「受付」「取消」「訂正」「差戻し」など、事実の境界が曖昧）
• いつ の基準が割れる（例: 入力時/承認時/締め処理時/外部応答時 のどれを指すかが曖昧）
• 誰が／何が が混在して割れる（例: 人の操作/システム自動/外部起点が混ざり、起点が一意にならない）
• 発生条件 が複数パターンで揉める（例: 部分返品、分割納品、在庫差異の許容、締め済みへの訂正など）
• 事実データ の範囲が合意できない（例: ID体系、金額内訳、訂正元ID、理由の必須性、個人情報の含有可否など）

目安:

• 重要な「確定」を伴う出来事（売上確定/在庫確定/会計確定など）は、上記の曖昧さが起きやすいため BES 化を優先検討します。

2.1 BEL からのリンク

個別 BES を作成したら、対応する BEL の一覧表で イベントIDをBESファイルへのリンク に更新します。

• 例（例示はコード表記）: [bes-sale-checkout](./bes-sale-checkout.md)

3. メタデータ（Frontmatter）

Frontmatter は docs/handbook/shared/schemas/spec-frontmatter.schema.yaml の制約に従います。

項目	説明	必須
id	BES ID（例: bes-sale-checkout）	○
type	domain 固定	○
title	業務イベント名（例: 業務イベント: 会計確定（販売））	○
status	draft/ready/deprecated	○
based_on	根拠となる仕様ID（BEL/UIS/BPS 等）	任意
supersedes	置き換え関係（古仕様→新仕様）	任意

3.1 ID規約

• BES ID は bes-... の形式を推奨します（例: bes-sale-checkout）。
• type: domain は業務ドメイン仕様であることを示します。

4. 本文テンプレ（最小）

BES の責務は次に 限定 し、各項目を見出しとしてこの順序で記述します。

1. 何が起きたか
2. いつ
3. 誰が／何が
4. 発生条件
5. 事実データ

補足:

• 結果（出力/状態変化/通知）や例外、購読先、詳細手順は BES の責務外です。必要なら BPS（業務プロセス仕様）側で扱います。
• イベントとプロセスは独立に保ち、起動関係は BPS（業務プロセス仕様）側で記載します。

5. 禁止事項

項目	理由
物理テーブル名・物理カラム名・SQL全文	概念レベル逸脱
実装クラス/関数名・APIの実装詳細	実装依存で変更に弱い
UIコンポーネント名、クリック手順の逐語列挙	UI変更に弱い
BRのロジックを本文に重複記載	変更時に不整合が起きる

6. サンプル（最小）

---
id: bes-sale-checkout
type: domain
title: 業務イベント: 会計確定（販売）
status: draft
part_of: []
based_on:
 - bel-sale
 - uis-sale
supersedes: []
---

## 1. 何が起きたか

- 販売の会計が確定した。

## 2. いつ

- 会計確定操作の実行時。

## 3. 誰が／何が

- 店員（人）。

## 4. 発生条件

- 対象の取引が確定可能な状態である。

## 5. 事実データ

- 取引ID
- 明細（商品、数量、単価 等）
- 支払情報（支払方法、受領金額 等）

7. 生成 AI への指示テンプレート

• 以下のルールに従って、業務イベント（BEV）仕様 を 1 つ作成してください。出力は Markdown とします。

• 対象は 1 つの業務イベント（bes-...）です。

• 業務イベントの責務は次に 限定 してください：

  何が起きたか / いつ / 誰が／何が / 発生条件 / 事実データ

• 結果（出力/状態変化/通知）や例外、購読先、詳細手順は書かないでください（BPS 側へ寄せる）。

• 禁止: 物理テーブル名・物理カラム名・SQL全文、実装クラス/関数名・API実装詳細、UIコンポーネント名、クリック手順の逐語列挙

• 先頭に YAML Frontmatter を付与し、以下の形式で記述してください（id / type / title / status は必須）：

  ---
  id: bes-<英小文字とハイフンで構成したID>
  type: domain
  title: 業務イベント: <イベント名>
  status: draft
  part_of: []
  based_on: []
  supersedes: []
  ---

• 本文は次の見出し（日本語）をこの順序で必ず含めてください：

  1. 何が起きたか
  2. いつ
  3. 誰が／何が
  4. 発生条件
  5. 事実データ

• 事実データ は、その時点で観測できる情報（ペイロード）を概念レベルで列挙してください。

• イベントとプロセスは独立に保ち、起動関係は BPS（業務プロセス仕様）側で記載してください。

• 判断/計算が必要な場合は、本文に直書きせず implements に br-... を列挙してください。

• この BES を作成した場合、対応する BEL の一覧表ではイベントIDをリンクに更新する前提で作成してください（例示はコード表記）：[bes-...](./bes-....md)