# 一起編輯調香筆記

不需要會寫程式。所有內容都放在兩個 JSON 檔裡，可以直接在 GitHub 網頁上編輯。

- `data/materials.json` — 香料庫
- `data/recipes.json` — 配方庫

## 最簡單的方式：在 GitHub 網頁上改

1. 打開要改的檔案，例如 [`data/materials.json`](data/materials.json)
2. 點右上角的鉛筆圖示 ✏️
3. 改完後往下捲，填寫「你改了什麼」，選 **Create a new branch and start a pull request**
4. 送出。有人會來看，沒問題就會合併

不確定格式對不對？沒關係，送出後會自動跑檢查，錯了會告訴你哪一行有問題。

## 完全不想碰 JSON

直接開一個 [Issue](../../issues/new/choose)，把你想加的香料或配方寫在裡面就好。

---

## 新增一支香料

複製這個範本，填進 `materials` 陣列裡：

```json
{
  "id": "basil",
  "zh": "羅勒",
  "en": "Basil",
  "note": "top",
  "family": "herbal",
  "type": "essential",
  "intensity": 4,
  "tenacity": "1-2 小時",
  "desc": "清新的青草辛香，帶茴香般的甜尾，義式料理感強烈。",
  "blends": ["bergamot", "lime", "geranium", "clarysage"],
  "ifra": { "limit": null, "reason": "一般用量安全" },
  "tips": "極易氧化，開封後三個月內用完最好。"
}
```

### 欄位說明

| 欄位 | 必填 | 說明 |
|---|---|---|
| `id` | ✅ | 全小寫英文，不含空格，全站唯一。通常用英文名去掉空格 |
| `zh` | ✅ | 中文名。有多種常見譯名時用 `／` 分隔，例如 `絲柏／柏樹` |
| `en` | ✅ | 英文名 |
| `note` | ✅ | `top`（前調）／ `middle`（中調）／ `base`（後調） |
| `family` | ✅ | `citrus` `floral` `herbal` `woody` `resin` `spice` `green` `tea` `musk` `balsam` |
| `type` | ✅ | `essential`（精油）／ `absolute`（原精）／ `synthetic`（合成香精） |
| `intensity` | ✅ | 香氣強度 1–5。1 是幾乎聞不到，5 是一滴就主導全場 |
| `tenacity` | ✅ | 留香時間，自由文字，例如 `"3-5 小時"` |
| `desc` | ✅ | 氣味描述。**寫你真的聞到什麼**，而不是行銷詞。兩句以內 |
| `blends` | ✅ | 常見搭配，填其他香料的 `id` 陣列。填不存在的 id 會被檢查擋下 |
| `ifra.limit` | ✅ | 建議上限（佔成品體積的 %）。沒有明確限制就填 `null` |
| `ifra.reason` | ✅ | 為什麼有這個限制，或為什麼沒有 |
| `tips` | ✅ | 實際使用心得。這是最有價值的欄位 |

### 關於 `note` 的判斷

前中後調講的是**揮發速度**，不是香味類型。判斷不了時，參考同家族的既有香料：柑橘類幾乎都是前調、樹脂與重木質都是後調、花香多半落在中調。

邊界案例（生薑、丁香、杜松、絲柏）本來就有爭議，你如果覺得現在的分類不對，歡迎在 PR 裡說明理由一起討論。

### 關於 `ifra`

這是最需要謹慎的欄位。請注意：

- 填 `limit` 時請附上你的依據（供應商 SDS、IFRA 標準文件、學術資料），寫在 PR 說明裡
- **不確定就填 `null`**，並在 `reason` 寫「請依供應商 SDS」。寧可保守，不要編造數字
- 合成香精（`type: synthetic`）各家配方不同，一律填 `null`

---

## 分享一支配方

複製這個範本，填進 `recipes.json` 的 `recipes` 陣列裡：

```json
{
  "id": "citrus-woods",
  "name": "柑橘木質",
  "author": "@你的GitHub帳號",
  "date": "2026-07-22",
  "type": "EDT",
  "desc": "一句話說明這支香水想做什麼。",
  "items": [
    { "id": "bergamot", "ml": 0.8 },
    { "id": "lavender", "ml": 0.6 },
    { "id": "cedarwood", "ml": 0.7 }
  ],
  "alcohol99": 27.9,
  "alcohol95": 0,
  "water": 0,
  "aging": 14,
  "notes": "熟成過程的觀察、踩到的坑、下次會怎麼改。"
}
```

`items` 裡的 `id` 必須是 `materials.json` 裡已存在的香料。

### 寫配方的小提醒

- **請寫 `notes`。** 「第 3 天太衝、第 14 天才融合」這種話，比配方本身更有價值
- `date` 用 `YYYY-MM-DD`
- `type` 填 `Parfum` / `EDP` / `EDT` / `EDC` / `Body Mist`，濃度會自動算，不用你填
- 在計算機頁面按「複製成 Markdown」可以快速拿到自己的配方數據

---

## 自動檢查

送出 PR 後會自動驗證：

- JSON 語法正確
- 必填欄位齊全、值在允許範圍內
- `id` 沒有重複
- `blends` 與配方 `items` 引用的香料都真實存在

檢查沒過不代表你的內容有問題，多半只是少個逗號。點進去看錯誤訊息會告訴你哪一筆、哪個欄位。改好再推一次就好。

## 行為準則

這是一個興趣社群。討論分類、氣味描述、用量的差異都很正常——每個人的鼻子和買到的油都不一樣。請假設對方是善意的，並說明你的理由而不只是結論。