# XSPA 店家探索站台

以 PHP + MySQL/MariaDB 打造的店家資訊站台：前台探索／搜尋／詳情、會員系統、推薦技師、站內貨幣（N 幣）、新手村 API 同步，以及完整的後台營運工具。

> **本包為 LITE 版**：不含討論區（`forum/`）與外掛管理。快速安裝見 **`INSTALL-LITE.txt`**；環境需求見 **`ENVIRONMENT.txt`**。

---

## 功能模組一覽

| 模組 | 說明 | 主要入口 |
| --- | --- | --- |
| 店家探索 | 列表、搜尋、城市篩選、店家詳情 | `index.php`、`store.php` |
| 資料同步 | 自新手村 API 更新 `spa_store_snapshots` | 後台 `admin/sync.php` |
| 圖片快取（選用） | 封面／相簿預先下載至 `uploads/stores/` | 後台 `admin/sync.php` → 同步圖片 |
| 推薦技師 | 建檔、評論、點讚、標籤、收藏 | 店家頁、`admin/masseurs.php` |
| 會員推薦店家 | 定點／非定點送審，管理員核准後公開 | `member_add_store.php`、`admin/approve_stores.php` |
| 站內貨幣 | 獎勵、轉帳、付費文章、帳本；顯示名稱可自訂 | 後台 `admin/ncoin.php`、`member_profile.php` |
| 會員回報 | 歇業、更名、技師離店等群眾回報 | 探索列表／店家頁 |
| 瀏覽統計 | 頁面瀏覽次數、訪客、在線 | 後台 `admin/stats.php` |
| 變現 | Google AdSense | `admin/adsense.php` |

設定檔範本見 `data/*.example.json`；環境變數完整列表見 `config/app.php` 註解。

---

## LITE 版說明

本安裝包**不含** `forum/` 目錄，系統自動：

- 後台**不顯示**「外掛管理」
- 功能快速設定最高僅**模式三**（無討論區模式四）
- 前台導覽不出現討論區連結

若要完整版（含討論區），請部署含 `forum/bootstrap.php` 的完整包。

---

## 系統需求

詳細環境說明（本機 XAMPP、共享主機、必要／選用擴充）見 **`ENVIRONMENT.txt`**。

最低需求摘要：

- PHP 8.0+（建議 8.1+；必要：`pdo_mysql`）
- MySQL 5.7+ 或 MariaDB 10.3+
- Apache 或 Nginx（無需 mod_rewrite）
- 可寫入：`config/`、`data/`、`uploads/`
- 同步／寄信／圖片下載建議啟用 **curl**；中文建議 **mbstring**

---

## 目錄結構

```
fate/
├── install/                         安裝精靈（未安裝時 index 與 admin 導向）
├── login.php / register.php       登入、註冊
├── member_profile.php               我的帳號（N 幣、轉帳、收藏）
├── member_add_store.php             會員推薦店家
├── config/                          app.php、pdo.php、db.php
├── admin/                           後台（見下方「後台頁面」）
├── api/                             AJAX（技師、回報、廣告計次等）
├── includes/                        共用 PHP 邏輯
├── templates/default|minimal/       前台模版
├── static/                          前台 CSS／JS
├── data/                            JSON 設定（*.example.json 為範本）
├── sql/install.sql                  一鍵建庫建表
└── uploads/                         頭像、技師圖、店家快取、廣告圖
    └── stores/                      圖片同步快取 + 會員上傳（member_* 前綴）
```

---

## 安裝步驟

### 1. 放置檔案

將 `fate/` 放到網站根目錄或子目錄（例如 `https://example.com/fate/`）。

### 2. 執行安裝精靈

瀏覽 **`/install/`**（或首頁 `index.php`，未安裝時會自動導向）。若尚未完成安裝，進入後台也會自動導向此頁。

精靈會依序：

0. **環境與目錄權限**（PHP、PDO、`config/`／`data/`／`uploads/` 可寫等；可一鍵建立目錄／修正權限）
1. **填寫資料庫連線**（請使用主機控制台**已建立**的 MySQL 資料庫與使用者；測試後寫入 `config/db.php`）
2. 在該資料庫內**建立全部資料表**（精靈不會 `CREATE DATABASE`；共享主機須先在 HestiaCP／cPanel 建庫）
3. 建立第一位 `role = admin` 管理員並登入後台

安裝完成後請**刪除或限制** `install/` 目錄存取。

亦可改用手動匯入 `sql/install.sql`（具 root 權限的本機環境可含建庫），再開啟 `/install/` 建立管理員。

### 3. 複製設定範本（選用）

```bash
cp data/fate_secrets.example.json       data/fate_secrets.json
cp data/fate_mail_settings.example.json data/fate_mail_settings.json
cp data/fate_adsense.example.json       data/fate_adsense.json
cp data/fate_ui_settings.example.json   data/fate_ui_settings.json
cp data/fate_plugins.example.json       data/fate_plugins.json
```

亦可登入後台於對應頁面填寫；`fate_ncoin_settings.json`、`fate_masseur_rewards.json` 等會在後台首次儲存時自動建立。

