feat(B08): 기초잡석 물량·용수 축 (확정 3차 ②④) — 옹벽 묶음 다섯 조각이 다 참

기초잡석(②)
- 두께 0.2m(사용자 확정). 폭은 버림 폭과 같아(KCS 34 50 05) **버림 × 두께 비**로 나옴
  ⇒ 관측 원단위로 오는 옹벽에도 값이 섬(버림 0.15㎥/m ⇒ 잡석 0.30㎥/m)
- destination `unit_price` — 운반·부설·다짐 품이 붙는 공종이라 자재총괄에 안 섞임
- 인계에 FP-12-25 줄로 섬. 묶음 구조물(옹벽)은 조각이 이미 세므로 건너뜀
- 두께는 설정 `rubble_base_thickness_m` 로 화면에서 바꿀 수 있음

용수 축(④)
- 품셈 9-13 의 18구분을 토질 × 육상/용수 × 심도로 골라 자식 코드로 내려감
- ⚠ 기본 「육상」은 **통상값이고 사용자 확정이 아님** — 그 사실을 줄 사유에 적음
- 3m 초과 칸은 원문에 없어 상위 코드 + 사유

- 설정 신설: rubble_base_thickness_m(0.2) · structure_trench_water(육상)
- tmp/tests 신설 test_b08_rubble_base.py(7건) + 터파기 시험 6건 추가

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

B08_Quantity/B08_Quantity_Engine_Handoff.py

@@ -44,7 +44,10 @@ from typing import Any, Iterable
 
 from B08_Quantity.B08_Quantity_Engine_BasisUnit import verify_unit_matches_basis
 from B08_Quantity.B08_Quantity_Engine_Handoff_Spoil import spoil_haul_rows
-from B08_Quantity.B08_Quantity_Engine_Handoff_Trench import structure_earthwork_rows
+from B08_Quantity.B08_Quantity_Engine_Handoff_Trench import (
+    rubble_base_rows,
+    structure_earthwork_rows,
+)
 
 # ⚠ 파일만 갈랐고 **계약은 그대로다** — 종전에 이 이름으로 가져다 쓰던 곳이 그대로 돌게
 #   여기서 다시 내보낸다(2026-09-08 분리).
@@ -107,6 +110,7 @@ def build_handoff(
     ground_methods: dict[str, str | None] | None = None,
     concrete_placing_method: str | None = None,
     bench_cut_depth_m: float | None = None,
+    structure_trench_water: str | None = None,
 ) -> dict[str, Any]:
     """B09 가 그대로 받는 모양. 없는 표는 건너뛰되 **빈 표와 구별해 적는다**."""
     table = mapping or load_mapping()
