良好的目錄結構是可維護專案的基石。建議採用以下模組化佈局：
project-root/ ├── public/ # Web 公開目錄（DocumentRoot） │ ├── index.php # 入口檔案 │ ├── assets/ # 靜態資源 │ │ ├── css/ │ │ ├── js/ │ │ ├── images/ │ │ └── fonts/ │ └── uploads/ # 用戶上傳檔案（需權限隔離） ├── src/ # 應用核心代碼（不可直接訪問） │ ├── Config/ # 配置檔案 │ ├── Controller/ # 控制器 │ ├── Model/ # 模型/資料層 │ ├── View/ # 視圖模板 │ ├── Service/ # 業務邏輯服務 │ ├── Middleware/ # 中間件 │ └── Utils/ # 工具類 ├── tests/ # 測試代碼 ├── vendor/ # Composer 依賴（.gitignore） ├── storage/ # 儲存目錄（日誌、快取、編譯模板） │ ├── logs/ │ ├── cache/ │ └── framework/ ├── .env # 環境變數（不提交版本庫） ├── composer.json └── README.md
public/ 可被 Web 直接訪問，核心代碼置於文檔根目錄之外User/、Order/ 而非單純的 Controller/Model）.env，結構化配置用 Config/ 下的 PHP 陣列檔| 類型 | 規範 | 範例 | 說明 |
|---|---|---|---|
| 目錄 | kebab-case（小寫+連字符） | user-profile, order-management | 語義清晰、URL 友好 |
| PHP 類別檔 | StudlyCaps（大駝峰）+ .php | UserController.php, OrderService.php | 類名與檔名一致，支援 PSR-4 自動載入 |
| PHP 非類別檔 | snake_case（小寫+底線）+ .php | config.php, helpers.php, bootstrap.php | 功能性腳本、配置檔 |
| 視圖模板 | kebab-case + .phtml/.blade.php | user-profile.phtml, order-list.blade.php | 區別於純 PHP 邏輯檔 |
| 資源檔 | kebab-case | main-style.css, app-script.js, logo.png | 統一小寫，避免大小寫敏感問題 |
| 測試檔 | 同被測類名 + Test.php | UserControllerTest.php | PHPUnit 慣例 |
images/ 或 img/ - 圖片資源styles/ 或 css/ - 樣式表scripts/ 或 js/ - JavaScriptincludes/ 或 inc/ - 共用引入檔media/ - 多媒體檔案fonts/ - 字體檔案vendor/ - 第三方庫migrations/ - 資料庫遷移腳本seeds/ - 測試種子數據yonghu/） → ✅ 英文語義命名（user/）UserController.php vs usercontroller.php） → ✅ 統一大小寫規範，Linux 區分大小寫config/ vs cfg/ vs conf/） → ✅ 專案內統一術語表統一的目錄結構與命名規範，能降低團隊認知負擔、避免跨平台部署問題、提升自動化工具鏈的可用性。建議在專案啟動時制定並寫入 CONTRIBUTING.md，配合程式碼審查強制執行。
