# 報告生成

:::warning[⚠️]

**Beta 預覽版**  
Report Generation API 目前位於 `/beta` 路徑下，屬於預覽版功能。API 介面、欄位、處理行為及回應格式可能隨產品迭代調整（包含但不限於變更規格、移除功能），APMIC 不保證其向下相容性。

:::

報告用於根據已建立完成的報告模板與指定的知識版本（Fileset），自動產生一份完整報告。系統會依照模板的撰寫指引逐章節檢索資料並生成內容，經使用者確認後套回模板版面，最後可匯出為 PDF。  
系統會依序完成以下處理：

- **草稿生成**：依照模板的 `writing_guidelines`，逐章節執行知識庫檢索與內容撰寫，產生 `draft`。

- **草稿確認**：由使用者檢視或修改各章節內容後回傳，作為套版依據。

- **模板填充**：將確認後的章節內容拆解為模板的各個 slot，並渲染為完整的 `rendered_html`。

- **報告匯出**：將完成的報告轉換為 PDF 檔案，並透過 Files API 取得檔案。

建立報告前，請先完成報告模板（狀態為 `completed`，詳見「建立報告模板」章節），並準備好要作為資料來源的 Fileset。

---

### API 一覽

| 功能 | Method | Endpoint |
| --- | --- | --- |
| 建立報告 | `POST` | `/beta/report-generation/reports` |
| 取得報告 | `GET` | `/beta/report-generation/reports/{report_id}` |
| 確認報告草稿 | `POST` | `/beta/report-generation/reports/{report_id}/confirm` |
| 匯出報告 | `POST` | `/beta/report-generation/reports/{report_id}/export` |
| 刪除報告 | `DELETE` | `/beta/report-generation/reports/{report_id}` |

---

### 操作流程

```text
準備已完成的報告模板與 Fileset
    ↓
建立報告（state: generating_draft）
    ↓
系統逐章節生成草稿（完成後 state: pending_review，發送 Webhook）
    ↓
取得並確認或修改草稿（state: filling_template）
    ↓
系統填充模板並渲染（完成後 state: completed，發送 Webhook）
    ↓
匯出 PDF
```

建立報告時，模板內容是以 `template` 物件**直接帶入**，而非傳入 `template_id`。請先透過報告模板 API 取得模板內容：

```text
GET /beta/report-generation/templates/{template_id}?expand=jinja_html,writing_guidelines
```

再將取得的 `jinja_html` 與 `writing_guidelines` 放入建立報告的 `template` 欄位。`writing_guidelines` 只有在模板狀態為 `completed` 時才會回傳。

---

## 1. 建立報告

建立一份新的報告，並啟動非同步草稿生成程序。

### Endpoint

```text
POST /beta/report-generation/reports
```

建立成功後回傳 `201 Created`，報告狀態會先進入：

```text
generating_draft
```

草稿生成完成後，狀態會轉為：

```text
pending_review
```

若有設定 `webhook_url`，系統會在草稿生成完成或失敗時傳送通知。

---

### Request Headers

| Header | Value |
| --- | --- |
| `Authorization` | `Bearer <your-api-key>` |
| `Content-Type` | `application/json` |
| `accept` | `application/json` |

---

### Request Body

```json
{
  "template": {
    "jinja_html": "<html><body><h1>{{ company_name }}</h1></body></html>",
    "writing_guidelines": {
      "global_guide": "本報告應以正式、客觀且資料導向的語氣撰寫。",
      "chapters": [
        {
          "guide": "本章節作為整份報告的摘要。",
          "slot_map": [
            {
              "name": "company_name",
              "description": "填入報告對象的公司名稱。",
              "style": "純文字，不含額外標籤。"
            }
          ]
        }
      ]
    }
  },
  "fileset_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
  "prompt": "請針對 2026 年第二季的營運狀況撰寫報告。",
  "expert_model": "gemini-3.1-pro",
  "metadata": {
    "department": "finance"
  },
  "webhook_url": "https://example.com/webhooks/report"
}
```

### 欄位說明

