---
# System prepended metadata

title: Backend API

---

Backend API
===

:::success
全域 API 路由: `huh`
:::

---
### 登入模組 Auth (`/api/auth`)
- ==POST== `/api/auth/login` -- 使用者登入
:::spoiler **Request Body**
```json
{
  "email": "neoxy@example.com",
  "password": "wtf9487wtf"
}
```
:::
:::spoiler **Response**
```json
{
  "message": "Login successful",
  "token": "JWT token string"
}
```
:::

---
### 使用者模組 User (`/api/user`)
:::success
**role**: 權限 (`member`, `manager`, `admin`)
:::
- ==POST== `/api/user/` -- 註冊新用戶
:::spoiler **Request Body**
```json
{
  "name": "Neoxy",
  "email": "neoxy@example.com",
  "password": "wtf9487wtf",
  "role": "admin"
}
```
:::
:::spoiler **Response**
```json
{
  "message": "Registration successed",
}
```
:::
- ==GET== `/api/user/` -- 取得所有用戶資料
- ==GET== `/api/user/:role` -- 根據權限取得用戶資料
- ==GET== `/api/user/:id` -- 根據 ID 取得用戶資料
- ==GET== `/api/user/me` -- 取得登入者本身資料
:::spoiler **Response**
**Search All & by Role**
```json
[
  {
    "id": 1,
    "name": "Neoxy",
    "email": "neoxy@example.com",
    "role": "member"
  },
//...
]
```
**Search by User ID & by Self**
```json
 {
    "id": 1,
    "name": "Neoxy",
    "email": "neoxy@example.com",
    "role": "member"
 }
```
:::
- ==PATCH== `/api/user/me` -- 修改自己的用戶資料
:::spoiler **Request Body**
```json
{
  "name": "username"
}
```
:::
:::spoiler **Response**
```json
{
  "message": "Profile updated",
}
```
:::

---
### 申請經費模組 Budget (`/api/budget`)
:::success
**status**: 款項狀態 (`pending`, `rejected`, `approved`, `settled`)
:::
- ==POST== `/api/budget/` — 建立新的申請經費款項
:::spoiler **Request Body**
```json
{
  "title": "Project A",
  "amount": 50000,
  "description": "Budget for Project A"
}
```
:::
:::spoiler **Response**
```json
{
  "message": "Budget created",
  "result": {
    "id": 1,
    "title": "Project A",
    "amount": 50000,
    "description": "Budget for Project A",
    "status": "pending",
    "createdAt": "2025-08-13 15:30:00",
    "updatedAt": "2025-08-13 15:30:00"
  }
}
```
:::

- ==GET== `/api/budget/` — 取得所有款項（限 manager、admin）
:::spoiler **Query Params**
```json
id (optional)      - 款項 ID
status (optional)  - 篩選狀態 (pending, rejected, approved, settled)
userId (optional)  - 指定用戶 ID
```
:::
:::spoiler **Response**
```json
[
  {
    "id": 1,
    "title": "Project A",
    "amount": 50000,
    "description": "Budget for Project A",
    "status": "pending",
    "createdAt": "2025-08-13 15:30:00",
    "updatedAt": "2025-08-13 15:30:00",
    "user": {
      "id": 2,
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
]
```
:::
- ==GET== `/api/budget/me` — 取得自己的款項
:::spoiler **Query Params**
```json
id (optional)      - 款項 ID
status (optional)  - 篩選狀態 (pending, rejected, approved, settled)
```
:::
:::spoiler **Response**
```json
[
  {
    "id": 2,
    "title": "Team Building",
    "amount": 15000,
    "description": "Annual team building event",
    "status": "approved",
    "createdAt": "2025-08-10 10:00:00",
    "updatedAt": "2025-08-12 18:20:00"
  }
]
```
:::
- ==PATCH== `/api/budget/:id` — 修改款項內容
:::spoiler **Request Body**
```json
{
  "title": "Project A - Updated",
  "amount": 52000,
  "description": "Updated description"
}
```
:::
:::spoiler **Response**
```json
{
  "message": "Budget updated",
  "result": {
    "id": 1,
    "title": "Project A - Updated",
    "amount": 52000,
    "description": "Updated description",
    "status": "pending",
    "createdAt": "2025-08-13 15:30:00",
    "updatedAt": "2025-08-13 16:00:00",
    "user": {
      "id": 2,
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}
```
:::
- ==PATCH== `/api/budget/:id/status` — 更新款項狀態（限 manager、admin）
:::spoiler **Request Body**
```json
{
  "status": "approved" //(pending, rejected, approved)
}
```
:::
:::spoiler **Response**
```json
{
  "message": "Status updated",
  "budget": {
    "id": 1,
    "title": "Project A",
    "amount": 50000,
    "description": "Budget for Project A",
    "status": "approved",
    "createdAt": "2025-08-13 15:30:00",
    "updatedAt": "2025-08-13 15:40:00"
  }
}
```
:::
- ==PATCH== `/api/budget/:id/settle` — 標記款項為已結清（限 manager、admin）
:::spoiler **Response**
```json
{
  "message": "Budget marked as settled"
}
```
:::
- ==DELETE== `/api/budget/:id` — 刪除款項
:::spoiler **Response**
```json
{
  "message": "Budget deleted"
}
```
:::

