# 勞工與宿舍管理系統

香港勞工仲介／宿舍管理的內部後台，涵蓋工人檔案、公司店鋪、宿舍、文件、會計、問題追蹤與 Excel 匯入等功能。

## 環境需求

- PHP 8.3+
- Composer 2.x
- SQLite（開發）或 MySQL / MariaDB（建議生產環境）
- [Laragon](https://laragon.org/)（Windows 本機開發）

## Laragon 快速開始

```bash
# 1. 進入專案目錄
cd c:\laragon\www\worker-system

# 2. 安裝依賴
composer install

# 3. 環境設定
copy .env.example .env
php artisan key:generate

# 4. 資料庫
php artisan migrate

# 5. 建立管理員（請立即更改密碼）
php artisan app:provision-admin --password=你的安全密碼

# 6. 放置 Word 合約樣板（匯出合約功能需要）
# 將 contract_template.docx 放到 storage/app/
```

瀏覽器開啟 Laragon 對應網址（例如 `http://worker-system.test`），使用管理員帳號登入。

## 常用指令

| 指令 | 說明 |
|------|------|
| `php artisan app:provision-admin` | 建立或更新管理員帳號 |
| `php artisan documents:provision-folders` | 為所有工人／公司補建文件資料夾 |
| `php artisan queue:work` | 執行背景佇列（智能宿舍分配需要） |
| `php artisan test` | 執行測試 |
| `php artisan migrate` | 執行資料庫遷移 |

## 背景佇列

智能宿舍分配（地理編碼、路線距離計算）使用 Queue。本機開發請另開終端機執行：

```bash
php artisan queue:work
```

生產環境建議以 Supervisor 或 Windows 服務常駐執行。

## 主要模組

| 模組 | 路由 | 說明 |
|------|------|------|
| 儀表板 | `/dashboard` | 宿舍空位、合約到期、問題通知 |
| 工人檔案 | `/workers` | CRUD、Word 合約匯出 |
| 宿舍管理 | `/dormitories` | 宿舍 CRUD、容量管理 |
| 智能宿位分配 | `/smart-dorm-assignment` | 依距離推薦宿舍 |
| 會計管理 | `/accounting` | 租金收支、月結／年報 |
| 問題追蹤板 | `/issues` | Issue 建立、回覆、指派 |
| 文件處理 | `/documents` | 工人／公司 PDF 上傳與預覽 |
| Excel 匯入 | `/import` | 僅管理員可用 |
| 帳號管理 | `/users` | 僅管理員可用 |

## 權限說明

- **管理員（admin）**：完整權限，含刪除、Excel 匯入、帳號管理
- **一般用戶（user）**：可新增／編輯大部分資料，刪除受限

## 檔案與樣板

| 路徑 | 用途 |
|------|------|
| `storage/app/contract_template.docx` | 工人合約 Word 匯出樣板 |
| `storage/app/documents/` | 上傳的 PDF 文件（勿公開） |
| `config/documents.php` | 文件類別與大小限制設定 |

Word 樣板可用以下佔位符：`${zh_name}`、`${en_name}`、`${id_card}`、`${branch_name}`、`${position}`

## 測試

```bash
php artisan test
```

## 部署指南

| 檔案 | 適用情境 |
|------|----------|
| `DEPLOY.md` | 一般 Linux／Windows 測試伺服器（自行裝 Nginx/Apache + MySQL） |
| `BT-DEPLOY.md` | 有 root 的伺服器 + 寶塔面板（aaPanel） |
| `IONOS-DEPLOY.md` | IONOS Web Hosting 共享主機（無 root、無寶塔，靠 cron 跑排程） |

## 生產環境部署檢查清單

```
□ APP_ENV=production、APP_DEBUG=false
□ 使用 MySQL/PostgreSQL，勿用 SQLite
□ SESSION_ENCRYPT=true
□ php artisan migrate --force
□ php artisan app:provision-admin（建立管理員）
□ 設定 queue worker 常駐
□ 放置 contract_template.docx
□ 啟用 HTTPS
□ 確認 storage/app/documents/ 不可從公網直接存取
□ 定期備份資料庫（含個人身份資料）
```

## 設計文件

詳細業務規則與模組設計請參閱 `docs/plans/`：

- `2026-08-26-accounting-design.md` — 會計模組
- `2026-08-26-smart-dorm-assignment-design.md` — 智能宿舍分配
- `2026-08-26-account-management-design.md` — 帳號管理

## 技術棧

- Laravel 13
- Bootstrap 5 + Bootstrap Icons
- maatwebsite/excel — Excel 匯入
- phpoffice/phpword — Word 合約匯出

## 授權

MIT License