Aislo/resources/master_data/_틀.md

# 마스터 데이터 파일 틀

`resources/master_data/` 첫 층 = 정본. `old/` · `ref/` 는 읽지 않음.

## 1. 용어

- **요소** = 원문에 적힌 이름·수 그대로. 계산하지 않음.
- **일위대가 로직** = 요소를 변수로 끌어와 조립한 단위당 계산법. 설계 값 자리는 비움.
- 다른 것을 끌어와 계산하면 로직(기계 시간당 경비 · 기계 작업량 식 포함).

## 2. 파일

- 날짜 없음 · 마스터는 항상 최신. UTF-8 · LF · 들여쓰기 2칸 · 칸 이름은 한글.
- 그룹 = 인력 · 재료 · 기계 · 소요량 · 계수 · 환율 · 요율 · 로직

| 그룹 | 파일 이름 |
|---|---|
| 인력 | `인력.json` 하나 — 줄마다 `조사` |
| 기계 | `기계.json` 하나 — 줄마다 `세부분류` |
| 재료 | `재료_<원문>.json` — 시중물가 · 나라장터자재 · 오피넷유가 · 품셈재료 |
| 환율 · 요율 | `환율_한국은행환율.json` · `요율_조달청제비율.json` |
| 소요량 · 계수 · 로직 | `<그룹>_<원문>_<NN>장_<장 제목>.json` — 예 `소요량_건설품셈_10장_창호_및_유리공사.json` |

- 장 파일 — 장 번호는 두 자리 · 장 제목은 원문 본문 폴더 이름 그대로 · 부문은 이름에 넣지 않음.
- 장 파일 머리 — `부문`(건설품셈만 · 공통 · 토목 · 건축 · 기계설비 · 유지관리) · `차례`(그룹 안 목록 차례: 산림 1~14장 → 건설 공통 → 토목 → 건축 → 기계설비 → 유지관리).
- 원문 이름 = 산림품셈 · 건설품셈 · 건설노임 · 제조노임 · 엔지니어링노임 · 측량노임 · 건설사업관리노임 · SW노임 · 산림노임 · 준용대상 · 나라장터자재 · 오피넷유가 · 시중물가 · 한국은행환율 · 조달청제비율 · 품셈재료 · 자체

## 3. 키

- 모든 요소 줄 · 표 · 로직에 `키` = 테이블ID(영문 대문자 2) + 6자리 일련번호 — `LB000123`. 특수문자·한글 없음.
- 한 번 준 키는 안 바뀜 · 지운 줄의 키는 다시 쓰지 않음. 키는 전체에서 하나.
- 원문이 준 번호·옛 열쇠(직종 `1018` · 기계 `0201-0070` · `13-4-1 메쌓기` · 시중물가 코드)는 `원문번호` 칸 — 같은 테이블 안에서 하나.
- 대장 `_키대장.json` = 키 ↔ 원문번호 ↔ 파일 · 테이블별 `다음` 번호. 새 줄은 대장의 다음 번호를 받음(M01 저장 · 빌더).

| ID | 테이블 | ID | 테이블 |
|---|---|---|---|
| LB | 인력 | QF · QC | 소요량 산림 · 건설 |
| MT | 재료 시중물가 | CF · CC | 계수 산림 · 건설 |
| MN | 재료 나라장터 | FX | 환율 |
| MO | 재료 유가 | RT | 요율 |
| MP | 재료 품셈재료 | GF · GC · GX | 로직 산림 · 건설 · 자체 |
| EQ | 기계 | | |

- 빌더는 옛 모양(`열쇠` · 원문별 파일)으로 쓰고 끝에 `scripts/master_keys.py` 의 `adopt` 를 부름 — 키·원문번호·한 테이블·장 파일 이름으로 받음. 옛 이름으로 읽기는 `old_view`.

## 4. 출처

- 한 칸 · `원문 이름 + 번호` — 「산림품셈 13-4-1」 · 「건설품셈 공통 8-4-1」(건설은 부문 필수) · 「건설노임 1018」 · 「자체」
- [주] 는 뒤에 붙임 — 「산림품셈 13-4-4 주⑩」
- 판(기준일)은 파일 머리에 한 번 · 인력·기계는 갈래 묶음 안에.

## 5. 요소 파일

```json
{
  "그룹": "인력",
  "조사": {
    "건설업": { "원문": "건설노임", "판": "2026-01-01", "비고": ["…"] }
  },
  "줄": [
    { "키": "LB000018", "원문번호": "1018", "조사": "건설업", "이름": "포설공", "규격": "", "단위": "원/일", "값": 0, "출처": "건설노임 1018" }
  ]
}
```

