YAML設定リファレンス (YAML Configuration Reference)

レイアウト、マッピング、ロジックをカバーする、template.yamlファイルを手動で編集するための包括的なガイド。

このガイドは、template.yaml ファイルを直接編集したい上級ユーザーや開発者を対象としています。このファイルは、プロファイルの「信頼できる唯一の情報源 (Single Source of Truth)」として機能し、PDFレイアウト、データマッピング、計算ロジックを定義します。

ファイルの場所

設定ファイルはワークスペース内のプロファイルディレクトリにあります：

Documents/PDFMailEngine_Workspace/Profiles/<YourProfileName>/template.yaml

デフォルトのワークスペースは、ドキュメントフォルダ内の PDFMailEngine_Workspace フォルダです。ワークスペースの場所はアプリケーション設定から変更できます。

1. PAGE Configuration (ページ構成)

PDFキャンバスの物理的特性を定義します。

size: 標準サイズ (A3, A4, A5, B4, B5, LETTER, LEGAL).
orientation: PORTRAIT (縦) または LANDSCAPE (横).
margins: ミリメートル単位のグローバル余白。

手動アセット管理

YAMLファイルで背景PDFを手動で追加する場合、アプリケーションはファイルをプロファイルフォルダに自動的にインポートしません。

あなたは手動で .pdf ファイルをプロファイルディレクトリにコピーする必要があります。

デザイナーのデフォルトパス: assets/background/
推奨: 相対パスを使用してください（例：./background.pdf または assets/background/bg.pdf）。

PAGE:
  size: "A4"
  orientation: "PORTRAIT"
  margins:
    top: 20
    bottom: 20
    left: 20
    right: 20
  background: "assets/background/stationery.pdf" # オプションの背景PDF

2. FONTS (フォント)

カスタムTrueType (.ttf) または OpenType (.otf) フォントを登録します。

手動アセット管理

あなたは手動でフォントファイルをプロファイルディレクトリにコピーする必要があります。

デザイナーのデフォルトパス: assets/fonts/

FONTS:
  # FontName : Relative Path
  "MyCustomFont": "assets/fonts/MyFont-Bold.ttf"
  "CorporateFont": "Corporate-Regular.otf"

3. MAPPING (データバインディング)

CSV/Excelの列ヘッダーを、テンプレート内で使用される内部変数名にマッピングします。

構文: InternalKey: "CSV Column Header"

MAPPING:
  # Internal : External
  customer_name: "Customer Name"
  invoice_no: "Invoice Number"
  date: "Issue Date"
  amount: "Total Amount"

4. CALCULATIONS (計算)

データ取り込み中に実行する自動計算を定義します。

構文の一貫性

変数には {{ }} 中括弧を使用してください。 テキストフィールドとの一貫性を保つため、計算式であっても変数名を {{ }} で囲むことを推奨します。

標準: {{ quantity }} * {{ price }}

scope:
- item: 各行に対して計算されます（例：{{ quantity }} * {{ price }}）。
- group: 行のグループに対して計算されます（例：合計の sum）。
expression: 数式。floor(), ceil(), round() などの math 関数をサポートします。

CALCULATIONS:
  # 行レベルの計算（例：税金）
  - scope: "item"
    target: "tax_amount"
    expression: "floor({{ amount }} * 0.10)" # math関数を使用
 
  # total_with_tax の由来を示すためにこれを追加
  - scope: "item"
    target: "total_with_tax"
    expression: "{{ amount }} + {{ tax_amount }}"
 
  # グループレベルの計算（請求書内の全行の合計）
  - scope: "group"
    target: "grand_total"
    type: "sum" # 'sum' は値を合計します
    field: "total_with_tax"

5. LAYOUT (レイアウト)

LAYOUT リストは、PDF上のすべての視覚要素を定義します。要素は順序通りに描画されます（後の要素が上に描画されます）。

座標系 (Coordinate System)

座標の原点

デザイナーで作成したテンプレートは左上原点 (top-left) の座標系を使用します（Y=0 がページの上端）。PAGE キーを使用して YAML を手動編集する場合、デフォルトの座標系は左下原点 (bottom-left) です（Y=0 がページの下端）。

座標系は自動的に判定されます：canvas キー（デザイナー形式）を使用するテンプレートは左上原点、PAGE キーを使用するテンプレートは左下原点になります。

共通プロパティ (Common Properties)

ほとんどの要素は以下のプロパティをサポートしています：

x, y: ミリメートル単位の位置。
visible: 要素の表示/非表示を制御する条件式（詳細は以下を参照）。
position: absolute（デフォルト）または relative。

`visible` プロパティの使い方

visible プロパティは、現在のデータ行に対して評価される Python 式を受け付けます。式が False（または偽の値）と評価された場合、その要素は非表示になります。

利用可能な組み込み関数: int(), float(), str(), len()

# 金額が正の場合のみ表示
- type: "text"
  value: "合計: {{ amount }}"
  visible: "{{ amount }} > 0"
  x: 20
  y: 250

# フィールドが空でない場合のみ表示
- type: "text"
  value: "備考: {{ note }}"
  visible: "len(str({{ note }})) > 0"
  x: 20
  y: 240

# 複数条件の組み合わせ
- type: "text"
  value: "割引適用済み"
  visible: "{{ discount_rate }} > 0 and {{ amount }} >= 10000"
  x: 20
  y: 230

