star-cloud/README.md

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

> 基於 Docker 的全方位智能販賣機後台管理系統

Star Cloud 是一個專為智能販賣機設計的後台管理系統，提供機台監控、庫存管理、銷售分析與會員管理等完整功能。本專案採用 Docker Compose 容器化架構，實現快速部署與環境一致性。

---

## 技術架構

### 容器化架構
本專案完全運行在 Docker 容器中，包含以下服務：

| 服務 | 容器名稱 | 技術 | 用途 | 連接埠 |
|------|---------|------|------|--------|
| **應用程式** | star-cloud-laravel | Laravel 10 + PHP 8.5 | Web 應用與 API | 8090:80, 5175:5175 |
| **資料庫** | star-cloud-mysql | MySQL 8.0 | 關聯式資料庫 | 3306:3306 |
| **快取** | star-cloud-redis | Redis Alpine | 快取與 Session | 6380:6379 |

### 後端技術棧

- **Framework**: Laravel 10.x
- **Language**: PHP 8.5+
- **Database**: MySQL 8.0
- **Cache/Session**: Redis
- **Authentication**: Laravel Sanctum (API Token)
- **Package Manager**: Composer 2.x

### 前端技術棧

- **Template Engine**: Blade Templates
- **UI Library**: Preline UI 3.x (Tailwind CSS 組件庫)
- **CSS Framework**: Tailwind CSS 3.x
- **JavaScript**: Alpine.js 3.x (輕量級互動框架)
- **Build Tool**: Vite 5.x
- **HTTP Client**: Axios

---

## 快速開始

### 前置需求

確保您的系統已安裝以下軟體：

- **Docker** 20.10+
- **Docker Compose** 2.0+
- **Git**

