業務イベント仕様 作成ルール
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/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml の制約に従います。
| 項目 | 説明 | 必須 |
|---|---|---|
| id | BES ID（例: bes-sale-checkout） | ○ |
| type | requirement 固定 | ○ | | title | 業務イベント名（例: 業務イベント: 会計確定（販売）） | ○ | | status | draft/ready/deprecated | ○ | | based_on | 根拠となる仕様ID（BEL/UIS/BPS 等） | 任意 | | supersedes | 置き換え関係（古仕様→新仕様） | 任意 |
3.1 ID規約
- BES ID は
bes-...の形式を推奨します（例:bes-sale-checkout）。 type: requirementは機能・業務イベントの要件であることを示します。
4. 本文テンプレ（最小）
BES の責務は次に 限定 し、各項目を見出しとしてこの順序で記述します。
- 何が起きたか
- いつ
- 誰が／何が
- 発生条件
- 事実データ
補足:
- 結果（出力/状態変化/通知）や例外、購読先、詳細手順は BES の責務外です。必要なら BPS（業務プロセス仕様）側で扱います。
- イベントとプロセスは独立に保ち、起動関係は BPS（業務プロセス仕様）側で記載します。
5. 禁止事項
| 項目 | 理由 |
|---|---|
| 物理テーブル名・物理カラム名・SQL全文 | 概念レベル逸脱 |
| 実装クラス/関数名・APIの実装詳細 | 実装依存で変更に弱い |
| UIコンポーネント名、クリック手順の逐語列挙 | UI変更に弱い |
| BRのロジックを本文に重複記載 | 変更時に不整合が起きる |
6. サンプル（最小）
markdown
---
id: bes-sale-checkout
type: requirement
title: 業務イベント: 会計確定（販売）
status: draft
part_of: []
based_on:
- bel-sale
- uis-sale
supersedes: []
---
## 1. 何が起きたか
- 販売の会計が確定した。
## 2. いつ
- 会計確定操作の実行時。
## 3. 誰が／何が
- 店員（人）。
## 4. 発生条件
- 対象の取引が確定可能な状態である。
## 5. 事実データ
- 取引ID
- 明細（商品、数量、単価 等）
- 支払情報（支払方法、受領金額 等）