# ProfitInfo 數據結構文檔

## 概述
此文檔定義了 `ProfitInfo` 方法中 `$viewData` 的完整數據結構，用於在線修改和管理成本利潤報表數據。

## 數據結構

### 1. basicInfo (基本信息)

包含團隊和業務相關的基本信息。

```json
{
  "tourName": "瑞士火車團三大名峰10日",
  "tourCode": "EUTPE20260608100A",
  "tourNumber": "M260209001T5",
  "departDate": "2026/06/08~2026/06/17",
  "businessPerson": "郭采縈",
  "cooperator": "找到了旅行社",
  "lead": "協力商派遣",
  "headCount": "28人"
}
```

| 欄位 | 類型 | 說明 | 範例 |
|------|------|------|------|
| tourName | string | 團名 | 瑞士火車團三大名峰10日 |
| tourCode | string | 團號 | EUTPE20260608100A |
| tourNumber | string | 結算訂單 | M260209001T5 |
| departDate | string | 出團日期範圍 | 2026/06/08~2026/06/17 |
| businessPerson | string | 業務名稱 | 郭采縈 |
| cooperator | string | 協力商 | 找到了旅行社 |
| lead | string | 本團領隊 | 協力商派遣 |
| headCount | string | 本團人數 | 28人 |

---

### 2. businessIncome (營業收入)

包含所有營業收入項目和總計。

```json
{
  "items": [
    {
      "seq": 1,
      "description": "團費 - 農會選任+眷屬",
      "unitPrice": 98500,
      "quantity": 24,
      "subtotal": 2364000,
      "notes": "實訂23人"
    },
    {
      "seq": 2,
      "description": "團費 - 刷卡價 (郭采縈)",
      "unitPrice": 97716,
      "quantity": 1,
      "subtotal": 97716,
      "notes": "郭采縈$95800"
    }
  ],
  "total": 2813465
}
```

| 欄位 | 類型 | 說明 |
|------|------|------|
| items | array | 收入項目陣列 |
| items[].seq | int | 序號 |
| items[].description | string | 交易項目與摘要 |
| items[].unitPrice | int | 單價 |
| items[].quantity | int | 數量 |
| items[].subtotal | int | 小計金額 (= unitPrice × quantity) |
| items[].notes | string | 備註 |
| total | int | 收入總計 |

---

### 3. businessCost (營業成本)

包含所有營業成本項目和總計。

```json
{
  "items": [
    {
      "seq": 1,
      "description": "團費",
      "unitPrice": 95800,
      "quantity": 27,
      "subtotal": 2586600,
      "notes": "含追加中式午餐4餐、自費活動2項"
    },
    {
      "seq": 2,
      "description": "團費 (許玉惠)",
      "unitPrice": 77049,
      "quantity": 1,
      "subtotal": 77049,
      "notes": "原定團費扣除機票取消費"
    }
  ],
  "total": 2788148
}
```

| 欄位 | 類型 | 說明 |
|------|------|------|
| items | array | 成本項目陣列 |
| items[].seq | int | 序號 |
| items[].description | string | 交易項目與摘要 |
| items[].unitPrice | int | 單價 |
| items[].quantity | int | 數量 |
| items[].subtotal | int | 小計金額 (= unitPrice × quantity) |
| items[].notes | string | 備註 |
| total | int | 成本總計 |

---

### 4. otherIncome (其他收入)

包含所有其他收入項目和總計。

```json
{
  "items": [
    {
      "seq": 1,
      "description": "王志堅團費餘額",
      "unitPrice": 18751,
      "quantity": 1,
      "subtotal": 18751,
      "notes": ""
    }
  ],
  "total": 18751
}
```

| 欄位 | 類型 | 說明 |
|------|------|------|
| items | array | 其他收入項目陣列 |
| items[].seq | int | 序號 |
| items[].description | string | 交易項目與摘要 |
| items[].unitPrice | int | 單價 |
| items[].quantity | int | 數量 |
| items[].subtotal | int | 小計金額 |
| items[].notes | string | 備註 |
| total | int | 其他收入總計 |

