eomsangdon/Aislo
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

auto: 2026-08-14 18:31 (EOMSANGDON-HOME)

Browse Source
This commit is contained in:
eomsangdon
2026-08-14 18:31:31 +09:00
parent 6b81bd4c2a
commit 537b8629e3
1 changed files with 0 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files
resources/knowledge/2026-07-25_verify_stmate_stc_xlsx_webapp_feasibility.md
-346
View File
@@ -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 의존도를 단계적으로 줄이면서도 기존 결과와의 정합성을 유지할 수 있다.