# 一起編輯製皂筆記

這個站的內容全部放在三個 JSON 檔裡，不用會寫程式也能改。

- `data/oils.json` — 油品庫
- `data/additives.json` — 精油、粉類與其他添加物
- `data/recipes.json` — 配方庫

**完全不想碰 JSON？** 直接開一個 [Issue](../../issues/new/choose)，把你知道的填進表單，有人會幫你加。

---

## 最需要幫忙的地方

目前 50 支油裡有 **30 支的 `tips`（使用心得）是空的**。數值都已經填好，缺的是「這支油實際做起來如何」的第一手經驗——洗感、trace 速度、成品顏色、你踩過的坑。

在油品庫按「待補心得」就能看到是哪 30 支。

同樣重要的是**修正**：現有 20 支的心得都標著 `"verified": false`，代表整理自公開資料、還沒有人實際驗證過。如果你做過某支油發現內容不對，那個修正比新增一支油更有價值。

---

## 改資料的流程

1. 在 GitHub 上找到要改的檔案，按右上角的鉛筆圖示
2. 改完在下方填一句話說明改了什麼
3. 選 **Create a new branch and start a pull request**
4. 送出

每個 PR 都會自動跑格式檢查。有錯的話 CI 會用中文告訴你哪一筆、哪個欄位有問題，改好再推一次就好。

想在本機先檢查：

```bash
node scripts/validate.mjs
```

---

## 新增一支油

在 `data/oils.json` 的 `oils` 陣列裡加一筆：

```json
{
  "id": "camellia",
  "zh": "苦茶油",
  "en": "Camellia Oil",
  "cat": "soft",
  "sap_naoh": 0.1362,
  "sap_koh": 0.1911,
  "ins": 108,
  "iodine": 83,
  "fa": {
    "lauric": 0, "myristic": 0, "palmitic": 9, "stearic": 2,
    "ricinoleic": 0, "oleic": 78, "linoleic": 9, "linolenic": 0
  },
  "max": null,
  "core": true,
  "verified": false,
  "tips": "台灣本地就有的好油，油酸高達 78%……",
  "blends": ["coconut76", "castor", "olive", "ricebran"]
}
```

| 欄位 | 說明 |
| --- | --- |
| `id` | 只能用小寫英文字母與數字，不可重複 |
| `zh` / `en` | 中文名／英文名 |
| `cat` | `hard` 硬油／`soft` 軟油／`butter` 脂類／`special` 特殊 |
| `sap_naoh` | 皂化價，**每公克油需要幾公克 NaOH**（不是 mg KOH/g）。範圍 0.05–0.30 |
| `sap_koh` | 同上但用 KOH。**必須約等於 `sap_naoh × 1.403`**，CI 會檢查 |
| `ins` | INS 值，0–300 的整數 |
| `iodine` | 碘價，0–250 |
| `fa` | 八種脂肪酸的百分比。**八個欄位都要填，沒有就填 0**。加總須落在 80–105 |
| `max` | 建議用量上限（%）。沒有特定上限就填 `null` |
| `core` | 有完整心得與搭配就填 `true`，只有數值填 `false` |
| `verified` | 心得經過你實際製作驗證才填 `true` |
| `tips` | 使用心得。沒有就填空字串 `""` |
| `blends` | 常見搭配的油品 id 陣列。`core` 為 `true` 時至少要一個 |

**蠟酯類**（蜜蠟、荷荷芭、羊毛脂）的主要成分不在這八個欄位裡，脂肪酸加總會遠低於 80。請加上 `"wax": true`，驗證就會跳過加總檢查。

**只有一種單元不飽和脂肪酸例外**：棕櫚油酸（palmitoleic）沒有獨立欄位，慣例是併入 `oleic`，因為兩者在皂中的表現接近。澳洲胡桃油與沙棘油都是這樣處理的，請在 `tips` 裡註明。

### 數值該去哪裡找

按可信度排序：

1. **供應商的規格表或 COA** — 最準，因為那就是你手上這批油的實測值
2. 油脂化學的教科書與期刊
3. 皂化價對照表（SoapCalc、Brambleberry、The Sage 等）

請在 PR 說明裡附上出處。**不要從別的計算機網站直接抄一整批**——那些表本身也有錯，而且授權不明。

---

## 寫使用心得的方針

心得欄是這個站跟一般皂化計算機唯一的差別，值得寫好。

**寫這些：**

