refactor(M02): 자재 조합 표를 마스터 템플릿으로 옮김 · M02 좌측 「자재 조합」 컨테이너

- 표 resources/master_data/자재조합.json → resources/master_template/자재조합.json(git mv) · 키 UM 은 표 안 「다음」 번호 · _키대장 · master_keys 의 UM 뺌 · check_master 틀이 새 자리를 같이 봄
- 서버: M01 /api/m01/matset* 뺌 · M02 저장소 M02_MasterTemplete_Matset.py(목록 · 새로 · 고치기 · 지우기 · 쓰는 열 검사) · 길 GET/POST /api/m02/material-combos · PUT/DELETE /api/m02/material-combos/{키} · 갈라 내기(branchMaterialCombo)도 이 저장소로
- 화면: M01 좌측 「자재 조합」 컨테이너 뺌 · M02 좌측 「자재 조합」 컨테이너(찾기 · 키 맨 앞 목록 · 새로 · 본떠 만들기 · 지우기) · 메인 칸 상세(이름 · 비고 · 본뜬키 · 담은 자재 표 · 자재 더하기 · 빼기 · 저장) · 쓰는 열이 있으면 지우기는 확인 창 없이 알림
- 시험: test_m01_matset → test_m02_matset · test_m02_combo_branch 사본 자리 · 실제 자재 코드

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VwJQ5eRrCKf3nH9EFeKvJz

M02_MasterTemplete/M02_MasterTemplete_Api_Fetch.ts

@@ -36,11 +36,14 @@ async function call<T>(path: string, init: RequestInit = {}): Promise<T> {
     ...init,
   });
   const body = (await response.json().catch(() => ({}))) as { detail?: unknown } & T;
-  if (response.status === 409)
+  // 서버 까닭 목록(`{errors: [...]}` — 422 검사 걸림 · 409 쓰는 곳 있어 못 지움)은 글로
+  const errors = (body.detail as { errors?: unknown } | null)?.errors;
+  const said = Array.isArray(errors) ? errors.join(" / ") : "";
+  if (response.status === 409 && !said)
     throw new StaleError(typeof body.detail === "string" ? body.detail : "409");
   if (!response.ok) {
     const detail = body.detail;
-    throw new Error(typeof detail === "string" ? detail : `HTTP ${response.status}`);
+    throw new Error(said || (typeof detail === "string" ? detail : `HTTP ${response.status}`));
   }
   return body;
 }
@@ -208,6 +211,33 @@ export const branchMaterialCombo = (
     body: JSON.stringify(body),
   });
 
