演算式の設定ガイド

このドキュメントは SWPF のテンプレート定義で type: "EXPRESSION" を使い、演算式 expr を評価して結果を得るための手順と注意点を、初心者でも迷わないようにサンプル付きでまとめたものです。

---

1. EXPRESSION とは何か

type: "EXPRESSION" は、テンプレート（TEMPLATE_JSON）に書いた 演算式 を評価し、 数値（または数値として扱える値） を結果として返すためのタイプです。

RULE_JSON が「どの templateid を選ぶか」を決めるのに対し、EXPRESSION は「選ばれたテンプレートで数値を計算して結果を作る」役割です。 「不快指数」「VPD」「露点」「温度補正」などの計算が典型です。

---

2. 登場人物（RULE_JSON と同じ要領）

2.1 RAW（生データ）

{
  "temp": 28.4,
  "humid": 62,
  "device": {"id": "A-001"}
}

2.2 PARAMS_JSON（論理名 → 生データのパス）

{
  "TEMP": "temp",
  "HUMID": "humid",
  "DEVICE_ID": "device.id"
}

2.3 PARAMS_MAP（評価器が参照する実値マップ）

PARAMS_JSON に従い RAW から抽出した実値です。EXPRESSION は基本的にこれだけを参照します。

{
  "TEMP": 28.4,
  "HUMID": 62,
  "DEVICE_ID": "A-001"
}

---

3. EXPRESSION テンプレートの最小構造

EXPRESSION は最低限、次の3つを持つのがおすすめです。

{
  "type": "EXPRESSION",
  "label": "My Formula",
  "expr": "TEMP + HUMID",
  "result_key": "my_formula"
}

• type：必ず "EXPRESSION"
• expr：演算式（文字列）
• result_key：計算結果の格納キー（INPUT.RESULTS に積むときの名前）
• label：表示用（ログやUIがある場合に便利）

---

4. expr（演算式）の書き方

4.1 基本は「変数名＝PARAMS_MAP のキー」

演算式内の TEMP や HUMID は、PARAMS_MAP のキーを参照します。 つまり「RAWの temp を直接書く」のではなく、PARAMS_JSON で定義した論理名を使います。

{
  "type": "EXPRESSION",
  "label": "TempPlusHumid",
  "expr": "TEMP + HUMID",
  "result_key": "temp_plus_humid"
}

4.2 演算子（最低限のルール）

SWPFで安全に運用する前提で、まずは以下だけに絞るのがおすすめです。

• OK 四則演算：+ - * /
• OK 括弧：( ... )
• OK 小数：0.81 など
• 注意 0割：/ 0 になりうる式はガード（後述）
• 注意 未定義変数：値が null 扱いになり、結果が null / エラーになる可能性

※ 使える「関数（例：round, min, max など）」は ExpressionEvaluator の実装で許可したものだけになります。 ここでは “実装差で事故が起きない” ように、まずは四則演算＋括弧を基本として説明します。関数を使いたい場合は「許可関数一覧」をSWPF側で固定するのがおすすめです。

---

5. 代表例：不快指数（DISCOMFORT_INDEX）

よく使う例として、不快指数（DI）を EXPRESSION で定義します。

{
  "DISCOMFORT_INDEX": {
    "type": "EXPRESSION",
    "label": "Discomfort Index",
    "expr": "0.81 * TEMP + 0.01 * HUMID * (0.99 * TEMP - 14.3) + 46.3",
    "result_key": "discomfort_index"
  }
}

このときの流れ（ざっくり）：

1. RAWから TEMP, HUMID を PARAMS_JSON に従って抽出
2. PARAMS_MAP を作成（TEMP=28.4, HUMID=62）
3. expr を評価して数値結果を得る
4. result_key（ここでは discomfort_index）として INPUT.RESULTS に積む

---

6. 結果（RESULTS）への格納イメージ

実装にもよりますが、SWPFでは「評価結果を RESULTS に格納し、後続の処理が参照できる」形にするのが定石です。

{
  "key": "discomfort_index",
  "value": 54.4,
  "type": "EXPRESSION",
  "template_id": "DISCOMFORT_INDEX",
  "at": "2026-01-01T12:34:56+09:00"
}

---

7. “事故りやすい”ポイントと対策

7.1 変数が未定義（PARAMS_MAPに無い）

症状：

• 結果が null / 0 / NaN 相当になったり、評価エラーになる
• ログに Undefined var 的な痕跡が出る

対策：

• PARAMS_JSON に論理名（例：TEMP）があるか
• RAWのパス（例：temp / device.id）が正しいか
• 値が数値として来ているか（例："28.4" でも is_numericならOK、"HIGH" はNG）

7.2 0割（ゼロ除算）

例えば平均や比率の式で DENOM が 0 になり得ます。

• 分母が0になる可能性があるなら、事前に RULE_JSON で分岐して安全側テンプレートへ
• または、評価器側で “ゼロ除算ガード” を実装しておく（推奨）

7.3 型の混在（文字列 vs 数値）

• 温度・湿度は数値で来る想定に統一する
• もしRAWが文字列で来るなら、PARAMS_MAP 構築時に数値化する方針がおすすめ

---

8. チートシート（コピペ用）

8.1 最小 EXPRESSION

{
  "type": "EXPRESSION",
  "label": "Sum",
  "expr": "TEMP + HUMID",
  "result_key": "sum_temp_humid"
}

8.2 平均（例：3点平均）

{
  "type": "EXPRESSION",
  "label": "Avg3",
  "expr": "(A + B + C) / 3",
  "result_key": "avg3"
}

8.3 しきい値判定に使う前処理（例：補正温度）

{
  "type": "EXPRESSION",
  "label": "TempCorrected",
  "expr": "TEMP + TEMP_OFFSET",
  "result_key": "temp_corrected"
}

注意 TEMP_OFFSET のような “定数” を式で使う場合、PARAMS_MAP に入る必要があります。
（例：テンプレート側の params_map 拡張、または RAW/DEFAULT の注入など、SWPF内の設計方針で統一してください）

---

9. 実装・運用のおすすめパターン

9.1 基本は「計算 → 判定 → 通知/制御」

1. EXPRESSION で指標を計算（例：DI、VPD、露点）
2. RULE_JSON で指標を判定（例：DI >= 75 なら警告）
3. MAIL/CONTROL のテンプレートを選択して実行

9.2 result_key 命名ルール（おすすめ）

• 英小文字のスネークケース：discomfort_index, dew_point, vpd
• 単位を含めたいなら末尾に：temp_c, humid_pct（ただし冗長なら省略でもOK）

---

10. よくある質問（FAQ）

Q. expr に RAW のキー（temp など）を直接書いて良い？

A. おすすめしません。 SWPFでは PARAMS_JSON → PARAMS_MAP で “論理名” に正規化してから参照する方が保守しやすいです。

Q. 関数（round/max/min など）は使える？

A. ExpressionEvaluator の実装次第です。 「使える関数一覧」をSWPF側で固定してドキュメント化するのが安全です。まずは四則演算＋括弧で運用し、必要になったら許可関数を追加する流れがおすすめです。

Q. 結果を小数第1位に丸めたい

A. 2択です。

• 評価器が round() を許可しているなら：round(EXPR, 1) のような形（実装に合わせる）
• 許可していないなら：結果格納時に丸め処理を入れる（UI表示用だけ丸める、でもOK）

---