帳票仕様 作成ルール

Business Document Specification (BDS) Documentation Rules

本ドキュメントは、業務分析・要求定義のために 帳票仕様を統一形式で記述する標準ルールです。

帳票仕様は、業務ユーザーが利用する「出力物」（印刷物/PDF/CSV/Excel等）の内容を、業務用語でレビュー可能な形で定義します。

1. 全体方針

• 帳票は 業務ユーザー視点で、目的・出力タイミング・表示項目・集計/算出を明確にします。
• 実装詳細（例: 物理テーブル名・物理カラム名・SQL全文、実装クラス/関数名、テンプレートエンジンやライブラリ名）は記載しません。
• 1ファイル = 1帳票。

2. 用語定義

用語	定義
帳票	業務で利用する出力物（印刷物/PDF/CSV/Excel/画面出力等）
表示項目	帳票に出力される項目（ヘッダ、明細、フッタ、集計値、注記等）
抽出条件	対象データの範囲を決める条件（期間、店舗、状態、担当者等）
集計/算出	帳票内で計算・集計される値（合計、平均、税、差額、件数、グループ化）
出力形式	PDF/CSV/Excel/印刷/画面など、提供するファイル/媒体と形式
配布/配信	ダウンロード、メール送付、印刷、外部システム連携などの提供方法

3. ファイル命名・ID規則

• ファイル名: bds-<番号>-<短い日本語名>.md（例: bds-0010-日次売上サマリ.md）
• Frontmatter:
  • id: bds-daily-sales-summary のように小文字ハイフン形式
  • title: 「日次売上サマリ」などの帳票名

4. 推奨 Frontmatter 項目

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

項目	説明	必須
id	帳票ID（bds-...）	○
type	domain 固定	○
title	帳票名	○
status	draft/ready/deprecated	○
based_on	根拠となる仕様ID（BPS/UIS/BR/BES 等）	任意
supersedes	置き換え関係（古仕様→新仕様）	任意

4.1 ID規約

• BDS の id は正規表現 ^bds-[a-z0-9-]+$ に合致する一意IDを使用します。
• type: domain は業務ドメイン仕様（業務側の合意対象）であることを示します。

5. 本文構成（標準テンプレ）

各 BDS ファイルは以下見出しを順番に並べます。

1. 概要
2. 利用者/利用目的
3. 出力タイミング/トリガー
4. 出力形式/配布・配信
5. 抽出条件/対象範囲
6. 表示項目
7. 集計/算出ルール
8. 例外/注意事項
9. メモ / 将来課題

6. 記述ガイド詳細

6.1 概要

1〜3文で「この帳票が何を示すか」を業務用語で記述します。

6.2 利用者/利用目的

• 利用者（例: 店主、経理担当、バイヤー）
• 利用目的（例: 日次の売上状況を把握し、翌日の発注判断に使う）

6.3 出力タイミング/トリガー

• 出力の契機（例: 日次締め、会計確定、手動出力、バッチ）
• 対象期間の基準（営業日、締め日時、会計確定日時など）

6.4 出力形式/配布・配信

• 出力形式（PDF/CSV/Excel/印刷/画面）を明示します。
• 配布・配信（ダウンロード、メール送付、印刷、外部連携）を明示します。
• CSV 等のエクスポートがある場合は、- 文字コード（例: UTF-8）- ヘッダ行の有無 - 区切り文字（例: カンマ） を記載します（ただし実装ライブラリ名等は不要）。

6.5 抽出条件/対象範囲

• 対象となるデータの範囲（期間、店舗、担当者、ステータス等）を列挙します。
• 除外条件（取消は除外、締め済みのみ対象 等）があれば明記します。

6.6 表示項目

表示項目は表（Markdown table）で列挙します。レイアウト指定はせず、何が出力されるかを記述します。

推奨フォーマット:

No	区分	項目名	意味/定義	型・書式	出力例	備考
1	ヘッダ	出力日	帳票生成日	date	2025-12-20	-

補足:

• 「区分」は必要に応じて ヘッダ/明細/フッタ 等を使い分けます（不要なら省略してもよい）。
• 項目の意味が用語集にある場合は、備考に tm-... を併記して整合性を保ちます。

6.7 集計/算出ルール

• 集計単位（店舗別、商品別、日別など）とグルーピング条件を明確にします。
• 算出式は、業務上の意味が分かる形で記述します（例: 「売上合計 = 数量 × 単価 の合計」）。
• 端数処理、税の扱い、丸め（四捨五入/切り捨て/切り上げ）は明記します。

6.8 例外/注意事項