+/* --- 자재 조합 표(마스터 템플릿 `자재조합.json`) — 좌측 「자재 조합」 컨테이너 --- */
+/** 표 통째 — 판(파일 판본) · 줄(담은 자재 포함) · 쓰는곳(키 → 쓰는 구조물 열 이름들) */
+export const listMaterialCombos = (): Promise<{
+  판: string;
+  줄: MaterialCombo[];
+  쓰는곳: Record<string, string[]>;
+}> => call("/material-combos");
+
+/** 새로 · 본떠 만들기(`본뜬키`) — 키는 서버가 표 「다음」 번호로 줌 */
+export const createMaterialCombo = (
+  판: string,
+  줄: Omit<MaterialCombo, "키">,
+): Promise<{ 키: string; 판: string; 줄: MaterialCombo }> =>
+  call("/material-combos", { method: "POST", body: JSON.stringify({ 판, 줄 }) });
+
+/** 고치기 — 이름 · 비고 · 담은자재(본뜬키 · 소유는 서버가 있던 것으로) */
+export const editMaterialCombo = (
+  키: string,
+  판: string,
+  줄: MaterialCombo,
+): Promise<{ 키: string; 판: string; 줄: MaterialCombo }> =>
+  call(`/material-combos/${enc(키)}`, { method: "PUT", body: JSON.stringify({ 판, 줄 }) });
+
+/** 지우기 — 구조물 열이 쓰면 서버가 막고 그 열 이름들을 까닭으로 줌 */
+export const deleteMaterialCombo = (키: string, 판: string): Promise<unknown> =>
+  call(`/material-combos/${enc(키)}?판=${enc(판)}`, { method: "DELETE" });
+
 /** 다른 열(`from`) 구조물 도면 내용을 받는 열(`column`)로 가져옴 — 도번 · 열은 받는 쪽 그대로 */
 export const copyStructure = async (column: string, from: string): Promise<void> => {
   await call(`/structures/${enc(column)}/copy?from=${enc(from)}`, { method: "POST" });

M02_MasterTemplete/M02_MasterTemplete_Branch.py

@@ -1,7 +1,7 @@
 """조합 갈라 내기 — 구조물 열 하나가 가리키는 조합을 고친 내용으로 새로 만들어 그 열만 새 키를
 가리키게 함(PLAN 15장 · 검토 `14_조합편집검토.md` 1장).
   · 일위대가 조합(UA · `일위대가조합.json`) — 새 줄은 M01 조합 저장소가 만듦(부르기만)
-  · 자재 조합(UM · `자재조합.json`) — M01 마스터 저장(`save`)으로 더함(키 = 대장 다음 번호)
+  · 자재 조합(UM · 마스터 템플릿 `자재조합.json`) — M02 자재 조합 저장소가 만듦(표 「다음」 번호)
 
 조합은 여러 열 · 모든 프로젝트가 같이 씀 — 제자리 고치지 않음. 담은 것의 집합(차례 · 메모 무시)이
 이미 있는 조합과 같으면 새로 안 만들고 그 키 · 새 줄의 본뜬키 = 원래 키 · 소유 현장.
@@ -13,10 +13,10 @@ from typing import Any, Callable
 
 from M01_MasterData import M01_MasterData_Store as m01
 from M01_MasterData import M01_MasterData_Store_Combo as combo_store
+from M02_MasterTemplete import M02_MasterTemplete_Matset as matset
 from M02_MasterTemplete import M02_MasterTemplete_Store as store
 
 _OWNER = "현장"
-MATERIAL_FILE = "자재조합.json"
 
 
 def _m01(fn, *args):
@@ -39,7 +39,7 @@ def _branch(
     column: str,
     version: str,
     field: str,
-    file: str,
+    rows: list[dict],
     slot: str,
     ident: str,
     items: list[dict],
@@ -61,7 +61,6 @@ def _branch(
     def body(got) -> frozenset[str]:
         return frozenset(str(x.get(ident) or "") for x in got or [] if isinstance(x, dict))
 
-    rows = _m01(m01.read, file)[0].get("줄") or []
     same = [r for r in rows if body(r.get(slot)) == body(items)]
     hit = next((r for r in same if source and r.get("키") == source), same[0] if same else None)
     if hit:
@@ -101,20 +100,12 @@ def branch_combo(
         return str(_m01(combo_store.combo_new, row, _OWNER)["key"])
 
     name = name.strip() or str(was.get("이름") or source)
-    return _branch(
-        column, version, "일위대가", combo_store.FILE, "담은로직", "로직", items, source, make, name
-    )
-
-
-def _material_rows() -> list[dict]:
-    return _m01(m01.read, MATERIAL_FILE)[0].get("줄") or []
+    rows = _m01(m01.read, combo_store.FILE)[0].get("줄") or []
+    return _branch(column, version, "일위대가", rows, "담은로직", "로직", items, source, make, name)
 
 
 def material_combo(key: str) -> dict[str, Any]:
-    row = next((r for r in _material_rows() if r.get("키") == key), None)
-    if row is None:
-        raise store.StoreError(404, f"없는 자재 조합 「{key}」")
-    return row
+    return matset.one(key)
 
 
 def branch_material_combo(
@@ -128,24 +119,12 @@ def branch_material_combo(
         if isinstance(x, dict)
     ]
 
-    def make(made_name: str, rows: list[dict]) -> str:
+    def make(made_name: str, _rows) -> str:
         row = {"이름": made_name, "담은자재": items, "본뜬키": source or None, "소유": _OWNER}
-        before = {r.get("키") for r in rows}
-        _m01(
-            m01.save,
-            [
-                {
-                    "file": MATERIAL_FILE,
-                    "version": _m01(m01.read, MATERIAL_FILE)[1],
-                    "changes": [{"op": "add", "row": {**row, "비고": None}}],
-                }
-            ],
-        )
-        return str(next(r["키"] for r in _material_rows() if r.get("키") not in before))
+        return matset.create(row)["키"]
 
     heads = next((c for c in store._structure_columns() if c["id"] == column), {})
     default = " ".join(h for h in store._heads(heads) if h) if heads else column
     name = name.strip() or str(was.get("이름") or default or column)
-    return _branch(
-        column, version, "자재조합", MATERIAL_FILE, "담은자재", "코드", items, source, make, name
-    )
+    rows = matset.listing()["줄"]
+    return _branch(column, version, "자재조합", rows, "담은자재", "코드", items, source, make, name)

M02_MasterTemplete/M02_MasterTemplete_Materials.ts

@@ -118,8 +118,8 @@ export interface MaterialPanelOptions {
   unlink: (codes: string[]) => void;
 }
 
-/** 자재 고르기 창 — 이름 · 규격 · 코드 낱말로 찾아 하나 고름 */
-function pickMaterial(done: (item: MaterialItem) => void): void {
+/** 자재 고르기 창 — 이름 · 규격 · 코드 낱말로 찾아 하나 고름(좌측 자재 조합 상세도 씀) */
+export function pickMaterial(done: (item: MaterialItem) => void): void {
   openModal({
     title: TEXT.pickTitle,
     closeLabel: TEXT.pickClose,

M02_MasterTemplete/M02_MasterTemplete_Matset.py

@@ -0,0 +1,133 @@
+"""M02 자재 조합 저장소 — 마스터 템플릿 표 `자재조합.json`(구조물집계표조합.json 과 같은 자리).
+
+줄 = 키 UM · 이름 · 담은자재(코드 · 이름 · 규격 · 단위) · 본뜬키 · 소유 · 비고 — 수량 · 단가는 안 둠
+(재료산출 몫). 키는 표 안 「다음」 번호(지운 키는 다시 안 씀) · 집계표 열 `자재조합` 칸이 가리킴.
+틀 검사 = `master_material_combo.check_form`(check_master 와 같은 것) · 판 = 파일 sha256 앞 16자.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from common_util.common_util_json import atomic_write_json
+from M01_MasterData import M01_MasterData_Store as m01
+from M02_MasterTemplete import M02_MasterTemplete_Store as store
+
+mmc = m01.cm.mmc  # 자재 조합 틀(`resources/master_data/scripts/master_material_combo.py`)
+FILE = mmc.FILE
+OWNERS = mmc.OWNERS
+_HEAD = "UM"
+
+
+def _load() -> tuple[dict[str, Any], str]:
+    """(표, 판) — 파일이 없으면 빈 표 · 판 빈 글."""
+    path = store.FOLDER / FILE
+    if not path.is_file():
+        return {"그룹": mmc.GROUP, "판": "2026", "비고": [], "다음": 1, "줄": []}, ""
+    raw = path.read_bytes()
+    return json.loads(raw), store.version_of(raw)
+
+
+def _find(doc: dict, key: str) -> dict[str, Any]:
+    row = next((r for r in doc["줄"] if r.get("키") == key), None)
+    if row is None:
+        raise store.StoreError(404, f"없는 자재 조합 「{key}」")
+    return row
+
+
+def listing() -> dict[str, Any]:
+    """표 통째 — 판 · 줄(담은 자재 포함 · 작아서 한 번에) · 쓰는곳(키 → 쓰는 구조물 열 이름들)."""
+    doc, version = _load()
+    used: dict[str, list[str]] = {}
+    for col in store._structure_columns():
+        if key := col.get("자재조합"):
+            used.setdefault(key, []).append(_name(col))
+    return {"판": version, "줄": doc["줄"], "쓰는곳": used}
+
+
+def _name(col: dict) -> str:
+    return " ".join(h for h in store._heads(col) if h) or col["id"]
+
+
+def one(key: str) -> dict[str, Any]:
+    return _find(_load()[0], key)
+
+
+def users_of(key: str) -> list[str]:
+    """구조물집계표에서 `자재조합` 칸이 이 키인 열 — 머리 글(없으면 열 id)."""
+    out = []
+    for col in store._structure_columns():
+        if col.get("자재조합") == key:
+            out.append(_name(col))
+    return out
+
+
+def _clean(row: Any, key: str, keep: dict | None = None) -> dict[str, Any]:
+    """서버가 잡는 칸 — 키 · 열 한 벌 · 자재 줄 네 칸 · 본뜬키는 만들 때만(고칠 때는 있던 것)."""
+    if not isinstance(row, dict):
+        raise store.StoreError(400, "자재 조합 줄이 묶음 아님")
+    name = row.get("이름")
+    if not isinstance(name, str) or not name.strip():
+        raise store.StoreError(400, "자재 조합 줄에 「이름」 이 없거나 글자 아님")
+    got = row.get("담은자재")
+    got = [
+        {c: m.get(c) for c in mmc.ITEM_COLS} if isinstance(m, dict) else m
+        for m in (got if isinstance(got, list) else [])
+    ]
+    known = {str(r.get("키")) for d in m01.loaded()[0].values() for r in d.get("줄") or []}
+    lost = [str(m.get("코드")) for m in got if isinstance(m, dict) and m.get("코드") not in known]
+    if lost:
+        raise store.StoreError(422, {"errors": [f"마스터에 없는 자재 {' · '.join(lost)}"]})
+    base = keep or row
+    owner = base.get("소유") or OWNERS[0]
+    return {
+        "키": key,
+        "이름": name.strip(),
+        "담은자재": got,
+        "본뜬키": base.get("본뜬키") or None,
+        "소유": owner,
+        "비고": row.get("비고") or None,
+    }
+
+
+def _save(doc: dict, version: str) -> str:
+    """틀 검사 → 판이 같을 때만 씀 → 새 판."""
+    if errors := mmc.check_form(FILE, doc):
+        raise store.StoreError(422, {"errors": errors})
+    path = store.FOLDER / FILE
+    with store._LOCK:
+        have = store.version_of(path.read_bytes()) if path.is_file() else ""
+        if have != (version or ""):
+            raise store.StoreError(409, {"stale": [FILE], "판": have})
+        atomic_write_json(path, doc)
+        return store.version_of(path.read_bytes())
+
+
+def create(row: Any, version: str | None = None) -> dict[str, Any]:
+    """새 줄 — 키 = 「다음」 번호 · 본뜬키는 있는 다른 키만. `version` None = 지금 판(갈라 내기)."""
+    doc, have = _load()
+    key = f"{_HEAD}{int(doc.get('다음') or 1):06d}"
+    fixed = _clean(row, key)
+    if fixed["본뜬키"] and fixed["본뜬키"] not in {r.get("키") for r in doc["줄"]}:
+        raise store.StoreError(400, f"본뜬키 「{fixed['본뜬키']}」 — 있는 다른 자재 조합 키여야 함")
+    doc = {**doc, "다음": int(doc.get("다음") or 1) + 1, "줄": [*doc["줄"], fixed]}
+    return {"키": key, "판": _save(doc, have if version is None else version), "줄": fixed}
+
+
+def edit(key: str, row: Any, version: str) -> dict[str, Any]:
+    doc, _ = _load()
+    fixed = _clean(row, key, keep=_find(doc, key))
+    doc = {**doc, "줄": [fixed if r.get("키") == key else r for r in doc["줄"]]}
+    return {"키": key, "판": _save(doc, version), "줄": fixed}
+
+
+def delete(key: str, version: str) -> dict[str, Any]:
+    """지우기 — 구조물 열이 쓰면 409 + 열 이름들(지우지 않음)."""
+    doc, _ = _load()
+    _find(doc, key)
+    if users := users_of(key):
+        msg = f"구조물 {len(users)} 곳이 쓰는 자재 조합이라 못 지움 — {' · '.join(users)}"
+        raise store.StoreError(409, {"errors": [msg], "users": users})
+    doc = {**doc, "줄": [r for r in doc["줄"] if r.get("키") != key]}
+    return {"판": _save(doc, version)}

M02_MasterTemplete/M02_MasterTemplete_Matset.ts

@@ -0,0 +1,264 @@
+/* =============================================================================
+ * M02_MasterTemplete_Matset.ts
+ * 좌측 「자재 조합」 컨테이너 — 찾기 · 목록(키 맨 앞) · 새로 · 본떠 만들기 · 지우기(컨테이너 안) ·
+ * 줄을 누르면 메인 칸에 상세: 이름 · 비고 · 본뜬키 · 담은 자재 표(빼기) · [자재 더하기] · [저장].
+ * 표 = 마스터 템플릿 `자재조합.json`(키 UM · 서버 `M02_MasterTemplete_Matset.py`) · 지우기는 쓰는 열이
+ * 있으면 서버가 막음. 재료산출 옆 판이 갈라 낸 조합도 같은 표라 여기 보임(펼칠 때 새로 받음).
+ * ========================================================================== */
+
+import {
+  createButton,
+  createInputField,
+  el,
+  showConfirmDialog,
+  showToast,
+} from "@ui/ui_template_elements";
+import { t as L } from "@ui/ui_template_locale";
+import {
+  createMaterialCombo,
+  deleteMaterialCombo,
+  editMaterialCombo,
+  listMaterialCombos,
+  StaleError,
+  type MaterialCombo,
+} from "./M02_MasterTemplete_Api_Fetch";
+import { pickMaterial } from "./M02_MasterTemplete_Materials";
+import { tm } from "./M02_MasterTemplete_Matset_Text";
+
+export interface MatsetSectionOptions {
+  isAdmin: boolean;
+  /** 저장 안 한 고침을 버릴지 확인 — 취소면 false */
+  confirmLeave: () => Promise<boolean>;
+  /** 메인 칸에 상세를 띄움 — 고침 표시 손잡이를 돌려받음 */
+  show: (label: string, node: HTMLElement) => (dirty: boolean) => void;
+  /** 메인 칸을 비움(지운 뒤) */
+  close: () => void;
+  /** 상세를 열었음 — 좌측 다른 줄 고름 표시를 지움 */
+  onOpen: () => void;
+}
+
+export interface MatsetSection {
+  title: string;
+  body: HTMLElement;
+  /** 새로 · 본떠 만들기 · 지우기 줄(관리자만 · 아니면 빈 목록) */
+  actions: HTMLElement[];
+  /** 표를 새로 받아 목록을 다시 그림 */
+  refresh: () => Promise<void>;
+  /** 다른 양식을 열었음 — 고름 표시만 지움 */
+  clear: () => void;
+}
+
+const why = (error: unknown): string => (error instanceof Error ? error.message : "");
+
+export function buildMatsetSection(opt: MatsetSectionOptions): MatsetSection {
+  let all: MaterialCombo[] = [];
+  let version = "";
+  let used: Record<string, string[]> = {};
+  let q = "";
+  /** 열린 상세의 키 — 새(저장 전)는 빈 글 · 안 열렸으면 null */
+  let openKey: string | null = null;
+
+  const find = createInputField({ type: "search", placeholder: tm("Search") });
+  const list = el("div", { className: "m02-side__items ui-sidebar-list" });
+  const body = el("div", { className: "m02-side__items", children: [find.root, list] });
+  find.input.addEventListener("input", () => {
+    q = find.input.value.trim().toLowerCase();
+    paintList();
+  });
+
+  const btnNew = createButton({ label: L("M02_New"), variant: "filled", size: "sm" });
+  const btnCopy = createButton({ label: L("M02_Copy"), variant: "ghost", size: "sm" });
+  const btnDel = createButton({ label: L("M02_Delete"), variant: "danger", size: "sm" });
+  const actions = opt.isAdmin
+    ? [el("div", { className: "m02-side__row", children: [btnNew, btnCopy, btnDel] })]
+    : [];
+  const paintButtons = (): void => {
+    btnCopy.disabled = btnDel.disabled = !openKey;
+  };
+
+  function paintList(): void {
+    const shown = all.filter((x) => !q || `${x.키} ${x.이름}`.toLowerCase().includes(q));
+    list.replaceChildren(
+      ...(shown.length
+        ? shown.map((x) => {
+            const b = el("button", {
+              className: `m02-side__item ui-sidebar-row${x.키 === openKey ? " is-active" : ""}`,
+              text: `${x.키} ${x.이름}`,
+              attrs: { type: "button", "data-matset-key": x.키 },
+            });
+            b.addEventListener("click", () => void select(x.키));
+            return b;
+          })
+        : [el("p", { className: "m02-side__empty", text: tm("Empty") })]),
+    );
+  }
+
+  async function refresh(): Promise<void> {
+    try {
+      ({ 판: version, 줄: all, 쓰는곳: used } = await listMaterialCombos());
+    } catch (error) {
+      showToast(tm("Load_Failed", why(error)), "error");
+    }
+    paintList();
+    paintButtons();
+  }
+
+  async function select(key: string): Promise<void> {
+    if (key === openKey || !(await opt.confirmLeave())) return;
+    const row = all.find((x) => x.키 === key);
+    if (row) draw(structuredClone(row), false);
+  }
+
+  /** 메인 칸 상세 — `row` 는 고칠 사본(저장 전까지 표에 안 들어감) */
+  function draw(row: MaterialCombo, isNew: boolean): void {
+    openKey = isNew ? "" : row.키;
+    const edit = opt.isAdmin;
+    const field = (label: string, name: "이름" | "비고") => {
+      const f = createInputField({ type: "text", label });
+      f.input.value = row[name] ?? "";
+      f.input.disabled = !edit;
+      f.input.setAttribute("data-matset-field", name);
+      f.input.addEventListener("input", () => {
+        if (name === "이름") row.이름 = f.input.value;
+        else row.비고 = f.input.value || null;
+        setDirty(true);
+      });
+      return f.root;
+    };
+    const table = el("div", { className: "m02-matset__table" });
+    const paintItems = (): void => {
+      const head = el("div", {
+        className: "m02-mat__row m02-mat__row--head",
+        children: [tm("Col_Code"), tm("Col_Name"), tm("Col_Spec"), tm("Col_Unit"), "", ""].map(
+          (t) => el("span", { text: t }),
+        ),
+      });
+      const rows = row.담은자재.map((m, i) => {
+        const acts = el("span");
+        if (edit) {
+          const del = createButton({ label: tm("Remove"), variant: "ghost", size: "sm" });
+          del.addEventListener("click", () => {
+            row.담은자재.splice(i, 1);
+            setDirty(true);
+            paintItems();
+          });
+          acts.append(del);
+        }
+        return el("div", {
+          className: "m02-mat__row",
+          attrs: { "data-matset-item": m.코드 },
+          children: [m.코드, m.이름 ?? "", m.규격 ?? "", m.단위 ?? "", ""]
+            .map((t) => el("span", { text: t }))
+            .concat(acts),
+        });
+      });
+      table.replaceChildren(
+        head,
+        ...(rows.length ? rows : [el("p", { className: "m02-side__empty", text: tm("NoItem") })]),
+      );
+    };
+    paintItems();
+
+    const add = createButton({ label: tm("AddItem"), variant: "ghost" });
+    add.addEventListener("click", () =>
+      pickMaterial((m) => {
+        if (row.담은자재.some((x) => x.코드 === m.코드)) return;
+        row.담은자재.push({ 코드: m.코드, 이름: m.이름, 규격: m.규격, 단위: m.단위 });
+        setDirty(true);
+        paintItems();
+      }),
+    );
+    const save = createButton({ label: tm("Save"), variant: "filled" });
+    save.addEventListener("click", async () => {
+      if (!row.이름.trim()) return showToast(tm("NeedName"), "error");
+      if (!row.담은자재.length) return showToast(tm("NeedItem"), "error");
+      save.disabled = true; // 연달아 눌러도 한 번만
+      try {
+        const { 키, ...rest } = row;
+        const done = isNew
+          ? await createMaterialCombo(version, rest)
+          : await editMaterialCombo(키, version, row);
+        setDirty(false);
+        showToast(tm("Saved"), "success");
+        await refresh();
+        draw(structuredClone(done.줄), false);
+      } catch (error) {
+        if (error instanceof StaleError) {
+          showToast(tm("Stale"), "error");
+          await refresh();
+        } else showToast(tm("Failed", why(error)), "error");
+      } finally {
+        save.disabled = false;
+      }
+    });
+
+    const node = el("div", {
+      className: "m02-matset",
+      children: [
+        el("div", {
+          className: "m02-matset__fields",
+          children: [
+            field(tm("Head_Name"), "이름"),
+            field(tm("Head_Note"), "비고"),
+            el("p", {
+              className: "m02-side__empty",
+              text: `${tm("Head_Origin")}: ${row.본뜬키 ?? tm("Origin_Self")}`,
+              attrs: { "data-matset-origin": row.본뜬키 ?? "" },
+            }),
+          ],
+        }),
+        el("h3", { className: "m02-matset__head", text: tm("Items_Title") }),
+        table,
+        ...(edit ? [el("div", { className: "m02-side__row", children: [add, save] })] : []),
+      ],
+    });
+    const setDirty = opt.show(isNew ? tm("New") : `${row.키} ${row.이름}`, node);
+    if (isNew) setDirty(true);
+    opt.onOpen();
+    paintList();
+    paintButtons();
+  }
+
+  btnNew.addEventListener("click", async () => {
+    if (!(await opt.confirmLeave())) return;
+    draw({ 키: "", 이름: "", 담은자재: [], 본뜬키: null, 소유: "현장", 비고: null }, true);
+  });
+  btnCopy.addEventListener("click", async () => {
+    const from = all.find((x) => x.키 === openKey);
+    if (!from || !(await opt.confirmLeave())) return;
+    const copy = structuredClone(from);
+    draw({ ...copy, 키: "", 이름: tm("CopyName", from.이름), 본뜬키: from.키, 소유: "현장" }, true);
+  });
+  btnDel.addEventListener("click", async () => {
+    const key = openKey;
+    if (!key) return;
+    await refresh(); // 최신 판 · 쓰는 열로
+    // 쓰는 열이 있으면 확인 창 없이 바로 알림(서버도 막음)
+    const users = used[key] ?? [];
+    if (users.length) return showToast(tm("InUse", users.join(" · ")), "error");
+    if (!(await showConfirmDialog(tm("DeleteAsk", key)))) return;
+    try {
+      await deleteMaterialCombo(key, version);
+      showToast(tm("Deleted"), "success");
+      openKey = null;
+      opt.close();
+    } catch (error) {
+      showToast(tm("Failed", why(error)), "error");
+    }
+    await refresh();
+  });
+
+  paintButtons();
+  return {
+    title: tm("Title"),
+    body,
+    actions,
+    refresh,
+    clear: () => {
+      if (openKey === null) return;
+      openKey = null;
+      paintList();
+      paintButtons();
+    },
+  };
+}

M02_MasterTemplete/M02_MasterTemplete_Matset_Text.ts

@@ -0,0 +1,49 @@
+/* =============================================================================
+ * M02_MasterTemplete_Matset_Text.ts
+ * 좌측 「자재 조합」 컨테이너 · 상세 화면 글자 — [한국어, 영어]
+ * ========================================================================== */
+
+import { currentLanguageIndex } from "@ui/ui_template_locale";
+
+const TEXT = {
+  Title: ["자재 조합", "Material sets"],
+  Search: ["키 · 이름으로 찾기", "Search by key or name"],
+  Empty: ["자재 조합 없음", "No material sets"],
+  New: ["새 자재 조합(저장 전)", "New material set (unsaved)"],
+  CopyName: ["{value} 본뜸", "{value} copy"],
+  Save: ["저장", "Save"],
+  InUse: [
+    "{value} 열이 쓰는 자재 조합이라 못 지움",
+    "Used by the column(s) {value} — cannot delete",
+  ],
+  DeleteAsk: ["자재 조합 {value} 을 지울까요?", "Delete material set {value}?"],
+  Saved: ["저장함", "Saved"],
+  Deleted: ["지움", "Deleted"],
+  Stale: [
+    "그 사이 자재 조합 표가 바뀜 — 목록을 새로 받았으니 다시 고쳐 주세요",
+    "The table changed meanwhile — reloaded, please edit again",
+  ],
+  NeedName: ["이름을 적어야 저장됨", "A name is required"],
+  NeedItem: ["담은 자재가 하나는 있어야 저장됨", "Add at least one material"],
+  Load_Failed: ["자재 조합을 못 받음 — {value}", "Could not load material sets — {value}"],
+  Failed: ["자재 조합을 못 고침 — {value}", "Could not change the material set — {value}"],
+  Head_Name: ["이름", "Name"],
+  Head_Note: ["비고", "Note"],
+  Head_Origin: ["본뜬키", "Copied from"],
+  Origin_Self: ["원본", "Original"],
+  Items_Title: ["담은 자재", "Materials in it"],
+  Col_Code: ["코드", "Code"],
+  Col_Name: ["이름", "Name"],
+  Col_Spec: ["규격", "Spec"],
+  Col_Unit: ["단위", "Unit"],
+  Remove: ["빼기", "Remove"],
+  AddItem: ["자재 더하기", "Add material"],
+  NoItem: ["담은 자재 없음", "No materials yet"],
+} as const satisfies Record<string, readonly [string, string]>;
+
+export type MatsetTextKey = keyof typeof TEXT;
+
+export function tm(key: MatsetTextKey, value = ""): string {
+  const entry = TEXT[key];
+  return (entry[currentLanguageIndex as 0 | 1] ?? entry[0]).replace("{value}", value);
+}

M02_MasterTemplete/M02_MasterTemplete_Router.py

@@ -11,6 +11,7 @@ from fastapi import APIRouter, HTTPException, Query
 from pydantic import BaseModel
 
 from M02_MasterTemplete import M02_MasterTemplete_Branch as branch
+from M02_MasterTemplete import M02_MasterTemplete_Matset as matset
 from M02_MasterTemplete import M02_MasterTemplete_Store as store
 
 router = APIRouter(prefix="/api/m02", tags=["M02 MasterTemplete"])
@@ -35,6 +36,11 @@ class MaterialBranchBody(BaseModel):
     판: str = ""
 
 
+class MatsetBody(BaseModel):
+    판: str = ""  # 자재 조합 표 판 — 어긋나면 409
+    줄: dict[str, Any]
+
+
 def _call(fn, *args):
     try:
         return fn(*args)
@@ -78,12 +84,37 @@ def post_structure_material_combo(column: str, body: MaterialBranchBody) -> dict
     )
 
 
