# 帳票設計書 6-Sales Order Shipment Report

## 概要

本ドキュメントは、InvenTreeシステムにおける出荷レポートの設計仕様を記載する。このレポートは販売オーダーの出荷情報を出力し、出荷割当一覧をPDF形式で表示する帳票である。

### 本帳票の処理概要

本帳票は、販売オーダーに紐づく出荷（Shipment）の詳細情報を出力するレポートを生成する。出荷に割り当てられた在庫品目の一覧を表示し、出荷作業の確認と記録に使用される。

**業務上の目的・背景**：出荷業務において、どの在庫品目がどの販売オーダーに対して出荷されるかを明確にすることは、誤出荷防止と在庫管理の観点で重要である。本帳票は、出荷作業者への指示書として、また出荷記録として機能する。

**帳票の利用シーン**：出荷作業前のピッキングリスト、出荷時の内容確認書、顧客への送付物リスト、出荷履歴の記録として利用される。

**主要な出力内容**：
1. 出荷の基本情報（出荷参照番号、販売オーダー情報）
2. 顧客情報
3. 出荷割当一覧（部品、在庫品目情報）

**帳票の出力タイミング**：販売オーダーの出荷タブから、出荷準備時または出荷完了時に出力される。

**帳票の利用者**：出荷担当者、倉庫管理者、配送担当者

## 帳票種別

出荷明細書

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | 販売オーダー詳細画面 - 出荷タブ | /sales/sales-order/{so_id}/shipments/ | レポート出力ボタン |
| - | レポート印刷API | /api/report/print/ | POSTリクエスト |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | PDF |
| 用紙サイズ | A4（設定により変更可能） |
| 向き | 縦 |
| ファイル名 | output.pdf（テンプレート設定により変更可能） |
| 出力方法 | ダウンロード |
| 文字コード | UTF-8 |

### PDF固有設定

| 項目 | 内容 |
|-----|------|
| パスワード保護 | 無 |
| 印刷制限 | 無 |
| 電子署名 | 無 |

## 帳票レイアウト

### レイアウト概要

```
┌─────────────────────────────────────┐
│  [Customer Logo]   Shipment         │
│                    {prefix}{ref}    │
│                    Sales Order {SO} │
│                    {customer_name}  │
├─────────────────────────────────────┤
│  Allocations                        │
│  ┌─────────────────────────────┐   │
│  │Part              |Stock Item│   │
│  │------------------|----------|   │
│  │[img] part_name   |Serial: x │   │
│  │[img] part_name   |Qty: x    │   │
│  │[img] part_name   |Qty: x    │   │
│  └─────────────────────────────┘   │
├─────────────────────────────────────┤
│  {date}                            │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 顧客ロゴ | 顧客企業ロゴ | company_image order.customer | 画像（幅150px） |
| 2 | タイトル | "Shipment" | 固定値 | テキスト（h3） |
| 3 | 出荷参照番号 | プレフィックス + 参照番号 | prefix, reference | テキスト |
| 4 | 販売オーダー | 関連販売オーダー参照番号 | order.reference | テキスト（イタリック） |
| 5 | 顧客名 | 顧客企業名 | order.customer.name | テキスト |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | Part | 部品名 + サムネイル | allocation.line.part.full_name | テキスト+画像 | 自動 |
| 2 | Stock Item | 在庫品目情報 | allocation.item | 条件付き表示 | 自動 |

### Stock Item列の表示条件

| 条件 | 表示内容 |
|------|---------|
| シリアル品 (quantity=1 かつ serial存在) | "Serial Number: {serial}" |
| バッチ品 (batch存在) | "Quantity: {qty} - Batch: {batch}" |
| その他 | "Quantity: {qty}" |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 日付 | 出力日 | date | 日付形式 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| shipment_id | 対象出荷のID | Yes |
| allocations | 出荷割当一覧 | - |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | 割当のデフォルト順序 | - |

### 改ページ条件

割当項目が多い場合、ページ下端で自動改ページ

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| order_salesordershipment | 出荷情報 | 直接参照 |
| order_salesorder | 販売オーダー | shipment.order_id |
| company_company | 顧客情報 | salesorder.customer_id |
| order_salesorderallocation | 出荷割当 | allocation.shipment_id |
| order_salesorderlineitem | 販売明細 | allocation.line_id |
| stock_stockitem | 在庫品目 | allocation.item_id |
| part_part | 部品情報 | stockitem.part_id |

### テーブル別参照項目詳細

#### order_salesorderallocation

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| line | 販売明細行 | - | ForeignKey |
| item | 在庫品目 | - | ForeignKey |
| quantity | 割当数量 | - | - |

#### stock_stockitem

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| serial | シリアル番号 | - | NULL許容 |
| batch | バッチ番号 | - | NULL許容 |
| quantity | 数量 | - | - |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| - | - | - | 本帳票に計算項目なし |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[出力要求] --> B[パラメータ検証]
    B --> C[Shipment取得]
    C --> D[SalesOrder取得]
    D --> E[Allocations取得]
    E --> F[コンテキスト生成]
    F --> G[HTMLレンダリング]
    G --> H[WeasyPrintでPDF変換]
    H --> I[DataOutput保存]
    I --> J[ファイル返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| データなし | 指定された出荷が存在しない | No valid items provided to template | 有効な出荷IDを指定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1出荷あたり最大30割当 |
| 目標出力時間 | 3秒以内 |
| 同時出力数上限 | システム設定による |

## セキュリティ考慮事項

- 認証済みユーザーのみがレポートを出力可能
- 出荷データへのアクセス権限は既存の権限モデルに従う
- 出力ログはDataOutputモデルに記録

## 備考

- テンプレートファイル: `src/backend/InvenTree/report/templates/report/inventree_sales_order_shipment_report.html`
- 基底テンプレート: `inventree_order_report_base.html`を継承
- シリアル品/バッチ品/一般品で表示形式が変わる条件分岐あり
- i18n対応済み（多言語対応）

---

## コードリーディングガイド

本帳票を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.py | `src/backend/InvenTree/order/models.py` | SalesOrderShipmentモデル定義を確認 |

#### Step 2: テンプレートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | inventree_sales_order_shipment_report.html | `src/backend/InvenTree/report/templates/report/` | 帳票全体構造 |

**主要処理フロー**:
- **9-17行目**: ヘッダー部（顧客ロゴ、出荷情報、販売オーダー情報）
- **21-54行目**: Allocationsテーブル
- **44-50行目**: Stock Item表示の条件分岐（シリアル/バッチ/一般）

### プログラム呼び出し階層図

```
ReportPrint.post() [api.py:253]
    │
    └─ ReportTemplate.print() [report/models.py:465]
           │
           ├─ get_context()
           │      │
           │      └─ shipment.report_context()
           │             │
           │             ├─ allocations (SalesOrderAllocation QuerySet)
           │             └─ order (SalesOrder)
           │
           └─ render() → HTML → PDF
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| inventree_sales_order_shipment_report.html | `src/backend/InvenTree/report/templates/report/` | テンプレート | 出荷レポートのHTMLテンプレート |
| inventree_order_report_base.html | `src/backend/InvenTree/report/templates/report/` | テンプレート | オーダー系共通基底テンプレート |
| models.py | `src/backend/InvenTree/order/` | ソース | SalesOrderShipment, SalesOrderAllocationモデル定義 |
| models.py | `src/backend/InvenTree/stock/` | ソース | StockItemモデル定義 |
