mama/star-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[FEAT] 完善個人資料頭像上傳功能與導覽列介面優化

Browse Source
This commit is contained in:
sky121113
2026-03-13 09:30:07 +08:00
parent 773396fc90
commit ea460cf6d9
15 changed files with 234 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files

408
README.md
View File

@@ -1,388 +1,112 @@
# Star Cloud 智能販賣機管理平台
> 基於 Docker 的全方位智能販賣機後台管理系統
> 基於 Docker 的全方位智能販賣機後台管理系統 (Cloud 平台)
Star Cloud 是一個專為智能販賣機設計的後台管理系統，提供機台監控、庫存管理、銷售分析與會員管理等完整功能。本專案採用 Docker Compose 容器化架構，實現快速部署與環境一致性。
Star Cloud 是一個專為智能販賣機設計的後台管理系統，負責管理機台、商品、銷售數據，並為硬體端點提供專用的 API。
---
## 技術架構
## 🚀 技術架構
### 容器化架構
本專案完全運行在 Docker 容器中，包含以下服務：
### 核心架構
本專案採用 **傳統單體式架構 (Monolithic Architecture)**，結合 Laravel Blade 引擎進行伺服器端渲染 (SSR)。
| 服務 | 容器名稱 | 技術 | 用途 | 連接埠 |
| 服務 | 容器名稱 | 技術 | 用途 | 本地 Port |
|------|---------|------|------|--------|
| **應用程式** | 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 |
| **應用程式** | `star-cloud-laravel` | Laravel 12 + PHP 8.5 | 核心業務與渲染 | 8090 |
| **資料庫** | `star-cloud-mysql` | MySQL 8.0 | 數據持久化 | 3306 |
| **快取/隊列** | `star-cloud-redis` | Redis Alpine | IoT 高併發隊列 | 6380 |
### 後端技術棧
- **Framework**: Laravel 10.x
- **Language**: PHP 8.5+
- **Framework**: Laravel 12.x
- **Language**: PHP 8.5
- **Redis**: 用於 IoT 高併發隊列 (B010, B600 等)
- **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
- **View**: Laravel Blade
- **CSS**: Tailwind CSS + **Preline UI**
- **JS**: Alpine.js (行為控制)
- **Build**: Vite
---
## 快速開始
## 🛠️ 開發環境 (Laravel Sail)
本專案建議使用 **Laravel Sail** 進行開發，避免直接在宿主機執行指令。
### 前置需求
- Docker Desktop (Windows/Mac) 或 Docker Engine (Linux)
- Git
確保您的系統已安裝以下軟體：
### 快速啟動
1. `clone` 專案並進入目錄
2. `cp .env.example .env`
3. `./vendor/bin/sail up -d`
4. `./vendor/bin/sail composer install`
5. `./vendor/bin/sail artisan key:generate`
6. `./vendor/bin/sail artisan migrate --seed`
7. `./vendor/bin/sail npm install`
8. `./vendor/bin/sail npm run dev`
- **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`
> - 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
### 常用開發指令
| 功能 | 指令 |
|------|------|
| 啟動環境 | `./vendor/bin/sail up -d` |
| 停止環境 | `./vendor/bin/sail down` |
| Artisan 指令 | `./vendor/bin/sail artisan <cmd>` |
| Composer 指令 | `./vendor/bin/sail composer <cmd>` |
| NPM 指令 | `./vendor/bin/sail npm <cmd>` |
| 執行測試 | `./vendor/bin/sail test` |
---
## Docker 常用指令
## 🔐 API 規範
### 容器管理
系統 API 分為兩大類，遵循不同的設計慣例：
```bash
# 啟動所有服務
docker compose up -d
### 1. Admin/Web API (`/api/v1/...`)
- **對象**: 後台管理介面、APP UI。
- **認證**: Laravel Sanctum (Session/Token)。
- **格式**: 標準 RESTful JSON。
# 停止所有服務
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
```
### 2. Machine IoT API (`/api/app/...`)
- **對象**: 智能販賣機、計時器等硬體。
- **認證**: Header `Authorization: Bearer <api_token>`。
- **高併發處理**: 核心日誌 (B010 心跳、B600 交易) **嚴禁直寫 DB**，必須進入 **Redis Queue** 背景異步處理。
---
## 主要功能模組
## 🌐 多語系支援 (I18n)
### 核心功能
| 模組 | 功能描述 |
|------|---------|
| **儀錶板** | 銷售數據總覽、機台狀態即時監控、營收統計圖表 |
| **機台管理** | 機台列表、遠端控制、日誌查詢、維修管理、效期控制 |
| **倉庫管理** | 倉庫列表、庫存管理、調撥單、採購單、補貨單 |
| **商品管理** | 商品資料、分類管理、商品報表分析 |
| **銷售管理** | 交易紀錄、金流管理、促銷設定、營收報表 |
| **會員系統** | 會員管理、點數系統、來店禮、Line 整合 |
| **權限控制** | 角色管理、權限分配、功能權限設定 |
| **遠端管理** | 機台重啟、遠端出貨、遠端結帳、庫存調整 |
所有 UI 顯示文字必須支援多語系，禁止 Hard-coded。
- **語系檔案**: `lang/zh_TW.json`, `lang/en.json`, `lang/ja.json`。
- **呼叫方式**: 使用 `__('Phrases in English')` 或 `@lang('...')`。
- **命名規範**: 優先使用「英文原始詞彙」作為 Key 名稱。
---
## 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
- `app/Http/Controllers/`: 控制器
- `app/Models/{Domain}/`: 分領域的模型 (如 `Machine`, `Member`)
- `app/Services/{Domain}/`: 封裝商業邏輯與資料異動
- `app/Jobs/{Domain}/`: IoT 異步隊列處理任務 (重要)
- `resources/views/`: Blade 模板 (按功能分資料夾)
- `resources/views/components/`: 可重用的 UI 組件
- `routes/`: 路由定義 (`web.php` 與 `api.php`)
---
## 故障排除
## 🚢 CI/CD 與部署
### 容器無法啟動
```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
```
- **自動化工具**: Gitea Actions (`.gitea/workflows/`)。
- **Demo 環境**: 推送到 `demo` 分支會自動部署至 `demo-cloud.taiwan-star.com.tw`。
- **伺服器路徑**: `/var/www/star-cloud-demo` (透過 `ssh gitea_work` 登入)。
---
## 授權與版權
© Star Cloud. All Rights Reserved.
---