kimminsung/dwg-dxf-viewer-sample
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README.md 업데이트

Browse Source
This commit is contained in:
lectom
2026-07-29 10:45:03 +09:00
parent 41a94cc181
commit 110bd59118
1 changed files with 116 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+116 -12
View File
@@ -7,6 +7,77 @@ Three.js 기반 npm workspace입니다.
좌표, 단위, 원점, 형상 허용오차, topology와 CAD/BIM 의미 정보의 보존을
보장하는 운영용 engineering viewer로는 아직 검증되지 않았습니다.
## 개발 스택 및 구성 정책
이 저장소의 표준 개발 대상은 **Linux x86_64 container**입니다. Windows host에서는
Docker Desktop 또는 WSL2를 container runtime 진입점으로만 사용하며, Windows drive
path와 host의 `node_modules`를 표준 build 입력으로 사용하지 않습니다.
| 구분 | 표준 stack | 구성 정책 |
|---|---|---|
| Host·container | Linux x86_64, glibc 기반 image | Chrome과 native npm package 호환성이 확인될 때까지 Debian/Ubuntu 계열을 기준으로 하며 Alpine/musl은 별도 검증 없이 사용하지 않음 |
| JavaScript runtime | Node.js 24 이상, npm 11 이상 | `package.json#engines`가 지원 하한이며 container와 CI에서는 24.x·11.x의 exact version 및 base image digest를 고정 |
| Package 관리 | npm workspaces, `package-lock.json` | clean environment는 `npm ci`만 사용하고 lockfile을 canonical dependency graph로 취급하며 host `node_modules`를 container에 mount하지 않음 |
| Application | Vite 8, TypeScript 7, Three.js r185 | `apps/*`는 실행 application, `packages/*`는 workspace 내부 module로 유지하며 browser runtime asset은 Vite `BASE_URL`을 따름 |
| Unit·contract test | Vitest 4 | root `tests/**/*.test.ts`를 기준으로 하고 변경 시 관련 test부터 실행한 뒤 전체 suite를 실행 |
| Browser E2E | Playwright 1.62, system Chrome/Chromium | browser binary와 Linux system library를 E2E image에 고정하고 `PLAYWRIGHT_CHROMIUM_EXECUTABLE`로 경로를 주입 |
| Runtime decoder | acadrust DWG WASM, Draco, Basis, web-ifc | `npm ci`의 `postinstall`로 설치 dependency와 version이 맞는 artifact를 staging하며 수동 복사를 canonical 절차로 사용하지 않음 |
| Optional asset tool | Puppeteer Core, ffmpeg, Blender, `toktx` | application build의 필수 dependency가 아니며 별도 asset-tool image/profile과 별도 license BOM으로 격리 |
공통 구성 원칙은 다음과 같습니다.
- tracked text file과 shell script는 LF를 사용하고 canonical command는 POSIX shell
문법과 repository-relative path로 작성합니다.
- development, production build, E2E, optional asset processing은 서로 다른
container target 또는 profile로 분리합니다. production artifact에 compiler,
browser, fixture와 asset tool을 포함하지 않습니다.
- container process는 non-root user로 실행하고 source는 read-only mount를
우선합니다. dependency cache와 build output만 별도 writable volume을 사용합니다.
- host에서 직접 실행할 때 Vite는 loopback에만 bind합니다. container에서 port를
publish할 때만 container 전용 설정으로 `0.0.0.0`에 bind하고 공개 network에
노출하지 않습니다.
- Node.js, npm, Chrome/Chromium과 base image는 floating tag가 아니라 exact
version으로 고정합니다. Renovate 같은 자동 갱신을 사용하더라도 `npm run verify`
통과 후에만 lock과 image pin을 갱신합니다.
- source build/test image와 외부 배포 artifact의 license·provenance gate는
동일하지 않습니다. 아래 `외부 의존성·라이선스 감사`의 `NO-GO` 항목을 container
전환만으로 해소된 것으로 간주하지 않습니다.
## Linux 컨테이너 전환 검증
2026-07-29 기준 installed dependency 상태에서 typecheck, unit test 6개와 production
build는 Linux/WSL2 x86_64에서 다시 통과했습니다. 기존 검증 기록의 Playwright E2E
16개 통과 결과는 있으나 이번 문서 변경에 대한 E2E 재실행은 요청에 따라 뒤로
미뤘습니다. tracked text file은 LF이며 lockfile에는 Linux glibc와 musl용 native
optional package가 포함되어 있습니다. 따라서 application code를 Windows 전용
구현에서 이식하는 작업은 거의 끝났지만, clean `npm ci`부터 시작하는 재현 가능한
container 개발 환경의 정의와 현재 E2E 재검증은 아직 완료되지 않았습니다.
| 항목 | 현재 상태 | container 전환 판단 |
|---|---|---|
| Container 정의 | Dockerfile, `.dockerignore`, Compose/devcontainer 없음 | **Blocker** — 동일 image를 개발·CI에서 재현할 수 없음 |
| Dev server network | 2D·3D Vite가 `127.0.0.1`에 고정 | **Blocker** — container port publish 후 host에서 접근할 별도 bind 설정 필요 |
| E2E browser | `/usr/bin/google-chrome`을 기본 경로로 가정 | **Blocker** — Chrome/Chromium과 shared library를 image에 설치·고정해야 함 |
| Native ABI | Linux glibc/musl package가 lockfile에 모두 존재 | **Decision** — 우선 glibc를 baseline으로 고정하고 musl은 별도 test matrix로 검증 |
| Clean container gate | 현재 container CI 없음 | **Blocker** — clean `npm ci && npm run verify`를 release gate로 추가해야 함 |
| File·path 규칙 | tracked text는 LF, runtime code는 Node path API 사용 | 통과. 단, 하위 2D README의 Windows drive path는 정리 필요 |
| Offline asset pipeline | ffmpeg·Blender·`toktx`가 core lockfile 밖에 있음 | core 개발은 통과. asset-tool image와 version/license pin은 후속 작업 |
권장 구현 순서는 다음과 같습니다.
1. Node.js 24 기반 glibc image의 digest와 non-root user를 고정한 multi-stage
Dockerfile 및 `.dockerignore`를 추가합니다.
2. host loopback 기본값은 유지하고 container script에서만 2D `5173`, 3D `3333`
port를 `0.0.0.0`에 bind합니다.
3. Chrome/Chromium과 필요한 Linux library를 포함한 E2E target을 만들고
`PLAYWRIGHT_CHROMIUM_EXECUTABLE`을 명시합니다.
4. container 안에서 `npm ci`, `npm run verify`를 수행하는 CI job을 추가하고
host `node_modules`가 섞이지 않는지 확인합니다.
5. ffmpeg·Blender·`toktx`가 필요한 3D asset pipeline은 별도 image/profile로
분리하고 core application image에는 포함하지 않습니다.
6. `apps/viewer-2d-sample/README.md`의 standalone Windows layout과 실행 명령을
현재 npm workspace 및 Linux container 기준으로 갱신합니다.
## 검토 기준
| 항목 | 내용 |
@@ -14,15 +85,23 @@ Three.js 기반 npm workspace입니다.
| 기준일 | 2026-07-29 |
| 기준 commit | `cadbd5fb60d300dbb3fdc891fdbbabfbcd5b9109` |
| 기준 tree | 위 commit 이후 이 README 변경 포함 |
| 대상 | `cyhan/dwg-dxf-viewer-sample` |
| 대상 | `kimminsung/dwg-dxf-viewer-sample` |
| 참조 | 형제 저장소 `hmwebviewer/README.md`의 분석 구조와 3D asset provenance |
| 검토 범위 | workspace 구조, 2D/3D 기능, source·test·build 설정, 입력 경계, npm dependency, WASM·font·decoder·fixture license |
| 기능 판정 | **내부 개발·기능 검증 조건부 GO** |
| 기능 판정 | **내부 개발·기능 검증 정확도 및 품질 게이트 무시할 수 있으면 GO** |
| 외부 배포 판정 | **NO-GO — license·source 제공·asset provenance blocker 존재** |
외부 배포 판정은 기술적인 compliance 준비 상태를 뜻합니다. 법률 자문이 아니며,
실제 계약·특허·상표와 배포 승인은 조직의 법무·오픈소스 정책으로 확정해야 합니다.
## 현재 판정
운영 release에는 format별 정확도 contract, 3D 입력 제한·cancellation·Worker 격리,
프로젝트 license, MPL source 제공, third-party 고지와 sample provenance blocker가
남아 있습니다. 특히 “상업 사용 가능한 dependency”와 “현재 artifact를 조건 없이
상업 배포할 수 있음”은 같은 뜻이 아닙니다.
## Workspace 구성
| Workspace | 역할 | 주요 runtime |
@@ -223,6 +302,41 @@ MPL-2.0과 OFL-1.1 전문이 있습니다. 그러나 이 파일들은 두 Vite a
license가 포함되지 않습니다. `UNKNOWN` 3개처럼 보이는 lockfile entry는
`@hmwebviewer/*` first-party workspace link이며 제3자 license 누락이 아닙니다.
#### MPL-2.0 npm package 전체 목록
`package-lock.json`에서 `license: "MPL-2.0"`으로 선언된 13개 entry를 전부
나열하면 다음과 같습니다. 이는 **13개의 독립 codebase**를 의미하지 않습니다.
`web-ifc` 1개와, 동일한 Lightning CSS source에서 배포되는 core package 1개 및
platform별 optional native package 11개로 구성됩니다.
| npm package | Version | 설치·실행 범위 | 공식 source repository |
|---|---:|---|---|
| `web-ifc` | `0.0.77` | production runtime. IFC parser JS가 bundle되고 single-thread WASM이 application public asset으로 staging됨 | [ThatOpen/engine_web-ifc](https://github.com/ThatOpen/engine_web-ifc) |
| `lightningcss` | `1.33.0` | Vite build dependency. CSS parse·transform·minify core와 현재 platform용 native binding 선택 | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-android-arm64` | `1.33.0` | optional dev package, Android ARM64 native binding | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-darwin-arm64` | `1.33.0` | optional dev package, macOS ARM64 native binding | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-darwin-x64` | `1.33.0` | optional dev package, macOS x86_64 native binding | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-freebsd-x64` | `1.33.0` | optional dev package, FreeBSD x86_64 native binding | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-linux-arm-gnueabihf` | `1.33.0` | optional dev package, Linux ARM hard-float GNU native binding | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-linux-arm64-gnu` | `1.33.0` | optional dev package, Linux ARM64 glibc native binding | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-linux-arm64-musl` | `1.33.0` | optional dev package, Linux ARM64 musl native binding | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-linux-x64-gnu` | `1.33.0` | optional dev package, Linux x86_64 glibc native binding. 현재 표준 container 대상 | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-linux-x64-musl` | `1.33.0` | optional dev package, Linux x86_64 musl native binding | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-win32-arm64-msvc` | `1.33.0` | optional dev package, Windows ARM64 MSVC native binding | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
| `lightningcss-win32-x64-msvc` | `1.33.0` | optional dev package, Windows x86_64 MSVC native binding | [parcel-bundler/lightningcss v1.33.0](https://github.com/parcel-bundler/lightningcss/tree/v1.33.0) |
Lightning CSS의 12개 entry는 모두 동일한 MPL-2.0 source tree와 release version을
가리키지만 lockfile 및 SBOM에서는 서로 다른 배포 package로 유지합니다. 실제 install
시 npm은 host OS·CPU·libc와 맞는 optional binding만 선택합니다. 이 project의
production browser artifact에는 Lightning CSS code가 포함되지 않지만, build
container 또는 `node_modules`를 제3자에게 전달한다면 선택된 binding과 covered
source 제공 방법을 함께 관리해야 합니다.
`web-ifc@0.0.77` package가 선언한 공식 repository는 위 root URL이며 package
metadata에는 exact source commit(`gitHead`)이 없습니다. 따라서 외부 배포 전에
registry tarball과 대응하는 source commit/archive를 별도로 고정하고, 수정 여부와
covered source 취득 방법을 배포 고지에 기록해야 합니다.
### Build·test·offline 도구
| 구성요소 | lockfile 기준 | 역할 | License·배포 판단 |
@@ -413,13 +527,3 @@ engineering 정확도와 외부 배포 compliance를 승인하는 test는 아닙
하위 2D README에는 통합 전 standalone layout이, 3D tools README에는 과거 KTX2
계획이 남아 있습니다. 현재 workspace의 canonical 개요와 배포 판단은 이 문서를
기준으로 하며, 하위 문서는 후속 정합성 정리가 필요합니다.
## 현재 판정
2D와 3D sample의 주요 load path, lifecycle, decoder staging과 subpath 배포를
검증하는 자동화가 있습니다. 내부 기능 검증용 workspace로는 사용할 수 있습니다.
운영 release에는 format별 정확도 contract, 3D 입력 제한·cancellation·Worker 격리,
프로젝트 license, MPL source 제공, third-party 고지와 sample provenance blocker가
남아 있습니다. 특히 “상업 사용 가능한 dependency”와 “현재 artifact를 조건 없이
상업 배포할 수 있음”은 같은 뜻이 아닙니다.