Text (テキスト)

静的テキストまたは Jinja2 構文 {{ key }} を使用した動的変数を表示します。

- type: "text"
  value: "Invoice #{{ invoice_no }}" # Dynamic
  x: 20
  y: 250
  font_family: "Helvetica"
  font_size: 12
  font_weight: "bold"
  align: "LEFT" # LEFT, CENTER, RIGHT
  color: "#000000"
  opacity: 1.0

Image (画像)

画像ファイルを埋め込みます。

手動アセット管理

あなたは手動で画像ファイルをプロファイルディレクトリにコピーする必要があります。

デザイナーのデフォルトパス: assets/images/

- type: "image"
  path: "assets/images/logo.png"
  x: 150
  y: 260
  width: 40
  height: 20

Group Table (明細テーブル)

データ行（明細/ラインアイテム）を反復処理する動的テーブルをレンダリングします。

- type: "group_table"
  x: 20
  y: 180
  # Global Styles
  header_height: 8
  row_height: 6
  border_color: "#000000"
  grid_color: "#cccccc"
  alt_row_color: "#f0f0f0" # シマウマ縞模様
  
  columns:
    - header: "Item"
      key: "item_name"
      width: 60
      align: "LEFT"
      
    - header: "Price"
      key: "unit_price"
      width: 30
      align: "RIGHT"
      format: "currency" # カンマ付きでフォーマット

Static Table (静的テーブル)

行を手動で定義する固定グリッドをレンダリングします。フッター、銀行口座情報、署名欄などに便利です。

- type: "static_table"
  x: 20
  y: 50
  width: 170 # オプション。指定されていない場合は列幅の合計から推論されます
  
  columns:
    - width: 30
      header: "Label"
    - width: 140
      header: "Value"
  
  # 手動で定義された行
  rows:
    - ["Bank Name", "Mizuho Bank"]
    - ["Account No", "{{ account_number }}"] # 変数を使用可能
    - ["Note", "Please pay within 30 days"]

Barcode (バーコード)

1次元バーコードを生成します。

サポートされているタイプ: CODE128, JAN (EAN13 mixed), EAN13, EAN8, CODE39, UPCA, NW-7 (Codabar), ITF.

- type: "barcode"
  value: "{{ invoice_no }}"
  x: 20
  y: 20
  width: 50        # 最大幅（必要に応じて縮小されます）
  height: 10       # 全体の高さ
  
  barcode_type: "CODE128"
  bar_width: 1.0   # バーの太さ
  bar_height: 10   # バーの高さ
  
  # 人間が読めるテキスト
  human_readable: true
  hr_font: "Helvetica"
  hr_size: 10
  hr_color: "#000000"

QR Code (QRコード)

2次元QRコードを生成します。

誤り訂正レベル: L (7%), M (15%), Q (25%), H (30%).

- type: "qrcode"
  value: "https://example.com/inv/{{ invoice_no }}"
  x: 150
  y: 20
  width: 20       # サイズ（アスペクト比固定）
  
  qr_error_level: "M"
  qr_quiet_zone: true   # 白い余白を含める
  
  color: "#000000"      # 前景色
  back_color: "#ffffff" # 背景色
  opacity: 1.0

Shapes (図形 - Rect / Line)

YAML 手動編集のみ

図形要素（rect および line）はデザイナー UI から追加できません。YAML ファイルを直接編集する場合のみ使用可能です。

Rect（矩形）のプロパティ:

x, y: ミリメートル単位の位置。
width, height: ミリメートル単位のサイズ。
stroke_color: 枠線の色（16進数、例："#000000"）。
fill_color: 塗りつぶしの色（16進数、例："#f0f0f0"）。省略すると塗りつぶしなし。
stroke_width: 枠線の太さ（ポイント単位、デフォルト：1）。
opacity: 不透明度。0.0（透明）から 1.0（不透明）。

Line（線）のプロパティ: 線は height: 0（水平線）または width: 0（垂直線）の矩形として描画されます。

x, y: ミリメートル単位の開始位置。
width: 水平線の長さ。
height: 垂直線の長さ。水平線の場合は 0 を設定。
stroke_color: 線の色（16進数）。
stroke_width: 線の太さ（ポイント単位）。

# 枠線と塗りつぶしのある矩形
- type: "rect"
  x: 10
  y: 100
  width: 190
  height: 50
  stroke_color: "#000000"
  fill_color: "#f0f0f0"
  stroke_width: 1

# 水平線
- type: "line"
  x: 10
  y: 200
  width: 190
  height: 0
  stroke_width: 2
  stroke_color: "#000000"

YAML設定リファレンス (YAML Configuration Reference)

ファイルの場所

1. PAGE Configuration (ページ構成)

手動アセット管理

2. FONTS (フォント)

手動アセット管理

3. MAPPING (データバインディング)

4. CALCULATIONS (計算)

構文の一貫性

5. LAYOUT (レイアウト)

座標系 (Coordinate System)

座標の原点

共通プロパティ (Common Properties)

visible プロパティの使い方

Text (テキスト)

Image (画像)

手動アセット管理

Group Table (明細テーブル)

Static Table (静的テーブル)

Barcode (バーコード)

QR Code (QRコード)

Shapes (図形 - Rect / Line)

YAML 手動編集のみ

`visible` プロパティの使い方