star-cloud/README.md

# Star Cloud 智能販賣機管理平台

## 專案簡介 (Project Description)
Star Cloud 是一個專為智能販賣機設計的後台管理系統，旨在提供全方位的機台監控、庫存管理、銷售分析與會員管理功能。透過此平台，管理者可以即時掌握機台運營狀態，優化補貨流程，並透過數據分析提升營運效益。

## 技術棧 (Technology Stack)

### 後端 (Backend)
- **Framework**: Laravel 10.x
- **Language**: PHP 8.1+
- **Database**: MySQL 8.0+
- **Authentication**: Laravel Sanctum (API Token Authentication)
- **Tools**: Composer

### 前端 (Frontend)
- **Framework**: Blade Templates (Laravel 預設樣板引擎)
- **CSS Framework**: Tailwind CSS 3.x
- **JavaScript**: Alpine.js 3.x
- **Build Tool**: Vite 5.x
- **HTTP Client**: Axios

## 安裝與使用說明 (Installation & Usage)

請依照以下步驟將專案 Clone 至本地端並開始運行：

### 1. 下載專案 (Clone Repository)
```bash
git clone <repository_url>
cd star-cloud
```

### 2. 安裝依賴套件 (Install Dependencies)

安裝後端 PHP 套件：
```bash
composer install
```

安裝前端 Node.js 套件：
```bash
npm install
```

### 3. 環境變數設定 (Environment Setup)
複製範例環境設定檔：
```bash
cp .env.example .env
```

請開啟 `.env` 檔案，並依照您的本地環境設定資料庫連線資訊：
```dotenv
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=star_cloud
DB_USERNAME=root
DB_PASSWORD=your_password
```

產生應用程式金鑰 (Application Key)：
```bash
php artisan key:generate
```

### 4. 資料庫遷移 (Database Migration)
執行 Migration 以建立資料庫結構：
```bash
php artisan migrate
```
*(若專案包含預設資料，可加上 `--seed` 參數)*

### 5. 編譯前端資源 (Build Frontend Assets)
啟動開發模式 (Hot Module Replacement)：
```bash
npm run dev
```
或編譯生產環境檔案：
```bash
npm run build
```

### 6. 啟動伺服器 (Start Server)
啟動 Laravel 開發伺服器：
```bash
php artisan serve
```
預設網址為：http://localhost:8000

## 主要功能模組
- **儀錶板 (Dashboard)**: 銷售數據概覽、機台狀態監控
- **機台管理 (Machine Management)**: 機台列表、遠端控制、日誌查詢
- **商品與庫存 (Inventory)**: 商品管理、進銷存、補貨單
- **銷售管理 (Sales)**: 交易紀錄、營收報表
- **權限設定 (Permissions)**: 角色與權限分配

---
© Star Cloud. All Rights Reserved.