みつるシステム → WOaky
生産実績連携のしくみ

1. 全体像

現場の入力からWOakyの在庫が動くまで、そして結果がシートに返るまで。

2. 送るデータ

1行 = 1生産伝票。1リクエストに最大500件まとめられます。

// POST /api/production-slips/import
// Authorization: Bearer <GAS_IMPORT_TOKEN>  ※値はHeroku環境変数。ここには載せません
{
  "dry_run": false,  // true にすると検証のみ（→ 5章）
  "slips": [
    {
      "external_key":          "20260724_1000201_0003_1",
      "produced_at":           "2026-07-24",
      "warehouse_code":        "0003",
      "product_code":          "1000201",
      "completed_quantity":    100,
      "adjustment_quantity":   -10,
      "b_grade_quantity":      5,
      "b_grade_product_code":  "1000201-1",
      "disposal_quantity":     10,
      "return_quantity":       20,
      "single_product_code":   "*1000201"
    }
  ]
}

3. WOaky側で起きること

受信した1行につき、以下の4パターンが該当分だけ実行されます。全ての在庫移動は stock_ledgers に記録されます。

4. 返し方とエラー運用

送信した全行の結果が、送信順のまま返ります。GAS側はそれをそのままシートの各行に書き戻せます。

1行ずつ独立したトランザクションで処理するので、エラー行があっても正常な行は取り込まれます。 HTTPステータスは全行OKなら 200、エラー行が1件でもあれば 207。 認証エラーは 401、リクエスト自体の形式エラー（slipsが無い・501件以上）は 422 です。

{
  "summary": { "total": 4, "imported": 1, "skipped": 1, "error": 2 },
  "results": [
    { "index": 0, "status": "imported", "slip_no": "PP-20260724-001",
      "message": "取り込みました（伝票番号 PP-20260724-001）" },
    { "index": 1, "status": "skipped",  "slip_no": "PP-20260723-005",
      "message": "取込済みのためスキップしました（伝票番号 PP-20260723-005）" },
    { "index": 2, "status": "error", "error_code": "product_not_found",
      "field": "product_code", "value": "ZZZ-9999",
      "message": "商品コード ZZZ-9999 が商品マスタに見つかりません" }
  ]
}

5. dry_run（お試し送信）

2026-08-05追加。連携開始前に、在庫を1件も動かさずにエラーだけ洗い出すための仕組み。

{
  "dry_run": true,
  "slips": [ ... ]
}

// 返り
{
  "dry_run": true,
  "summary": { "total": 2, "imported": 0, "validated": 1, "skipped": 0, "error": 1 },
  "results": [
    { "index": 0, "status": "validated",
      "message": "取込可能です（検証のみ。伝票は登録していません）" },
    { "index": 1, "status": "error", "error_code": "product_not_found",
      "field": "product_code", "value": "ZZZ-9999",
      "message": "商品コード ZZZ-9999 が商品マスタに見つかりません" }
  ]
}

本番環境（v74）で動作確認済み。存在しないコードは product_not_found、実在するコードは validated を返し、 同じ external_key を再送しても消費されないことを確認しています。

6. 決着した論点

7/23〜8/3のやりとりで固まった設計判断。ここが連携の性格を決めています。

※ GAS側から「マスタが二重持ちになるのでは」という指摘がありましたが、GAS側に持つのは対応表ではなく入力欄です。対応表はWOaky側にしか存在しません。

7. 見つかった穴

8/3にGAS側の実装コード（Code.gs / index.html）を突き合わせて分かったこと。修正依頼済みです。

8. これまでの経緯

• 2026-07-23 Slack・議事録で方式を議論

  単品/B品コードの持ち方、返品の戻し先が未決のまま終了。

• 2026-07-24 WOaky側で仕様確定・実装・本番デプロイ（PR #8）

  案A採用、処分は0025へ振替、返品は0098へ単純振替。仕様書v2をGAS側へ共有。

• 2026-07-24 レスポンスを行ごとの結果形式に変更（PR #10）

  summary + results 形式に。シートへそのまま書き戻せる設計へ。

• 2026-08-01 GAS側からの4点照会に回答

  案Aを実データ根拠つきで維持、0003固定を撤回、返品はv2が正、と回答。

• 2026-08-03 GAS側の実装コードを受領・突き合わせ

  ドライラン結果は送信可218件／要確認242件（大半は単品コード未入力）。差分行の正体と3つの穴が判明。

• 2026-08-05 dry_run（お試し送信）を実装・本番デプロイ（PR #13 / v74）

  公式運用開始まで時間があるうちに繋いでエラーを潰しきるため。在庫を汚さず何度でも試せる。

• 次 マスタ整備 → dry_runで全行検証 → 連携開始

  倉庫・商品マスタを整えてから dry_run で残りのエラーを潰す。連携開始日は運営課に「基幹への手打ちをいつまで続けるか」を確認して日単位で切る。未設定のうちは何も送らない既定。

9. 残っている宿題

WOaky側（岡崎）

• 整備マスタ整備（倉庫・商品・商品カテゴリ）。dry_runのエラーの大半はここが埋まれば消える。担当者・部門は連携には使わない
• 確認梱包アプリ／工場アプリの「過不足」列が何と何の差なのかをWOに確認する（過不足送信の可否がこれ待ち）
• 確認梱包の既定倉庫は 0002（会津）か 0003（会津工場）か。間違えると完成品在庫が別倉庫に積まれる
• 確認0024「不良商品」は仕入不良専用か。B品の行き先の判断材料
• 実装B品・処分・返品の行き先倉庫を任意項目で上書き可能にする（b_grade_warehouse_code 等）。現状はB品=生産倉庫、処分=0025、返品=0098でハードコード。運用が固まってから判断
• 連絡連携開始日を確定して伝える

みつるシステム側

• 対応dry_run に対応して、全行を試し送りしてもらう（送信関数に dry_run を渡すだけ。仕様書v3にサンプルコードあり）
• 修正残数フィルタを「0以外」に揃え、減る方向の差分行も必ず画面に出す
• 修正負の値が混じる差分行は送信対象にせず「要確認」で止める（運営課→岡崎→WOaky画面で手修正）
• 修正過不足を送らない設定のとき、「良品+過不足がマイナス」チェックをスキップする
• 修正アーカイブ取消を論理削除にして external_key の連番を守る
• 共有B品コードの照合リスト（不足分をWOakyのマスタに登録する）
• 共有要確認242件の内訳（単品コード未入力以外が何件か）