仕様書
指示書作成ツールの動作仕様を網羅したドキュメントです。
表示条件・非表示条件・計算ロジック・レイアウト仕様をすべて記載しています。
Python / Flask
Shopify API 2024-04
4ブランド対応
最終更新: 2026-04-15
システム概要
本ツールはShopifyに登録されている注文データを取得し、ブランドごとに最適化された指示書（印刷用PDF相当のHTML）を生成するWebアプリケーションです。
| 項目 | 内容 |
|---|---|
| フレームワーク | Python / Flask |
| Shopify API | REST Admin API 2024-04 |
| デプロイ先 | VPS（160.251.184.172）、PM2管理 |
| ログ | logs/app.log（最新200行を /logs で確認可能） |
| ルート | / トップ、/generate 印刷生成、/spec 仕様書、/settings 設定、/logs 実行ログ |
対応ブランド
| ブランドID | 表示名 | Shopify接続設定 | 特記事項 |
|---|---|---|---|
photopri | PHOTOPRI | 環境変数 PHOTOPRI_SHOP / PHOTOPRI_TOKEN | バンドル商品処理あり |
artgraph | ARTGRAPH | 環境変数 ARTGRAPH_SHOP / ARTGRAPH_TOKEN | 納期タグ計算・商品画像ギャラリーあり |
e1 | E1 | 環境変数 E1_SHOP / E1_TOKEN | PHOTOPRIと同じチェックリスト |
qoo | Qoo | 環境変数 QOO_SHOP / QOO_TOKEN | ギフト処理あり |
注文取得方法
| 取得方法 | パラメータ | 説明 |
|---|---|---|
| 日付範囲指定 | 開始日時〜終了日時（JST） | 指定範囲内に作成された全注文を取得（ページネーション対応、最大250件/回） |
| 注文番号指定 | 注文番号（改行区切り、複数可） | #付き・なし両対応。1件ずつAPIリクエスト |
営業日ルール：
土日・日本祝日（
jpholidayライブラリ使用）を除いた平日のみを営業日として扱います。納期計算はすべてこのルールに基づきます。
削除済み商品の処理
Shopifyで注文から商品を削除・キャンセルすると line_item.current_quantity が 0 になります。本ツールではこれを「削除済み商品」として扱い、以下の処理すべてから除外します。
| 処理 | 削除済み商品の扱い |
|---|---|
| 合計点数の計算 | ✅ 除外（current_quantity > 0 のみ合計） |
| 指示書への商品表示 | ✅ 除外（テンプレート側でフィルタリング） |
| ARTGRAPHの商品画像ギャラリー | ✅ 除外 |
| チェックリスト判定 | ✅ 除外（全判定関数でフィルタリング済み） |
| 納期タグ計算 | ✅ 除外 |
| マルニ例外ルール判定 | ✅ 除外 |
| 特殊商品マーカー判定 | ✅ 除外 |
後方互換性：
current_quantity フィールドが存在しない古いAPIレスポンスでは、quantity（または 1）をデフォルト値として使用するため、除外されません。
メインチェックリスト
各注文には必ず1つのメインチェックリストが付与されます。ブランドと注文内容に応じてテンプレートが選択されます。
PHOTOPRI / E1
| 条件 | 使用テンプレート | 列構成 |
|---|---|---|
| 色紙印刷モード ON | 検品用(photopri、e1) | 項目 / チェック（1列） |
| 通常 | 印刷用 | 項目 / 顧 / 印（2列） |
印刷用テンプレート項目： 枚数・データ数 / 納期サイズ / レイヤー数 / スマートオブジェクト / 印刷レイアウト / 支払い方法/確定 / 日付タグ / 担当者サイン（担当者サインはチェックなし）
ARTGRAPH
| 条件 | 使用テンプレート | 列構成 |
|---|---|---|
| 色紙印刷モード ON | 検品用(artgraph) | 項目 / チェック（1列） |
| 通常 | artgraph. | 項目 / 顧 / 印（2列）＋備考欄 |
artgraph.テンプレート項目： 枚数 / サイズ / 支払方法 / 日付タグ / 担当者サイン（担当者サインはチェックなし）
Qoo
| 条件 | 使用テンプレート | 列構成 |
|---|---|---|
| 色紙印刷モード ON | 検品用(qoo) | 項目 / チェック（1列） |
| 通常 | Qoo専用 | 項目 / 顧 / 梱（2列） |
Qoo専用テンプレート項目： 入金確認 / データチェック / 切り抜き・加工 / 加筆・レタッチ / レイアウト送付 / デザインFIX / 日付タグ / ギフト依頼 / 出荷予定日お知らせ / 担当サイン
「ギフト依頼」「出荷予定日お知らせ」「担当サイン」は一部のチェックボックスが表示されません（
no_checkbox定義による制御）。追加チェックリスト
メインチェックリストに加え、注文内容に応じて1つ以上の追加チェックリストが自動付与されます。色紙印刷モードがONの場合は追加チェックリストは表示されません。
PHOTOPRI の追加チェックリスト
| チェックリスト名 | 追加条件 |
|---|---|
| マルニ外注(photopri) | 商品名に「アルミ額装」「木製額装」「木製パネル加工」「ブックマット加工」のいずれかを含む商品がある |
| 内製用（在庫あり） | 商品名に「キャンバス木枠張り」「スチレンパネル加工」のいずれかを含む商品がある |
| 検品用(photopri、e1) | 常に付与（最後に追加） |
ARTGRAPH の追加チェックリスト
| チェックリスト名 | 追加条件（追加順） |
|---|---|
| マルニ外注(artgraph) | variant_titleに「アルミ」を含む商品がある |
| 内製用（在庫あり） |
以下のいずれか1つ以上を満たす（条件①〜④はOR判定、①が最優先）： ① variant_titleに「ウッド」を含む ② 商品名に「Canvas」を含む ③ 商品名に「Postcard」＋ variant_titleに「ナチュラル」を含む ④ 商品名に「Postcard」＋ variant_titleに「ブラウン」を含む |
| オリジナルプリント外注 | 商品名に「Memo」を含む |
| ヨツバ印刷外注 | 商品名に「Phone Case」を含む |
| 検品用(artgraph) | 商品名に「Poster」「Canvas」「Postcard」のいずれかを含む場合のみ（最後に追加） |
内製用（在庫あり）のヘッダー色： 水色（#b3e5fc）でハイライト表示されます（他のチェックリストのグレーと区別）。
Qoo の追加チェックリスト
| チェックリスト名 | 追加条件 |
|---|---|
| 内製用（在庫あり） | 商品名に「似顔絵キャンバス」「フォトキャンバス」「似顔絵フォトスタンド」「フォトスタンド」のいずれか、またはvariant_titleに「ウッド」「木製スタンド」を含む |
| ラッピング | 商品名に「ギフトラッピング」を含む |
| オリジナルプリント外注 | 商品名に「おさんぽバッグ」「ステッカー」「マグカップ」「ブランケット」「Tシャツ」「パーカー」のいずれかを含む |
| ヨツバ印刷外注 | 商品名に「スマホケース」「アクリルキーホルダー」「ハンディファン」「コンパクトミラー」のいずれかを含む |
| 検品用(qoo) | 常に付与（最後に追加） |
共通追加チェックリスト（お試しプリントセット）
全ブランド共通で、商品名に「お試しプリント」を含む商品がある場合、そのvariant_titleに応じて以下のいずれかが追加されます。
| variant_titleのキーワード | 追加されるチェックリスト | 枚数 |
|---|---|---|
| 光沢紙セット | 光沢紙セット(14種) | 14項目 |
| マット紙セット | マット紙セット(12種) | 12項目 |
| イラストセット | イラストセット(10種) | 10項目 |
| キャンバスセット | キャンバスセット(3種) | 3項目 |
| 和紙セット | 和紙セット(5種) | 5項目 |
| 全用紙セット | 全用紙セット(全29種) | 29項目 |
商品表示ルール
各注文に紐づく商品（line_item）は以下の条件でフィルタリングして表示されます。
非表示条件（スキップされる商品）
| 条件 | 理由 |
|---|---|
current_quantity == 0 | 削除・キャンセル済み商品 |
bundle_is_sub == True | バンドル商品のサブアイテム（別途入れ子で表示） |
| Qooブランドで商品名が「ペットの数」 | 注文オプション選択肢であり印刷不要 |
各商品カードに表示される内容
| 要素 | 内容 | 備考 |
|---|---|---|
| 商品画像 | Shopify商品画像（48×48px） | なければグレーの空白ボックス |
| 商品名 | 折り返し表示 | ARTGRAPHで「Canvas」を含む場合はピンクハイライト |
| 数量 | 〇点 | |
| バリエーション | variant_title（ARTGRAPHは特殊表示） | 詳細は「バリエーション表示(ARTGRAPH)」参照 |
| 価格 | ¥〇〇〇〇 | |
| 管理番号 | 水色背景でハイライト | Shopify商品に管理番号が設定されている場合のみ |
| 商品プロパティ | 注文時のカスタム項目 | ブランド別の非表示リスト・ハイライトルールあり |
| 📃インチ数 | 手書き用メモ欄 | 全商品共通 |
プロパティ表示ルール
非表示プロパティ（ブランド別）
| ブランド | 非表示にするプロパティ名 |
|---|---|
| PHOTOPRI |
_入稿データURL、サイズ、フレームカラー、用紙種類、加工種別、_bundle_id、_bundle_type、データそのまま印刷了承、完全データ余白3mm了承、画像の周囲が数mmカットされることを了承しました:＋ プロパティ名が「入稿データ」で始まるもの すべて |
| E1 | プロパティ名が「ファイルアップロード」で始まるもの すべて |
| ARTGRAPH | なし（全プロパティ表示） |
| Qoo | なし（全プロパティ表示） |
ハイライト表示プロパティ（★マーク＋黄色枠）
| 適用 | 対象プロパティ名 |
|---|---|
| 全ブランド共通 | 備考欄、データに関する備考 |
| PHOTOPRI専用 | レイアウト確認、印刷レイアウト |
バリエーション表示（ARTGRAPH専用）
ARTGRAPHブランドの場合、variant_titleを ' / ' で分割し、以下のラベルを付けて縦並びで表示します。
| 分割順序 | ラベル | 加工 |
|---|---|---|
| 1番目 | サイズ | そのまま表示 |
| 2番目 | フレーム | そのまま表示 |
| 3番目 | 余白 | 「余白」プレフィックスを除去して表示（例: 「余白なし」→「なし」） |
表示例：
// 変換前: B2(515×728) / なし / 余白なし
サイズ B2(515×728)
フレーム なし
余白 なし
「ウッド」または「アルミ」を含むパーツはピンクハイライト（#ffb6c1）で強調表示されます。他のブランドはvariant_titleをそのまま1行表示します。
商品画像ギャラリー（ARTGRAPH専用）
ARTGRAPHブランドの場合、注文の全商品画像を1つのギャラリースペースにまとめて表示します（指示書下部に配置）。
| 表示条件 | 詳細 |
|---|---|
| ブランド | artgraphのみ |
| 対象商品 | current_quantity > 0（削除済みは除外）かつ image_url が設定されている商品 |
納期タグ計算（ARTGRAPH専用）
ARTGRAPHの注文のみ、以下のルールに基づいて納期タグを自動計算します。
注文日の補正ルール： 注文が平日（営業日）の 0:00〜11:59 に作成された場合、計算基準日を「1営業日前」に補正します（午前中受注を前日扱い）。
納期タグ計算ルール（通常時）
| 優先度 | 条件 | 結果の形式 | 営業日数 |
|---|---|---|---|
| 最優先 | マルニ例外ルール該当（下記参照） | 〇月〇日 |
+2営業日 |
| 2 | 商品名に「Phone Case」または「Memo」を含む | 〇月〇日〜〇月〇日 |
+10〜+14営業日 |
| 3 | 「Poster」＋ variant_titleに「ウッド」 | 出荷:〇月〇日<br>出力:〇月〇日 |
出荷:+10 / 出力:+3 |
| 4 | 商品名に「Canvas」を含む | 出荷:〇月〇日<br>出力:〇月〇日 |
出荷:+10 / 出力:+3 |
| 5 | 「Poster」＋ variant_titleに「アルミ」 | 〇月〇日 |
+2営業日 |
| 6（デフォルト） | 上記以外すべて | 〇月〇日 |
+3営業日 |
臨時期間の扱い
設定された臨時期間（GWや年末年始など）内に作成された注文については、以下の臨時ルールが優先して適用されます。
▼ 設定されている臨時期間一覧
| 名称 | 対象期間（JST） |
|---|---|
| 2026年GW期間 | 2026年4月24日 12:00 〜 2026年5月12日 12:00 |
▼ 臨時期間中の納期タグ計算ルール
| 条件 | 結果の形式 | 営業日数 |
|---|---|---|
| マルニ例外ルール該当（下記参照） | 〇月〇日〜〇月〇日 |
＋2営業日～＋3営業日 |
| 商品名に「Phone Case」または「Memo」を含む | 〇月〇日〜〇月〇日 |
変更なし（+10〜+14営業日） |
| 「Poster」＋ variant_titleに「ウッド」 | 出荷:〇月〇日<br>出力:〇月〇日 |
出荷:+12 / 出力:+5 |
| 商品名に「Canvas」を含む | 出荷:〇月〇日<br>出力:〇月〇日 |
出荷:+12 / 出力:+5 |
| 「Poster」＋ variant_titleに「アルミ」 | 〇月〇日〜〇月〇日 |
＋2営業日～＋3営業日 |
| 上記以外すべて | 〇月〇日 |
＋5営業日 |
2行表示の場合、出荷日を上に・出力日を下に表示します（修正前は「出力日→出荷日」の順だったが2026-04-15に修正）。
マルニ例外ルール（ARTGRAPH専用）
商品分類定義
| 分類名 | 判定条件 |
|---|---|
| マルニ商品 | 商品名に「Poster」＋ variant_titleに「アルミ」 |
| マルニ例外商品① | 商品名に「Poster」＋ variant_titleに「なし」 |
| マルニ例外商品② | 商品名に「Postcard」 |
| マルニ関連外商品 | 上記3つ以外すべて |
判定結果と影響
| 結果値 | 条件（注文内の商品組み合わせ） | 表示への影響 |
|---|---|---|
'maruni' |
以下のいずれか： ・マルニ商品のみ ・マルニ商品＋例外商品①のみ ・マルニ商品＋例外商品②のみ ・マルニ商品＋例外商品①＋例外商品②のみ ・マルニ商品＋マルニ関連外商品（混在含む） |
納期タグ「マルニ」として表示（+2営業日）、出荷日タグをShopifyに書き込まない |
None |
上記以外（マルニ商品なし） | 通常の納期計算ルールに従う |
Shopify出荷日タグの自動付与（ARTGRAPH専用）
指示書生成時、ARTGRAPHの注文に対して出荷日をShopifyのタグに自動書き込みします。
| 納期タグのフォーマット | Shopifyに書き込むタグ |
|---|---|
〇月〇日（単一日） | 日付のみ（例: 25日） |
〇月〇日〜〇月△日（範囲） | 遅い方の日のみ（例: 14日） |
出荷:〇月〇日<br>出力:〇月〇日（2行） | 出荷日のみ（例: 25日） |
書き込みスキップ条件： マルニ例外ルールで
'maruni' と判定された注文には出荷日タグを書き込みません。また、既に同じタグが存在する場合も重複追加しません。
タイムライン
指示書の各注文カードに、Shopifyの注文イベント（コメント）をタイムライン形式で表示します。
| 項目 | 内容 |
|---|---|
| 取得API | orders/{id}/events.json?limit=250 |
| 表示対象 | verb == 'comment' のイベントのみ |
| 表示ユーザー | STAFF PRINT、YutaMatsumura のみ |
| 時刻変換 | UTC → JST（Asia/Tokyo） |
| グループ化 | 日付単位でまとめて表示 |
改修ログ
2026-04-24
新機能納期計算に「臨時期間」ロジックを追加
2026年4月24日12:00〜5月12日12:00（JST）の注文に対して、通常とは異なる営業日数を適用する臨時期間を実装。マルニ/アルミ+2〜+3営業日、Poster+ウッド/Canvas +12/+5日、デフォルト+5営業日。
2026-04-15
新機能仕様書ページを新規作成
左サイドバー付きの仕様書ページ（/spec）を作成。目次・各ロジックの説明・改修ログを含む。
2026-04-15
新機能実行ログページを追加（/logs）
最新200行のアプリログを表示。30秒自動更新、ERRORは赤・WARNINGは黄色でカラー表示。
2026-04-15
新機能グローバルナビゲーションヘッダーを追加
指示書印刷 / 仕様書 / 設定 / 実行ログの4つのメニューを持つ固定ヘッダーを全ページに追加。
2026-04-15
UI改善ARTGRAPHバリエーション表示を改善
variant_titleを「/」で分割し、サイズ・フレーム・余白のラベル付き縦並び表示に変更。文字サイズも拡大（0.8em→1.0em）。
2026-04-15
バグ修正削除済み商品の除外処理を全関数に追加
チェックリスト判定・納期計算・マルニ例外ルール・特殊商品マーカー・画像ギャラリーの全処理でcurrent_quantity=0の商品を除外するよう修正。
2026-04-15
バグ修正2行納期表示の順序・表記修正
「出力→出荷日」の順だったものを「出荷→出力」の順に修正。「出荷日:」→「出荷:」に表記も統一。
2026-04-15
UI改善「内製用（在庫あり）」チェックリストのヘッダー色を水色に変更
他のチェックリストのグレーと区別するため、zaiko-tableクラスを追加しヘッダー背景を#b3e5fcに変更。
2026-04-08
バグ修正商品名の省略表示を折り返し表示に変更
商品名セルのスタイルをwhite-space:nowrap/text-overflow:ellipsisから、white-space:normal/word-break:break-wordに変更し、長い商品名が最後まで表示されるよう修正。
2026-04-08
改修ARTGRAPHの内製用（在庫あり）条件を更新
条件③「Postcard + ナチュラル」・条件④「Postcard + ブラウン」を商品名（title）で判定するよう修正。ウッド条件（①）を追加。