| 欄位 | 型別 | 必填 | 說明 |
| --- | --- | --- | --- |
| `template` | object | 是 | 報告模板內容，包含 `jinja_html` 與 `writing_guidelines` |
| `template.jinja_html` | string | 是 | 模板的 Jinja HTML 框架 |
| `template.writing_guidelines` | object | 否 | 模板的撰寫指引 |
| `fileset_ids` | array of string | 是 | 作為資料來源的 Fileset ID（UUID）列表，知識庫檢索只會在這些範圍內進行 |
| `prompt` | string | 是 | 本次報告的任務描述，例如報告期間、關注重點或特定需求。系統會依此與撰寫指引決定各章節的資料檢索方向與撰寫內容。請務必提供非空白的內容 |
| `expert_model` | string | 否 | 指定章節撰寫與章節整合階段使用的模型，未提供時採用系統預設模型。資料檢索與模板填充階段不受此設定影響。可用模型可由「取得所有模型」API 查詢 |
| `metadata` | object | 否 | 自訂附加資訊（Key-Value） |
| `webhook_url` | string (URL) | 否 | 接收非同步處理通知的 Webhook URL，需為合法的 HTTP / HTTPS URL |
| `id` | string (uuid) | 否 | 指定報告 ID，用於重新執行失敗的報告，詳見下方說明 |

`writing_guidelines` 的結構需與報告模板 API 產出的格式一致，即包含 `global_guide` 與 `chapters` 兩個頂層欄位，詳見「建立報告模板」章節的「`writing_guidelines` 結構」。`chapters` 的順序即為系統生成章節的順序，`chapters[].slot_map` 決定套版階段會填入哪些 slot。若 `chapters` 為空，系統沒有可生成的章節，報告會轉為 `failed`。  
`expert_model` 會一併寫入回應的 `metadata.expert_model`。

---

### 撰寫指引對生成結果的影響

系統完全依據 `writing_guidelines` 決定報告的章節結構與各章節內容，因此撰寫指引的品質會直接影響生成結果。如需調整，建議先透過「更新報告模板」API 修改模板的撰寫指引，再重新取得並帶入建立報告的請求。

| 欄位 | 對生成結果的影響 |
| --- | --- |
| `global_guide` | 所有章節共用的最高層級規範，影響資料檢索、章節撰寫與章節整合 |
| `chapters` | 陣列長度即為報告的章節數量，順序即為生成與呈現的順序 |
| `chapters[].guide` | 單一章節的撰寫任務說明，同時決定該章節檢索資料的方向 |
| `chapters[].slot_map` | 決定該章節在套版階段會填入哪些 slot |
| `slot_map[].description` | 資料檢索與內容撰寫時的重要依據 |
| `slot_map[].style` | 章節內容與 slot 值的輸出格式依據，決定內容為 HTML 結構或純文字 |

各章節會獨立生成、彼此不共用上下文；所有章節完成後，系統會再統一整合全部章節，處理術語一致、段落銜接與 HTML 結構。整合不會新增或刪除章節，也不負責事實查核或內容審查。生成內容僅來自指定 Fileset 的檢索結果，知識庫缺乏相關資料時，章節內容可能不完整。章節內容目前不支援圖片（`<img>`）。

---

### 重新執行失敗的報告

若帶入 `id`：

- 該 ID 的報告已存在且狀態為 `failed` 時，系統會以本次請求的內容覆寫，並重新執行生成流程。重新執行時 `draft`、`rendered_html` 與匯出檔案 ID 都會被清除，狀態重設為 `generating_draft`；`fail_detail` 會保留先前的失敗紀錄。

- 該 ID 的報告已存在且狀態為其他值時，回傳 `409`（`REPORT_GENERATION_004`），不會覆寫既有資料。

- 該 ID 的報告不存在時，系統會以該 ID 建立新報告。

---

### cURL 範例

