From 855bac10295e5ee21f608eba1c17f60c8117b2a9 Mon Sep 17 00:00:00 2001 From: umsangdon Date: Wed, 12 Aug 2026 19:45:00 +0900 Subject: [PATCH] =?UTF-8?q?docs(knowledge):=20STmate=20STC/XLSX=20?= =?UTF-8?q?=EC=9B=B9=EC=95=B1=20=EC=A0=81=EC=9A=A9=EC=84=B1=20=EA=B2=80?= =?UTF-8?q?=EC=A6=9D=EB=B3=B4=EA=B3=A0=EC=84=9C=20=EC=9D=B4=EA=B4=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/raw에서 resources/knowledge 루트로 이동 (docs/raw는 git 미추적이라 추가로만 기록) - 2026-07-25자 PARTIAL PASS 보고서: STC 구조, 금액 대조, P0 누락정보, 웹앱 관리 방향 Co-Authored-By: Claude Fable 5 --- ...rify_stmate_stc_xlsx_webapp_feasibility.md | 346 ++++++++++++++++++ 1 file changed, 346 insertions(+) create mode 100644 resources/knowledge/2026-07-25_verify_stmate_stc_xlsx_webapp_feasibility.md diff --git a/resources/knowledge/2026-07-25_verify_stmate_stc_xlsx_webapp_feasibility.md b/resources/knowledge/2026-07-25_verify_stmate_stc_xlsx_webapp_feasibility.md new file mode 100644 index 00000000..2ad45817 --- /dev/null +++ b/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 의존도를 단계적으로 줄이면서도 기존 결과와의 정합성을 유지할 수 있다.