# Cursor Rules for AIA Taiwan Official Website

## 🎯 專案核心原則

這是一個 **Laravel 12 + Inertia.js + React 19 + TypeScript** 專案，運行於 Docker 環境。

### 資料流模式（必須遵循）
```
Database → Model → Controller → Resource → Inertia::render() → React TSX
```

---

## 📋 開發工作流程（自動執行）

### ✅ 修改程式碼前
1. **先讀取相關文件**：
   - `laravel/resources/docs/laravel-structure.md` - 技術實作指南
   - `laravel/resources/docs/site-structure.md` - 頁面路由對照
   - `laravel/resources/docs/test.md` - 測試部署流程

### ✅ 修改程式碼時
1. **後端修改（Controller/Resource）**：
   - 使用 Controller 處理路由（不用 Route closure）
   - 使用 Resource 格式化資料
   - Resource 輸出必須加 `->resolve()`
   - 使用 `with()` 避免 N+1 查詢
   - 圖片路徑：`asset('uploads/' . $this->image_url)`
   - 日期格式：`->format('Y-m-d H:i:s')`

2. **前端修改（React/TSX）**：
   - TypeScript 型別必須對應 Resource 結構
   - 使用 Inertia router 導航（不用 axios）
   - 元件位置：`resources/js/components/aia/`
   - 頁面位置：`resources/js/pages/`

### ✅ 修改程式碼後（必須自動執行）
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. **提供驗證步驟**：
   - 告訴使用者要訪問哪個 URL
   - 提示使用者硬刷新瀏覽器（Ctrl+Shift+R）

---

## 🐳 Docker 環境規則

所有 PHP/Artisan 指令必須透過 Docker 執行：
```bash
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && [指令]"
```

**容器內路徑**：`/data/www/official-en-aia/laravel/`  
**Host 路徑**：`/root/liveserver2024/data/www/official-en-aia/laravel/`

---

## 🚀 常用指令速查

### 完整部署（Build + 清快取）
```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"
```

### 程式碼品質檢查
```bash
cd /root/liveserver2024/data/www/official-en-aia/laravel
npm run lint      # ESLint 修復
npm run format    # Prettier 格式化
npm run types     # TypeScript 檢查
```

### 測試與除錯
```bash
# Laravel Tinker（測試 Model/Resource）
docker exec -it php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan tinker"

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

# 路由列表
docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan route:list"
```

---

## ⚠️ 關鍵禁止事項

### ❌ 絕對不要做的事
1. **不要**使用 Route closure 傳遞資料（改用 Controller）
2. **不要**在前端用 axios 取資料（改用 Inertia router）
3. **不要**忘記 Resource 加 `->resolve()`
4. **不要**忘記清除 Response Cache
5. **不要**自動執行 Git 操作（commit/push/pull）
6. **不要**創建不必要的 REST API（Inertia 已處理）

### ✅ 正確做法範例

#### Controller（動態頁面）
```php
use App\Http\Resources\PostResource;

public function index(Request $request): Response
{
    $posts = Post::query()
        ->where('status', 'publish')
        ->with('categories')  // ✅ 避免 N+1
        ->paginate(12);

    return Inertia::render('news', [
        'posts' => PostResource::collection($posts),  // ✅ 使用 Resource
    ]);
}
```

#### Resource（資料格式化）
```php
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'image_url' => $this->image_url 
            ? asset('uploads/' . $this->image_url)  // ✅ 拼接完整路徑
            : null,
        'published_at' => $this->published_at?->format('Y-m-d H:i:s'),  // ✅ 格式化日期
    ];
}
```

#### 前端導航（使用 Inertia）
```typescript
import { router } from '@inertiajs/react';

// ✅ 正確
router.get('/news', { type: 'event' }, { 
    preserveState: true,
    preserveScroll: true 
});

// ❌ 錯誤
axios.get('/api/news?type=event');
```

---

## 📁 檔案結構規範

### Controller 位置
`app/Http/Controllers/[Name]Controller.php`

### Resource 位置
`app/Http/Resources/[Name]Resource.php`

### Model 位置
`app/Models/[Name].php`

### React 元件
- AIA 元件：`resources/js/components/aia/`
- UI 元件：`resources/js/components/ui/`
- 頁面：`resources/js/pages/`
- Layout：`resources/js/layouts/aia/`

### TypeScript 型別
`resources/js/types/index.d.ts` 或各頁面內定義

---

## 🔍 除錯流程

### 前端修改看不到變化？
1. `npm run build`
2. `docker exec php8.2 bash -c "cd /data/www/official-en-aia/laravel && php artisan responsecache:clear"`
3. 瀏覽器硬刷新（Ctrl+Shift+R）

### 圖片顯示不出來？
1. 檢查資料庫：相對路徑（如 `2025/07/image.png`）
2. 檢查 Resource：有無 `asset('uploads/' . $path)`
3. 檢查權限：`public/uploads/` 是否 755

### N+1 查詢問題？
```php
// ❌ 每個 post 都會額外查詢 categories
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->categories->pluck('name');
}

// ✅ 只查詢 2 次
$posts = Post::with('categories')->get();
```

---

## 🎨 元件開發參考

1. **先查 Storybook**：http://project.docs.isobar.tw/aia/aia-official-en
2. **參考映射表**：`laravel/resources/docs/structure-frontend.md`
3. **複雜互動**：使用 `@vendor-web` 的 JavaScript 橋接

---

## 📊 資料庫 Models

### Post（新聞/活動）
- `post_type`: 'news' | 'event'
- 關聯：`categories` (多對多)
- Scope：`Post::published()->ofType('news')->ordered()->get()`

### Member（團隊成員）
- `member_type`: 'board' | 'executive'
- Scope：`Member::published()->ofType('board')->ordered()->get()`

### Category（分類）
- 關聯：`posts` (多對多)

---

## 🧪 測試網址

- 測試站：https://4aia.isobar.com.tw/
- Storybook：http://project.docs.isobar.tw/aia/aia-official-en
- 本機後台：http://localhost/admin

---

## 💡 AI 工作原則

1. **主動讀取文件**：修改前先讀 `resources/docs/` 相關文件
2. **自動執行 build**：前端修改後自動 build + 清快取
3. **提供驗證步驟**：告知使用者如何測試修改
4. **同步型別定義**：Resource 改動後同步 TypeScript 型別
5. **不執行 Git 操作**：只提供建議的 commit 訊息
6. **完整測試路徑**：提供完整的測試 URL 和預期結果

---

## 📚 延伸閱讀

完整文件請參考：
- `CLAUDE.md` - 專案完整說明文件
- `laravel/resources/docs/ClaudeCode/README.md` - 架構策略說明
- `laravel/README.md` - 人類快速上手指南