PART 01 — 外部インターフェース定義書
外部システム連携・ファイル連携・通信方式・データフォーマット設計で定義すべきこと

// POST https://api.xxx-payment.com/v1/charges
// Content-Type: application/json
// Authorization: Bearer {API_KEY}
{
  "order_id":      "OD-000001",       // 必須 / string / 自システム受注番号（最大50文字）
  "amount":        15000,              // 必須 / integer / 金額（円）/ 1以上10,000,000未満
  "currency":      "JPY",             // 必須 / string / 通貨コード（現在JPYのみ）
  "customer_id":   "CUST-001",        // 必須 / string / 顧客識別子
  "card_token":    "tok_xxxxxxxxxx",  // 必須 / string / カードトークン（フロントエンドで取得）
  "description":   "受注番号OD-000001の決済", // 任意 / string / 最大200文字
  "metadata": {                       // 任意 / object / 追加情報（ログ用）
    "product_count": 3,
    "customer_email": "customer@example.com"
  }
}

// レスポンス（成功 HTTP 200）
{
  "charge_id":    "chr_xxxxxxxxxx",   // 決済ID（自システムで保存必須）
  "status":       "succeeded",        // "succeeded" / "pending" / "failed"
  "amount":       15000,
  "created_at":   "2026-06-17T10:00:00Z"
}

"""
SFTPから連携ファイル（CSV）を受信してバリデーション・DB投入するスクリプト。
pip install paramiko pandas psycopg2-binary
"""
import paramiko
import pandas as pd
import psycopg2
from datetime import date
from pathlib import Path
import logging

logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
log = logging.getLogger(__name__)

SFTP_CONFIG = {
    "hostname": "sftp.warehouse-system.co.jp",
    "port": 22,
    "username": "appuser",
    "key_filename": "/etc/keys/wms_rsa",  # 秘密鍵パス
}
REMOTE_DIR = "/in/stock/"
LOCAL_DIR = Path("/tmp/wms_files/")
LOCAL_DIR.mkdir(exist_ok=True)

# 受信ファイルの必須カラム
REQUIRED_COLS = ["product_code", "warehouse_code", "stock_quantity", "updated_at"]


def download_today_file() -> Path | None:
    """本日付の在庫更新ファイルをSFTPからダウンロードする"""
    today = date.today().strftime("%Y%m%d")
    remote_csv  = f"{REMOTE_DIR}stock_update_{today}.csv"
    remote_done = f"{REMOTE_DIR}stock_update_{today}.done"
    local_csv   = LOCAL_DIR / f"stock_update_{today}.csv"

    with paramiko.SSHClient() as ssh:
        ssh.set_missing_host_key_policy(paramiko.RejectPolicy())
        ssh.connect(**SFTP_CONFIG)
        with ssh.open_sftp() as sftp:
            # .doneファイルの存在確認（取り込み完了通知）
            try:
                sftp.stat(remote_done)
            except FileNotFoundError:
                log.warning(f".doneファイルがありません: {remote_done}")
                return None
            # CSVファイルをダウンロード
            sftp.get(remote_csv, str(local_csv))
            log.info(f"ダウンロード完了: {remote_csv} → {local_csv}")
    return local_csv


def validate_stock_csv(df: pd.DataFrame) -> list[str]:
    """在庫更新CSVのバリデーション"""
    errors = []
    for col in REQUIRED_COLS:
        if col not in df.columns:
            errors.append(f"必須カラム '{col}' がありません")
    if errors:
        return errors

    # 件数チェック
    if len(df) == 0:
        errors.append("データが0件です")

    # 数値チェック
    try:
        df["stock_quantity"] = pd.to_numeric(df["stock_quantity"])
        if (df["stock_quantity"] < 0).any():
            errors.append("在庫数量に負の値があります")
    except Exception:
        errors.append("stock_quantity に数値以外の値があります")

    # 重複チェック（商品コード × 倉庫コードの組み合わせ）
    dup = df.duplicated(subset=["product_code", "warehouse_code"])
    if dup.any():
        errors.append(f"重複レコードあり: {df[dup][['product_code','warehouse_code']].to_dict('records')}")

    return errors


if __name__ == "__main__":
    csv_path = download_today_file()
    if csv_path is None:
        log.info("本日の連携ファイルはまだ準備されていません")
        exit(0)

    df = pd.read_csv(csv_path, encoding="utf-8", dtype={"product_code": str})
    log.info(f"読込件数: {len(df)}件")

    errors = validate_stock_csv(df)
    if errors:
        log.error("バリデーションエラー:")
        for e in errors:
            log.error(f"  {e}")
        exit(1)

    log.info("バリデーションOK — DB投入処理を開始します")
    # DB投入処理は省略（post-03-data-items.htmlのサンプルを参照）