# STMATE w 8.0 테스트 앱 계획서 및 검증 아카이브

이 문서는 `tools/stmate-test/` 폴더 내 독립 웹앱의 개발 계획 및 검증 이력을 자체 보관·관리하는 문서입니다.

## 1. 개요 및 요구사항
- **목적**: 경쟁사 데스크톱 프로그램 STMATE(w 8.0, 경영정보(주))의 95% 이상 복제 수준 달성 및 독립 웹앱 구축
- **작업 경로**: `tools/stmate-test/`
- **구동 서버**: `http://127.0.0.1:8095` (FastAPI + DBF/SMT/STC/JB_R 직결 엔진)
- **외부 연동**: 로그인 및 공용 DB 의존 없음, 실무 프로젝트 DBF/SMT/STC 100% 무손실 연동

---

## 2. 세부 개발 및 검증 항목

- [x] **화면 및 메뉴 체계 복제 (TWM_STMATE_START_8X)**
  - 상단 5대 메뉴(`Act_PrjList`, `Act_Init`, `Act_BoqEdit`, `Act_KanJub`, `Act_KanRate`, `Act_StageEdit`, `Act_Print`)
  - 8버튼 메인 툴바 및 하단 순공사비·간접비·도급액·총공사비 집계바
  - 9개 메인 작업 화면:
    - `wPrjList`: 공사목록표 및 하단 `BOQ11.DBF` 미리보기
    - `wBoq`: 계층 내역서(`T1..T6`/`E1..E6`/`C*`), 공종번호 자동입력(`wITNum`), 내역할증(`wBoqRate`), 단수보정(`wM_Rate`), 일위풀기(`wExpnd`), 수량산출 연결(`wQtyList`), 내역보관함 (1)(2)(3)
    - `wM_Set_Sys`: 환경설정 (환율, ECD 소수위, 계산식, 환산식 `1/8*16/12*25/20`)
    - `wM_JabPum`: 단가목록표 (5대 가격지 비교 `wM_Boxa`, 기준단가 비율조정 `wM_Edt_Hal`, 표준 카탈로그 브라우저)
    - `wM_Edit_iLWi`: 일위대가·단가산출 수식 편집기 (`COSTN.SMT` 64B 블록 전개식, 표준 카탈로그 894코드·350레시피·21특수산식)
    - `wM_KanJub`: 제잡비 계산서 (4탭 `T/S/TA/SA`, 16대 콤보박스 및 이윤 끝전조정)
    - `wM_KAN_RATE`: 원가계산기준 제비율표 (`RATE_R/RA/M/B.DBF` 50×35 및 `ST_BSC/*.JB_R` 파일 직결)
    - `wStage`: 설계 후속 단계 (`wM_Mk_Cont` 계약내역, `wM_Boq_ExecX` 실행내역, `wM_KanJub_K` 기성내역, `REVISION` 설계변경 증감대비표)
    - `PM_Prt`: 30종 보고서 인쇄 미리보기 및 6시트 엑셀(`.xls`), 조달청 `<T3_C3B>` XML, JDL 내보내기

- [x] **100% 범용 `COSTN.SMT` 수식 인터프리터 (`smt_engine.js`)**
  - 봉화군 2024 `COSTN.SMT` 전수 65/65건(100%) 1원 오차 없이 일치 검증:
    - `;;` 헤더 변수 분리 파싱
    - `[A]`, `[D]'%'`, `N'%'` ($N \ge 1 \Rightarrow N \times 0.01$, $N < 1 \Rightarrow N$)
    - `&PA01:M&`, `&RA01:M&`, `&PS_M&`, `&RC_S:S&` 라벨·구간·누적 소계 처리
    - `&L00020&` 기구손료 인건비 누적소계 자동참조
    - `(-=)` 소계제외 블록, `(=)`/`(==)`/`(===)` 구간합산
    - 운반비(`운반`) 경비(`S`) 일괄 귀속 규칙

- [x] **5단 연쇄 재계산 엔진 (`cascadeRecalculateAll` / `[계산완료]`)**
  - 기초단가(`L*`/`M*`/`S*`) 변경 시 실시간 연쇄 전파:
    1. 중기사용료(`X*` 25/25건 100% 일치, 운전사 노임 좌→우 `1/8*16/12*25/20` 시간당 환산)
    2. 단가산출(`D*` 65/65건 100% 일치)
    3. 일위대가(`B*` 45/45건 100% 일치, 공구손료·잡품 `재료비의 %`/`노무비의 %` 구분)
    4. 내역서(`BOQ11.DBF` 141행)
    5. 원가계산서(`PRJLST.DBF/.SMT`)

- [x] **다중 슬롯 DBF 양방향 저장 (`/api/save`)**
  - 당초설계(`*1`), 설계변경(`*2`), 계약내역(`*3`) 멀티 슬롯 컬럼을 `COSTN.DBF`, `BOQ11.DBF`, `PRJLST.DBF`, `PRJLST.SMT`, `COSTN.SMT` 및 `.STC` 아카이브에 무손실 저장