```bash
curl -X POST 'https://api.bcm.apmic.ai/beta/report-generation/reports' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "template": {
      "jinja_html": "<html><body><h1>{{ company_name }}</h1></body></html>",
      "writing_guidelines": {
        "global_guide": "本報告應以正式、客觀且資料導向的語氣撰寫。",
        "chapters": [
          {
            "guide": "本章節作為整份報告的摘要。",
            "slot_map": [
              {
                "name": "company_name",
                "description": "填入報告對象的公司名稱。",
                "style": "純文字，不含額外標籤。"
              }
            ]
          }
        ]
      }
    },
    "fileset_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "prompt": "請針對 2026 年第二季的營運狀況撰寫報告。",
    "webhook_url": "https://example.com/webhooks/report"
  }'
```

---

### Response 範例

```json
{
  "object": "report",
  "id": "8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70",
  "metadata": {
    "department": "finance",
    "expert_model": "gemini-3.1-pro"
  },
  "state": "generating_draft",
  "fileset_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
  "prompt": "請針對 2026 年第二季的營運狀況撰寫報告。",
  "exports": {
    "pdf_file_id": null,
    "docx_file_id": null
  },
  "fail_detail": [],
  "webhook_url": "https://example.com/webhooks/report",
  "template": {
    "jinja_html": "<html><body><h1>{{ company_name }}</h1></body></html>",
    "writing_guidelines": {
      "global_guide": "本報告應以正式、客觀且資料導向的語氣撰寫。",
      "chapters": ["..."]
    }
  },
  "draft": null,
  "rendered_html": null
}
```

建立報告的回應會包含本次帶入的 `template`；`draft` 與 `rendered_html` 尚未產生，以 `null` 回傳。

### Response 欄位

| 欄位 | 型別 | 說明 |
| --- | --- | --- |
| `object` | string | 資源類型，固定為 `report` |
| `id` | string (uuid) | 報告 ID |
| `metadata` | object | 報告附加資訊，包含 `expert_model` |
| `state` | string | 報告目前的處理狀態，請參考下方「報告狀態」 |
| `fileset_ids` | array of string | 本報告使用的 Fileset ID 列表 |
| `prompt` | string \| null | 本報告的任務描述 |
| `exports` | object | 已匯出檔案的 ID，包含 `pdf_file_id` 與 `docx_file_id` |
| `fail_detail` | array | 失敗紀錄，無失敗時為空陣列 |
| `webhook_url` | string \| null | 接收通知的 Webhook URL |
| `template` | object \| null | 報告使用的模板內容；取得報告 API 需透過 `expand` 取得 |
| `draft` | object \| null | 章節草稿內容；取得報告 API 需透過 `expand` 取得 |
| `rendered_html` | string \| null | 套版完成的完整 HTML；取得報告 API 需透過 `expand` 取得 |

報告 API 的回應一律包含上表所有欄位；未展開或尚未產生的欄位以 `null` 回傳，而非從回應中移除。  
後續查詢、確認、匯出或刪除報告時，請使用回應中的 `id` 作為 `report_id`。

---

## 2. 取得報告

取得指定報告的目前狀態與資料。

### Endpoint

```text
GET /beta/report-generation/reports/{report_id}
```

### Path Parameters

| 參數 | 型別 | 必填 | 說明 |
| --- | --- | --- | --- |
| `report_id` | string (uuid) | 是 | 報告 ID，非合法 UUID 時回傳 `422` |

---

### Query Parameters

#### `expand`

`expand` 用於額外取得報告內容。

| 參數 | 型別 | 必填 | 說明 |
| --- | --- | --- | --- |
| `expand` | array of string | 否 | 指定要展開的欄位 |

支援的欄位包括：

| 欄位 | 說明 |
| --- | --- |
| `template` | 建立報告時帶入的模板內容 |
| `draft` | 各章節的草稿內容與引用來源 |
| `rendered_html` | 套版完成後的完整 HTML |

多個欄位可使用逗號分隔：

```text
GET /beta/report-generation/reports/{report_id}?expand=template,draft,rendered_html
```

也可以重複傳入：

```text
GET /beta/report-generation/reports/{report_id}?expand=draft&expand=rendered_html
```