> `config/db.php` 與 `data/*.json`（非 `*.example.json`）含敏感資訊，已在 `.gitignore` 排除，勿提交公開。

### 4. 目錄權限

網站執行身分需可寫入 `config/`（寫入 `db.php`）、`data/`、`uploads/`（含 `avatars/`、`stores/`）。Apache 主機已內建 `config/.htaccess`、`data/.htaccess` 阻擋 HTTP 直接讀取設定與金鑰；Nginx／IIS 須另行設定 deny。

（管理員帳號由安裝精靈建立；若需手動指定，可對既有會員執行 `UPDATE members SET role = 'admin', status = 1 WHERE username = '…'`。）

---

## 後台頁面

| 路徑 | 用途 |
| --- | --- |
| `admin/index.php` | 概覽、待辦、快捷連結 |
| `admin/sync.php` | **同步店家** + **同步圖片至本站**（選用） |
| `admin/spa_api_key.php` | 新手村 API 金鑰、本站 URL 白名單 |
| `admin/site_modes.php` | 功能模式一鍵切換（LITE 三種／完整版四種） |
| `admin/masseurs.php` | 推薦技師、標籤、預設頭像 |
| `admin/approve_stores.php` | 審核會員推薦店家 |
| `admin/ncoin.php` | 貨幣名稱、獎勵、轉帳、手動發放、帳本 |
| `admin/members.php` | 會員、審核、停權、信箱驗證 |
| `admin/email_settings.php` | 驗證信範本、發信管道（Brevo／SMTP／mail()）、反向 IMAP 驗證 |
| `admin/template.php` | 站名、副標、模版、社群連結 |
| `admin/stats.php` | 瀏覽統計、建立 `fate_visit_log` |
| `admin/adsense.php` | Google AdSense |

---

## 新手村同步（概要）

1. 至 **新手村 API** 設定金鑰，並將本站網址加入白名單（不可為 IP／localhost）。
2. 後台 **同步店家** → 分批更新 `spa_store_snapshots`（不含圖片下載）。
3. （選用）**同步圖片至本站** → 快取至 `uploads/stores/`；前台 `fate_spa_asset_url()` 自動本地優先、無檔則走新手村。
4. CLI：`php admin/sync_spa_stores.php`（與後台同一套 step 邏輯）。

圖片同步注意：建議 ≥6GB 空間、流量自負；**不擁有相片版權，請勿加浮水印**；可「刪除所有已下載相片」還原（會保留 `member_` 前綴的會員上傳）。

---

## 站內貨幣（N 幣）

- 後台 **站內貨幣設定/紀錄** 可自訂前台顯示名稱（預設「N 幣」）、各行為獎勵、轉帳手續費與留底、手動發放。
- **技師標籤獎勵**可設同一技師／每日技師數上限（僅限制 N 幣發放，**不限制**標籤點選次數）。
- 帳本來源：`fate_reward_ledger`。
- 會員：`member_profile.php` → N 幣歷程／轉帳。

設定檔：`data/fate_ncoin_settings.json`、`data/fate_masseur_rewards.json`（後者含技師與回報獎勵，於 ncoin 頁統一編輯）。

---

## 常用環境變數

| 變數 | 說明 |
| --- | --- |
| `FATE_DB_*` | 資料庫連線 |
| `FATE_TEMPLATE` | 強制前台模版識別名；或後台「網站與模版」切換 |
| `FATE_SESSION_COOKIE_PATH` | 子目錄部署時設 `/fate/` 等 |
| `FATE_SESSION_LIFETIME_SEC` | 登入 Session 最長秒數（預設 30 天） |
| `FATE_PUBLIC_SITE_ORIGIN` | 對外網址（驗證信連結） |
| `FATE_BREVO_API_KEY` | Brevo 寄信 |
| `FATE_DISABLE_PUBLIC_REGISTRATION` | `1` 關閉註冊 |
| `FATE_MEMBER_MANUAL_APPROVAL` | 鎖定新會員人工審核（`1` 開／`0` 關）；未設時由後台開關控制，預設關 |
| `FATE_SPA_API_BASE` | 新手村 API 根 URL |
| `FATE_SYNC_BATCH_DETAIL` | 資料同步每批店家數 |
| `FATE_SYNC_BATCH_IMAGES` | 圖片同步每批張數 |

完整列表見 `config/app.php` 註解。

---

## 注意事項

- **獨立部署、無 newbies**：同步與 API 金鑰功能停用；店家資料可改寫入 `spa_store_snapshots` 或後台手動新增。
- **金鑰與設定勿公開**：`config/db.php`、`data/*.json`（非 example）勿提交版本庫或打包公開；金鑰可改以環境變數 `FATE_SECRETS_FILE` 指向 web 根目錄外。
- **Schema**：全新安裝以 `sql/install.sql` 為準（已涵蓋會員、店家快照表結構、論壇、技師、N 幣等全部表與欄位）。舊站升級仍可由執行時 `ensure_table`／`ALTER` 補齊；新站請直接匯入 install.sql。
- **子目錄部署**：記得設定 `FATE_SESSION_COOKIE_PATH` 與 `FATE_PUBLIC_SITE_ORIGIN`。

---

## 授權

請依專案實際授權條款使用。
