# 報表

報表端點都是唯讀的 `GET`，回應包在 `{"data": …}` 裡。所有請求都要帶：

```
Authorization: Bearer <你的 API key>
Accept: application/json
```

## 端點一覽

| 端點 | 內容 | 參數 |
|---|---|---|
| `GET https://station-flow.staging.quanhox.com.tw/api/v1/routines/{routineId}/report/progress` | 某個例行事務（routine）目前的進度與各站件數 | 無 |
| `GET https://station-flow.staging.quanhox.com.tw/api/v1/routines/{routineId}/report/flow` | 各站進出件數與每日流向 | `date`、`date_from`、`date_to`、`user_id` |
| `GET https://station-flow.staging.quanhox.com.tw/api/v1/routines/{routineId}/report/logs` | 該例行事務所有票的完整流轉紀錄 | 無 |
| `GET https://station-flow.staging.quanhox.com.tw/api/v1/report/workload` | 組織內每個人近 N 天的流轉次數，依類型拆分 | `days` |
| `GET https://station-flow.staging.quanhox.com.tw/api/v1/report/user/{userId}/daily` | 某人某一天的流轉紀錄 | `date` |

## 權限與資料範圍

- 只看得到**目前組織**的資料。別組織的 routine 回 404「例行事務不存在」；不是本組織成員的使用者回 404「使用者不存在」。
- **flow 報表**：非管理者**一律只統計自己做的流轉**。帶別人的 `user_id` 不會報錯，而是被伺服器改成你自己；不帶也一樣只看自己。組織管理者不帶 `user_id` 看全組織，帶了就只看那個人。
- 其他報表只要是組織成員就能查，不另外限制角色。

## 日期與時區

- 時間欄位（`created_at`）為 UTC。
- `date`、`date_from`、`date_to` 格式 `YYYY-MM-DD`，以 **UTC 日期**比對。台灣時間（UTC+8）凌晨 0–8 點發生的流轉，會算在前一個 UTC 日。

## 進度報表 progress

```bash
curl -s -X GET "https://station-flow.staging.quanhox.com.tw/api/v1/routines/3/report/progress" \
  -H "Authorization: Bearer $SF_KEY" -H "Accept: application/json"
```

```json
{"data":{
  "routine_id": 3,
  "total_tasks": 40,
  "completed_tasks": 25,
  "in_progress_tasks": 15,
  "progress_percentage": 62.5,
  "stations": [
    {"station_id": 11, "station_name": "撰稿", "type": "normal", "task_count": 6, "percentage": 15.0}
  ]
}}
```

- 「完成」＝票停在結束（`end`）或存查（`archive`）類型的站。
- `stations` 只列流程**現行版本**的站；`total_tasks`、`completed_tasks` 則算這個 routine 的所有票（包含停在舊版本站的票）。

## 流向報表 flow

```bash
curl -s -X GET "https://station-flow.staging.quanhox.com.tw/api/v1/routines/3/report/flow?date_from=2026-10-01&date_to=2026-10-29" \
  -H "Authorization: Bearer $SF_KEY" -H "Accept: application/json"
```

```json
{"data":{
  "routine_id": 3,
  "date": null,
  "stations": [
    {"station_id": 11, "station_name": "撰稿", "type": "normal", "entered": 12, "exited": 10, "net": 2}
  ],
  "daily": [
    {"date": "2026-10-28", "to_station_name": "審稿", "count": 4}
  ]
}}
```

- `date`：只看某一天；`date_from`／`date_to`：區間（含頭尾），可只給一邊。
- `entered`＝進入該站的次數，`exited`＝離開該站的次數，`net`＝兩者相減。依**站名**比對，所以新舊版本中同名的站會合併計算。
- `stations` 只列現行版本的站；`daily` 依日期與目的站名分組。
- 留言也是一筆流轉紀錄（來源站與目的站都是目前站），會計入進出次數。

## 日誌報表 logs

```bash
curl -s -X GET "https://station-flow.staging.quanhox.com.tw/api/v1/routines/3/report/logs" \
  -H "Authorization: Bearer $SF_KEY" -H "Accept: application/json"
```

`data` 是陣列，依時間由舊到新，每筆：

```json
{"task_id": 57, "from_station_name": "撰稿", "to_station_name": "審稿",
 "transition_type": "normal", "transition_name": "送審", "transition_tone": "positive",
 "is_return": false, "comment": "初稿完成", "actor": {"id": 8, "name": "小明"},
 "created_at": "2026-10-28T03:12:00.000000Z"}
```

- `transition_type`：`normal`（走出口）、`rollback`（退回上一站）、`exception`（進異常站）、`jumpback`（從異常站跳回）、`comment`（留言）。
- `is_return: true` 表示這是一次「退件」：`normal` 流轉且出口的 tone 為 `negative`。
- 沒有分頁也沒有篩選，會回整個 routine 的全部紀錄。只需要單張票的歷史時，改用 `GET https://station-flow.staging.quanhox.com.tw/api/v1/tasks/{id}/logs`。

## 工作量報表 workload

```bash
curl -s -X GET "https://station-flow.staging.quanhox.com.tw/api/v1/report/workload?days=7" \
  -H "Authorization: Bearer $SF_KEY" -H "Accept: application/json"
```

```json
{"data":[
  {"user_id": 8, "name": "小明", "total": 23,
   "by_type": {"normal": 15, "reject": 2, "rollback": 1, "exception": 0, "jumpback": 0, "comment": 5},
   "count": 23}
]}
```

- 唯一參數 `days`，預設 30，最小 1；統計從 N 天前（UTC）當天 0 點起到現在。
- 依 `total` 由大到小排序。`count` 與 `total` 相同，為相容舊用法保留。
- `reject`＝走了 tone 為 `negative` 的出口（退件），已從 `normal` 拆出，`normal` 只算非退件；各類加總等於 `total`。
- 統計的是整個組織，不限單一 routine。帳號已刪除的人 `name` 顯示「(已刪除)」。

## 個人每日報表 user daily

```bash
curl -s -X GET "https://station-flow.staging.quanhox.com.tw/api/v1/report/user/8/daily?date=2026-10-28" \
  -H "Authorization: Bearer $SF_KEY" -H "Accept: application/json"
```

```json
{"data":[
  {"task_id": 57, "from_station_name": "撰稿", "to_station_name": "審稿",
   "transition_type": "normal", "comment": "初稿完成", "created_at": "2026-10-28T03:12:00.000000Z"}
]}
```

- 唯一參數 `date`（`YYYY-MM-DD`，UTC），預設今天（UTC）。一次只查一天，要多天就逐日呼叫。
- 只列這個人當天做的流轉與留言，依時間由舊到新。

## 常見錯誤

| HTTP | 情況 | 怎麼處理 |
|---|---|---|
| 401 | 沒帶或帶錯 API key | 檢查 `Authorization` header |
| 404 | routine 不存在或不屬於目前組織；使用者不是目前組織成員 | 先用 `GET https://station-flow.staging.quanhox.com.tw/api/v1/routines` 或 `GET https://station-flow.staging.quanhox.com.tw/api/v1/users` 確認 id |
| 回傳只有自己的資料 | 非管理者查 flow 報表 | 正常行為，伺服器強制只看自己 |