指定不支援的欄位時，API 會回傳 `400`（`REPORT_GENERATION_006`），並在 `fields` 中列出不支援的欄位。

---

### cURL 範例

```bash
curl -X GET 'https://api.bcm.apmic.ai/beta/report-generation/reports/8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70?expand=draft' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY"
```

---

### Response 範例

```json
{
  "object": "report",
  "id": "8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70",
  "metadata": {
    "department": "finance",
    "expert_model": "gemini-3.1-pro"
  },
  "state": "pending_review",
  "fileset_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
  "prompt": "請針對 2026 年第二季的營運狀況撰寫報告。",
  "exports": {
    "pdf_file_id": null,
    "docx_file_id": null
  },
  "fail_detail": [],
  "webhook_url": "https://example.com/webhooks/report",
  "template": null,
  "draft": {
    "chapters": [
      {
        "chapter_id": 0,
        "state": "completed",
        "content": "<p>本季整體營收較前一季成長 12%。</p>",
        "references": [
          {
            "chunk_id": "d2f1a8c0-1b3e-4c5d-9a7b-6e8f0a1b2c3d",
            "metadata": {
              "file_id": "e49a877e-738d-4f7c-93f6-0bb4b58b9a53",
              "filename": "2026Q2_financial.pdf"
            },
            "page_content": "2026 年第二季合併營收為新台幣 ..."
          }
        ]
      }
    ]
  },
  "rendered_html": null
}
```

報告仍在處理中時，尚未產生的欄位會以 `null` 回傳。

---

## 3. 確認報告草稿

確認系統生成的章節草稿，並啟動模板填充程序。

### Endpoint

```text
POST /beta/report-generation/reports/{report_id}/confirm
```

此 API 可在報告狀態為以下值時呼叫，其他狀態會回傳 `409`（`REPORT_GENERATION_004`）：

```text
pending_review
failed
```

允許在 `failed` 狀態下呼叫，是為了讓使用者以修正後的內容重新套版。報告尚未產生任何草稿內容時（例如草稿生成階段就失敗），呼叫此 API 會回傳 `409`（`REPORT_GENERATION_007`），請改以「重新執行失敗的報告」方式重新建立。  
確認前，請先取得草稿內容：

```text
GET /beta/report-generation/reports/{report_id}?expand=draft
```

---

### Request Body

```json
{
  "chapters": [
    {
      "chapter_id": 0,
      "content": "<p>本季整體營收較前一季成長 12%。</p>"
    },
    {
      "chapter_id": 1,
      "content": "<p>主要成長動能來自海外市場。</p>"
    }
  ]
}
```

### 欄位說明

| 欄位 | 型別 | 必填 | 說明 |
| --- | --- | --- | --- |
| `chapters` | array | 是 | 確認後的章節內容列表 |
| `chapters[].chapter_id` | integer | 是 | 章節編號，對應 `draft.chapters` 中的章節 |
| `chapters[].content` | string | 是 | 確認或修改後的章節內容 |

Request Body 不接受上表以外的頂層欄位，帶入未定義的欄位會回傳 `422`。

- `chapters` 會**完整取代**原有的草稿內容。未包含在請求中的章節不會被保留，也不會參與後續套版，因此請帶入所有需要出現在報告中的章節。

- 各章節的 `state` 與 `references` 由系統沿用原草稿的值，不需在請求中提供。

- `chapter_id` 必須是目前草稿中存在的章節編號。建議依 `chapter_id` 由小到大送出草稿中的全部章節。

- 草稿中 `state` 為 `failed` 的章節，可直接以人工撰寫的內容取代後送出。

確認後，系統會依各章節在撰寫指引中的 `slot_map`，將章節內容拆解為各 slot 的值並填入模板：

- slot 的值只會從章節內容中擷取或改寫，不會加入章節中沒有的資訊，因此請將需要出現在報告中的內容完整寫入對應章節。

- slot 的值會依該 slot 的 `style` 輸出 HTML，且套入模板時不會做 HTML 跳脫，值中的 HTML 會直接生效。

