a985e62254
All checks were successful
Publish ParaWiki / build-and-deploy (push) Successful in 30s
## Output/guides/cimery-dev-guide.md
- related-adr 에 ADR-004 추가, updated 2026-04-15.
- 권위 순서: ADR-004 삽입.
- 아키텍처 파이프라인 다이어그램: salsa(Sprint 24), USD(21), IFC4X3(33~36)
구현 스프린트 표기.
- Feature 카탈로그 실제 구현 현황 반영:
Must v1: 다경간·PSC-I/SteelBox·T형/π형 피어 전부 완료.
Should v1.1: Diaphragm·Haunch·Skew·Camber·Variable Depth 구현 완료.
- 구현 우선순위: "수직 관통 완료" 현황 추가.
## cimery/CLAUDE.md
- 크레이트 구조 Sprint 39 현황으로 재작성:
· ifc/ 신규 (Sprint 33~36)
· macros/ 신규 (Sprint 38)
· app/ (Sprint 23)
· 의존 방향 업데이트: core → ir → {dsl, kernel, usd, ifc}
- 업그레이드 경로 표: 5개 축(incremental/kernel/viewer/dsl/ifc) 의
현재·다음 단계 표.
- 참조 ADR 목록에 ADR-004 추가.
## wiki/log.md
- ADR-004 entry 추가 (2026-04-15).
PROGRESS.md 는 이전 커밋에서 반영 완료.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
124 lines
6.8 KiB
Markdown
124 lines
6.8 KiB
Markdown
---
|
|
title: cimery 개발 지침
|
|
updated: 2026-04-15
|
|
related-adr:
|
|
- "[[ADR-001-tech-stack]]"
|
|
- "[[ADR-002-feature-dsl]]"
|
|
- "[[ADR-003-architecture-followups]]"
|
|
- "[[ADR-004-sprint-25-39-decisions]]"
|
|
---
|
|
|
|
# cimery 개발 지침
|
|
|
|
cimery 관련 작업 시 먼저 읽는 문서. CLAUDE.md에서 링크된다.
|
|
|
|
## 권위 순서 (Source of Truth)
|
|
1. `Output/reports/ADR-001-tech-stack.md` — 기술 스택
|
|
2. `Output/reports/ADR-002-feature-dsl.md` — Feature DSL 아키텍처
|
|
3. `Output/reports/ADR-003-architecture-followups.md` — UI·IFC·CI/CD·USD·Plugin·Feature 카탈로그·LOD·UX 등
|
|
4. `Output/reports/ADR-004-sprint-25-39-decisions.md` — 거더교 MVP 확장·IFC4X3 Add2·proc-macro 스캐폴딩 15결정
|
|
5. 본 문서 — 지침 요약·규약
|
|
6. `~/.claude/.../memory/` — 개인 선호·작업 방식
|
|
|
|
ADR과 본 문서가 충돌하면 **ADR 우선**. ADR 개정은 새 ADR로 수행 (`status: superseded-by:`).
|
|
|
|
## 기술 스택 핵심
|
|
- **언어:** Rust (전 계층)
|
|
- **UI:** Leptos + `<canvas>` wgpu 3D 뷰포트 (Tauri v2 데스크톱 + PWA 웹 듀얼)
|
|
- **기하 커널:** OpenCascade.js(웹) / opencascade-rs(데스크톱), `GeomKernel` trait 추상화
|
|
- **렌더:** wgpu → WebGPU (MVP Chromium 기반만)
|
|
- **IFC:** 런타임 `ifc-lite-core`, 검증용 `IfcOpenShell`
|
|
- **증분 계산:** `salsa` crate (Feature 단위 query, 비싼 sub-step만 개별)
|
|
- **IR 직렬화:** JSON 선행 → MessagePack 승격
|
|
- **단위:** 자체 newtype (`Mm`, `M` 등), 경계 명시 변환
|
|
- **FEM:** 자체 솔루션 연계 (외부 의존 최소)
|
|
- **파일 구조:** 폴더 기반 플레인 텍스트, AI·diff 친화 최우선
|
|
|
|
## 아키텍처 파이프라인
|
|
```
|
|
Rust DSL (builder + macro_rules! 설탕)
|
|
└─ #[param(unit, range, default)] attribute 메타 ← 스캐폴딩(Sprint 38)
|
|
↓
|
|
IR (JSON/MessagePack, 결정론적 직렬화)
|
|
↓
|
|
salsa query (Feature 단위, Lazy/Reactive) — Sprint 24 구현
|
|
↓
|
|
Evaluator → GeomKernel trait
|
|
├─→ 자체 wgpu 뷰어 (egui 패널 + Ortho/Perspective)
|
|
├─→ USD export (Sprint 21)
|
|
└─→ IFC4X3 Add2 export (Sprint 33~36, Alignment+PSC-I+Pset_BeamCommon)
|
|
```
|
|
CSV 라운드트립(Sprint 7): 개발자 템플릿 → CSV export → 엔지니어 편집 → CSV import → DSL 소스 재생성.
|
|
|
|
## 코드 규약
|
|
- **단위 강제:** 구조물 `Mm`, 선형 `M`. 암묵 변환 금지. 경계 함수 시그니처에 명시.
|
|
- **Feature 파라미터 선언:** `#[param(unit="mm", range=10..=200, default=150)]` — AI 친화.
|
|
- **결정론:** 같은 IR → 같은 기하. 연산 순서 고정, 정렬된 입력만 통과. CI 1순위 테스트.
|
|
- **Feature 조합:** 2단 composite 허용, 공유 그래프 금지.
|
|
- **에러:** `Result<_, FeatureError>` + 경로 포함 메시지 (`girder_3.flange_thickness < web_thickness`).
|
|
- **검증:** 음수·단위 불일치는 타입 수준, 범위·상호제약은 런타임 `Result`.
|
|
- **테스트 4층 (MVP부터 필수):**
|
|
1. IR 스냅샷 (`insta`)
|
|
2. 기하 불변량 (부피·무게중심·바운딩박스·체크섬, 허용 오차)
|
|
3. 두 커널 cross-check (OpenCascade.js ↔ opencascade-rs)
|
|
4. `proptest` 속성 기반 (self-intersection 없음·부피 양수 등)
|
|
|
|
## Revit UX 호환
|
|
- 기본 마우스·키보드 조작, 리본·패널·속성창·뷰 큐브 = Revit 관습.
|
|
- 리본 12탭: Home·Alignment·Structure·Feature·Site&GIS·Annotate·Analyze·Construction·Insert·View·Manage·Modify.
|
|
- 2글자 keyin(VG·WT·ZE·SD) 보존 — **한글 IME 활성 시 입력 라우팅 주의.**
|
|
- 선택·필터: Category = **Feature kind**. cimery 고유 = 선형 기반 선택·규칙 선택·영향권 하이라이트.
|
|
- 개념 다른 영역은 "Revit Element ≠ cimery Feature instance"처럼 차이를 공식 문서화.
|
|
|
|
## Feature 카탈로그 (MVP 거더교) — Sprint 39 시점
|
|
- **Must (v1) — 구현 완료:** Girder(PSC-I·SteelBox) · Deck Slab · Pier(T형·π형) · Abutment · Bearing · Alignment(입력) · 다경간
|
|
- **Should (v1.1) — 구현 완료:** Cross Beam · Expansion Joint · Parapet · Diaphragm(격벽) · Haunch · Skew · Camber · Variable Depth
|
|
- **Could (v2):** Foundation · Approach Slab · Drainage · IfcPile
|
|
- **Won't (v3+):** 철근·사장교·현수교·아치·트러스
|
|
|
|
## 사용자 설정 (VS Code 3계층 모델)
|
|
```
|
|
~/.cimery/settings.json # User 전역
|
|
~/.cimery/keybindings.json # 키맵 분리
|
|
<project>/.cimery/settings.json # Project (Git 커밋)
|
|
<project>/.cimery/settings.local.json # 개인 override (.gitignore)
|
|
```
|
|
병합: Default ← User ← Project ← Project.local. 좌표계·tolerance는 **Project 전용 잠금.**
|
|
|
|
## 구현 우선순위 — 엔드-투-엔드 수직 슬라이스
|
|
**12개 ADR-003 결정을 동시 진행 금지.**
|
|
첫 **Girder 1개**로 전 계층(DSL → IR → salsa → evaluator → OCCT → wgpu → USD) **한 번 관통**한 뒤 수평 확장. 뷰어 한 달·DSL 한 달 식 수평 접근은 치명적.
|
|
|
|
**Sprint 1~39 현황:** 수직 관통 완료. Girder·Deck·Pier·Abutment·Bearing 전부 DSL→IR→kernel→viewer→USD+IFC 파이프라인 연결됨. ADR-004 참조.
|
|
|
|
## 함정 체크리스트
|
|
- 두 OCCT 백엔드 수치 미세 차이 → cross-check 조기 검증.
|
|
- 기하 연산 비결정성 → 결정론 테스트 CI 1순위.
|
|
- 대형 좌표 f32 정밀도 부족 → 내부 f64 + 프로젝트 원점 오프셋. GPU 전송 시 f32 + 원점 재계산.
|
|
- mm ↔ m 경계 타입 강제.
|
|
- Tauri WebView ≠ PWA 파일 I/O → 추상화 레이어 필수.
|
|
- WebGPU Safari/Firefox 미지원 → Chromium 전용 MVP, 사용자에 명확 고지.
|
|
- `ifc-lite-core` 단일 유지보수자 → 어댑터로 격리·핀·포크 정책.
|
|
- Tauri updater Ed25519 개인키 → HSM/Key Vault 수준 관리 (초기부터 계획).
|
|
- WASM 플러그인(v2 Extism) 무한 루프 → cooperative 중단 플래그.
|
|
- Revit 2글자 keyin vs 한글 IME → IME 상태 기반 입력 라우팅.
|
|
|
|
## CI/CD·배포 (준비 단계)
|
|
- **메인 CI:** Gitea Actions (`.gitea/workflows/`).
|
|
- **Win/macOS 빌드·서명·릴리스:** GitHub Actions 미러.
|
|
- **업데이터:** Tauri v2 Ed25519 키쌍 + `latest.json` CDN.
|
|
- **Windows 서명:** Azure Trusted Signing 우선 검토.
|
|
- **채널:** `nightly` / `beta` / `stable` = Git 태그 prefix.
|
|
- **웹 배포:** Cloudflare Pages (별도 `cimery-web.pages.dev` 예정).
|
|
|
|
## 프로젝트 구조 (예정)
|
|
```
|
|
ParaWiki/ # 현 저장소 루트
|
|
├── wiki/, raw/, Output/ # 지식 저장소 (기존)
|
|
└── cimery/ # 개발 시작 시 별도 서브프로젝트
|
|
├── CLAUDE.md # cimery 자체 세부 개발 지침 (본 문서 기반)
|
|
├── Cargo.toml # workspace
|
|
└── crates/ # core / dsl / ir / kernel / ui / ...
|
|
```
|
|
`cimery/` 디렉터리 생성 시 해당 폴더에 **세부 CLAUDE.md 작성** — 크레이트 의존 그래프, 빌드 명령, 코드 레이아웃, 기여 가이드.
|