Pier_v1/RAG/design-model-box-sample_2/README.md

# Drawing Model Studio

도면 업로드 → 콘크리트 형상 확인 → 철근 생성·검토를 제공하는 웹 프로그램입니다.
`design-model-box-sample`과 같은 프런트/백엔드 분리 구조를 사용하되, 분석·생성 기능은 이 저장소의 코드를 유지합니다.

## 구성

```text
src/
  frontend/
    index.html                # 페이지
    dxf_rasterizer.html        # 도면 미리보기
    src/                      # 화면·모델 커널 JS, CSS
  backend/
    serve.py                  # 권장 진입점 (8097)
    server.py, server_8097.py  # 업로드·분석·작업 API
    cad_*.py, drawing_*.py, local_*.py  # 연결된 도면/배근 로직
    *.json, *_RULES.md         # 실제 런타임에서 읽는 스키마·규칙·자료
    _legacy/                  # 기존 어댑터의 필수 호환 실행 파일
    pyproject.toml
    requirements.txt
Dockerfile, compose.yaml, Makefile
.runtime-data/                # 실행 후 생성, Git 제외
```

테스트 코드·진단 도구·보고서·샘플/실험 저장본·원본 CAD·인증 파일은 배포에 포함하지 않습니다. **클론하면 빈 작업 페이지가 열립니다.** 도면을 업로드하거나 페이지의 `작업 JSON 불러오기`로 별도 전달받은 작업 파일을 여세요. 서버 내부 작업 JSON과 UI 내보내기 JSON은 다른 형식입니다.

## 실행 (Linux / WSL2)

검증 Python 버전: **3.14.4**, 지원 범위: **3.14.x**. 런타임은 표준 라이브러리를 사용하며 pip 패키지 설치·Node 빌드가 필요하지 않습니다. `SIGUSR1`을 사용하는 기존 진입점 때문에 Windows native 대신 WSL2를 사용합니다.

```bash
git clone https://gitea.hmac.kr/is-div/design-model-box-sample_2.git
cd design-model-box-sample_2
python3.14 -m venv .venv
. .venv/bin/activate
python src/backend/serve.py
```

접속: **http://localhost:8097/**. 종료: `Ctrl+C`.

다른 포트·저장 폴더:

```bash
DMS_DATA_DIR=/원하는/영구저장폴더 python src/backend/serve.py --port 8098
```

기본 저장 위치는 저장소의 `.runtime-data/`입니다. 다른 클론·기존 서버의 `/tmp` 저장본을 바꾸지 않습니다. `src/backend/server.py` 직접 실행은 과거8095 진입점이므로 권장하지 않습니다.

## Docker

```bash
docker compose up --build
# 종료 (작업 데이터 볼륨 유지)
docker compose down
```

호스트에는 `127.0.0.1:8097`만 공개하고, 작업 데이터는 `studio-data` 볼륨에 영구 저장합니다. `docker compose down -v`는 데이터를 삭제하므로 사용하지 마세요.

## 도면·분석 준비

- **DXF:** 로컬 파서 사용.
- **DWG:** LibreDWG `dwg2dxf`를 별도 설치해 `PATH` 또는 `DMS_DWG2DXF=/절대경로/dwg2dxf`로 지정합니다. 변환기는 저장소/Docker 이미지에 포함하지 않았습니다. 없으면 DXF로 입력하세요.
- **외부 분석:** 별도 서비스 인증과 도면 전송 승인이 필요합니다. 인증 정보는 저장소에 넣지 마세요. 저장 작업을 보는 데 외부 분석 인증은 필요하지 않습니다.
- **보안:** 작성 서버는 기본 localhost 전용입니다. 사내 공유에는 아래 인증 게이트웨이 또는 열람 전용 서버를 사용하세요. 인증 게이트웨이 사용자는 연결된 서버의 분석 계정과 작업 저장소를 공유합니다.

## 캐시와 작업 단계

