# 機能設計書: 会社マスタ管理

## 1. 機能概要

### 1.1 機能の目的
会社マスタ管理機能は、InvenTreeシステムにおける取引先（サプライヤー、製造元、顧客）の基本情報を管理するための機能である。会社マスタは、購買、販売、部品調達の基盤となる重要なマスタデータである。

### 1.2 機能の範囲
- 会社情報の登録・更新・削除・参照
- 会社の役割（サプライヤー/製造元/顧客）の管理
- 会社の有効/無効状態の管理
- 会社情報の検索・フィルタリング
- 会社関連データのエクスポート

### 1.3 関連画面
| 画面ID | 画面名 | 関連操作 |
|--------|--------|----------|
| SCR-COMPANY-LIST | 会社一覧 | 会社の検索・フィルタリング |
| SCR-COMPANY-DETAIL | 会社詳細 | 会社情報の編集・削除 |

## 2. 機能仕様

### 2.1 会社情報の管理

#### 2.1.1 データ項目
| フィールド名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| name | String | Yes | 会社名（一意） |
| description | String | No | 会社の説明 |
| website | URL | No | Webサイト |
| phone | String | No | 電話番号 |
| email | Email | No | メールアドレス |
| currency | String | No | 通貨コード |
| tax_id | String | No | 税務ID |
| is_supplier | Boolean | No | サプライヤーフラグ |
| is_manufacturer | Boolean | No | 製造元フラグ |
| is_customer | Boolean | No | 顧客フラグ |
| active | Boolean | No | 有効フラグ（デフォルト: true） |
| image | Image | No | 会社のロゴ/画像 |

#### 2.1.2 会社の役割
会社は複数の役割を同時に持つことができる：

| 役割 | フラグ | 説明 |
|------|--------|------|
| サプライヤー | is_supplier | 部品の供給元 |
| 製造元 | is_manufacturer | 部品の製造元 |
| 顧客 | is_customer | 製品の販売先 |

### 2.2 会社一覧API

#### 2.2.1 エンドポイント
- **URL**: `GET /api/company/`
- **メソッド**: GET（一覧取得）, POST（新規作成）
- **シリアライザ**: `CompanySerializer`
- **権限**: 認証済みユーザー

#### 2.2.2 フィルタパラメータ
| パラメータ名 | 型 | 説明 |
|-------------|------|------|
| is_customer | Boolean | 顧客のみ |
| is_manufacturer | Boolean | 製造元のみ |
| is_supplier | Boolean | サプライヤーのみ |
| name | String | 会社名で絞り込み |
| active | Boolean | 有効/無効で絞り込み |

#### 2.2.3 検索フィールド
- name: 会社名
- description: 説明
- website: Webサイト
- tax_id: 税務ID

#### 2.2.4 ソートフィールド
- active: 有効フラグ
- name: 会社名
- parts_supplied: 供給部品数（アノテーション）
- parts_manufactured: 製造部品数（アノテーション）

### 2.3 会社詳細API

#### 2.3.1 エンドポイント
- **URL**: `GET/PUT/PATCH/DELETE /api/company/{pk}/`
- **メソッド**: GET（詳細取得）, PUT/PATCH（更新）, DELETE（削除）
- **シリアライザ**: `CompanySerializer`
- **権限**: 認証済みユーザー

#### 2.3.2 更新処理
会社情報の更新時には以下のフィールドが更新可能：
- 基本情報（name, description, website, phone, email等）
- 役割フラグ（is_supplier, is_manufacturer, is_customer）
- 有効フラグ（active）

#### 2.3.3 削除処理
会社の削除時には関連データの整合性チェックが行われる。
- 関連するサプライヤー部品
- 関連する製造元部品
- 関連する注文

## 3. データモデル

### 3.1 Companyモデル
```python
class Company(InvenTree.models.InvenTreeMetadataModel):
    name = models.CharField(max_length=100, unique=True)
    description = models.CharField(max_length=500, blank=True)
    website = models.URLField(blank=True)
    phone = models.CharField(max_length=50, blank=True)
    email = models.EmailField(blank=True)
    currency = models.CharField(max_length=10, blank=True)
    tax_id = models.CharField(max_length=100, blank=True)

    is_supplier = models.BooleanField(default=False)
    is_manufacturer = models.BooleanField(default=False)
    is_customer = models.BooleanField(default=False)

    active = models.BooleanField(default=True)
    image = StdImageField(...)
```

