bun_orders_lite/README.md

# Bun Lite 订单管理系统

一個基於 Bun 運行時的輕量級後端服務，使用 SQLite 數據庫實現訂單管理功能。

## 功能特性

- 使用 Bun 作為運行時環境
- SQLite 作為數據庫存儲
- RESTful API 接口設計
- 支持條件查詢和分頁功能
- 訂單創建和查詢功能

## 技術棧

- [Bun](https://bun.sh/) - JavaScript/TypeScript 運行時
- SQLite - 嵌入式數據庫
- TypeScript - 類型安全

## 安裝步驟

1. 確保系統已安裝 Bun：
   ```bash
   # 安裝 Bun（如果尚未安裝）
   curl -fsSL https://bun.sh/install | bash
   ```

2. 克隆項目到本地：
   ```bash
   git clone <your-repo-url>
   cd bun_lite
   ```

3. 安裝依賴：
   ```bash
   bun install
   ```

## 啟動服務

開發模式啟動：
```bash
bun run dev
```

或者直接運行：
```bash
bun run index.ts
```

服務將在 `http://localhost:3000` 上運行。

## API 接口說明

### 1. 添加訂單

- **接口地址**: `POST /api/orders`
- **請求頭**: `Content-Type: application/json`
- **請求參數**:

| 參數 | 類型 | 必填 | 說明 |
|------|------|------|------|
| customer_name | string | 是 | 客戶姓名 |
| product_name | string | 是 | 商品名稱 |
| quantity | number | 是 | 數量 |
| price | number | 是 | 單價 |
| status | string | 否 | 訂單狀態（默認為 pending） |

- **響應參數**:

| 參數 | 類型 | 說明 |
|------|------|------|
| success | boolean | 是否成功 |
| message | string | 響應消息 |
| data.id | number | 新增訂單的ID |
| data.customer_name | string | 客戶姓名 |
| data.product_name | string | 商品名稱 |
| data.quantity | number | 數量 |
| data.price | number | 單價 |
| data.status | string | 訂單狀態 |

- **示例請求**:
```json
{
  "customer_name": "張三",
  "product_name": "iPhone 15",
  "quantity": 2,
  "price": 999.99,
  "status": "completed"
}
```

### 2. 查詢訂單列表

- **接口地址**: `GET /api/orders`
- **查詢參數**:

| 參數 | 類型 | 必填 | 默認值 | 說明 |
|------|------|------|--------|------|
| page | number | 否 | 1 | 頁碼 |
| pageSize | number | 否 | 10 | 每頁顯示數量 |
| customerName | string | 否 | - | 按客戶姓名模糊查詢 |
| productName | string | 否 | - | 按商品名稱模糊查詢 |
| status | string | 否 | - | 按訂單狀態精確查詢 |

- **響應參數**:

| 參數 | 類型 | 說明 |
|------|------|------|
| success | boolean | 是否成功 |
| data.orders | array | 訂單列表 |
| data.pagination.page | number | 當前頁碼 |
| data.pagination.pageSize | number | 每頁顯示數量 |
| data.pagination.total | number | 總記錄數 |
| data.pagination.totalPages | number | 總頁數 |

- **示例響應**:
```json
{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 1,
        "customer_name": "張三",
        "product_name": "iPhone 15",
        "quantity": 2,
        "price": 999.99,
        "status": "completed",
        "created_at": "2023-12-01 10:30:00"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 1,
      "totalPages": 1
    }
  }
}
```

## 示例用法

### 添加訂單
```bash
curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "李四",
    "product_name": "MacBook Pro",
    "quantity": 1,
    "price": 1999.99,
    "status": "pending"
  }'
```

### 查詢訂單列表
```bash
curl "http://localhost:3000/api/orders?page=1&pageSize=10&customerName=張&status=pending"
```

## 數據庫結構

數據庫使用 SQLite，包含一個表：

### orders 表

| 字段 | 類型 | 說明 |
|------|------|------|
| id | INTEGER | 主鍵，自增長 |
| customer_name | TEXT | 客戶姓名 |
| product_name | TEXT | 商品名稱 |
| quantity | INTEGER | 數量 |
| price | REAL | 單價 |
| status | TEXT | 訂單狀態 |
| created_at | DATETIME | 創建時間 |

## 項目結構

```
bun_lite/
├── index.ts          # 主應用文件
├── package.json      # 項目配置
├── tsconfig.json     # TypeScript 配置
├── README.md         # 項目說明
├── install.sql       # 數據庫初始化腳本
└── api.md            # API 接口文檔
```

## 環境要求

- Bun >= 1.0.0
- Node.js >= 18.0.0 (Bun 需要此版本或更高)

## 開發指南

1. 在開發模式下運行：`bun run dev`
2. 代碼更改後自動重載
3. 所有 API 接口都支持跨域請求

## 注意事項

- 數據庫文件 `orders.db` 會自動創建
- 服務器默認運行在 3000 端口
- 所有接口均返回 JSON 格式數據