- 도면명과 원본 SHA-256이 도면 묶음 전체에서 일치하면 저장 모델을 재사용합니다. 같은 이름의 다른 내용은 재사용하지 않습니다.
- 사내 HTTP 주소에서 브라우저 SHA-256 기능을 사용할 수 없으면 원본 바이트를 서버에서 해시하여 동일하게 대조합니다. 이 조회 자체는 도면 분석을 실행하지 않습니다.
- 먼저 **콘크리트 외관만** 표시하고, 형상 확인 후 **철근 버튼**을 누르면 저장된 철근을 재분석 없이 표시합니다. 철근이 없는 캐시는 일반 철근 생성으로 진행합니다.
- 저장된 형상·철근·미완료 검토 상태는 변경하지 않습니다. 주황색 접속슬래브 종방향 설치선은 경사 대조 후 표시하는 미완성 검토선이며, 제작 길이 불일치를 유지하고 OBJ 철근에서는 제외합니다.

## 회사 내부 비밀번호 인증 실행 (선택)

작성 서버를 실행한 상태에서, 별도 터미널에서 저장소 최상위 기준으로 실행합니다.

```bash
python tools/set_company_password.py
python src/backend/company_access_server.py --port 18097 --upstream-port 8097 --auth-file .runtime-data/company-auth.json
```

비밀번호는 터미널에서 숨김 입력하며 기본 비밀번호는 없습니다. 실제 비밀번호·해시 파일·세션은 Git에 포함하지 않습니다. 해시 파일은 로컬에 권한 600으로 생성됩니다. 클론한 환경마다 별도로 설정해야 합니다. 비밀번호 변경 시 `--auth-file`로 `.runtime-data/` 안의 새 파일을 생성한 뒤 해당 파일로 게이트웨이를 재시작하세요. 재시작하면 기존 로그인 세션도 만료됩니다.

인증 후 도면 업로드·분석·철근 생성과 기존 캐시 조회를 사용할 수 있습니다. 작성 서버로 요청을 전달하므로 별도 모델 저장소를 만들지 않습니다. 로그인은 8시간 유효하며 로그아웃 버튼과 반복 인증 시도 제한을 제공합니다.

**현재 HTTP 연결은 비밀번호와 도면 전송을 암호화하지 않습니다.** 승인된 사내망으로 접속을 제한하고, 기밀 전송에는 별도 HTTPS 구성이 필요합니다. HTTPS 종료 프록시 연결은 이 실행 설정에 포함하지 않습니다.

### 열람 전용 대안

작성 서버를 먼저 실행해 저장 폴더를 만든 뒤 별도 터미널에서 실행합니다.

```bash
python src/backend/company_view_server.py --port 18097
```

동일한 `DMS_DATA_DIR`을 지정하거나 `--job-root`로 저장 작업 폴더를 선택할 수 있습니다. 이 서버는 원본 업로드·분석 세션·요청 본문을 공개하지 않으며 조회로 분석 작업을 재개하지 않습니다. 클론에 모델 데이터는 포함되지 않습니다.

인증 실행 모드와 열람 전용 모드는 같은 18097 포트에 동시에 실행하지 않습니다.

### 사내 포트 전달

WSL에서 사내 Windows 주소의 8097을 선택한 공유 서버 18097로 전달하려면, 네트워크 공개 승인을 받은 뒤 **관리자 PowerShell**에서 실행하세요.

```powershell
.\tools\setup_windows_port_8097.ps1 -ListenAddress <이-PC의-사내-10.x-IPv4> -WslAddress <현재-WSL-172.x-IPv4>
```

스크립트는 지정한 회사 IP의 TCP 8097만 전달하고 `10.0.0.0/8` 인바운드를 지속 허용합니다. 기존 8094는 변경하지 않습니다. 회사 주소 또는 WSL 주소가 바뀌면 다시 설정해야 하며, 선택한 공유 서버와 WSL이 실행 중이어야 접속할 수 있습니다. 공유 주소는 `http://<회사-IP>:8097/?job=<작업-ID>`입니다. 자동 시작·자동 배포는 포함하지 않습니다.