- 模板中未被任何章節填入的 slot 會渲染為空白，不會產生錯誤。

---

### cURL 範例

```bash
curl -X POST 'https://api.bcm.apmic.ai/beta/report-generation/reports/8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70/confirm' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "chapters": [
      {
        "chapter_id": 0,
        "content": "<p>本季整體營收較前一季成長 12%。</p>"
      }
    ]
  }'
```

確認成功後回傳 `202 Accepted`，回應內容為更新後的報告（包含 `template` 與更新後的 `draft`），處理期間報告會進入：

```text
filling_template
```

完成後則轉為：

```text
completed
```

套版失敗時則轉為 `failed`。兩種情況都會發送 Webhook 通知（若有設定 `webhook_url`）。

---

## 4. 匯出報告

將完成的報告匯出為檔案。

### Endpoint

```text
POST /beta/report-generation/reports/{report_id}/export
```

此 API 僅適用於狀態為以下值的報告，其他狀態會回傳 `409`（`REPORT_GENERATION_004`）：

```text
completed
```

匯出為同步處理，API 會在 PDF 產生完成後才回應。

---

### Query Parameters

| 參數 | 型別 | 必填 | 說明 |
| --- | --- | --- | --- |
| `format` | string | 否 | 匯出格式，目前僅支援 `pdf`，其他值會回傳 `422` |

同一份報告以相同格式重複呼叫時，會回傳先前已產生的檔案，不會重新生成。

---

### cURL 範例

```bash
curl -X POST 'https://api.bcm.apmic.ai/beta/report-generation/reports/8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70/export?format=pdf' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY"
```

---

### Response 範例

```json
{
  "object": "file",
  "id": "b7c4e2a1-9d8f-4a3b-8c2d-1e0f9a8b7c6d",
  "filename": "report_8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70.pdf",
  "filetype": "application/pdf",
  "bytes": 482913,
  "metadata": {
    "report_id": "8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70",
    "export_format": "pdf"
  },
  "purpose": "report_export",
  "created_at": "2026-10-08T08:10:00.123456Z",
  "expires_at": null
}
```

### Response 欄位

| 欄位 | 型別 | 說明 |
| --- | --- | --- |
| `object` | string | 資源類型，固定為 `file` |
| `id` | string (uuid) | 檔案 ID，可透過「下載檔案」API 下載 |
| `filename` | string | 檔案名稱，格式為 `report_{report_id}.pdf` |
| `filetype` | string | 檔案的 MIME 類型 |
| `bytes` | integer | 檔案大小（位元組） |
| `metadata` | object | 檔案附加資訊，包含來源報告 ID 與匯出格式 |
| `purpose` | string | 檔案用途，匯出報告固定為 `report_export` |
| `created_at` | string (date-time) | 檔案建立時間 |
| `expires_at` | string \| null | 檔案到期時間 |

匯出後的檔案 ID 也會寫入報告的 `exports.pdf_file_id`，可在取得報告時一併查看。匯出檔案的結構與其他檔案相同，詳見「檔案物件」章節。

---

## 5. 刪除報告

刪除一份報告。

### Endpoint

```text
DELETE /beta/report-generation/reports/{report_id}
```

刪除後資料無法復原。報告處於任何狀態都可以刪除，包含處理中的報告。

---

### cURL 範例

```bash
curl -X DELETE 'https://api.bcm.apmic.ai/beta/report-generation/reports/8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY"
```

---

### Response 範例

```json
{
  "id": "8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70",
  "object": "report",
  "deleted": true
}
```

報告不存在或不屬於目前的 API Key 時，回傳 `404`（`REPORT_GENERATION_001`）。  
已匯出的 PDF 檔案不會隨報告一併刪除，如需移除請另行透過「刪除單一檔案」API 處理。

---

## 報告狀態

