README.md 업데이트
This commit is contained in:
@@ -7,77 +7,6 @@ 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 기준으로 갱신합니다.
|
||||
|
||||
## 검토 기준
|
||||
|
||||
| 항목 | 내용 |
|
||||
@@ -93,6 +22,7 @@ container 개발 환경의 정의와 현재 E2E 재검증은 아직 완료되지
|
||||
|
||||
외부 배포 판정은 기술적인 compliance 준비 상태를 뜻합니다. 법률 자문이 아니며,
|
||||
실제 계약·특허·상표와 배포 승인은 조직의 법무·오픈소스 정책으로 확정해야 합니다.
|
||||
업무용 프로젝트라기보다 취미용 개발 프로젝트에 가까운 성과물입니다.
|
||||
|
||||
## 현재 판정
|
||||
|
||||
@@ -439,6 +369,79 @@ commercial SaaS 배포를 승인하지 않습니다.
|
||||
- 미사용 `web-ifc-mt.wasm`과 중복 decoder artifact의 배포 필요성 결정
|
||||
- runtime/build/sample을 구분한 SBOM과 CI의 unknown-license/provenance gate
|
||||
|
||||
|
||||
## 개발 스택 및 구성 정책
|
||||
|
||||
이 저장소의 표준 개발 대상은 **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 기준으로 갱신합니다.
|
||||
|
||||
|
||||
## 설치와 실행
|
||||
|
||||
요구 환경은 Node.js 24 이상, npm 11 이상과 WebGL을 지원하는 browser입니다.
|
||||
|
||||
Reference in New Issue
Block a user