From 110bd59118f03c03297e431079b74e009c3ecf44 Mon Sep 17 00:00:00 2001 From: Lectom Date: Wed, 29 Jul 2026 10:45:03 +0900 Subject: [PATCH] =?UTF-8?q?README.md=20=EC=97=85=EB=8D=B0=EC=9D=B4?= =?UTF-8?q?=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 128 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 116 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 1f84dcc..9b34e01 100644 --- a/README.md +++ b/README.md @@ -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를 조건 없이 -상업 배포할 수 있음”은 같은 뜻이 아닙니다.