- [x] **보고서 엑셀 내보내기 원본 STMATE 1:1 복제 (`excel_builder.py` + `/api/export-xlsx`)**
  - 원본 STMATE 엑셀 산출물 분석 기반 11개 시트 구성 및 네이티브 하이퍼링크/수식 구현:
    - `〓 목 차 〓`: 전 시트 바로가기 `=HYPERLINK("#'시트명'!A1", "시트명 →")` 수식 적용
    - 전 시트 상단 우측: 목차 복귀 `=HYPERLINK("#'〓 목 차 〓'!B2", "목차 →")` 수식 적용
    - `설계내역서` ↔ `단가산출근거목록표` / `일위대가목록표` 간 셀 참조 수식 및 `=ROUNDDOWN(수량*단가, 0)` 수식화
    - 원가계산서 비목별 연동 수식 및 11개 시트 스타일링 (헤더 폰트, 테두리, 열 너비 자동 조정)
    - 백엔드 생성기(`excel_builder.py`, 452줄) + 서버 엔드포인트(`server.py`, 630줄) + UI 연동(`app.js`, 689줄)
    - 전 파일 700줄 제한 엄격 준수 및 ruff/prettier 포맷팅 적용

---

## 3. 검증 결과 기록

### 자체 검증 (2026-11-05)
- **700줄 제한 및 포맷터**: 소스코드 10개 파일 전체 700줄 이하 준수 및 ruff/prettier 포맷 완료.
- **브라우저 결함 수정 5건**:
  1. `wBoq` 상단 헤더 관급자재 합계(`govMatTotal: govRawTotal`) 누락 수정 (`143,554,309원` 표시)
  2. `wM_KanJub` 및 `PM_Prt` 산정기초 금액 열(`base: baseAmt`) 표시
  3. `wStage` 설계변경 증감대비표 런타임 에러 수정
  4. `wM_Edit_iLWi` `D00016` 굴삭기 $Q$ 산식 중간 변수 반올림($f=0.85 \rightarrow Q=22.85$) 적용으로 DB 단가(`3,825원`) 일치
  5. `wExpnd` 모달 내역서 전개 삽입 연동

### 자체 검증 (2026-11-07 · 95%+ 완전 복제 고도화)
- **Playwright 브라우저 엔진 전수 검증 통과 (`verify_95_fidelity.py`)**:
  - `COSTN.SMT` 65/65건 100% 일치
  - 중기사용료 `X*` 25/25건 100% 일치
  - 단가산출 `D*` 65/65건 100% 일치
  - 일위대가 `B*` 45/45건 100% 일치
  - 봉화군 2024 산림유역관리사업 기준:
    - 직접공사비(`TCOST1`): `781,283,415원`
    - 도급액(`FINAL_SUPPLY`): `1,270,728,000원`
    - 관급자재대: `143,555,000원`
    - 총공사비(`COSTW1`): `1,414,283,000원` (1원 오차 없이 100% 일치)
  - 동적 연쇄 전파 확인: 경유 `M00018` +100원 인상 시 `X00006` `65,015`→`65,627`원, `D00016` `3,825`→`3,878`원, 총공사비 `1,414,283,000`→`1,423,700,000`원 정상 반영
  - 6시트 엑셀 워크북(`237,840`바이트) 및 조달청 XML(`52,252`바이트) 정상 생성
  - 9개 화면 전 과정 콘솔/페이지 런타임 에러 `0건`

### 자체 검증 (2026-11-07 · 엑셀 원본 STMATE 1:1 하이퍼링크/수식 고도화)
- **11개 시트 엑셀 내보내기 검증 완료**:
  - `〓 목 차 〓`, `공사원가계산서`, `단가산출근거목록표`, `일위대가목록표`, `설계내역서`, `중기사용료`, `단가산출근거`, `일위대가표`, `재료비목록표`, `노무비목록표`, `경비목록표` 총 11개 시트 정상 생성.
  - 목차의 각 항목별 바로가기 `=HYPERLINK("#'시트명'!A1", "시트명 →")` 및 세부 시트의 목차 복귀 `=HYPERLINK("#'〓 목 차 〓'!B2", "목차 →")` 네이티브 엑셀 하이퍼링크 수식 동작 확인.
  - 내역서 단가 참조 수식(`=단가산출근거목록표!F{row}`, `=일위대가목록표!F{row}`) 및 산출금액 내림 함수(`=ROUNDDOWN(...)`) 정상 반영.
  - 서버 상시 구동 상태에서 `POST /api/export-xlsx` 엔드포인트 200 OK 응답 확인.
  - 전체 소스코드 파일 700줄 이하 준수 (excel_builder.py: 452줄, server.py: 630줄, app.js: 689줄 등) 및 포맷터 완료.