+# 자재 조합 표(마스터 템플릿 `자재조합.json` · 키 UM) — 좌측 「자재 조합」 컨테이너
+@router.get("/material-combos")
+def get_material_combos() -> dict:
+    """표 통째 — `{판, 줄}`(줄마다 담은 자재 포함)."""
+    return _call(matset.listing)
+
+
 @router.get("/material-combos/{key}")
 def get_material_combo(key: str) -> dict:
     """자재 조합 한 줄(키 UM) — 키 · 이름 · 담은자재 · 본뜬키 · 소유 · 비고."""
     return _call(branch.material_combo, key)
 
 
+@router.post("/material-combos")
+def post_material_combo(body: MatsetBody) -> dict:
+    """새로 · 본떠 만들기(`줄.본뜬키`) — 키는 표 「다음」 번호 · `{키, 판, 줄}`."""
+    return _call(matset.create, body.줄, body.판)
+
+
+@router.put("/material-combos/{key}")
+def put_material_combo(key: str, body: MatsetBody) -> dict:
+    """고치기 — 이름 · 비고 · 담은자재(본뜬키 · 소유는 있던 것)."""
+    return _call(matset.edit, key, body.줄, body.판)
+
+
+@router.delete("/material-combos/{key}")
+def delete_material_combo(key: str, 판: str = "") -> dict:
+    """지우기 — 구조물 열이 쓰면 409 `{errors, users}`."""
+    return _call(matset.delete, key, 판)
+
+
 # 복사 가져오기 — 다른 열(`from`) 내용을 받는 열로 · 번호 · 열은 받는 쪽 그대로
 @router.post("/structures/{column}/copy")
 def post_structure_copy(column: str, source: str = Query(alias="from")) -> dict:

