feat(M01): 사람이 읽는 식 줄 API — 비목 묶음마다 「단가 * 수량식 = 금액」 과 소계

- 엔진 `resources/master_data/scripts/master_text.py` — 식 마디를 그 자리에서 나온 수로 풀어 한 줄 글로(찾기·로직·만약·중간 값·요소는 글자로 안 나감 · 「… / 100」 은 「… %」 · 수는 화면과 같은 자릿수) - `POST /text` — 몸은 `/calc` 와 같음 · 답 `{ok, groups: [{비목, 줄, 소계, 끝수}], 계}` · 멈추면 까닭 한 줄 - 중간 값·끝수는 따로 줄로 안 보임(끝수는 소계 옆 한 마디) · 덧줄은 그 비목의 한 줄 · 하위 로직 줄은 비목마다 한 줄 - 단가 0 이거나 안 쓰는 줄은 까닭 한 마디 - 시험 `resources/tester/test_m01_text.py` 6 통과(13-4-1 · 12-4 · 12-17-1 · 계가 `/calc` 와 같음) · M01 시험 41 통과 · typecheck 통과 · 일괄 시험 계산 1,291 그대로 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JgUhN55Z3BCYhUJTjwTNfj
2026-09-21 19:37:55 +09:00
parent f062e51e0d
commit d12f471c93
5 changed files with 323 additions and 0 deletions
@@ -56,6 +56,14 @@
 - 저장 안 한 새 초안 = `key` "" · `row` 에 로직 한 줄 통째 · `file` 은 안 보내도 됨(서버가 메모리에만 얹음). 「만들기」 모달의 [시험 계산] 이 이 길을 씀 — 키를 미리 받지 않음.
 - `끝수` 가 묶음이면 계산 끝에 붙음(6장) · 글자면 설명일 뿐 계산에 안 붙음.

+`POST /text` — 몸은 `/calc` 와 같고, 같은 계산을 **사람이 읽는 식 줄**로 돌려줌(화면은 받은 글을 그대로 찍음).
+
+- 됨 — `{ok: true, groups: [{비목, 줄: [{이름, 글, 금액, 까닭?}], 소계, 끝수}], 계}` · 멈춤은 `/calc` 와 같은 `{ok: false, reason}`.
+- `글` = 호표 줄은 「단가 \* 수량식 = 금액」 · 덧줄은 「식 = 금액」. 중간 값 · 요소 · `찾기()` · `로직()` · `만약()` 은 글자로 안 나오고 **그 자리에서 나온 수**로 · 「… / 100」 은 「… %」 로 · 수는 화면과 같은 자릿수(소수 넷째 자리까지 · 천 단위 쉼표).
+- `비목` = `노무비` · `재료비` · `경비`(돈 아닌 로직은 묶음 하나 `결과`) · 줄이 없는 비목은 빠짐 · `소계` 는 끝수까지 붙은 값이고 `끝수` 는 그 한 마디(「원 미만 버림」 · 없으면 "") — 끝수는 따로 줄로 안 보임.
+- 하위 로직 줄처럼 한 줄이 여러 비목에 걸리면 비목마다 한 줄씩 · 그 비목 몫으로 단가를 되계산해 적음.
+- `까닭` = 단가가 0 이거나 못 구한 줄의 한 마디(「수량 0 — 이 조건에서는 안 쓰는 줄」 · 「단가 0 — 「MP000082」 값이 아직 없음」).
+
 ## 4. 저장

 `POST /save` 받음 `{files: [{file, version, changes: [{op, key, row}]}]}`