> **提示**：Windows 使用者建議安裝 [Docker Desktop](https://www.docker.com/products/docker-desktop/)，Linux 使用者可參考 [官方安裝文件](https://docs.docker.com/engine/install/)

### 安裝步驟

#### 1. Clone 專案

```bash
git clone <repository_url>
cd star-cloud
```

#### 2. 環境設定

複製環境變數範例檔案：

```bash
cp .env.example .env
```

**重要設定**（`.env` 檔案）：

```env
# 應用程式設定
APP_NAME=Star Cloud
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8090

# 資料庫設定（對應 Docker Compose 服務）
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=star_cloud
DB_USERNAME=sail
DB_PASSWORD=password

# Redis 設定（對應 Docker Compose 服務）
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379

# Vite 開發伺服器
VITE_PORT=5175
```

#### 3. 啟動 Docker 容器

啟動所有服務（應用程式、資料庫、Redis）：

```bash
docker compose up -d
```

> **說明**：`-d` 參數表示背景執行

檢查容器狀態：

```bash
docker compose ps
```

預期輸出：
```
NAME                 STATUS         PORTS
star-cloud-laravel   Up X minutes   0.0.0.0:8090->80/tcp, 0.0.0.0:5175->5175/tcp
star-cloud-mysql     Up X minutes   0.0.0.0:3306->3306/tcp
star-cloud-redis     Up X minutes   0.0.0.0:6380->6379/tcp
```

#### 4. 初始化應用程式

**4.1 安裝後端依賴**

```bash
docker compose exec laravel.test composer install
```

**4.2 產生應用程式金鑰**

```bash
docker compose exec laravel.test php artisan key:generate
```

**4.3 執行資料庫遷移與種子**

```bash
docker compose exec laravel.test php artisan migrate --seed
```

> **預設管理員帳號**：
> - Email: `admin@star-cloud.com`
> - Password: `password`

**4.4 安裝前端依賴**

```bash
docker compose exec laravel.test npm install
```

**4.5 編譯前端資源**

```bash
# 開發模式（支援 Hot Module Replacement）
docker compose exec laravel.test npm run dev

# 或生產模式
docker compose exec laravel.test npm run build
```

#### 5. 訪問應用程式

- **應用程式**: http://localhost:8090
- **Vite Dev Server**: http://localhost:5175

---

## Docker 常用指令

### 容器管理

```bash
# 啟動所有服務
docker compose up -d

# 停止所有服務
docker compose down

# 重啟服務
docker compose restart

# 查看容器日誌
docker compose logs -f laravel.test

# 進入應用程式容器
docker compose exec laravel.test bash
```

### Laravel 指令

所有 Laravel Artisan 指令需在容器內執行：

```bash
# 執行 Artisan 指令
docker compose exec laravel.test php artisan <command>

# 範例：清除快取
docker compose exec laravel.test php artisan cache:clear

# 範例：執行 Migration
docker compose exec laravel.test php artisan migrate

# 範例：建立新 Controller
docker compose exec laravel.test php artisan make:controller ExampleController
```

### 前端開發

```bash
# 安裝 npm 套件
docker compose exec laravel.test npm install

# 開發模式（即時編譯）
docker compose exec laravel.test npm run dev

# 生產編譯
docker compose exec laravel.test npm run build
```

### 資料庫操作

```bash
# 進入 MySQL 容器
docker compose exec mysql bash

# 直接執行 SQL
docker compose exec mysql mysql -u sail -ppassword star_cloud

# 備份資料庫
docker compose exec mysql mysqldump -u sail -ppassword star_cloud > backup.sql

# 還原資料庫
docker compose exec -T mysql mysql -u sail -ppassword star_cloud < backup.sql
```

---

## 主要功能模組

### 核心功能

| 模組 | 功能描述 |
|------|---------|
| **儀錶板** | 銷售數據總覽、機台狀態即時監控、營收統計圖表 |
| **機台管理** | 機台列表、遠端控制、日誌查詢、維修管理、效期控制 |
| **倉庫管理** | 倉庫列表、庫存管理、調撥單、採購單、補貨單 |
| **商品管理** | 商品資料、分類管理、商品報表分析 |
| **銷售管理** | 交易紀錄、金流管理、促銷設定、營收報表 |
| **會員系統** | 會員管理、點數系統、來店禮、Line 整合 |
| **權限控制** | 角色管理、權限分配、功能權限設定 |
| **遠端管理** | 機台重啟、遠端出貨、遠端結帳、庫存調整 |

---

## Preline UI 組件庫

本專案已整合 **Preline UI 3.x**，這是一個基於 Tailwind CSS 的開源 UI 組件庫，提供 50+ 預構建組件。

### 可用組件類別

- **Navigation**: 導航列、側邊欄、分頁、麵包屑、頁籤
- **Forms**: 輸入框、選擇器、開關、檔案上傳、日期選擇器
- **Overlays**: 模態框、抽屜、下拉選單、提示框、彈出框
- **Data Display**: 表格、卡片、時間軸、折疊面板、徽章
- **Feedback**: 通知、警告、載入狀態、進度條

### 使用範例

```html
<!-- 下拉選單 -->
<div class="hs-dropdown relative inline-flex">
  <button type="button" class="hs-dropdown-toggle px-4 py-2 bg-blue-600 text-white rounded-lg">
    選單 <svg class="w-4 h-4 inline ml-2">...</svg>
  </button>
  <div class="hs-dropdown-menu hidden bg-white shadow-lg rounded-lg p-2 mt-2">
    <a class="block px-3 py-2 rounded hover:bg-gray-100" href="#">選項 1</a>
    <a class="block px-3 py-2 rounded hover:bg-gray-100" href="#">選項 2</a>
  </div>
</div>

<!-- 模態框 -->
<button type="button" data-hs-overlay="#my-modal" class="px-4 py-2 bg-blue-600 text-white rounded-lg">
  開啟模態框
</button>
<div id="my-modal" class="hs-overlay hidden">
  <!-- 模態框內容 -->
</div>
```

**更多資源**：
- 官方文件: https://preline.co/docs/
- 組件範例: https://preline.co/examples.html
- GitHub: https://github.com/htmlstreamofficial/preline

---

## 故障排除

### 容器無法啟動

```bash
# 檢查容器日誌
docker compose logs

# 重建容器
docker compose down
docker compose up -d --build
```

### 連接資料庫失敗

確認 `.env` 中 `DB_HOST` 設定為 `mysql`（容器服務名稱），而非 `127.0.0.1`。

### 前端資源編譯失敗

```bash
# 清除 node_modules 重新安裝
docker compose exec laravel.test rm -rf node_modules
docker compose exec laravel.test npm install
docker compose exec laravel.test npm run build
```

### 權限問題

```bash
# 修正儲存目錄權限
docker compose exec laravel.test chmod -R 775 storage bootstrap/cache
```

---

## 部署至生產環境

### 1. 環境變數設定

將 `.env` 中的設定調整為生產環境：

```env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com
```

### 2. 編譯前端資源

```bash
docker compose exec laravel.test npm run build
```

### 3. 優化 Laravel

```bash
docker compose exec laravel.test php artisan config:cache
docker compose exec laravel.test php artisan route:cache
docker compose exec laravel.test php artisan view:cache
```

### 4. 設定 HTTPS

建議使用 Nginx Reverse Proxy + Let's Encrypt SSL 憑證。

---

## 開發團隊協作

### Git Workflow

```bash
# 拉取最新程式碼
git pull origin main

# 重建容器（若 Docker 設定有變更）
docker compose down
docker compose up -d

# 更新依賴
docker compose exec laravel.test composer install
docker compose exec laravel.test npm install

# 執行 Migration
docker compose exec laravel.test php artisan migrate
```

---

## 授權與版權

© Star Cloud. All Rights Reserved.

---

## 技術支援

如有問題或建議，請聯繫開發團隊或提交 Issue。