Merge pull request 'chore: 加入 Windsurf 規則與啟動文件' (#42) from chore/windsurf-startup-docs into master

Reviewed-on: #42

.gitignore

@@ -27,6 +27,4 @@ yarn-error.log
 /frontend/dist
 /frontend/.env
 
-# windsurf
-.windsurf/rules
 

.windsurf/rules/ponytail-lazy-senior-dev-mode.md

@@ -0,0 +1,26 @@
+# Ponytail, lazy senior dev mode
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+## Before writing any code
+
+Stop at the first rung that holds:
+
+- Does this need to be built at all? (YAGNI)
+- Does the standard library already do this? Use it.
+- Does a native platform feature cover it? Use it.
+- Does an already-installed dependency solve it? Use it.
+- Can this be one line? Make it one line.
+- Only then: write the minimum code that works.
+
+## Rules
+
+  - No abstractions that weren't explicitly requested.
+  - No new dependency if it can be avoided.
+  - No boilerplate nobody asked for.
+  - Deletion over addition. Boring over clever. Fewest files possible.
+  - Question complex requests: "Do you actually need X, or does Y cover it?"
+  - Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
+  - Mark intentional simplifications with a ponytail: comment. If the shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic), the comment names the ceiling and the upgrade path.
+  
+Not lazy about: input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

docs/STARTUP.md

@@ -0,0 +1,193 @@
+# CFDivePlatform 啟動指令
+
+## 專案位置
+
+```powershell
+C:\laragon\www\CFDivePlatform
+```
+
+## 1. 進入專案目錄
+
+```powershell
+cd C:\laragon\www\CFDivePlatform
+```
+
+## 2. 準備 `.env`
+
+如果尚未建立 `.env`：
+
+```powershell
+copy .env.example .env
+```
+
+確認 `.env` 至少設定以下項目：
+
+```env
+APP_KEY=
+DB_DATABASE=CFDivePlatform
+DB_USERNAME=cfdiveuser
+DB_PASSWORD=your_password
+MYSQL_ROOT_PASSWORD=your_root_password
+
+REVERB_APP_ID=your_reverb_app_id
+REVERB_APP_KEY=your_reverb_app_key
+REVERB_APP_SECRET=your_reverb_app_secret
+VITE_REVERB_APP_KEY=your_reverb_app_key
+```
+
+如果 `APP_KEY` 是空的，可在容器啟動後執行：
+
+```powershell
+docker compose exec app php artisan key:generate
+```
+
+## 3. 啟動 Docker 服務
+
+第一次啟動，或 Dockerfile / compose 設定有變更時：
+
+```powershell
+docker compose up -d --build
+```
+
+平常啟動：
+
+```powershell
+docker compose up -d
+```
+
+## 4. 查看服務狀態
+
+```powershell
+docker compose ps
+```
+
+查看所有服務 log：
+
+```powershell
+docker compose logs -f
+```
+
+只查看 Laravel App log：
+
+```powershell
+docker compose logs -f app
+```
+
+## 5. 初始化與維護指令
+
+容器啟動時會自動執行部分初始化流程：
+
+- 安裝 Composer 依賴
+- 等待 MySQL 啟動
+- 執行 migration
+- 清除 Laravel cache
+- 建立 storage link
+- 產生 Swagger 文件
+
+如需手動執行，可使用：
+
+```powershell
+docker compose exec app composer install
+docker compose exec app php artisan migrate
+docker compose exec app php artisan storage:link
+docker compose exec app php artisan l5-swagger:generate
+```
+
+清除 Laravel 快取：
+
+```powershell
+docker compose exec app php artisan config:clear
+docker compose exec app php artisan cache:clear
+docker compose exec app php artisan route:clear
+docker compose exec app php artisan view:clear
+```
+
+## 6. 建立管理員帳號
+
+```powershell
+docker compose exec app php artisan app:create-admin "Admin" "admin@example.com" --password="your_password"
+```
+
+密碼至少需要 8 碼。
+
+## 7. 前端 Vite 開發模式
+
+如果要使用本機 Vite 開發模式：
+
+```powershell
+npm install
+npm run dev
+```
+
+正式建置：
+
+```powershell
+npm run build
+```
+
+Docker Compose 內也有 `frontend` 服務，預設網址為：
+
+```text
+http://localhost:5173
+```
+
+## 8. 重啟 frontend
+
+如果 frontend 是透過 Docker Compose 啟動：
+
+```powershell
+docker compose restart frontend
+```
+
+如果有修改 frontend 的 Dockerfile、環境變數或 build 內容，建議重建：
+
+```powershell
+docker compose up -d --build frontend
+```
+
+如果是使用本機 Vite 開發模式，先在原本終端機按 `Ctrl + C` 停止，再重新執行：
+
+```powershell
+npm run dev
+```
+
+## 9. 服務網址
+
+| 服務 | URL |
+| --- | --- |
+| API / Laravel + Nginx | <http://localhost:8080> |
+| Frontend Docker | <http://localhost:5173> |
+| phpMyAdmin | <http://localhost:8081> |
+| Mailpit | <http://localhost:8025> |
+| Reverb WebSocket | <ws://localhost:8085> |
+| Health Check | <http://localhost:8080/health> |
+
+## 10. 停止服務
+
+停止容器，但保留資料庫 volume：
+
+```powershell
+docker compose down
+```
+
+停止容器並移除 volume，會清除 MySQL 資料：
+
+```powershell
+docker compose down -v
+```
+
+## 最短啟動流程
+
+```powershell
+cd C:\laragon\www\CFDivePlatform
+copy .env.example .env
+docker compose up -d --build
+docker compose exec app php artisan key:generate
+docker compose ps
+```
+
+啟動完成後開啟：
+
+```text
+http://localhost:8080
+```