# AIA 人工智慧學校英文官網 - 安裝指南

本文件說明如何從 clone 專案到建立完整 Laravel 開發環境的完整流程。

## 系統需求

- Docker & Docker Compose
- Git
- Node.js 18+ (Host 端用於前端構建)
- npm 或 pnpm

## 專案架構

```
official-en-aia/
├── laravel/          # Laravel 應用程式 (主要開發目錄)
├── web/              # 前端原始碼 (舊版，如有)
├── storybook/        # 元件說明文件
├── design-token/     # Design token 產生器
├── utils/            # 資料產生工具
└── data/             # Design token 產出
```

## 安裝步驟

### 1. Clone 專案

```bash
cd /root/liveserver2024/data/www
git clone <repository-url> official-en-aia
cd official-en-aia
```

### 2. 啟動 Docker 環境

返回 Docker Compose 根目錄並啟動容器：

```bash
cd /root/liveserver2024
docker-compose up -d
```

這將啟動以下服務：
- `apache2`: Web 伺服器 (port 80, 443)
- `php8.2`: PHP-FPM 8.2
- `mysql8`: MySQL 8.0 資料庫
- `python2.7`, `python3.10`: Python 環境

### 3. 設定 Laravel 環境

#### 3.1 進入 Laravel 目錄

```bash
cd /root/liveserver2024/data/www/official-en-aia/laravel
```

#### 3.2 複製環境變數檔案

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

#### 3.3 編輯 `.env` 檔案

根據您的環境調整以下設定：

```env
APP_NAME="AIA Official EN"
APP_ENV=local
APP_DEBUG=true
APP_URL=https://4aia.isobar.com.tw

# 資料庫設定（如使用 MySQL）
DB_CONNECTION=mysql
DB_HOST=mysql8
DB_PORT=3306
DB_DATABASE=aia_official_en
DB_USERNAME=your_user
DB_PASSWORD=your_password

# 或使用 SQLite (預設)
DB_CONNECTION=sqlite
```

如果使用 MySQL，需要先在容器中創建資料庫：

```bash
docker exec -it mysql8 mysql -uroot -p
# 輸入密碼後執行：
CREATE DATABASE aia_official_en CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;
```

### 4. 安裝 PHP 依賴

在 php8.2 容器中安裝 Composer 依賴：

```bash
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && composer install"
```

### 5. 生成應用程式金鑰

```bash
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan key:generate"
```

### 6. 執行資料庫遷移和種子

```bash
# 執行遷移
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan migrate"

# 執行種子 (如有)
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan db:seed"
```

### 7. 安裝前端依賴

在 Host 端的 Laravel 目錄中：

```bash
cd /root/liveserver2024/data/www/official-en-aia/laravel
npm install
```

### 8. 建立儲存連結

```bash
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan storage:link"
```

### 9. 設定檔案權限

確保 Laravel 可以寫入必要的目錄：

```bash
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && chown -R www-data:www-data storage bootstrap/cache"
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && chmod -R 775 storage bootstrap/cache"
```

### 10. 構建前端資產

```bash
cd /root/liveserver2024/data/www/official-en-aia/laravel
npm run build
```

### 11. 清除快取

```bash
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan optimize:clear"
```

## 開發環境設定

### 前端開發模式

如果需要進行前端開發（熱重載）：

```bash
cd /root/liveserver2024/data/www/official-en-aia/laravel
npm run dev
```

### Inertia SSR 設定（選用）

目前 SSR 已停用（`config/inertia.php` 中 `'enabled' => false`）。

如需啟用 SSR：

1. 修改 `config/inertia.php`：
```php
'ssr' => [
    'enabled' => true,
    // ...
],
```

2. 構建 SSR：
```bash
npm run build:ssr
```

3. 啟動 SSR 伺服器：
```bash
docker exec -d php8.2 bash -c "cd /data/www/official-en-aia/laravel && node bootstrap/ssr/ssr.js"
```

## 常用指令

### PHP Artisan 指令

所有 artisan 指令需在 php8.2 容器中執行：

```bash
# 基本格式
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan <command>"

# 範例：
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan route:list"
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan tinker"
```

### 前端構建與快取清除

完整部署指令（一次執行）：

```bash
cd /root/liveserver2024/data/www/official-en-aia/laravel && \
npm run build && \
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan responsecache:clear"
```

### 清除所有快取

```bash
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan optimize:clear"
```

這會清除：
- Config cache
- Route cache
- View cache
- Event cache
- Response cache

## 訪問應用程式

- 本地開發：http://localhost 或設定的域名
- 測試站：https://4aia.isobar.com.tw/

## Storybook 開發（選用）

如需開發元件：

```bash
cd /root/liveserver2024/data/www/official-en-aia/storybook
npm install
npm run storybook
```

Storybook 文件：http://project.docs.isobar.tw/aia/aia-official-en

## 故障排除

### 前端更新不顯示

1. 重新構建前端：
```bash
cd /root/liveserver2024/data/www/official-en-aia/laravel
npm run build
```

2. 清除 Response Cache：
```bash
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan responsecache:clear"
```

3. 瀏覽器硬刷新：
- Windows/Linux: `Ctrl + Shift + R`
- Mac: `Cmd + Shift + R`

### 資料庫連線錯誤

檢查 `.env` 中的資料庫設定是否正確，以及容器名稱（`mysql8`）是否可連線。

### 權限問題

```bash
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && chmod -R 775 storage bootstrap/cache"
```

### 查看 Laravel 日誌

```bash
docker exec php8.2 bash -c "tail -f /data/www/official-en-aia/laravel/storage/logs/laravel.log"
```

## 技術堆疊

- **後端**: Laravel 12.0 + PHP 8.2
- **前端**: React 19 + Inertia.js 2.0 + TypeScript
- **樣式**: TailwindCSS 4 + PostCSS
- **構建工具**: Vite 6
- **管理面板**: Filament 3.2
- **資料庫**: MySQL 8.0 或 SQLite
- **快取**: Spatie Laravel Response Cache

## 進階設定

### Filament 管理面板

訪問管理面板：http://localhost/admin

需要先創建管理員帳號：

```bash
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan make:filament-user"
```

### 佇列處理

如需執行背景任務：

```bash
docker exec -d php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan queue:work"
```

### 排程任務

將以下加入 crontab（如需要）：

```cron
* * * * * docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan schedule:run" >> /dev/null 2>&1
```

## 參考文件

- Laravel 文件：https://laravel.com/docs
- Inertia.js 文件：https://inertiajs.com
- Filament 文件：https://filamentphp.com
- TailwindCSS 4：https://tailwindcss.com

## 支援

如遇問題，請查閱：
- [測試環境和設定](laravel/resources/docs/test.md)
- [專案 README](README.md)