- 洗感——乾爽還是滋潤，泡沫大還是綿密
- trace 速度快慢，會不會逼你趕工
- 成品顏色、氣味，以及會不會隨時間變化
- 建議用量與超過的後果
- 保存與酸敗傾向
- 採購上的注意事項（規格容易買錯、需要先融勻、價差大…）

**避免這些：**

- 療效宣稱。「保濕」可以，「治療濕疹」不行
- 沒有依據的絕對句。與其寫「絕對不能超過 20%」，不如寫「超過 20% 泡沫會被壓抑」
- 從商品文案抄來的行銷語言

**誠實標示 `verified`。** 沒有實作過就填 `false`，這不丟臉——整理二手資料本身就有價值，只是讀的人有權知道它的來源等級。

---

## 分享配方

最快的方式：在計算機按 **配方摘要 → 複製配方 JSON**，貼進 `data/recipes.json` 的 `recipes` 陣列，然後把 `author`、`desc`、`notes` 填一填。

```json
{
  "id": "my-recipe",
  "name": "配方名稱",
  "kind": "community",
  "goal": "allround",
  "author": "你的名字或 GitHub 帳號",
  "date": "2026-07-24",
  "desc": "一句話說明這個配方想解決什麼。",
  "oil_total": 1000,
  "superfat": 5,
  "lye_conc": 30,
  "cure": 42,
  "items": [
    { "id": "coconut76", "pct": 25 },
    { "id": "palm", "pct": 25 },
    { "id": "olive", "pct": 50 }
  ],
  "additives": [{ "id": "lavender", "pct": 2.5 }],
  "notes": "實作心得、踩過的坑、下次想調整的地方。"
}
```

| 欄位 | 說明 |
| --- | --- |
| `kind` | 社群投稿一律 `community`。`template` 保留給首頁的入門範本 |
| `goal` | `allround` 萬用／`face` 洗臉／`hair` 洗髮／`household` 家事／`baby` 嬰幼兒／`body` 沐浴 |
| `oil_total` | 預設總油重（g），載入計算機時的起始值 |
| `superfat` | 超脂率 %，0–20 |
| `lye_conc` | 鹼水濃度 %，20–50。**存濃度不存倍數**，因為倍數會隨超脂率漂移 |
| `cure` | 建議熟成天數 |
| `items` | 各油佔總油重的百分比，**加總必須是 100** |
| `additives` | 精油填百分比，粉類填每 1000g 油的克數。用量不可超過 `additives.json` 定義的 `max` |

`notes` 是最有價值的欄位。請寫你**實際做出來**的觀察，不要只寫配方設計理念。做了幾次、脫模好不好脫、熟成多久才好用、有沒有失敗過——這些才是別人真正需要的。

---

## 新增添加物

`data/additives.json` 的格式：

```json
{
  "id": "lavender",
  "zh": "薰衣草",
  "en": "Lavender",
  "kind": "eo",
  "unit": "pct_oil",
  "lo": 2,
  "hi": 3,
  "max": 3,
  "flags": [],
  "note": "手工皂最百搭的精油……"
}
```

- `kind`：`eo` 精油／`powder` 粉類／`other` 其他
- `unit`：`pct_oil` 佔油重百分比（精油用）／`g_per_kg` 每 1000g 油的克數（粉類用）
- `lo` / `hi`：常見用量範圍。`max`：建議上限，超過計算機會警告。沒有明確上限就填 `0`
- `flags`：`accel` 加速 trace／`irritant` 皮膚刺激／`discolor` 會變色／`fade` 會褪色／`heat` 會升溫／`caution` 特定族群禁忌

`note` 請寫清楚**為什麼**有這個上限。「肉桂上限 0.6%」不夠，要寫「強效皮膚刺激物」。

---

## 安全相關的內容

涉及安全的改動請附上依據。以下這些數字不接受「我覺得」：

- 超脂率、鹼水濃度的建議範圍
- 精油的用量上限
- 「新手入門」頁的操作步驟與警告

如果你認為現有的某條安全建議太保守或太寬鬆，請開 Issue 討論，附上來源，不要直接發 PR 改掉。

---

## 授權

送出貢獻即表示你同意：

- 程式碼以 [MIT](LICENSE) 授權
- 油品、添加物與配方內容以 [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/deed.zh-Hant) 授權

也就是說，別人可以自由使用與改作你的貢獻，只要標示來源並以相同方式分享。