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

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

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

ファイルの場所

設定ファイルはプロファイルディレクトリにあります：

%USERPROFILE%\.pdf_mail_engine\profiles\<YourProfileName>\template.yaml

1. PAGE Configuration (ページ構成)

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

size: 標準サイズ (A4, A3, 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上のすべての視覚要素を定義します。要素は順序通りに描画されます（後の要素が上に描画されます）。

共通プロパティ

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

x, y: ミリメートル単位の位置（デフォルトでは左下から）。
visible: 条件式（例：{{ amount }} > 0）。
position: absolute（デフォルト）または relative。

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)

- 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"