docs(knowledge): STmate STC/XLSX 웹앱 적용성 검증보고서 이관

- docs/raw에서 resources/knowledge 루트로 이동 (docs/raw는 git 미추적이라 추가로만 기록)
- 2026-07-25자 PARTIAL PASS 보고서: STC 구조, 금액 대조, P0 누락정보, 웹앱 관리 방향

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

resources/knowledge/2026-07-25_verify_stmate_stc_xlsx_webapp_feasibility.md

@@ -0,0 +1,346 @@
+# STmate STC·XLSX 웹앱 적용 가능성 및 누락정보 검증보고서
+
+## 1. 검증 개요
+
+- **검증일**: 2026-07-25
+- **검증 목적**: STmate 프로젝트 파일과 Excel 산출물에서 데이터 구조와 계산 로직을 추출하여 Aislo 웹앱의 수량산출·견적 기능으로 관리할 수 있는지 판단하고, 구현 전에 추가로 확보해야 할 정보를 식별한다.
+- **검증 대상**:
+  - `2024년 간선임도사업(기번3).STC`
+  - `2024년 간선임도사업(기번3).xlsx`
+- **검증 범위**:
+  - 파일 컨테이너와 내부 데이터 구조
+  - 공사비·공종·단가·수량·요율 정보
+  - Excel 수식과 STC 데이터의 대응 관계
+  - 웹앱 데이터 관리 및 계산 엔진 방향
+  - 누락정보와 후속 확보자료
+- **제외 범위**:
+  - 애플리케이션 소스코드 작성·수정
+  - `docs/raw/PLAN.md` 작성 또는 변경
+  - STmate 전용 난독화 데이터의 무리한 복호화
+  - B08/B09 실제 구현 검증
+
+## 2. 종합 판정
+
+### 2.1 판정
+
+**조건부 가능(PARTIAL PASS)** 이다.
+
+두 파일만으로 다음 항목은 충분히 파악할 수 있다.
+
+1. 공사비 계층과 공종별 내역 구조
+2. 재료비·노무비·경비·합계의 비용 분해 구조
+3. 수량 × 단가 및 집계표 간 연결 관계
+4. 일위대가·중기사용료·단가산출근거의 코드 체계
+5. 간접노무비, 보험료, 일반관리비, 이윤, 부가가치세 등 제경비 계산의 상당 부분
+6. Excel 시트 간 수식 의존 관계와 최종 공사비 집계 흐름
+7. STmate 프로젝트 원본과 Excel 산출물의 동일성 대조
+
+그러나 다음 항목은 두 파일만으로 완전하게 확정할 수 없다.
+
+1. STmate의 모든 DBF 필드 의미와 코드값 사전
+2. `BDQTY.DBF`, `SYSINFO.DBF` 등에 적용된 전용 인코딩 또는 난독화 규칙
+3. `.SMT` 메모 필드의 완전한 해석 규칙
+4. 모든 요율의 법적·행정적 근거, 적용 조건 및 유효기간
+5. 단계별 절사·반올림·보정·예외 처리의 공식 명세
+6. Excel 수식과 STmate 내부 계산 엔진이 항상 동일한지 여부
+7. 다른 사업·연도·공사유형·STmate 버전에도 동일한 규칙이 적용되는지 여부
+
+따라서 현재 자료는 **웹앱 데이터 모델과 계산 엔진을 설계하는 기준 샘플**로는 유효하지만, 곧바로 모든 사업에 적용할 범용 원가계산 규칙으로 확정해서는 안 된다.
+
+## 3. 확인된 파일 구조
+
+### 3.1 XLSX
+
+XLSX는 일반 OOXML ZIP 패키지이며 총 21개 시트로 구성된다.
+
+주요 시트는 다음과 같다.
+
+- 공사원가계산서
+- 총괄설계내역서
+- 설계내역서
+- 일위대가목록표 / 일위대가표
+- 단가산출근거목록표 / 단가산출근거
+- 환율및기초자료
+- 중기목록표 / 중기사용료
+- 재료비·노무비·경비 목록표
+- 자재단가대비표
+- 재료비·노무비·경비·중기 집계표
+- `〓 INITIAL 〓` veryHidden 시트
+
+문서 속성에는 `STmate w24.04로 작성`이 기록되어 있다. 숨겨진 `〓 INITIAL 〓` 시트에는 STmate 코드, 행 위치, 수량, 분류 및 재등록용 메타데이터가 포함된다. 따라서 이 Excel은 단순 보고서가 아니라 STmate 재등록을 고려한 교환 포맷 성격도 가진다.
+
+### 3.2 STC
+
+STC는 다음 파일을 포함한 ZIP 패키지이다.
+
+| 내부 파일 | 레코드 수 | 확인된 역할 |
+|---|---:|---|
+| `PRJLST.DBF` | 1 | 프로젝트 기본정보 및 총액 |
+| `BOQ11.DBF` | 261 | 공종 계층과 설계내역 |
+| `BDQTY.DBF` | 667 | 세부 수량·단가산출 구성으로 추정 |
+| `COSTN.DBF` | 186 | 품목·단가·가격출처·비용 분해 |
+| `RATE.DBF` | 41 | 요율 행렬 |
+| `RATE_M.DBF` | 25 | 추가 요율 |
+| `RATE_R.DBF` | 50 | 확장 요율 |
+| `RATE_RA.DBF` | 50 | 확장 요율 |
+| `SET_REP.DBF` | 75 | 출력 보고서 정의 |
+| `KONGJONG.DBF` | 1 | 공종 분류 |
+| `SYSINFO.DBF` | 8 | 시스템 정보 |
+
+`Start8x.Ini`와 `STini.MEM`에는 가격 출처명, 환율, 출력 설정, 프로젝트 설정과 STmate 버전이 저장되어 있다.
+
+## 4. 두 파일의 동일성 검증
+
+STC의 `PRJLST.DBF`, `BOQ11.DBF`와 XLSX의 공사원가계산서·총괄설계내역서·설계내역서에서 다음 금액이 동일하다.
+
+| 구분 | 금액 |
+|---|---:|
+| 직접 재료비 | 194,234,417원 |
+| 직접 노무비 | 346,800,554원 |
+| 산출 경비 | 169,324,165원 |
+| 직접공사비 합계 | 710,359,136원 |
+| 총원가 | 1,029,117,273원 |
+| 부가가치세 | 102,911,727원 |
+| 도급공사비 | 1,132,029,000원 |
+| 관급자재대 | 69,850,000원 |
+| 총공사비 | 1,201,879,000원 |
+
+프로젝트명 `2024년 간선임도사업(기번3)`과 위치 `울진 울진 대흥 산65`도 일치한다. 두 파일은 동일한 프로젝트의 원본 데이터와 Excel 산출물 관계로 판단할 수 있다.
+
+## 5. 확인 가능한 계산 흐름
+
+확인된 상위 계산 흐름은 다음과 같다.
+
+```text
+기초 단가·가격 출처·환율·요율
+    ↓
+재료 / 노무 / 장비 / 경비 단가
+    ↓
+일위대가 및 중기사용료
+    ↓
+단가산출근거
+    ↓
+설계 수량 × 적용 단가
+    ↓
+공종별 설계내역
+    ↓
+재료비·노무비·경비 집계
+    ↓
+총괄설계내역
+    ↓
+간접노무비·보험료·기타경비·일반관리비·이윤
+    ↓
+총원가·부가가치세·도급공사비·관급자재대
+    ↓
+총공사비
+```
+
+샘플에서 직접 확인된 제경비 계산에는 다음 항목이 있다.
+
+- 간접노무비: 직접노무비 × 14.5%
+- 산재보험료
+- 고용보험료
+- 건강보험료
+- 노인장기요양보험료
+- 연금보험료
+- 산업안전보건관리비
+- 기타경비
+- 환경보전비
+- 건설기계대여금 지급보증금액
+- 일반관리비
+- 이윤
+- 부가가치세
+- 조달수수료
+
+다만 표시된 산식만으로는 적용 대상 금액, 조건 분기, 상한·하한, 절사 위치 및 예외를 모두 확정할 수 없다.
+
+## 6. 현재 Aislo 문서와의 정합성
+
+`docs/wiki/` 기준으로 다음 사항이 확인된다.
+
+1. B08에는 145개 수량 템플릿이 정의되어 있다.
+   - 단가산출 40
+   - 일위대가 25
+   - 자재 37
+   - 중기 24
+   - 일식 5
+   - 노무 14
+2. `templete_calc_cost.xlsx`에 수량을 주입하여 수량집계표 → 착공내역서 → 총괄내역서 → 공사원가계산서로 연결되는 수식 파이프라인이 문서상 검증되어 있다.
+3. 향후 `unit_price_master` 성격의 연도별 표준품셈·노임단가·자재단가 관리가 필요하다고 기록되어 있다.
+4. 현재 `quantity_items`는 수량·단가·총액과 상세 JSON을 저장하는 수준이며, STmate의 공종 계층, 복합단가 구성, 가격 출처, 수식 버전, 계산 실행 이력을 완전히 표현하기에는 부족하다.
+5. B09 견적·문서 산출은 현재 셸 수준이며, `outputs`와 `output_files`도 산출 세션·파일 관리 중심이다.
+
+결론적으로 이번 STC·XLSX 분석은 기존 B08 템플릿과 방향이 일치한다. 다만 B08의 145개 고정 항목과 STmate 코드 체계를 직접 대응시키는 매핑표는 별도로 검증해야 한다.
+
+## 7. 웹앱 관리 방향
+
+### 7.1 관리 원칙
+
+Excel 파일을 장기적인 단일 진실 공급원(SSOT)으로 사용하지 않는 것이 적절하다.
+
+- DB: 원본 수량, 단가, 요율, 공식, 사용자 보정 및 계산 결과의 SSOT
+- 계산 엔진: 버전이 고정된 공식으로 재현 가능한 결과 생성
+- Excel: 호환성, 검토, 납품 및 STmate 교환용 산출물
+- STC: 원본 보존 및 비교 검증용 외부 시스템 파일
+
+Excel 수식에만 의존하면 수식 변경 이력, 사용자 수정, 동시 편집, 감사 추적 및 서버 재현성이 약해진다. 반대로 초기 단계부터 모든 Excel 수식을 자체 엔진으로 재작성하면 검증 범위가 지나치게 커진다. 따라서 단계적 전환이 적절하다.
+
+### 7.2 권장 데이터 영역
+
+다음 영역을 분리 관리하는 것이 필요하다.
+
+| 영역 | 관리 대상 |
+|---|---|
+| 원본 파일 | STC/XLSX 파일, 해시, 업로드자, 원본 버전 |
+| 프로젝트 기준 | 공사명, 위치, 연도, 공구, 적용 기준일 |
+| 공종 계층 | 공구 → 대공종 → 중공종 → 세부 내역 |
+| 품목 마스터 | 재료·노무·장비·경비 코드, 명칭, 규격, 단위 |
+| 가격 마스터 | 가격 출처, 기준일, 지역, 단가, 유효기간 |
+| 단가 구성 | 일위대가·중기사용료·단가산출근거 구성품과 투입량 |
+| 수량 | 설계수량, 사용자 보정수량, 확정수량, 산출근거 |
+| 요율·공식 | 보험료·일반관리비·이윤 등 계산식과 조건 |
+| 계산 실행 | 입력 스냅샷, 엔진 버전, 결과, 오류, 실행자 |
+| 사용자 보정 | 원값, 변경값, 변경 사유, 변경자, 승인 상태 |
+| 산출물 | XLSX/PDF/STC 호환 파일, 버전, 생성 시각 |
+| 검증 결과 | STmate/Excel 기준값과 웹앱 계산값의 차이 |
+
+### 7.3 필수 버전 관리
+
+다음 항목은 덮어쓰지 않고 버전 또는 유효기간 단위로 관리해야 한다.
+
+- 표준품셈
+- 노임단가
+- 자재단가
+- 장비단가
+- 환율
+- 제경비 요율
+- 계산 공식
+- Excel 출력 템플릿
+- STmate 코드 매핑
+
+프로젝트 계산 시 사용한 버전을 계산 실행 스냅샷에 고정해야 과거 견적을 동일하게 재현할 수 있다.
+
+### 7.4 권장 계산 구조
+
+계산식을 DB 문자열 하나로만 저장하거나 Python/TypeScript 코드에 직접 흩어 놓는 방식은 피하는 것이 좋다. 다음 요소를 분리한 규칙 모델이 필요하다.
+
+- 공식 식별자와 버전
+- 입력 변수
+- 적용 조건
+- 계산식
+- 반올림·절사 단위와 시점
+- 상한·하한
+- 포함·제외 대상
+- 출력 비용 분류
+- 법령·기준 출처
+- 유효기간
+
+동일 입력과 동일 규칙 버전이면 항상 동일 결과가 나오는 결정적 계산이어야 한다.
+
+### 7.5 단계적 구현 방향
+
+#### 1단계: 원본 보존과 대조
+
+- STC/XLSX 원본 및 SHA-256 해시 저장
+- 파일 내부 메타데이터와 프로젝트 정보 추출
+- 주요 총액과 공종 계층 대조
+- 파싱하지 못한 필드는 원문 바이트 또는 원본 파일로 보존
+
+#### 2단계: 정규화된 기준 모델
+
+- 공종 계층, 품목, 수량, 단가, 비용 분해를 DB로 정규화
+- STmate 코드와 B08 템플릿 ID의 매핑 테이블 작성
+- 외부 코드와 내부 안정 ID를 분리
+
+#### 3단계: 계산 규칙 재현
+
+- 샘플 Excel 수식을 계산 규칙 테스트 케이스로 전환
+- 직접공사비부터 제경비까지 단계별 결과 비교
+- 각 단계에서 오차 0원 또는 명시된 허용오차를 만족해야 다음 단계로 진행
+
+#### 4단계: 산출물 생성
+
+- DB 계산 결과를 Excel 템플릿에 기록
+- Excel, PDF 등 산출물 버전 관리
+- 필요할 경우 STmate 재등록 호환성은 별도 기능으로 검증
+
+## 8. 누락정보 및 우선순위
+
+### 8.1 구현 착수 전 필수(P0)
+
+| 누락정보 | 필요한 이유 |
+|---|---|
+| STmate 필드·코드 사전 | DBF 필드와 코드값을 업무 의미로 안정적으로 변환 |
+| 단계별 반올림·절사 규칙 | 1원 단위 차이가 상위 집계에서 확대되는 문제 방지 |
+| 제경비 공식 원문과 적용 조건 | Excel 표시식만으로 조건·상한·예외를 확정할 수 없음 |
+| 가격 출처별 적용단가 결정 규칙 | 조달·물가정보·물가자료·견적 중 무엇을 언제 선택하는지 필요 |
+| B08 145개 항목 ↔ STmate 코드 ↔ Excel 셀 매핑 | 기존 수량 결과와 견적 엔진 연결에 필수 |
+| 동일 프로젝트의 입력 전·후 샘플 | 한 변수 변경 시 어떤 테이블·수식·결과가 바뀌는지 확인 |
+| 최소 3개 이상의 추가 프로젝트 | 현재 한 사례에만 맞는 규칙으로 고착되는 것을 방지 |
+
+### 8.2 정확도 향상을 위해 필요(P1)
+
+- STmate 사용자 매뉴얼 또는 데이터 내보내기 명세
+- 연도별 표준품셈과 노임단가 원본
+- 자재단가 가격 출처 원본과 적용 기준일
+- 관급·사급, 도급·제외금액 구분 규칙
+- 일위대가 및 단가산출근거의 수량 산식 원문
+- `.SMT` 메모 필드 구조
+- `BDQTY.DBF` 난독화 또는 변환 규칙
+- 변경설계, 당초·변경 대비 자료
+- 0원 항목, 음수 항목, 부산물 공제, 할증·보정 사례
+
+### 8.3 운영 설계에 필요(P2)
+
+- 단가 및 공식 변경 승인 권한
+- 견적 확정·재계산·폐기 상태 정의
+- 사용자 수동 보정 허용 범위
+- 감사로그 보존기간
+- 산출물 버전 및 다운로드 정책
+- STmate 포맷 사용·역공학·재배포에 관한 라이선스 확인
+
+## 9. 추가로 확보할 권장 샘플 세트
+
+효율적인 역분석을 위해 무작위로 많은 파일을 모으기보다, 한 항목씩 변경한 비교 파일을 확보하는 것이 좋다.
+
+1. 빈 신규 프로젝트 STC/XLSX
+2. 재료 한 항목만 추가한 파일
+3. 수량 하나만 변경한 전·후 파일
+4. 단가 하나만 변경한 전·후 파일
+5. 간접노무비 또는 보험료율 하나만 변경한 전·후 파일
+6. 관급자재 포함/미포함 비교 파일
+7. 1공구와 다공구 비교 파일
+8. 당초설계와 변경설계 비교 파일
+9. 서로 다른 STmate 버전에서 저장한 동일 프로젝트
+10. 연도가 다른 동일 유형 사업
+
+이 비교 세트가 있으면 DBF 필드 변화, Excel 셀 변화 및 최종 금액 영향을 차분 분석하여 필드 의미와 계산 규칙을 훨씬 정확하게 확정할 수 있다.
+
+## 10. 검증 기준 제안
+
+향후 코드 작업에서는 다음 기준을 통과해야 한다.
+
+1. 프로젝트명·공구·공종 계층이 기준 파일과 일치한다.
+2. 모든 세부 내역의 코드·명칭·규격·단위·수량이 일치한다.
+3. 재료비·노무비·경비 단가와 금액이 단계별로 일치한다.
+4. 일위대가와 단가산출근거의 구성 합계가 일치한다.
+5. 직접공사비 710,359,136원이 정확히 재현된다.
+6. 제경비 계산 후 총공사비 1,201,879,000원이 정확히 재현된다.
+7. 계산 실행에 사용한 단가·요율·공식 버전을 조회할 수 있다.
+8. 사용자 보정 전후 값과 사유를 감사할 수 있다.
+9. 동일 입력과 동일 버전으로 재계산하면 동일 결과가 나온다.
+10. 생성된 Excel이 기준 템플릿의 시트명·수식·숨김 메타데이터를 훼손하지 않는다.
+
+## 11. 최종 결론
+
+두 파일은 Aislo의 B08 수량산출과 B09 견적·문서 기능을 설계하기 위한 가치가 높은 기준 자료이다. 데이터 계층, 비용 분해, 주요 수식 흐름 및 최종 금액은 상당 부분 추출 가능하며 웹앱 적용도 가능하다.
+
+다만 현재 자료 한 쌍만으로 STmate 전체 계산 엔진을 완전하게 재현했다고 판단할 수는 없다. 특히 코드 사전, 단계별 절사 규칙, 가격 적용 정책, 제경비 조건, 난독화 테이블 및 다양한 프로젝트 사례가 누락되어 있다.
+
+다음 코드 작업의 가장 안전한 출발점은 **STC 복제 구현**이 아니라 다음 세 가지이다.
+
+1. 원본 파일과 계산 근거를 손실 없이 보존하는 가져오기 계층
+2. 공종·품목·수량·단가·요율·공식의 버전형 기준 모델
+3. 기준 STC/XLSX와 단계별 금액을 자동 대조하는 회귀 검증 체계
+
+이 세 가지가 먼저 확립되면 Excel 의존도를 단계적으로 줄이면서도 기존 결과와의 정합성을 유지할 수 있다.