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 deleted file mode 100644 index 2ad45817..00000000 --- a/resources/knowledge/2026-07-25_verify_stmate_stc_xlsx_webapp_feasibility.md +++ /dev/null @@ -1,346 +0,0 @@ -# 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 의존도를 단계적으로 줄이면서도 기존 결과와의 정합성을 유지할 수 있다.