| 狀態 | 說明 | 建議操作 |
| --- | --- | --- |
| `generating_draft` | 系統正在逐章節檢索資料並生成草稿 | 等待 Webhook 通知或查詢最新狀態 |
| `pending_review` | 草稿已生成完成 | 取得 `draft` 並確認或修改章節內容 |
| `filling_template` | 系統正在將章節內容填入模板 | 等待 Webhook 通知或查詢最新狀態 |
| `completed` | 報告生成完成 | 取得 `rendered_html` 或匯出 PDF |
| `failed` | 報告處理失敗 | 檢查 `fail_detail`：草稿已產生時可重新確認草稿；否則以相同 `id` 重新建立報告 |

狀態流轉如下：

```text
generating_draft ──(草稿生成失敗)──→ failed ──(帶 id 重新建立)──→ generating_draft
       ↓
pending_review
       ↓ 呼叫確認 API
filling_template ──(套版失敗)──→ failed ──(重新確認草稿)──→ filling_template
       ↓
completed
```

---

## 報告主要欄位

### `template`

建立報告時帶入的模板內容，報告建立後即固定，不會隨原始模板的後續修改而變動。

```json
{
  "jinja_html": "<html><body><h1>{{ company_name }}</h1></body></html>",
  "writing_guidelines": {
    "global_guide": "本報告應以正式、客觀且資料導向的語氣撰寫。",
    "chapters": []
  }
}
```

### `draft`

各章節的草稿內容。`chapters` 的順序與編號對應模板 `writing_guidelines.chapters` 的順序。

```json
{
  "chapters": [
    {
      "chapter_id": 0,
      "state": "completed",
      "content": "<p>本季整體營收較前一季成長 12%。</p>",
      "references": []
    }
  ]
}
```

| 欄位 | 型別 | 說明 |
| --- | --- | --- |
| `chapter_id` | integer | 章節編號，自 `0` 起算 |
| `state` | string | 該章節的生成結果，`completed` 或 `failed` |
| `content` | string | 章節內容，通常為 HTML 片段 |
| `references` | array | 該章節生成時檢索到的知識庫片段，每筆包含 `chunk_id`、`metadata`（來源資訊，例如 `file_id` 與 `filename`）與 `page_content`（片段原文） |

`references` 記錄的是該章節生成時檢索到的資料片段，可用於追溯內容來源；但不代表章節內容與片段逐句對應，仍需人工檢視確認。  
個別章節生成失敗時，系統會自動重試；仍失敗時，該章節的 `state` 會是 `failed`，內容為失敗提示（`<p>本章生成失敗</p>`），但整份報告仍會進入 `pending_review`，可在確認草稿時自行補上內容。若所有章節皆生成失敗，或章節整合失敗，整份報告會轉為 `failed`，`fail_detail` 記錄 `failed_step` 為 `generate_report`。

### `rendered_html`

套版完成後的完整 HTML，可直接於瀏覽器開啟檢視，也是匯出 PDF 的來源。

### `exports`

已匯出檔案的 ID。目前僅支援匯出 PDF。

```json
{
  "pdf_file_id": "b7c4e2a1-9d8f-4a3b-8c2d-1e0f9a8b7c6d",
  "docx_file_id": null
}
```

### `fail_detail`

失敗紀錄陣列，每次失敗會累加一筆。

```json
[
  {
    "error": "...",
    "failed_step": "generate_report"
  }
]
```

| `failed_step` | 說明 |
| --- | --- |
| `enqueue` | 建立報告後排入生成佇列失敗（建立報告 API 會同時回傳錯誤） |
| `generate_report` | 草稿生成或章節整合階段失敗 |
| `fill_template` | 模板填充階段失敗 |
| `redelivered_message` | 生成任務被重新投遞後中止，需以相同 `id` 重新建立報告 |

`error` 為錯誤訊息文字。

---

## Webhook

建立報告時，可透過 `webhook_url` 指定接收非同步處理通知的 URL。系統只會在以下時間點發送通知：

| 時間點 | 通知時的 `state` |
| --- | --- |
| 草稿生成完成 | `pending_review` |
| 套版完成 | `completed` |
| 任一非同步階段失敗（草稿生成、套版、任務重新投遞） | `failed` |