@@ -132,7 +136,11 @@ def build_handoff(
         # 구조물이 낸 터파기·되메우기·잔토 — **공종 축으로 올린다.**
         #   ⚠ 종전에는 성분으로만 있고 아무도 안 받아 **내역서에 한 줄도 안 나갔다**
         #     (2026-09-08 B09 매김에서 드러남). 실무 토적집계에는 서는 줄이다(울진 D12~D14).
-        rows, misses = structure_earthwork_rows(unit_quantity_table, table)
+        rows, misses = structure_earthwork_rows(unit_quantity_table, table, structure_trench_water)
+        work_items.extend(rows)
+        unmatched.extend(misses)
+        # 기초잡석 — 버림이 선 구조물에 함께 서는 공종(확정 3차 ②). 묶음 구조물은 제외한다.
+        rows, misses = rubble_base_rows(unit_quantity_table, table)
         work_items.extend(rows)
         unmatched.extend(misses)
 

B08_Quantity/B08_Quantity_Engine_Handoff_Trench.py

@@ -23,6 +23,7 @@ from typing import Any
 from B08_Quantity.B08_Quantity_Engine_Handoff_Mapping import (
     BLOCKED_INPUT_MISSING,
     ORIGIN_EARTHWORK,
+    ORIGIN_STRUCTURE,
     WorkItemMapping,
 )
 from B08_Quantity.B08_Quantity_Engine_UnitQuantity import GROUND_TYPE_LABEL
@@ -36,6 +37,7 @@ DEPTH_BANDS: tuple[tuple[float, str], ...] = ((1.0, "0~1m"), (2.0, "1~2m"), (3.0
 DEPTH_OVER = "3m 초과"
 
 TRENCH_GROUP = "구조물터파기"
+RUBBLE_GROUP = "기초잡석"
 BACKFILL_GROUP = "되메우기"
 SPOIL_GROUP = "잔토처리"
 
@@ -47,6 +49,33 @@ WATER_BLOCKED_REASON = (
     " — 모른다고 육상으로 눅이지 않음"
 )
 GROUND_BLOCKED_REASON = "토질을 못 가름"
+
+#: 품셈 9-13 의 18구분 — **토질 3 × 육상/용수 × 심도 3**. 코드 차례가 원문 그대로다
+#: (육상토사 0~1·1~2·2~3 → 용수토사 셋 → 육상 암절취 셋 → … → 용수 발파암 셋).
+GROUND_ORDER = ("soil", "ripping_rock", "blasting_rock")
+WATER_ORDER = ("육상", "용수")
+DEPTH_ORDER = ("0~1m", "1~2m", "2~3m")
+#: ⚠ 3m 를 넘는 칸이 **원문에 없다** — 지어내지 않고 상위 코드로 두고 사유를 낸다.
+DEPTH_OVER_REASON = "심도 3m 를 넘는 칸이 품셈 9-13 원문에 없음 — 상위 코드로 둠"
+#: ⚠ **사용자 확정이 아니라 통상값**이다(2026-09-09 확정 3차 ④). 화면에도 그 사실이 뜨고
+#:   사용자가 「용수」로 뒤집으면 코드가 한 칸 옮겨 간다.
+WATER_DEFAULT_NOTE = "용수 유무 — 「육상」은 통상값이고 사용자 확정이 아님(확정 3차 ④)"
+
+
+def trench_child_code(parent: str | None, ground: str | None, water: str, band: str) -> str | None:
+    """품셈 9-13 의 18구분 중 한 칸. 축이 하나라도 없으면 `None`(상위 코드로 둔다)."""
+    if not parent or ground not in GROUND_ORDER or water not in WATER_ORDER:
+        return None
+    if band not in DEPTH_ORDER:
+        return None
+    index = (
+        GROUND_ORDER.index(ground) * len(WATER_ORDER) * len(DEPTH_ORDER)
+        + WATER_ORDER.index(water) * len(DEPTH_ORDER)
+        + DEPTH_ORDER.index(band)
+    )
+    return f"{parent}-{index + 1:02d}"
+
+
 SPOIL_REASON = (
     "사토로 실어 내는 몫이라 유토곡선(B06)이 세야 겹치지 않음 — ⚠ 지금 그 통로가 없어"
     " 어디에도 안 실림. 값을 버리지 않고 사유와 함께 넘김"
@@ -107,10 +136,56 @@ def _row(**fields: Any) -> dict[str, Any]:
     return row
 
 
-def structure_earthwork_rows(
+def rubble_base_rows(
     unit_quantity_table: dict[str, Any], mapping: WorkItemMapping
 ) -> tuple[list[dict[str, Any]], list[str]]:
-    """구조물이 낸 터파기·되메우기·잔토를 **공종 축**으로 올린다."""
+    """기초잡석(품셈 12-25) — 구조물 전개가 낸 성분을 **한 줄로** 올린다.
+
+    ⚠ **묶음으로 서는 구조물은 건너뛴다** — 옹벽 묶음에 이미 `FP-12-25` 조각이 있어
+      여기서 또 세우면 같은 잡석을 두 번 센다(타설 줄에서 이미 겪은 자리).
+    """
+    total = 0.0
+    bases: list[str] = []
+    for structure in unit_quantity_table.get("structures") or []:
+        if mapping.composite_for(str(structure.get("type_id") or "")):
+            continue
+        for component in structure.get("components") or []:
+            if str(component.get("name") or "") != RUBBLE_GROUP:
+                continue
+            amount = float(component.get("amount") or 0.0)
+            if amount <= 0:
+                continue
+            total += amount
+            basis = str(component.get("basis") or "")
+            if basis and basis not in bases:
+                bases.append(basis)
+    if total <= 0:
+        return [], []
+    entry = mapping.for_earthwork(RUBBLE_GROUP, None)
+    code = (entry or {}).get("work_item_code")
+    return [
+        _row(
+            work_item_code=code,
+            name=RUBBLE_GROUP,
+            spec="구조물",
+            spec_detail=bases[0] if bases else "구조물 전개 합",
+            quantity=round(total, 3),
+            origin=ORIGIN_STRUCTURE,
+            in_bill=code is not None,
+            in_bill_reason="" if code else "품셈 공종을 아직 못 이었습니다",
+        )
+    ], ([] if code else [RUBBLE_GROUP])
+
+
+def structure_earthwork_rows(
+    unit_quantity_table: dict[str, Any],
+    mapping: WorkItemMapping,
+    water: str | None = None,
+) -> tuple[list[dict[str, Any]], list[str]]:
+    """구조물이 낸 터파기·되메우기·잔토를 **공종 축**으로 올린다.
+
+    `water` 는 「육상」·「용수」. 안 주면 「안 정함」이라 상위 코드로 두고 사유를 낸다.
+    """
     # ⚠ 키는 **(심도, 토질)** 뿐이다 — 근거 문구까지 키에 넣으면 같은 「암절취 · 2~3m」이
     #   측점 문구가 다르다는 이유로 **두 줄로 갈린다**(2026-09-08 실화면에서 그랬다).
     trench: dict[tuple[str, str | None], float] = {}
@@ -156,20 +231,36 @@ def structure_earthwork_rows(
                 continue
             ground_basis = " · ".join(bases.get((band, ground)) or [])
             label = GROUND_TYPE_LABEL.get(str(ground), str(ground)) if ground else None
-            reason = WATER_BLOCKED_REASON if ground else f"{GROUND_BLOCKED_REASON} — {ground_basis}"
+            child = trench_child_code(code, ground, str(water or ""), band)
+            if not ground:
+                reason = f"{GROUND_BLOCKED_REASON} — {ground_basis}"
+            elif not water:
+                reason = WATER_BLOCKED_REASON
+            elif child is None:
+                reason = DEPTH_OVER_REASON
+            else:
+                reason = ""
+            detail = " · ".join(
+                part
+                for part in (
+                    "구조물 전개 합",
+                    ground_basis,
+                    WATER_DEFAULT_NOTE if water == "육상" else "",
+                )
+                if part
+            )
+            spec = " · ".join(part for part in (label or "", water or "", f"심도 {band}") if part)
             rows.append(
                 _row(
-                    work_item_code=code,
+                    work_item_code=child or code,
                     name=TRENCH_GROUP,
-                    spec=f"{label} · 심도 {band}" if label else f"심도 {band}",
+                    spec=spec,
                     ground_class=label,
-                    spec_detail=f"구조물 전개 합 · {ground_basis}"
-                    if ground_basis
-                    else "구조물 전개 합",
+                    spec_detail=detail,
                     quantity=amount,
-                    blocked_kind=BLOCKED_INPUT_MISSING,
+                    blocked_kind=BLOCKED_INPUT_MISSING if reason else None,
                     blocked_reason=reason,
-                    in_bill=False,
+                    in_bill=not reason,
                     in_bill_reason=reason,
                 )
             )

B08_Quantity/B08_Quantity_Engine_UnitQuantity.py

@@ -265,6 +265,15 @@ def fill_concrete_mpa(options: dict[str, Any]) -> tuple[str, str]:
 
 
 BLINDING_THICKNESS_M = 0.10
+
+#: 기초잡석 두께(m) — 2026-09-09 사용자 확정 3차 ② 「0.2 m」.
+#: ⚠ 품셈 12-25 는 **㎥당 품만** 주고 두께를 정하지 않는다(전 출처 소진). 폭은 **버림 폭과
+#:   같고**(KCS 34 50 05 「버림 콘크리트의 폭은 잡석다짐의 폭과 동일」) 그 폭은 확정 ⑪ 로
+#:   하단 길이다. ⇒ **기초잡석 = 버림 × (잡석두께 ÷ 버림두께)** 로 나온다 — 같은 폭·연장이라
+#:   두께 비만 곱하면 된다. 관측 원단위로 오는 구조물(옹벽)도 같은 식으로 선다
+#:   (버림 0.15㎥/m ÷ 0.1 = 폭 1.5m ⇒ 잡석 0.30㎥/m — 확정 3차 ② 의 그 값).
+RUBBLE_BASE_THICKNESS_M = 0.2
+RUBBLE_BASE_NAME = "기초잡석"
 #: 버림을 뺄 수 있는 칸 — 「기본은 넣고, 빼고 싶으면 뺀다」(사용자 확정 ⑭).
 #:   저장 제원에 이 칸이 없으면 **넣는 쪽**이 기본이다.
 BLINDING_OPTION_KEYS = ("blinding_concrete", "base_blinding")
@@ -293,6 +302,9 @@ DESTINATION = {
     #   있던 것을 줄로 꺼낸 것뿐이고, `material`·`earthwork` 어디에도 안 섞인다.
     #   ⚠ 「석적」은 정본에 없다(소광리 시트에만) — **안 낸다.**
     "입적": "reference",
+    # 기초잡석(품셈 12-25) — 운반·부설·다짐 품이 붙는 **공종**이라 일위대가로 간다.
+    #   자재총괄로 보내면 같은 잡석이 재료로 한 번 더 선다.
+    RUBBLE_BASE_NAME: "unit_price",
 }
 
 # ⚠ 배합 성분 — 산출물에 나타나면 안 된다(㉢). B09 일위대가가 배합표로 분해한다.
@@ -1182,11 +1194,38 @@ def _section_mode_at(
     return section_modes.get(nearest)
 
 
+def _rubble_base_component(
+    components: list[Component], thickness_m: float | None
+) -> Component | None:
+    """기초잡석 한 줄 — **버림 폭이 곧 잡석다짐 폭**이라 두께 비로 낸다(확정 3차 ②).
+
+    ⚠ 폭을 다시 세지 않는다. 버림이 이미 그 폭으로 서 있으므로 두께 비만 곱하면
+      **관측 원단위로 오는 구조물(옹벽)에도 같은 식이 선다** — 두 벌로 짜지 않는 자리다.
+    """
+    thickness = RUBBLE_BASE_THICKNESS_M if thickness_m is None else float(thickness_m)
+    if thickness <= 0:
+        return None
+    blinding = next((item for item in components if item.name == "버림콘크리트"), None)
+    if blinding is None or blinding.amount <= 0:
+        return None
+    ratio = thickness / BLINDING_THICKNESS_M
+    return Component(
+        RUBBLE_BASE_NAME,
+        "㎥",
+        blinding.amount * ratio,
+        DESTINATION[RUBBLE_BASE_NAME],
+        f"버림 {blinding.amount:.3f}㎥ × (잡석두께 {thickness:g} ÷ 버림두께"
+        f" {BLINDING_THICKNESS_M:g}) — 폭이 같음(KCS 34 50 05) · 두께는 사용자 확정 3차 ②"
+        " (품셈 12-25 는 ㎥당 품만 주고 두께를 정하지 않음)",
+    )
+
+
 def build_table(
     structures: Iterable[dict[str, Any]],
     names: dict[str, str] | None = None,
     section_modes: dict[float, str] | None = None,
     ground_types: dict[float, str] | None = None,
+    rubble_base_thickness_m: float | None = None,
 ) -> dict[str, Any]:
     """화면·API 가 그대로 쓰는 모양. 성분별 총량과 구조물별 내역을 함께 낸다."""
     observed = load_observed_table()
@@ -1199,6 +1238,10 @@ def build_table(
     for item in expanded_inputs:
         quantity = expand(item, names, observed, _section_mode_at(item, section_modes))
         quantity.ground_type, quantity.ground_type_basis = ground_type_at(item, ground_types)
+        # 기초잡석 — 버림이 선 구조물에 함께 선다(전개식이든 관측 원단위든 같은 자리).
+        rubble = _rubble_base_component(quantity.components, rubble_base_thickness_m)
+        if rubble is not None:
+            quantity.components.append(rubble)
         quantities.append(quantity)
     violations = verify_no_mix_components(quantities)
 

B08_Quantity/B08_Quantity_Router_Earthwork.py

@@ -268,11 +268,20 @@ class QuantitySettingsBody(BaseModel):
     bench_cut_depth_m: float | None = None
     # 사토장까지 운반거리(m). 유토곡선이 낸 사토를 **실어 내는 줄**이 이 값으로 선다.
     spoil_site_distance_m: float | None = None
+    # 기초잡석 두께(m) — 확정 3차 ② 0.2. 폭은 버림 폭과 같다(KCS 34 50 05).
+    rubble_base_thickness_m: float | None = None
+    # 구조물터파기 용수 유무 — "육상"·"용수". ⚠ 기본 육상은 **통상값**이지 사용자 확정이 아니다.
+    structure_trench_water: str | None = None
 
 
 #: `None` 이 「안 정함」을 뜻하는 칸 — 저장에서 **버리지 않고 그대로 덮어쓴다**.
 #: 빈 문자열로 되돌리는 칸(시공법·타설 방식)과 달리 숫자 칸은 되돌릴 값이 `None` 뿐이다.
-NULLABLE_SETTING_KEYS = ("topsoil_thickness_m", "bench_cut_depth_m", "spoil_site_distance_m")
+NULLABLE_SETTING_KEYS = (
+    "topsoil_thickness_m",
+    "bench_cut_depth_m",
+    "spoil_site_distance_m",
+    "rubble_base_thickness_m",
+)
 
 
 @router.put("/{project_id}/quantity/settings")

B08_Quantity/B08_Quantity_Router_Material.py

@@ -146,10 +146,14 @@ async def get_material_summary(project_id: UUID) -> JSONResponse:
             content={"status": "error", "message": "구조물 정본을 읽지 못했습니다."},
         )
 
-    unit_table = build_unit_table(
-        structures, names, await _section_modes(project_id), await _ground_types(project_id)
-    )
     settings = quantity_settings(project_root)
+    unit_table = build_unit_table(
+        structures,
+        names,
+        await _section_modes(project_id),
+        await _ground_types(project_id),
+        settings.get("rubble_base_thickness_m"),
+    )
     material_table = build_material_table(
         unit_table,
         supply_map=settings.get("material_supply") or {},
@@ -189,7 +193,11 @@ async def project_haul_inputs(project_id: UUID) -> dict[str, Any]:
         project_root = resolve_stored_project_path(stored_path)
         structures, names, _skipped = _collect_structures(project_root)
         unit_table = build_unit_table(
-            structures, names, await _section_modes(project_id), await _ground_types(project_id)
+            structures,
+            names,
+            await _section_modes(project_id),
+            await _ground_types(project_id),
+            quantity_settings(project_root).get("rubble_base_thickness_m"),
         )
     except Exception:
         logger.exception("B08 유토곡선 입력 조회 실패: project_id=%s", project_id)
@@ -224,10 +232,14 @@ async def get_handoff(project_id: UUID) -> JSONResponse:
         )
 
     structures, names, skipped = _collect_structures(project_root)
-    unit_table = build_unit_table(
-        structures, names, await _section_modes(project_id), await _ground_types(project_id)
-    )
     settings = quantity_settings(project_root)
+    unit_table = build_unit_table(
+        structures,
+        names,
+        await _section_modes(project_id),
+        await _ground_types(project_id),
+        settings.get("rubble_base_thickness_m"),
+    )
     material_table = build_material_table(
         unit_table, supply_map=settings.get("material_supply") or {}
     )
@@ -257,6 +269,8 @@ async def get_handoff(project_id: UUID) -> JSONResponse:
         concrete_placing_method=concrete_placing_method(settings)[0],
         # 층따기 길이 — 면적 × 이 값으로 ㎥ 를 낸다(확정 2차 ①). 안 넣었으면 막히고 사유가 감.
         bench_cut_depth_m=settings.get("bench_cut_depth_m"),
+        # 용수 유무 — 기본 「육상」은 **통상값**이다(확정 3차 ④). 사유·화면에 그 사실이 뜬다.
+        structure_trench_water=settings.get("structure_trench_water"),
     )
     handoff["summary"] = summarize(handoff)
     handoff["skipped_structures"] = skipped

common_util/common_util_project_settings.py

@@ -117,7 +117,16 @@ def default_settings() -> dict[str, Any]:
             "bench_cut_depth_m": None,
             # 사토장까지 운반거리(m) — 설계 입력이다. 품셈은 거리를 정하지 않는다.
             #   ⚠ `None` 은 「안 정함」이고, 그러면 사토 운반 줄이 **막힌 채로** 선다.
+            #   (2026-09-09 확정 3차 ③ — 권고할 값이 없어 **물음으로 남긴 자리**다.)
             "spoil_site_distance_m": None,
+            # 기초잡석 두께(m) — 2026-09-09 사용자 확정 3차 ② 「0.2 m」.
+            #   ⚠ 품셈 12-25 는 ㎥당 품만 주고 두께를 정하지 않는다. 폭은 버림 폭과 같고
+            #     (KCS 34 50 05) 두께가 이 값이다. 화면에서 바꿀 수 있다.
+            "rubble_base_thickness_m": 0.2,
+            # 구조물터파기 용수 유무 — 품셈 9-13 의 18구분 중 한 축.
+            #   ⚠ **사용자 확정이 아니라 통상값**이다(확정 3차 ④). 화면·사유에 그 사실을
+            #     적어 두고 사용자가 뒤집을 수 있게 둔다.
+            "structure_trench_water": "육상",
             "dataset_versions": {},
         },
         "estimation": {

resources/data_work_item_mapping/work_item_mapping_2026-01-01.json

@@ -117,6 +117,14 @@
       "basis_source": "산림사업 표준품셈(고시 2025-82) 9-13 구조물터파기 — 원문 L5022~5241.",
       "master_name": "구조물터파기",
       "note": "⚠ 상위 코드다. 품은 18구분(토질 3 × 육상/용수 × 심도 3) 하위에만 있어 그대로는 금액이 안 선다 — 토질·용수 칸이 생기면 FP-09-13-01~18 중 하나로 내려간다. 심도는 구조물 제원(직고 + 기초 깊이)에서 이미 갈라 둔다."
+    },
+    {
+      "group": "기초잡석",
+      "work_item_code": "FP-12-25",
+      "basis_unit": "㎥",
+      "basis_source": "산림사업 표준품셈(고시 2025-82) 12-25 기초잡석 「(단위: ㎥당)」.",
+      "master_name": "기초잡석",
+      "note": "품셈은 운반·부설·다짐 품만 주고 **두께·폭을 정하지 않는다.** 폭은 버림 폭과 같고(KCS 34 50 05) 두께는 사용자 확정 3차 ②(0.2m)다 — 화면에서 바꿀 수 있다."
     }
   ],
   "haul": [
@@ -297,9 +305,10 @@
             "code": "FP-12-25",
             "name": "기초잡석",
             "unit": "㎥",
-            "from_components": [],
-            "not_ready": true,
-            "why": "관측 원단위에 기초잡석 물량이 없음 — 울진 라이브러리 반중력식 H=2.0 항목에 그 줄이 없다"
+            "from_components": [
+              "기초잡석"
+            ],
+            "why": "관측 원단위에는 기초잡석 줄이 없으나 **버림 폭이 곧 잡석다짐 폭**이라(KCS 34 50 05) 버림 물량에서 두께 비로 나온다 — 버림 0.15㎥/m ÷ 0.1 = 폭 1.5m, 두께 0.2m(사용자 확정 3차 ②) ⇒ 0.30㎥/m."
           }
         ],
         "why": "품셈 12장에 「옹벽」 공종이 없음. 실무 내역은 「반중력식옹벽 H=2.0」 한 줄이고 그 일위대가가 위 공종을 묶음.",