代表的な 2〜6 個の注意点（0件、権限不足、締め前/締め後の違い、欠損データ等）を列挙します。

7. 命名・記述スタイル

• 帳票名は「対象 + 観点 + 粒度」: 例 日次売上サマリ, 商品別粗利一覧, 発注候補リスト
• 記述は「業務用語」を優先し、略語は用語集にあるもののみ使用します。

8. 禁止事項

項目	理由
物理テーブル名・物理カラム名・SQL全文	概念レベル逸脱（DB設計に記述）
実装クラス/関数名、ライブラリ名	実装依存で変更に弱い
レイアウト/座標/ピクセル指定	要求定義段階で過剰、変更に弱い
クリック手順の逐語列挙	UI変更に弱い（必要なら UI 仕様へ）
「正しく出る」等の曖昧表現	検証不能

9. よくある誤りと対策

• 「どのDBから取るか」を書いてしまう → 「どの業務データを出力するか」に置き換える。
• 表示項目が列挙だけで目的が不明 → 「利用者/利用目的」を先に明確化する。
• 集計が曖昧（合計/税/端数） → 集計単位・端数処理・税の扱いを明記する。

10. サンプル（簡易）

---
id: bds-daily-sales-summary
type: domain
title: 日次売上サマリ
status: draft
part_of: []
based_on: [bps-closing-daily, uis-closing, bes-sale-checkout]
supersedes: []
---

## 概要

営業日ごとの売上合計と内訳を確認するための帳票。

## 利用者/利用目的

- 利用者: 店主、経理担当
- 利用目的: 日次の売上状況を把握し、締め処理の確認に使う

## 出力タイミング/トリガー

- 日次締め処理の完了後に出力できる
- 手動出力（必要に応じて再出力可）

## 出力形式/配布・配信

- 画面表示とPDFダウンロード

## 抽出条件/対象範囲

- 対象期間: 指定した営業日（1日）
- 対象店舗: ログインユーザーの所属店舗

## 表示項目

| No  | 区分   | 項目名   | 意味/定義              | 型・書式         | 出力例     | 備考                |
| --- | ------ | -------- | ---------------------- | ---------------- | ---------- | ------------------- |
| 1   | ヘッダ | 営業日   | 集計対象の営業日       | date(YYYY-MM-DD) | 2025-12-19 | -                   |
| 2   | 明細   | 売上合計 | 当日の売上合計         | integer(円)      | 12345      | 税抜/税込は別ルール |
| 3   | 明細   | 取引件数 | 会計確定した取引の件数 | integer          | 42         | -                   |

## 集計/算出ルール

- 売上合計: 会計確定した取引の合計
- 端数処理: 税計算の端数は切り捨て（br-tax-rounding に従う）

## 例外/注意事項

- 取引が0件の場合でも帳票は出力できる（売上合計=0、取引件数=0）

## メモ / 将来課題

- 将来: 商品カテゴリ別の内訳を追加検討

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

• 以下のルールに従って、帳票仕様（Business Document Specification: BDS） を 1 帳票分作成してください。出力は Markdown とします。

• 対象は 1 つの帳票（bds-...）です。業務ユーザー視点で、目的・出力タイミング・表示項目・集計/算出を明確にしてください。

• 禁止: 物理テーブル名・物理カラム名・SQL全文、実装クラス/関数名、出力実装のライブラリ名、レイアウト/座標指定、クリック手順の逐語列挙

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

  1. 概要
  2. 利用者/利用目的
  3. 出力タイミング/トリガー
  4. 出力形式/配布・配信
  5. 抽出条件/対象範囲
  6. 表示項目
  7. 集計/算出ルール
  8. 例外/注意事項
  9. メモ / 将来課題

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

  ---
  id: bds-<英小文字とハイフンで構成したID> # 例: bds-daily-sales-summary
  type: domain
  title: <帳票名> # 例: 日次売上サマリ
  status: draft # draft / ready / deprecated のいずれか
  part_of: []
  based_on: []
  supersedes: []
  ---

• based_on には、関連する仕様の id（例: bps-... / uis-... / br-... / bes-... / bac-...）を列挙してください。該当がなければ [] としてください。

• 表示項目 はテーブル形式で列挙してください（レイアウト指定は禁止）。少なくとも次の列を含めてください：

  • No / 区分 / 項目名 / 意味/定義 / 型・書式 / 出力例 / 備考

• 集計/算出ルール は、集計単位（店舗別/商品別/日別等）、算出式、税・端数処理（四捨五入/切り捨て等）が分かるように記述してください。