建立報告（`generating_draft`）與呼叫確認草稿 API（`filling_template`）時的狀態變更不會發送通知，因為這兩個狀態會直接由 API 回應帶出。排入佇列失敗（`failed_step` 為 `enqueue`）時，建立報告 API 會直接回傳錯誤，也不會發送通知。  
Webhook 以 `POST` 發送 `application/json`，內容為完整的報告資料，欄位與取得報告 API 的回應一致，並且一律包含 `template`、`draft` 與 `rendered_html`，不受 `expand` 影響。  
Webhook 目前只會發送一次，接收端回應失敗或逾時時系統不會重送。收到通知後，建議再呼叫 GET API 確認最新報告狀態；若未收到通知，請以 GET API 輪詢狀態。

---

## 錯誤處理

當 Request Body、Path Parameter 或 Query Parameter 不符合 API Schema 時，API 會回傳 `422`：

```json
{
  "detail": [
    {
      "loc": ["body", "template"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

其餘錯誤會以下列格式回傳：

```json
{
  "error_code": "REPORT_GENERATION_004",
  "error_message": "Report is in completed state, expected pending_review. Please refer to the API documentation.",
  "state": "completed",
  "expected_state": "pending_review"
}
```

| HTTP | `error_code` | 說明 |
| --- | --- | --- |
| `401` | `AUTH_001` | 未提供 `Authorization` header |
| `403` | `AUTH_002` / `AUTH_003` | API Key 無效或已過期 |
| `404` | `REPORT_GENERATION_001` | 報告不存在，或不屬於目前的 API Key，附 `report_id` |
| `409` | `REPORT_GENERATION_004` | 報告目前狀態不允許此操作，附 `state` 與 `expected_state` |
| `409` | `REPORT_GENERATION_007` | 報告尚未產生草稿內容，無法確認，附 `report_id` |
| `400` | `REPORT_GENERATION_006` | `expand` 指定了不支援的欄位，附 `fields` |
| `422` | — | Request Body 或參數不符合 Schema |

草稿生成與章節整合等背景流程中的錯誤，不會直接由 API 回傳，而是讓報告轉為 `failed` 並記錄於 `fail_detail`。完整錯誤代碼請參考 [錯誤代碼說明-報告生成](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-報告生成.md)。

---

## 串接注意事項

| 項目 | 說明 |
| --- | --- |
| API 路徑 | Report Generation API 目前使用 `/beta`，屬預覽版功能，不保證向下相容 |
| 模板帶入方式 | 建立報告時需帶入完整的 `template` 物件，而非 `template_id` |
| 模板快照 | 報告會保留建立當下的模板內容，原始模板之後的修改不會影響既有報告 |
| 非同步處理 | 建立與確認報告後，需依 `state` 判斷處理進度 |
| Report ID | Path Parameter 使用 `report_id`，需為合法的 UUID |
| Expand | 可使用逗號分隔或重複傳入，支援 `template` / `draft` / `rendered_html` |
| Null 處理 | 未展開或尚未產生的欄位會以 `null` 回傳 |
| 章節取代 | 確認草稿時送出的 `chapters` 會完整取代原有草稿 |
| 失敗章節 | 個別章節失敗不會中斷整份報告，可在確認草稿時以人工內容補上 |
| 引用來源 | `references` 僅記錄檢索到的片段，不代表內容逐句對應，仍需人工檢視 |
| 模型選擇 | `expert_model` 影響章節撰寫與章節整合階段 |
| 匯出限制 | 匯出僅適用於 `completed` 狀態，且目前僅支援 PDF |
| 重複匯出 | 同一格式重複匯出會回傳既有檔案，不會重新生成 |
| 重新執行限制 | 帶 `id` 重新執行僅適用於 `failed` 狀態的報告 |
| 資料範圍 | 報告僅能由建立它的 API Key 查詢、確認、匯出與刪除，詳見「Tenant Scope 與資料隔離」章節 |
| Webhook | 僅在 `pending_review`、`completed`、`failed` 時發送且不重送，收到通知後建議再呼叫 GET API 確認最新狀態 |
