# 日語練習月誌後端上線規劃

## 目標

1. 公開站維持無登入、任何人可直接使用。
2. 前台盡量維持現在的靜態架構，不因為加後台就整站重做。
3. 管理者可以登入、編輯教材、上傳音檔與 PDF、安排發布。
4. 發布後仍輸出目前前台可直接讀取的 `data/materials.json`，降低前後台耦合。

## 建議落地架構

### 公開站

- 保留目前的 `index.html`、`styles.css`、`script.js`。
- 前台繼續讀取 `data/materials.json`。
- 學習者自己的進度仍先存在瀏覽器 `localStorage`。

### 管理端

- 建議技術線：`PHP 8.2 + MySQL 8 + 同站資料輸出`
- 原因：
  - 對 HostGator 最友善，不需要先把公開站搬離靜態部署。
  - 管理 API、登入與上傳流程都可以直接放在同一個主機方案內。
  - 發布時可以直接生成新的 `data/materials.json`，讓前台無痛沿用。

### 素材儲存

- 第一期可先存在站內檔案系統：
  - 私有暫存：`storage/uploads/tmp/`
  - 正式素材：`public/uploads/audio/`、`public/uploads/image/`、`public/uploads/pdf/`
- 若之後音檔變多，再切到 S3 相容物件儲存。

## 前後台拆分方式

### 公開站保持不變

- `GET /index.html`
- `GET /styles.css`
- `GET /script.js`
- `GET /data/materials.json`

### 管理端新增

- `GET /admin/`
- `POST /api/admin/auth/login`
- `GET /api/admin/me`
- `POST /api/admin/assets`
- `POST /api/admin/content-items`
- `POST /api/admin/publish/materials`

## 權限角色

- `super_admin`
  - 管理帳號、重設密碼、刪除內容、回滾發布版本。
- `editor`
  - 新增與編輯教材、上傳素材、建立草稿、送出發布。
- `reviewer`
  - 檢查內容、核准排程、不直接管理帳號。

第一期若只有一位管理者，可先只開 `super_admin` 與 `editor`。

## 內容生命週期

1. 建立草稿
2. 綁定標籤與主題
3. 綁定音檔或補充 PDF
4. 預覽輸出結果
5. 送審或直接發布
6. 生成新的 `data/materials.json`
7. 保留舊版快照，必要時回滾

## 發布模型

### 核心原則

- 資料庫保存可編輯的正規化資料。
- 公開站只吃發布後的靜態快照。
- 發布動作不是直接改前台 HTML，而是重新編譯教材 JSON。

### 好處

- 前台速度快，快取容易做。
- 後台故障時，公開站仍可讀取上一版 `materials.json`。
- 可以保留版本號與發布紀錄，出問題能快速回退。

## 第一期一定要做的功能

1. 管理者登入與安全 Session Cookie
2. 教材 CRUD
3. 主題管理與每日主題排程
4. 音檔、圖片、PDF 上傳
5. 發布按鈕與 JSON 快照輸出
6. 發布歷史與回滾

## 第二期再做的功能

1. 多人協作審核
2. 排程自動發布
3. 音檔波形、時長與轉檔
4. 學習者帳號與跨裝置同步
5. 搜尋、標籤報表、熱門內容分析

## 安全與維運要求

- 密碼只存 `password_hash`。
- 管理端 Cookie 必須 `HttpOnly`、`Secure`、`SameSite=Strict`。
- 所有上傳檔案都要重新命名，不能使用原始檔名直接公開。
- 上傳前檢查 MIME、大小、副檔名、惡意腳本。
- 發布前做 JSON 驗證，失敗時不覆蓋線上版。
- 每次發布都要留下版本號、操作者、時間、checksum。

## 推薦路線圖

### Phase 0

- 維持現在這個靜態站上線。
- 內容仍手動維護於 `data/materials.json`。

### Phase 1

- 做管理登入、教材 CRUD、素材上傳。
- 讓後台能產生新的 `data/materials.json`。

### Phase 2

- 補發布審核、排程與回滾。
- 將管理活動與發布歷史完整記錄。

### Phase 3

- 若需要會員化，再加入學習者帳號、雲端進度同步、收藏與個人推薦。

## 成功標準

- 管理者不用手改前台檔案，也能更新教材。
- 新增一個複誦句加音檔，五分鐘內可以從後台發到前台。
- 發布失敗不影響公開站既有內容。
- 前台仍然可以在 HostGator 靜態公開環境穩定運作。