## 모델 흐름과 보고서

- [도면 → 객체 → 철근 → 보고서 ERD](docs/DRAWING_TO_MODEL_ERD.md)
- [전체 흐름 PNG](docs/DRAWING_TO_MODEL_FLOW.png) · [확대·편집용 SVG](docs/DRAWING_TO_MODEL_FLOW.svg)
- 보고서의 모델 정보 탭에서 전체 콘크리트 합집합 밖의 철근 구간을 빨간 선·점으로 표시합니다. PDF에는 객체별 이미지와 위치·철근명을 포함합니다.
- 작업 JSON은 모델과 보고서 검사 결과를 함께 저장합니다. 모델·각도가 바뀌면 저장 검사를 재사용하지 않습니다.
- 부재 생성 오류는 해당 범위의 실패로 기록하고 독립적인 후속 부재 생성을 계속합니다. 부분 결과와 기존 모델은 보존하며, 미연결 항목을 통과로 바꾸지 않습니다. 원본 자체 접근 실패·사용자 취소·자원 부족 등 작업 공통 장애까지 계속할 수 있다는 뜻은 아닙니다.

## 현재 제한

### 2026-09-14 코드 확인

- 단면 리더·슬래브 단부 배근선·벽체 입면 경사를 원본 근거로 연결하는 공통 경로를 반영했습니다.
- 로컬 전체 회귀검사: **1,039건 통과, 실패·오류·건너뜀 0건**. 배포 폴더의 서버 시작과 주요 페이지/API 응답도 별도 확인했습니다.
- [연결 수정 범위](docs/REMAINING_FACE_BINDINGS_20260914.md) · [회귀검사 구성 수정](docs/REGRESSION_NO_SKIPS_20260914.md)
- 위 문서의 검사·부분 반영 명령은 원본을 보유한 로컬 검증 작업공간용입니다. 배포 저장소에는 원본 CAD, 검사 전용 자료·테스트, 모델 부분 교체 진단 도구를 포함하지 않습니다.
- 테스트 통과가 모든 새 도면의 전체 설계 검증 완료를 뜻하지는 않습니다.

- 원본 없는 `verified_box_cycle_adapter.cpython-314.pyc`는 `_legacy/`에 명시적으로 보존했습니다. 일반 캐시가 아닌 기존 실행 의존성이므로 삭제하면 안 됩니다. 원본 소스 복구·완전 대체는 미완료입니다. 8097의 주 배근 경로는 공통 소스 생성기를 사용하지만 과거 어댑터 참조도 남아 있습니다.
- `FINAL_rebar_model_formula_spec.json`에는 과거 측면 길이 비율과 중심선 설명의 불일치가 남아 있습니다. 이번 폴더 정리를 이유로 계산식을 바꾸지 않았습니다.
- 모든 임의 도면의 전체 철근 자동 완성을 보장하지 않습니다. 상세·피복·수량 미연결 및 검증 경고를 확인해야 합니다. 저장 모델 표시와 도면에서의 재생성 검증은 다릅니다.
- 최신 BR3는 사용자 승인 검토용 중앙 배치 정책을 포함합니다. 계산 여유는 도면 피복의 검증 완료를 뜻하지 않습니다.

이번 배포는 실행 코드·폴더 정리입니다. 기존 모델 보존과 실행 검사는 배포 밖의 로컬 자료로 수행하며, 전체 설계 검증 완료를 의미하지 않습니다.


task : B단계 작업 착수해줘
-Prism 시각 디자인 적용 시점: B단계에서 새로 만드는 화면(요약 띠, 근거표)부터 Prism으로 만들고 기존 화면 교체는 D단계에서 하는 것으로 해줘