Shipment Memo — 出荷メモ

出荷作業の各 shipment（Fulfillment の sot.lm_fulfillment_shipments = 注文 × 出荷元）に、オペレーターが時系列で残す手書きメモを追記します。出荷詳細ページのタイムライン（システムイベント + 手書きメモ）に新しい順で表示されます。追記のみ（編集・削除なし = 完全な記録 / 監査ログ）。

Base URL https://api.lmile.io · 認証 x-ingest-secret ヘッダー または operator JWT（Authorization: Bearer）（詳細） · shop はリクエストボディに含めます（API キーで呼ぶ場合は省略できます）

/api/routing/shipment/memo は機械間 secret（x-ingest-secret）と倉庫スタッフの operator JWT のどちらでも呼べます（系統はヘッダの有無で明示判別。詳細）。operator JWT 経由は投稿者（author_user_id = 検証済スタッフ ID）を記録し、body の authorUserId より優先します。

メモの一覧取得 API はありません。body / 投稿者はマーチャント私的注釈（PII 相当）のため、表示は merchant 管理 UI（出荷詳細ページ）が service_role で直読します。agent_read / LLM agent には露出しません。

エンドポイント

Method	Path	用途
POST	/api/routing/shipment/memo	出荷メモの追記（1 回 = 1 行・追記のみ）

---

POST /api/routing/shipment/memo

指定 shipment に手書きメモを 1 件追記します。投稿のたびに新しい行を append します（編集・削除はありません）。

リクエスト

POST https://api.lmile.io/api/routing/shipment/memo
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json

{
  "shop": "demo-store.myshopify.com",
  "shipmentId": "11494bc4-f45f-4d0b-9d68-fd26c1a503ec",
  "body": "お客様より時間指定の希望あり（午前中）。",
  "authorEmail": "[e-mail]"
}

ボディパラメータ

パラメータ	型	必須	説明
shop	string	✓	店舗ドメイン（API キーで呼ぶ場合は省略できます）
shipmentId	string (uuid)	✓	対象 shipment（sot.lm_fulfillment_shipments.id）。同一 shop に実在すること
body	string	✓	メモ本文（1〜2000 文字。前後空白は trim）
authorUserId	string (uuid)		投稿者の user id（監査用）。operator JWT 経由は検証済スタッフ ID が記録され、この値より優先されます
authorEmail	string		投稿者のメール（表示用）

レスポンス

{
  "ok": true,
  "memo": {
    "id": "a1b2c3d4-1111-2222-3333-444455556666",
    "body": "お客様より時間指定の希望あり（午前中）。",
    "author_email": "[e-mail]",
    "created_at": "2026-06-21T10:30:00.000Z"
  }
}

フィールド	説明
memo.id	追記したメモの id
memo.body	保存された本文
memo.author_email	投稿者メール（表示用。投稿者 user id は PII のため返しません）
memo.created_at	追記時刻（タイムラインの並び順キー）

挙動・冪等性

• 追記のみ（非冪等）: 呼ぶたびに sot.lm_shipment_memos へ 1 行 append します（同じ body の再 POST も別の行になります）。編集・削除の API はありません（完全な記録 / 監査ログ）。
• 投稿者: operator JWT 経由は検証済の staff_user_id（auth.users.id）を author_user_id に記録し、body の authorUserId より優先します。機械間 secret 経由は author_user_id = NULL（body の authorUserId を使用）。
• cross-tenant ガード: shipmentId が同一 shop に実在しない場合は 404 shipment_not_found（別 shop の shipment にメモは付けられません）。
• 表示: 一覧取得 API はありません。出荷詳細ページ（inventory-agent /mypage/routing/shipments/:shipmentId）が service_role で shop + shipment_id 絞り込みの直読を行い、created_at 降順でタイムラインに表示します。agent_read / LLM agent には露出しません（body / 投稿者 = PII 相当）。

エラー

エンドポイント固有:

Status	条件	レスポンス例
400	バリデーション失敗（body 空 / 2000 文字超 / shipmentId が uuid でない 等）	{ "ok": false, "error_kind": "invalid_input", "details": [{ "path": "body", "message": "..." }] }
404	shipmentId が同一 shop に存在しない	{ "ok": false, "error_kind": "shipment_not_found", "error": "shipment not found for shop" }

共通エラー（401 / 400 / 403 / 405 / 500 / 503）は Error Codes を参照。

データモデル

• sot.lm_shipment_memos — 出荷（shipment）単位の手書きメモ。shipment_id（→ sot.lm_fulfillment_shipments(id)・ON DELETE CASCADE）/ body（自由記述）/ author_user_id / author_email / created_at。追記のみ（updated_at なし）。body / 投稿者は PII 相当のため service_role 専用（公開 view / agent_read 非公開・agent_readonly grant なし）。INDEX (shop, shipment_id, created_at DESC)。
• sot.lm_fulfillment_shipments — メモの対象（出荷元ヘッダ。Fulfillment）。shipment 削除時はメモも CASCADE で削除されます。