# 勞工與宿舍管理系統 — 測試伺服器部署指南

本部署包含：程式碼 + vendor（無需 Composer）+ 文件字體 + 完整測試。
資料庫不留任何資料——部署後依下方步驟建立管理員並生成 Demo 資料。

---

## 事前準備（伺服器需求）

| 項目 | 需求 |
|---|---|
| PHP | 8.3+（需啟用擴充：pdo_mysql, zip, gd, mbstring, fileinfo, openssl） |
| 資料庫 | MySQL 8（建立空資料庫，例如 `worker_system`） |
| Web 伺服器 | Apache 或 Nginx |
| 磁碟 | `storage/`、`bootstrap/cache/` 需可寫入 |

> ⚠️ **Web root 必須指向 `public/` 資料夾**，不是專案根目錄！
> 指向錯誤會令 `.env`（含密碼）可被任何人下載。

---

## 部署步驟

### 1. 放置檔案
把整個資料夾解壓到伺服器，例如 `/var/www/worker-system`（Windows：`D:\www\worker-system`）。

### 2. 設定 .env
```bash
cp .env.example .env          # Windows: copy .env.example .env
php artisan key:generate      # ⚠️ 全新伺服器才執行；如要沿用本機加密資料請改用本機的 APP_KEY
```
編輯 `.env`：
```
APP_NAME=WorkerSystem
APP_ENV=production
APP_DEBUG=false
APP_URL=http://測試伺服器網址

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=worker_system
DB_USERNAME=<專用帳號>        # 不要用 root！
DB_PASSWORD=<密碼>
```

### 3. 建立專用資料庫帳號（MySQL）
```sql
CREATE USER 'worker_app'@'localhost' IDENTIFIED BY '你的密碼';
GRANT ALL PRIVILEGES ON worker_system.* TO 'worker_app'@'localhost';
FLUSH PRIVILEGES;
```

### 4. 初始化
```bash
php artisan migrate --force           # 建立所有資料表
php artisan storage:link              # 公開符號連結（如需要）
php artisan config:cache
php artisan route:cache
php artisan view:cache
```
Linux 權限：
```bash
chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
```

### 5. 建立管理員帳號
```bash
php artisan app:provision-admin
# 會輸出自動生成的密碼，請記下；或用：
# php artisan app:provision-admin --username=admin --password=你的密碼
```

### 6. 生成客戶試用資料（可選）
用管理員登入 → 側欄「Demo 資料」→ 按「生成 Demo 資料」。
系統會自動生成：試用帳號（demo_iris / demo_kent，密碼 demo12345）、
12 位工人、20 份可預覽 PDF、宿舍房號、近三個月會計帳目、問題板資料。

### 7. 背景程序（必要！）
**Linux（推薦）**：
```bash
# systemd 服務跑 queue
php artisan queue:work            # 或排程內建每分鐘消化

# cron 加入：
* * * * * cd /var/www/worker-system && php artisan schedule:run >> /dev/null 2>&1
```
**Windows**：常駐執行 `php artisan schedule:work`（Laragon 可加入自動啟動）。

沒有這個程序：智能分配的距離更新、每日到期提醒不會執行。

---

## 部署後驗證清單

- [ ] 開啟首頁 → 導向登入頁
- [ ] 管理員登入成功
- [ ] 儀表板數字正常顯示
- [ ] Demo 資料生成後，工人詳情頁的 PDF 可以預覽
- [ ] 會計 → 月結報告 → 「下載 PDF」中文字正常（檔案約 5MB）
- [ ] 工人詳情 → 「立即匯出」Word 正常（檔名：姓名資料表_日期.docx）
- [ ] 「更新距離資料」按鈕有反應（約 1 分鐘後重新整理頁面看到距離）
- [ ] 直接開 `https://網址/.env` 應該是 404（安全檢查）

---

## 常見問題

| 症狀 | 原因／解法 |
|---|---|
| 500 錯誤 | 檢查 `storage/logs/laravel.log`；多為權限或 .env 未設定 |
| PDF 中文方框 | 確認 `public/fonts/NotoSansTC-Regular.ttf` 存在；刪除 `storage/fonts/*` 後重試 |
| 距離更新沒反應 | queue worker / schedule:run 沒有執行 |
| 匯入 Excel 失敗 | 檔案需為 .xlsx/.xls；表頭需與模板一致 |
| 忘記管理員密碼 | `php artisan app:provision-admin --password=新密碼` |