---

### 5. profitAnalysis (損益計算)

包含損益分析的計算結果。

```json
{
  "totalIncome": 2813465,
  "totalCost": 2788148,
  "grossProfit": 25317,
  "otherIncomeAmount": 18751,
  "netProfit": 44068,
  "profitMargin": "50%",
  "businessShare": 22034
}
```

| 欄位 | 類型 | 說明 | 計算公式 |
|------|------|------|---------|
| totalIncome | int | 本團收款 | = businessIncome.total |
| totalCost | int | 本團成本 | = businessCost.total |
| grossProfit | int | 本團毛利 | = totalIncome - totalCost |
| otherIncomeAmount | int | 其他收入 | = otherIncome.total |
| netProfit | int | 本團利潤 | = grossProfit + otherIncomeAmount |
| profitMargin | string | 分潤率 | 百分比格式，例: "50%" |
| businessShare | int | 業務分潤金 | = netProfit × (profitMargin / 100) |

---

### 6. printDate (列印日期)

```
格式: "YYYY/M/D H:i"
範例: "2026/7/1 11:59"
```

---

## 完整 $viewData 結構

```php
$viewData = collect([
    "basicInfo" => collect([
        "tourName" => "...",
        "tourCode" => "...",
        "tourNumber" => "...",
        "departDate" => "...",
        "businessPerson" => "...",
        "cooperator" => "...",
        "lead" => "...",
        "headCount" => "..."
    ]),
    "businessIncome" => collect([
        "items" => collect([...]),
        "total" => 0
    ]),
    "businessCost" => collect([
        "items" => collect([...]),
        "total" => 0
    ]),
    "otherIncome" => collect([
        "items" => collect([...]),
        "total" => 0
    ]),
    "profitAnalysis" => collect([
        "totalIncome" => 0,
        "totalCost" => 0,
        "grossProfit" => 0,
        "otherIncomeAmount" => 0,
        "netProfit" => 0,
        "profitMargin" => "0%",
        "businessShare" => 0
    ]),
    "printDate" => "2026/7/1 11:59"
]);
```

---

## 數據來源

數據來自 `public/data/profit-data.json` 文件，該文件包含所有成本利潤報表的靜態數據。

### 修改流程

1. **編輯 JSON 文件**: 修改 `public/data/profit-data.json` 中的數據
2. **刷新頁面**: 訪問 `/Print/ProfitInfo/{product}/{api_token}` 路由
3. **數據自動加載**: 控制器會自動讀取 JSON 文件並渲染新數據

---

## 注意事項

- ✅ 所有數值類型的欄位應為 **整數** (int)，不要包含千位分隔符
- ✅ `profitMargin` 應為百分比格式字符串 (例: "50%")
- ✅ 日期格式應為 "YYYY/M/D H:i" (不補零)
- ✅ 計算的欄位 (如 `subtotal`, `total`, `netProfit` 等) 應手動確保正確
- ⚠️ 修改 JSON 文件後無需重啟應用，頁面刷新即可加載最新數據

---

## 範例：修改收入項目

### 原始數據
```json
{
  "seq": 1,
  "description": "團費 - 農會選任+眷屬",
  "unitPrice": 98500,
  "quantity": 24,
  "subtotal": 2364000,
  "notes": "實訂23人"
}
```

### 修改後
```json
{
  "seq": 1,
  "description": "團費 - 農會選任+眷屬",
  "unitPrice": 99000,          // 修改單價
  "quantity": 25,              // 修改數量
  "subtotal": 2475000,         // 更新小計 (99000 × 25)
  "notes": "實訂24人"           // 修改備註
}
```

修改後需要同時更新 `businessIncome.total` 和 `profitAnalysis` 的相關計算欄位。