- 인력 `조사` = 건설업 · 제조업 · 엔지니어링 · 측량 · 건설사업관리 · SW · 산림 · 준용대상 · 조사별 원문·판·비고는 머리 `조사` 묶음.
- 기계 `세부분류` = 건설품셈 · 산림품셈 · 세부분류별 원문·판·주는 머리 `세부분류` 묶음.
- 값이 여럿인 요소(기계)는 `값` 을 묶음으로 — `{ "가격": …, "상각비계수": …, "정비비계수": …, "관리비계수": …, "손료계수": …, "주연료": …, "주연료종류": …, "잡재료율": …, "조종원": …, "조종원직종": … }` · `손료계수` = 원문 「계」.
- 묶음 요소는 `단위` · `출처` 도 같은 모양의 묶음.
- 원문에 없는 값을 지어 넣지 않음. 원문 「-」 = 칸을 비움(`null`).
- `준용` = 값 없는 요소에 관리자가 고르는 유사 요소 키 — 준용 값을 미리 채우지 않음. 공표 노임에 이름이 온전히 같은 직종이 없으면 조사 「준용대상」.
- `통합` = 건설노임 원문 「통합·명칭변경 직종」 목록의 새 직종 키 · 갈리면 null + `후보`. `후보` = 비슷한 이름 글(「키 이름」 · 값 안 씀).
- `산정` = 건설노임 미공표 직종의 원문 4-라 값 `{ 값, 근거, 마지막공표[, 비고] }` — 원 미만 처리 안 함.
- 엔진 차례 = 값 → 준용 → 통합 → 산정 · 호표 출처에 「준용: <이름>」 · 「통합: <이름>」 · 「산정: …」.
- 원문 이름 대신 번호로 적은 값(`조종원직종` = 노임 원문번호 「1048」)은 원문 이름을 `비고` 칸에.

재료 값:

- `재료_시중물가` `값` = `{ "시중": { 가격정보 · 물가자료 · 유통물가 · 물가정보 · 거래가격, "면수": {…} }, "조달": { "값", "출처", "기준" } }` — 기본가·채택값 · 견적가 두지 않음. 조달 값이 없으면 비움.
- 조달 `출처` = 「가격정보」(시중물가 원천의 조달청 관급 단가 · `기준` = 원천 면수 글) · 「나라장터:<키>」(값 안 베낌 · 이름·규격·단위가 온전히 같은 짝만 · 애매하면 사람이 화면에서 이음).
- `재료_나라장터자재` = 조달 자료 — 머리 `자료` 에 밝힘.
- `재료_품셈재료` = 품셈이 부르는 재료 목록 — `{ 키, 원문번호, 이름, 규격, 단위, 요구절: [출처 모양], 연결 }` · 값 칸 없음.
- `연결` = 시중물가 키 하나 · 후보 조건 `{ 이름, 규격, 지역: "입력" }`(지역이 갈리는 레미콘·골재·아스콘) · `null`(아직 못 이음).
- 단가 = 연결된 줄의 시중·조달 값 가운데 낮은 값 · 호표 결과 줄에 `출처`(그 값의 칸). 후보 조건 = 품명 뿌리가 `이름` 으로 끝남 · 이름에 로직 입력 `자재지역` 글자 · 단위 같음 · 규격이 둘 이상 갈리면 멈춤 「후보 여럿」 · 그 지역 줄이 없으면 가까운 시군을 고르지 않고 멈춤 「지역 값 없음」.

## 6. 표형 요소 (소요량 · 계수)

원문 표 하나 = 표 하나. 머리가 여러 단이어도 **조건 칸 + 값 칸의 긴 줄**로 폄. 표들은 파일 머리 아래 `표` 칸에 목록으로 둠.

```json
{
  "키": "QF000041",
  "원문번호": "13-4-1 메쌓기",
  "이름": "메쌓기(인력)",
  "기준": "1㎡",
  "출처": "산림품셈 13-4-1",
  "조건": { "뒷길이": "수", "돌": "고르기", "쌓기": "고르기" },
  "값칸": { "석공": "인", "보통인부": "인" },
  "줄": [
    { "뒷길이": 35, "돌": "견치돌", "쌓기": "골쌓기", "석공": 0.5, "보통인부": 0.4 }
  ],
  "주": ["① …"]
}
```

- 건설품셈 표 · 로직의 원문번호 앞에 부문 — 「건축 1-1-1 계수」 · 「공통 8 기계 시간당 경비」.
- 조건 종류 — `수`(같은 값) · `고르기`(글자) · `범위`(줄에 `[아래, 위]` · 끝 열림은 `null` · 포함 여부는 `범위규칙` 에 「초과·이하」처럼).
- `범위규칙` 첫 마디 = 엔진이 읽는 이름 — 「초과·이하」 · 「이상·미만」 · 「이하」(위 끝만) · 「이상·이하」(양 끝 포함). 뒤 마디(` · ` 뒤)는 원문 설명. 「이하」 · 「이상·이하」는 여러 줄이 맞으면 위 끝이 가장 작은 줄.
- 원문 「-」 칸은 줄에서 그 값 칸을 뺌. 줄 전체가 「-」 면 줄을 뺌.
- 원문에 없는 조건 칸은 줄에서 뺌 — 빈 조건 칸은 그 조건에 무엇이든 맞음.
- 값 칸에 범위(「80 ∼ 100」)는 `[아래, 위]` — 로직은 설계자 입력 칸으로 받음(기본값 두지 않음).
- 수와 글이 섞인 칸(「20(135°)」)은 값 칸에 수 · `<값 칸>원문` 칸에 원문 글.
- 줄마다 단위가 다르면 `단위` 칸을 줄에 둠.
- 분수·식으로 적힌 값(「L/V×2×60」)은 값 칸에 식 글자 그대로 · `<값 칸>원문` 칸에 원문.
- 원문에 짝 표시 없이 나란히 놓인 줄은 `짝` 칸으로 묶음.
- 수는 원문 그대로(쉼표만 뺌). 단위 환산하지 않음.
- `주` 는 원문 글 그대로 — 계산에 쓰는 수가 들어 있으면 따로 계수 표로도 올림.