### 3.2 関連エンティティ
```
Company
├── Contact (連絡先: 1:N)
├── Address (住所: 1:N)
├── SupplierPart (サプライヤー部品: 1:N, is_supplier=True)
├── ManufacturerPart (製造元部品: 1:N, is_manufacturer=True)
├── SalesOrder (販売注文: 1:N, is_customer=True)
└── PurchaseOrder (購買注文: 1:N, is_supplier=True)
```

## 4. API仕様

### 4.1 一覧取得
```
GET /api/company/
```

**レスポンス例**:
```json
[
  {
    "pk": 1,
    "name": "Example Supplier",
    "description": "Main supplier for components",
    "website": "https://example.com",
    "phone": "+1-234-567-8900",
    "email": "contact@example.com",
    "currency": "USD",
    "is_supplier": true,
    "is_manufacturer": false,
    "is_customer": false,
    "active": true,
    "parts_supplied": 150,
    "parts_manufactured": 0
  }
]
```

### 4.2 新規作成
```
POST /api/company/
Content-Type: application/json

{
  "name": "New Company",
  "description": "New company description",
  "is_supplier": true,
  "active": true
}
```

### 4.3 更新
```
PATCH /api/company/{pk}/
Content-Type: application/json

{
  "active": false
}
```

### 4.4 削除
```
DELETE /api/company/{pk}/
```

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

### 5.1 推奨読解順序

1. **モデル定義**
   - `src/backend/InvenTree/company/models.py`
     - **Company**: 会社マスタモデル定義
     - フィールド定義、バリデーション、メソッド

2. **シリアライザ**
   - `src/backend/InvenTree/company/serializers.py`
     - **CompanySerializer**: 会社データのシリアライズ
     - **annotate_queryset()**: 供給部品数等のアノテーション

3. **APIエンドポイント**
   - `src/backend/InvenTree/company/api.py`
     - **40-52行目**: `CompanyMixin` - 共通クエリセット設定
     - **54-77行目**: `CompanyList` - 一覧API
     - **80-81行目**: `CompanyDetail` - 詳細API
     - **509-556行目**: `company_api_urls` - URLルーティング

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

```
[API Request: GET /api/company/]
    │
    ▼
CompanyList.get()
    │
    ├── CompanyMixin.get_queryset() [46-51行目]
    │   └── CompanySerializer.annotate_queryset()
    │       └── 供給部品数・製造部品数のアノテーション
    │
    ├── filter_backends = SEARCH_ORDER_FILTER [63行目]
    │   └── フィルタ適用
    │
    └── CompanySerializer.to_representation()
        └── レスポンス生成
```

```
[API Request: POST /api/company/]
    │
    ▼
CompanyList.post()
    │
    ├── CompanySerializer.is_valid()
    │   └── バリデーション
    │       ├── 会社名の一意性チェック
    │       └── 各フィールドのバリデーション
    │
    └── CompanySerializer.create()
        └── Company.objects.create()
```

### 5.3 データフロー図

```
[ユーザー入力]
    │
    ▼
┌─────────────────────────────────────┐
│ CompanySerializer                   │
│ ・name: 会社名                     │
│ ・description: 説明                │
│ ・is_supplier/manufacturer/customer│
│ ・active: 有効フラグ               │
└─────────────────────────────────────┘
    │
    ├── バリデーション
    │   ├── 名前の一意性
    │   └── 必須項目チェック
    │
    ▼
┌─────────────────────────────────────┐
│ Company Model                       │
│ ・データベースへの永続化           │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ 関連エンティティへの影響           │
│ ・SupplierPart (is_supplier)       │
│ ・ManufacturerPart (is_manufacturer)│
│ ・SalesOrder (is_customer)          │
└─────────────────────────────────────┘
```

### 5.4 関連ファイル一覧

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `src/backend/InvenTree/company/models.py` | Model | Company, Contact, Addressモデル定義 |
| `src/backend/InvenTree/company/serializers.py` | Serializer | CompanySerializer定義 |
| `src/backend/InvenTree/company/api.py` | API | RESTful APIエンドポイント定義 |
| `src/backend/InvenTree/company/admin.py` | Admin | Django管理サイト設定 |

## 6. 例外処理

### 6.1 バリデーションエラー
| エラー条件 | エラーメッセージ |
|-----------|-----------------|
| 会社名が空 | "This field is required" |
| 会社名が重複 | "Company with this name already exists" |
| 無効なURL | "Enter a valid URL" |
| 無効なメールアドレス | "Enter a valid email address" |

### 6.2 削除時エラー
| エラー条件 | エラーメッセージ |
|-----------|-----------------|
| 関連データあり | "Cannot delete company with related data" |

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

- APIアクセスには認証が必要
- 会社データの変更は適切な権限を持つユーザーのみ可能
- データエクスポート機能は権限制御される