M02_MasterTemplete/M02_MasterTemplete_UI_Main.ts

@@ -86,6 +86,8 @@ export interface MainHandle {
   current: () => Selection | null;
   /** 저장 안 한 고침이 있으면 버릴지 물음 — 취소면 false */
   confirmLeave: () => Promise<boolean>;
+  /** 양식 밖 화면(좌측 자재 조합 상세)을 띄움 — 머리는 제목만 · 고침 표시 손잡이를 돌려줌 */
+  showView: (label: string, node: HTMLElement) => (dirty: boolean) => void;
 }
 
 /** 이 층에서 고칠 수 있나 — 시스템은 관리자만 · 회사는 여기서 못 고침(공식으로 저장으로만) */
@@ -429,11 +431,23 @@ export function createMain(isAdmin: boolean, onSaved?: () => void): MainHandle {
     }
   }
 
+  function showView(label: string, node: HTMLElement): (d: boolean) => void {
+    ++seq;
+    dirty = false;
+    drop();
+    showNotice([]);
+    sel = null;
+    bar();
+    title.textContent = label;
+    host.replaceChildren(node);
+    return (d) => (dirty = d);
+  }
+
   save.addEventListener("click", () => void doSave());
   reload.addEventListener("click", async () => {
     if (sel && (await confirmLeave())) void open(sel);
   });
   bar();
   empty("");