---
### 報帳模組 Reimbursement (`/api/reimbursement`)
:::success
**status**: 款項狀態 (`pending`, `rejected`, `approved`, `settled`)
**sourceType**: 款項來源 (`direct`,`budget`)
:::
- ==POST== `/api/reimbursement/` — 建立新的報帳款項
:::spoiler **Request Body**
```json
{
  "title": "huh",
  "amount": 87,
  "description": "wtf",
  "budgetId": 87,// <- Optional
  "receipt": ["receipt1.png"]
}
```
:::
:::spoiler **Response**
```json
{
  "message": "Reimbursement created",
  "result": {
    "id": 1,
    "title": "huh",
    "amount": 87,
    "description": "wtf",
    "status": "pending",
    "createdAt": "2025-08-13 15:30:00",
    "updatedAt": "2025-08-13 15:30:00",
    "sourceType": "budget",
    "budgetId": 87,
  }
}
```
:::

- ==GET== `/api/reimbursement/` — 取得所有款項（限 manager、admin）
- ==GET== `/api/reimbursement/me` — 取得自己的款項
:::spoiler **Query Params**
```json
(optional)
status      - 篩選狀態 (pending, rejected, approved, settled)
keyword     - 關鍵字
time        - 時段 (yyyy-MM-dd),(yyyy-MM),(yyyy)
startDate   - 起始時間
endDate     - 終止時間
sourceType  - 報帳來源 (direct, budget)
```
:::
:::spoiler **Response**
**Search by All**
```json
[
  {
    "id": 87,
    "title": "huh",
    "amount": 87,
    "description": "wtf",
    "status": "pending",
    "createdAt": "2025-08-13 15:30:00",
    "updatedAt": "2025-08-13 15:30:00",
    "sourceType": "budget",
    "budgetId": 87,
    "user": {
      "id": 87,
      "name": "Neoxy",
      "email": "neoxy@example.com"
    }
  }
]
```
**Search by Slef**
```json
[
  {
    "id": 87,
    "title": "huh",
    "amount": 87,
    "description": "wtf",
    "status": "pending",
    "createdAt": "2025-08-13 15:30:00",
    "updatedAt": "2025-08-13 15:30:00",
    "sourceType": "budget",
    "budgetId": 87,
  }
]
```
:::
- ==PATCH== `/api/reimbursement/:id` — 修改款項內容
:::spoiler **Request Body**
```json
{
  "title": "huhuh",
  "amount": 9487,
  "description": "wtfff"
}
```
:::
:::spoiler **Response**
```json
{
  "message": "Reimbursement updated",
  "result": {
    "id": 87,
    "title": "huhuh",
    "amount": 9487,
    "description": "wtfff",
    "status": "pending",
    "createdAt": "2025-08-13 15:30:00",
    "updatedAt": "2025-08-13 16:00:00",
    "sourceType": "budget",
    "budgetId": 87,
    "user": {
      "id": 87,
      "name": "Neoxy",
      "email": "neoxy@example.com"
    }
  }
}
```
:::
- ==PATCH== `/api/reimbursement/:id/status` — 更新款項狀態（限 manager、admin）
:::spoiler **Request Body**
```json
{
  "status": "approved" //(pending, rejected, approved)
}
```
:::
:::spoiler **Response**
```json
{
  "message": "Status updated",
  "result": {
    "id": 87,
    "title": "huh",
    "amount": 87,
    "description": "wtf",
    "status": "approved",
    "sourceType": "type",
    "budgetId": 78,
    "createdAt": "2025-08-13 15:30:00",
    "updatedAt": "2025-08-13 15:40:00",
    "user": {
      "id": 87,
      "name": "Neoxy",
      "email": "neoxy@example.com"
    }
  }
}
```
:::
- ==PATCH== `/api/reimbursement/:id/settle` — 單筆標記款項為已結清（限 manager、admin）
:::spoiler **Response**
```json
{
  "message": "Reimbursement marked as settled"
}
```
:::
- ==PATCH== `/api/reimbursement/settle` — 多筆標記款項為已結清（限 manager、admin）
:::spoiler **Request Body**
```json
{
  "ids": [
      87, 787, 878, 9487
  ]
}
```
:::
:::spoiler **Response**
```json
{
  "message": "Reimbursements processed",
  "updated": [
      87, 878
  ],
  "skipped": [
      {
        "id": 787,
        "reason": "you are 87"
      },
      {
        "id": 9487,
        "reason": "you are 87"
      }
  ]
}
```
:::
- ==DELETE== `/api/reimbursement/:id` — 刪除款項
:::spoiler **Response**
```json
{
  "message": "Reimbursement deleted"
}
```
:::
- ==GET== `/api/reimbursement/export` — 輸出請款單
:::spoiler **Query Params**
```json
(optional)
keyword     - 關鍵字
time        - 時段 (yyyy-MM-dd),(yyyy-MM),(yyyy)
startDate   - 起始時間
endDate     - 終止時間
```
:::
:::spoiler **Response**
```json
Export .xlsx file
```
:::

---
### 請款紀錄模組 Disbursement (`/api/disbursement`)
- ==GET== `/api/disbursement/export` — 輸出歷史報帳紀錄
:::spoiler **Query Params**
```json
(optional)
keyword     - 關鍵字
time        - 時段 (yyyy-MM-dd),(yyyy-MM),(yyyy)
startDate   - 起始時間
endDate     - 終止時間
```
:::
:::spoiler **Response**
```json
Export .xlsx file
```
:::
- ==GET== `/api/disbursement/` — 取得所有款項（限 manager、admin）
:::spoiler **Query Params**
```json
(optional)
keyword     - 關鍵字
time        - 時段 (yyyy-MM-dd),(yyyy-MM),(yyyy)
startDate   - 起始時間
endDate     - 終止時間
```
:::
:::spoiler **Response**
```json
[
  {
    "id": 87,
    "title": "huh",
    "amount": 87,
    "description": "wtf",
    "settledAt": "2025-08-13 15:30:00",
    "sourceType": "budget",
    "reimbursementId": 87,
    "user": {
      "id": 87,
      "name": "Neoxy",
      "email": "neoxy@example.com"
    }
  }
]
```
:::