## 7. 로직 파일

```json
{
  "그룹": "로직",
  "원문": "산림품셈",
  "차례": 11,
  "줄": [
    {
      "키": "GF000123",
      "원문번호": "13-4-1 메쌓기",
      "이름": "돌쌓기 메쌓기(인력)",
      "결과단위": "원/㎡",
      "출처": "산림품셈 13-4-1",
      "소유": "공용",
      "입력": [
        { "이름": "뒷길이", "단위": "㎝" },
        { "이름": "돌", "고르기": ["견치돌", "깬돌", "깬잡석", "호박돌 및 야면석"] }
      ],
      "중간": [{ "이름": "증가율", "식": "…" }],
      "호표": [
        { "종류": "인력", "요소": "LB000002", "단위": "인", "수량": "…", "비목": "노무비" }
      ],
      "덧줄": [{ "이름": "잡재료비", "식": "노무비 * 0.05", "비목": "재료비", "출처": "…" }],
      "끝수": "원 미만 버림"
    }
  ]
}
```

- `호표` 줄 = 실무 일위대가표 한 줄(종류 · 이름·규격 · 단위 · 수량 · 단가 · 금액). 단가는 적지 않음 — `요소` 에서 옴. 금액 = 수량 × 단가.
- `종류` = 인력 · 재료 · 기계 · 로직(하위 로직의 결과를 단가로 씀) — 요소 키의 테이블ID 그룹과 같음.
- `비목` = 노무비 · 재료비 · 경비. `덧줄` 식에서 비목 합을 이름으로 씀.
- `결과단위` 가 돈이 아닌 로직(㎥/시간)은 `호표` 없이 `중간` + `결과` 식.
- `종류` 가 로직이고 `비목` 칸이 없는 호표 줄은 불러온 결과를 비목별로 나눠 얹음.
- 근거가 덜 선 줄은 `비고` 칸에 적음 — 「환산 근거 미확인」.
- 입력에 원문 범위가 있으면 `범위: [아래, 위]` · 기본값 두지 않음.
- `소유` = 공용 · 개인(뒤 단계 자리).

## 8. 변수 · 식

- 요소 — 키 `LB000123` · 값 묶음은 `.칸` — `EQ000045.주연료`.
- 입력·중간 값으로 요소를 고르면 `ID:원문번호` 에 `{이름}` 을 끼움 — `EQ:{기계}.가격` · `MO:경유:{지역}` · `LB:{조종원직종}`.
- 표 찾기 — `찾기(QF000041, 뒷길이=뒷길이, 돌=돌, 쌓기=쌓기).석공`
- 맞는 줄이 여럿이면 찾는 값 칸이 있는 줄만 봄. 값 칸·조건 이름에 괄호·빈칸이 있으면 작은따옴표 — `.'시공량(m)'` · `'규준틀 높이'=높이`
- 찾기·로직 인자의 글자 값은 작은따옴표 — `구분='V(다짐속도,km/hr)'` · 따옴표 없으면 이름(입력·중간).
- 로직 부르기 — `로직(GC000871, 기계='0201-0070')` · 돈 로직의 결과는 비목 묶음 `.노무비` `.재료비` `.경비` `.계` · 돈 아닌 로직은 수 하나.
- 입력 · 중간 · 비목 합은 이름 그대로.
- 후보 조건 품셈재료를 쓰는 로직(부르는 로직 포함)은 입력 `자재지역` 을 두고 하위 로직에 `자재지역=자재지역` 으로 넘김 — `지역` 은 유가 고르기.
- 쓸 수 있는 것 — `+ - * /` · 괄호 · 비교 `< <= > >= == !=` · `그리고` `또는` · `찾기` · `로직` · `만약(조건, 참, 거짓)` · `올림` `버림` `반올림`(자리) · `최소` `최대`. 그 밖은 쓰지 않음.
- 로직이 돌고 도는 참조를 만들지 않음.
- 사람이 읽는 자리(M01 화면 · 검사 알림)는 키 옆에 이름.

## 9. 검사

- 고친 뒤 `scripts/check_master.py` — 틀 · 본문 대조 · 로직 검사 · 키(모양 · 겹침 · 원문번호 겹침 · 대장 · 끊긴 키). 로직은 `계산` 으로 손 계산과 맞댐.