-  return { root, open, current: () => sel, confirmLeave };
+  return { root, open, current: () => sel, confirmLeave, showView };
 }

M02_MasterTemplete/M02_MasterTemplete_UI_Page.ts

@@ -23,6 +23,7 @@ export async function renderM02MasterTemplate(root: HTMLElement): Promise<void>
     onOpen: (sel) => void main.open(sel),
     getOpen: main.current,
     confirmLeave: main.confirmLeave,
+    showView: main.showView,
   });
 
   const layout = el("div", { className: "ui-workflow-layout m02-master" });

M02_MasterTemplete/M02_MasterTemplete_UI_Side.ts

@@ -3,7 +3,7 @@
  * 마스터 템플릿 좌측 패널 — 시스템 양식 목록(표/도면/구조물 도면/면적산출/재료산출) · 새로 · 본떠 · 지우기.
  * 서버 길은 계약 `6_계약.md`. 구조물 도면 · 면적산출 · 재료산출 줄은 집계표 구조물 열(꼴=수)마다 하나씩 —
  * 서버가 미리 만들어 둠(도번 SD · 면적번 SA · 재료번 SM + 같은 8자리) ·
- * 줄 글은 번호가 맨 앞(「SD01010100 돌기슭막이 …」).
+ * 줄 글은 번호가 맨 앞(「SD01010100 돌기슭막이 …」). 맨 아래 「자재 조합」 컨테이너는 `M02_MasterTemplete_Matset.ts`.
  * ========================================================================== */
 
 import {
@@ -34,6 +34,7 @@ import {
   structureLabel,
   type StructureColumn,
 } from "./M02_MasterTemplete_Structure";
+import { buildMatsetSection } from "./M02_MasterTemplete_Matset";
 import { canEdit, type Selection } from "./M02_MasterTemplete_UI_Main";
 
 const KINDS: { kind: Kind; label: () => string }[] = [
@@ -75,6 +76,8 @@ export interface SideOptions {
   getOpen: () => Selection | null;
   /** 저장 안 한 고침을 버릴지 확인 — 취소면 false */
   confirmLeave: () => Promise<boolean>;
+  /** 메인 칸에 양식 밖 화면(자재 조합 상세)을 띄움 */
+  showView: (label: string, node: HTMLElement) => (dirty: boolean) => void;
 }
 
 export interface SideHandle {
@@ -128,12 +131,30 @@ export function buildSide(opt: SideOptions): SideHandle {
     del.addEventListener("click", () => void deleteCurrent());
     return [el("div", { className: "m02-side__row", children: [btnNew, copy, del] })];
   };
+  const matset = buildMatsetSection({
+    isAdmin: canEdit(layer, opt.isAdmin),
+    confirmLeave: opt.confirmLeave,
+    show: opt.showView,
+    close: () => opt.onOpen(null),
+    onOpen: () => {
+      picked = null;
+      paintList();
+      paintColumns();
+      paintButtons();
+    },
+  });
+  const matsetSection = section(matset.title, matset.body, ...matset.actions);
+  // 펼칠 때마다 새로 받음 — 재료산출 옆 판이 갈라 낸 조합도 바로 보이게
+  matsetSection.querySelector(".ui-collapsible__title")?.addEventListener("click", () => {
+    if (matsetSection.classList.contains("is-collapsed")) void matset.refresh();
+  });
   const listHost = el("div", {
     className: "m02-side__lists ui-sidebar-panel",
     children: [
       section(L("M02_KindTable"), bodies.get("table")!, ...actionRow("table")),
       section(L("M02_KindDrawing"), bodies.get("drawing")!, ...actionRow("drawing")),
       ...COLUMN_KINDS.map((k, i) => section(k.label(), columnBodies[i])),
+      matsetSection,
     ],
   });
   attachCollapsible(listHost);
@@ -202,6 +223,7 @@ export function buildSide(opt: SideOptions): SideHandle {
   async function select(info: TemplateInfo): Promise<void> {
     if (!isOpen(info) && !(await opt.confirmLeave())) return;
     picked = null;
+    matset.clear();
     opt.onOpen({ layer, projectId: null, kind: info.종류, name: info.이름 });
     paintList();
     paintButtons();
@@ -210,6 +232,7 @@ export function buildSide(opt: SideOptions): SideHandle {
   async function selectColumn(col: StructureColumn, kind: ColumnKind): Promise<void> {
     if (!isPicked(kind, col.id) && !(await opt.confirmLeave())) return;
     picked = null;
+    matset.clear();
     // 제목은 편집 화면이 문서 번호를 앞에 붙임(「SD010101 돌기슭막이 …」)
     opt.onOpen({ layer, projectId: null, kind, name: col.id, label: columnHead(col) });
     paintColumns();
@@ -245,7 +268,7 @@ export function buildSide(opt: SideOptions): SideHandle {
     if (mine !== seq) return;
     paintList();
     paintButtons();
-    await refreshStructure();
+    await Promise.all([refreshStructure(), matset.refresh()]);
   }
 
   /* --- 시스템 층 새로 · 본떠 · 지우기(표 · 도면만 — 구조물 도면은 집계표 열이 정함) --- */

M02_MasterTemplete/M02_MasterTemplete_UI_Style.css

@@ -96,3 +96,25 @@
   flex-direction: column;
   gap: var(--spacing-4);
 }
+
+/* 좌측 「자재 조합」 상세(메인 칸) — 이름 · 비고 · 본뜬키 + 담은 자재 표(줄 모양은 재료산출 옆 판 `m02-mat__row`) */
+.m02-matset {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-12);
+  max-width: 56rem;
+  font-size: var(--text-body-sm);
+}
+
+.m02-matset__fields {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  gap: var(--spacing-12);
+}
+
+.m02-matset__head {
+  margin: 0;
+  color: var(--color-text);
+  font-size: var(--text-body);
+}