@@ -0,0 +1,184 @@
+# -*- coding: utf-8 -*-
+"""사람이 읽는 식 줄 — 비목 묶음마다 「이름 : 단가 * 수량식 = 금액」 과 소계.
+
+수는 화면과 같은 자릿수(소수 넷째 자리까지 · 천 단위 쉼표) · `찾기`·`로직`·중간 값·요소는
+글자로 내보내지 않고 그 자리에서 나온 수로 적음 · 끝수는 줄이 아니라 소계에 녹여 적음.
+계산 자체는 `master_formula.run` 이 한 벌만 함 — 이 글은 그 결과를 되읽어 적음.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+import master_formula as mf
+
+PLACES = Decimal("0.0001")  # 화면 `formatNumber` 와 같음(소수 넷째 자리까지)
+_PREC = {"또는": 1, "그리고": 2, "==": 3, "!=": 3, "<": 3, "<=": 3, ">": 3, ">=": 3}
+_PREC |= {"+": 4, "-": 4, "*": 5, "/": 5}
+_RIGHT_TIGHT = ("-", "/")  # 오른쪽 짝은 같은 세기라도 괄호가 필요함
+
+
+def fmt(value) -> str:
+    """화면에 보이는 자릿수 그대로 — 소수 넷째 자리까지 · 뒤 0 은 떼고 · 천 단위 쉼표."""
+    if not isinstance(value, Decimal):
+        return str(value)
+    cut = value.quantize(PLACES) if value.as_tuple().exponent < -4 else value
+    sign, digits = ("-", -cut) if cut < 0 else ("", cut)
+    whole, _, rest = f"{digits.normalize():f}".partition(".")
+    if "E" in whole or "e" in whole:  # 아주 큰 수 — 지수 꼴을 펴서 씀
+        whole, _, rest = f"{digits:f}".rstrip("0").rstrip(".").partition(".")
+    return sign + f"{int(whole):,}" + (f".{rest}" if rest else "")
+
+
+# ── 식을 수로 풀어 글로 ────────────────────────────────────────────────
+def render(node, env: dict, master, depth: int = 0) -> str:
+    """식 한 마디 → 글. 값이 정해지는 마디(요소 · 찾기 · 로직 · 이름)는 그 수로 바뀜."""
+    kind = node[0]
+    if kind == "num":
+        return fmt(node[1])
+    if kind == "str":
+        return f"'{node[1]}'"
+    if kind == "neg":
+        return "-" + render(node[1], env, master, depth)
+    if kind == "bin":
+        return _bin(node, env, master, depth)
+    if kind == "call" and node[1] == "만약":  # 걸린 쪽만 적음
+        test = mf.evaluate(node[2][0], env, master, depth)
+        return render(node[2][1] if test else node[2][2], env, master, depth)
+    return _value(node, env, master, depth)
+
+
+def _value(node, env: dict, master, depth: int) -> str:
+    value = mf.evaluate(node, env, master, depth)
+    if isinstance(value, dict):  # 로직 부르기 묶음 — 줄 금액에 쓰는 것은 「계」
+        value = value.get("계")
+    return fmt(value)
+
+
+def _bin(node, env: dict, master, depth: int) -> str:
+    _, op, left, right = node
+    if op == "/" and right[0] == "num" and right[1] == 100:  # 「… / 100」 은 퍼센트로
+        return f"{_side(left, node, env, master, depth, False)} %"
+    return (
+        f"{_side(left, node, env, master, depth, False)} {op} "
+        f"{_side(right, node, env, master, depth, True)}"
+    )
+
+
+def _side(child, parent, env: dict, master, depth: int, right: bool) -> str:
+    text = render(child, env, master, depth)
+    if child[0] != "bin":
+        return text
+    mine, up = _PREC[child[1]], _PREC[parent[1]]
+    if mine < up or (mine == up and right and parent[1] in _RIGHT_TIGHT):
+        return f"({text})"
+    return text
+
+
+# ── 줄 세우기 ─────────────────────────────────────────────────────────
+def _env_of(master, row: dict, given: dict, depth: int = 0) -> dict:
+    """입력 + 중간 — `run` 과 같은 차례로 다시 셈(덧줄 전 상태)."""
+    env = mf._inputs(row, given)
+    for step in row.get("중간", []):
+        env[step["이름"]] = mf.evaluate(mf.parse(step["식"]), env, master, depth)
+    return env
+
+
+def _why(item: dict, line: dict) -> str:
+    """단가를 못 구했거나 0 인 줄의 까닭 한 마디."""
+    if line["단가"] not in (0, None):
+        return ""
+    if line["수량"] == 0:
+        return "수량 0 — 이 조건에서는 안 쓰는 줄"
+    where = item.get("요소")
+    where = "재료 고르기 조건" if isinstance(where, dict) else f"「{where}」"
+    return f"단가 0 — {where} 값이 아직 없음"
+
+
+def _label(item: dict, line: dict) -> str:
+    spec = str(item.get("규격") or "").strip()
+    name = str(line.get("이름") or item.get("이름") or "")
+    return f"{name}({spec})" if spec else name
+
+
+def _line_text(item: dict, line: dict, env: dict, master, part: str | None) -> str:
+    """「단가 * 수량식 = 금액」 — 비목이 나뉜 로직 줄은 그 비목 몫만."""
+    qty = render(mf.parse(item["수량"]), env, master)
+    money = line["비목"][part] if part else line["금액"]
+    price = line["단가"] if part is None or line["수량"] == 0 else money / line["수량"]
+    return f"{fmt(price)} * {qty} = {fmt(money)}"
+
+
+def _extra_text(extra: dict, line: dict, env: dict, master) -> str:
+    return f"{render(mf.parse(extra['식']), env, master)} = {fmt(line['금액'])}"
+
+
+def lines(files: dict, key: str, given: dict) -> dict:
+    """로직 한 줄의 읽는 식 — 비목 묶음마다 줄과 소계 · 돈 아닌 로직은 「결과」 묶음 하나."""
+    master = mf.Master(files)
+    row = master.logic(key)
+    result = mf.run(master, key, given)
+    env = _env_of(master, row, given)
+    if "결과" in row:
+        text = f"{render(mf.parse(row['결과']['식']), env, master)} = {fmt(result['결과'])}"
+        one = {"이름": row.get("이름") or "", "글": text, "금액": result["결과"]}
+        group = {
+            "비목": "결과",
+            "줄": [one],
+            "소계": result["결과"],
+            "끝수": _cut_note(row, "결과"),
+        }
+        return {"ok": True, "groups": [group], "계": result["결과"]}
+    made: dict[str, list] = {name: [] for name in mf.COST_ITEMS}
+    shown = result["줄"]
+    env["줄"] = {r["이름"]: r["금액"] for r in shown if r["이름"]}
+    items = row.get("호표") or []
+    for item, line in zip(items, shown):
+        for part, money in line["비목"].items():
+            if money == 0 and len(line["비목"]) > 1:
+                continue  # 비목이 나뉜 로직 줄 — 몫이 없는 비목엔 안 적음
+            split = part if len(line["비목"]) > 1 else None
+            one = {
+                "이름": _label(item, line),
+                "글": _line_text(item, line, env, master, split),
+                "금액": money,
+            }
+            why = _why(item, line)
+            made[part].append({**one, "까닭": why} if why else one)
+    _extras(row, shown[len(items) :], made, env, master)
+    groups = [
+        {
+            "비목": name,
+            "줄": made[name],
+            "소계": result[name],
+            "끝수": _cut_note(row),
+        }
+        for name in mf.COST_ITEMS
+        if made[name]
+    ]
+    return {"ok": True, "groups": groups, "계": result["계"]}
+
+
+def _extras(row: dict, shown: list, made: dict, env: dict, master) -> None:
+    """덧줄 — 앞선 줄까지의 비목 합을 넣고 한 줄씩(식 안의 비목 이름은 그 수로 바뀜)."""
+    sums = {name: sum((one["금액"] for one in made[name]), Decimal(0)) for name in mf.COST_ITEMS}
+    for extra, line in zip(row.get("덧줄") or [], shown):
+        env.update(sums)
+        one = {
+            "이름": extra["이름"],
+            "글": _extra_text(extra, line, env, master),
+            "금액": line["금액"],
+        }
+        made[extra["비목"]].append(one)
+        sums[extra["비목"]] += line["금액"]
+        env[extra["이름"]] = line["금액"]
+
+
+def _cut_note(row: dict, on: str = "계") -> str:
+    """소계에 붙일 끝수 한 마디 — 끝수는 따로 줄로 보이지 않음."""
+    rule = row.get("끝수")
+    if not isinstance(rule, dict) or rule.get("대상") != on:
+        return ""
+    place = int(rule.get("자리") or 0)
+    where = "원 미만" if place == 0 else f"소수 {place + 1}째 자리에서"
+    return f"{where} {rule.get('방법')}"