RoomFit은 원룸과 소형 주거 공간에서 사용자의 생활 방식과 취향을 반영해
가구 구성과 배치를 추천하고, 결과를 3D 공간에서 직접 확인·수정할 수 있도록 만든 AI 기반 인테리어 서비스입니다.

사용자는 다음 세 가지 방식으로 공간을 준비할 수 있습니다.

• iPhone의 RoomPlan으로 실제 공간 스캔
• 제공되는 샘플 공간 선택
• 웹에서 방 크기와 구조를 입력해 직접 생성

이후 생활 목적, 디자인 취향, 색상, 필요한 가구를 선택하면 RoomFit이 배치안을 생성합니다.
추천 결과는 3D 에디터에서 확인할 수 있으며, 가구를 직접 조작하거나 자연어로 수정을 요청할 수 있습니다.

LLM은 사용자의 의도를 해석하고, 실제 배치 실행과 안전성 검증은 서버의 결정론적 로직이 담당합니다.

공간 스캔 또는 방 생성
        ↓
생활 목적·디자인 취향 선택
        ↓
필요한 가구와 참고 이미지 선택
        ↓
가구 구성 및 초기 배치 추천
        ↓
3D 에디터에서 직접 수정
        ↓
자연어 피드백으로 배치 변경
        ↓
충돌·경계·동선 검증
        ↓
최종 인테리어 확정 및 저장

• Apple RoomPlan 기반 실내 공간 촬영
• 스캔 결과 미리보기
• RoomPlan 데이터를 RoomFit JSON 형식으로 변환
• 촬영한 공간의 Backend 업로드
• 샘플 방 불러오기
• 웹에서 방 크기를 입력해 직접 생성
• App에서 업로드한 방을 Web의 Rooms 화면과 연결
• 사용자별 Room 목록 조회 및 선택

• 생활 목적 선택
• 인테리어 스타일 선택
• 선호 색상 팔레트 선택
• 스타일 참고 이미지 선택
• 필요한 가구 선택 및 관리
• 선택 정보를 기반으로 추천 Context 생성

• 벽, 바닥, 문, 창문을 포함한 방 구조 렌더링
• React Three Fiber·Three.js 기반 3D 뷰어
• 침대, 책상, 의자, 수납장, 소파, 책장 등 가구 렌더링
• 가구 선택 및 이동
• 가구 회전
• 가구 추가 및 삭제
• 가구 제품·디자인 교체
• 데스크톱 및 모바일 반응형 UI
• 추천 결과 확인 및 최종 확정

• 사용자 Context와 공간 구조를 이용한 가구 추천
• 가구 크기와 공간 제약을 고려한 초기 배치
• 자연어 피드백을 구조화된 작업 계획으로 변환
• 가구 이동·추가·삭제·교체 요청 처리
• LLM 호출 실패 시 Rule-based 해석기로 fallback
• 대상이 모호한 요청에 대한 clarification 응답
• 여러 작업이 포함된 복합 요청 처리
• 수정 결과를 새로운 Layout으로 저장

• 가구 간 충돌 검사
• 방 경계 이탈 검사
• 문 열림 영역 검사
• 창문 주변 여유 공간 검사
• 사용자 이동 동선 검사
• 검증 결과와 점수 제공
• 안전하지 않은 작업의 실패·경고·rollback 처리

RoomFit은 LLM이 최종 좌표를 직접 결정하는 구조를 사용하지 않습니다.

사용자 자연어 피드백
        ↓
LLM 의도 해석
        ↓
구조화된 작업 Plan
        ↓
대상·요청 의미 검증
        ↓
Backend 결정론적 실행
        ↓
충돌·경계·문·창문·동선 검증
        ↓
적용 / 추가 질문 / 실패 / 전체 rollback

• 같은 요청에 대한 실행 결과를 추적하기 쉽습니다.
• 존재하지 않는 가구나 임의 좌표 생성을 방지할 수 있습니다.
• 충돌과 경계 이탈을 서버에서 일관되게 검증할 수 있습니다.
• LLM 오류가 발생해도 Rule-based fallback을 사용할 수 있습니다.
• 모호한 요청은 임의 실행 대신 사용자에게 다시 물을 수 있습니다.

운영 배포: roomfit-web-tau.vercel.app

현재 main에는 다음 사용자 흐름이 구성되어 있습니다.

Home
→ Rooms
→ Manage Furniture
→ Preference
→ Reference Image
→ Add Furniture
→ Recommendation / 3D Editor
→ Layout Confirm

구현된 영역:

• Sample Room, App 업로드 Room, Web 생성 Room 관리
• Room 선택 및 삭제
• 생활 목적·스타일·색상 입력
• 스타일 참고 이미지 선택
• 가구 추가·제거
• RoomViewer 기반 3D 렌더링
• 벽·바닥·문·창문 렌더링
• 가구별 3D 컴포넌트와 모델 렌더링
• Backend Layout 추천·검증·피드백 API 연결
• 자연어 Feedback 결과 표시
• Layout 확정 및 Rooms 재조회
• Vitest 기반 테스트, ESLint, TypeScript Build 검증

개선 중인 영역:

• Rooms 통합 로딩·선택 UI 안정화
• 모호한 가구 대상의 후보 선택 UI
• selectedFurnitureId 기반 피드백 재요청
• Feedback 상태와 접근성 개선
• 대형 3D 번들의 로딩 최적화

운영 배포: roomfit-backend.onrender.com
Swagger: swagger-ui/index.html

구현된 핵심 API:

구현된 영역:

• Spring Boot 기반 REST API
• PostgreSQL·Spring Data JPA 기반 Room 및 Layout 영속화
• RoomPlan 구조 정규화 및 Import Warning 관리
• 사용자 Context 생성
• 제품 정보와 방 구조를 이용한 추천
• Rule-based 초기 배치
• LLM 기반 Feedback 의도 해석
• LLM 실패 시 Rule-based fallback
• 이동·추가·삭제·교체 등 결정론적 작업 실행
• 복합 작업과 rollback
• 충돌·경계·문·창문·동선 검증
• 점수와 경고 응답
• Docker·Render 배포
• Gradle 기반 테스트 및 Build

개선 중인 영역:

• 중복 타입 가구 대상의 모호성 검증 강화
• 회전 자연어 표현 지원 확대
• 크기·소재·디자인 교체 의도 정규화
• Target ambiguity와 Product ambiguity 분리
• 실제 RoomPlan 업로드 진단 강화
• Sample 데이터의 안전한 idempotent 갱신

초기 추천 배치에 LLM을 결합하는 Hybrid Placement는 아직 베타 단계이며, 안정성 강화 중입니다.

RoomFit-App은 iPhone의 공간 센서를 이용해 실제 방 구조를 Web 서비스로 전달하는 역할을 담당합니다.

구현된 영역:

• SwiftUI 기반 앱 화면
• Apple RoomPlan RoomCaptureView 연동
• 실시간 공간 촬영
• 촬영 시작·종료 및 결과 처리
• 스캔한 방의 3D 미리보기
• 벽·문·창문·가구 데이터 변환
• 좌표계·회전·크기 정규화
• RoomFit JSON Export
• Backend /api/rooms/upload 업로드
• 업로드 성공·실패 응답 처리
• 서버에서 반환한 Room ID 저장
• Web에서 업로드 Room을 이어서 사용할 수 있는 연동 흐름
• Sample Room 업로드

개선 중인 영역:

• 실촬영 Room의 업로드·재조회 안정성 진단
• 큰 Thumbnail 및 동적 Geometry 처리 검증
• 실제 기기 기반 End-to-End 회귀 테스트
• 사용자별 App–Web 연결 안정화

┌──────────────────────────┐
│      RoomFit iOS App     │
│  SwiftUI · RoomPlan      │
│  실제 공간 촬영·업로드   │
└────────────┬─────────────┘
             │ RoomFit JSON
             ▼
┌──────────────────────────┐
│     RoomFit Backend      │
│ Spring Boot · PostgreSQL │
│ Recommendation · LLM    │
│ Rule Engine · Validation │
└────────────┬─────────────┘
             │ REST API
             ▼
┌──────────────────────────┐
│       RoomFit Web        │
│ React · TypeScript       │
│ React Three Fiber        │
│ 3D Editor · Feedback UI  │
└──────────────────────────┘

• React
• TypeScript
• Vite
• React Three Fiber
• Three.js
• React Router
• Vitest
• ESLint
• Vercel

• Java 21
• Spring Boot
• Spring Data JPA
• PostgreSQL
• Gradle
• Swagger / OpenAPI
• Docker
• OpenAI-compatible Chat Completions API
• Render

• Swift
• SwiftUI
• Apple RoomPlan
• RealityKit / 3D Preview
• URLSession
• Xcode

RoomFit은 기능 구현뿐 아니라 안전한 AI 동작과 회귀 방지를 중요하게 다룹니다.

• Web Unit·Component Test
• Backend Unit·Integration Test
• TypeScript Type Check
• ESLint
• Gradle Test·Build
• API Smoke Test
• Preview Smoke Test
• Production End-to-End QA
• LLM Feedback 반복·모호성 테스트
• Room 경계·충돌·동선 검증
• 실제 기기 RoomPlan 테스트

사용자가 특정하지 않은 가구를 임의로 변경하지 않습니다.
모호한 요청은 clarification으로 전환하고, 안전하지 않은 복합 작업은 전체 rollback합니다.

LLM의 응답을 그대로 적용하지 않습니다.
Backend가 실제 대상, 허용 작업, 제품 후보, 좌표, 충돌 여부를 다시 검증합니다.

검증되지 않은 AI 초기 배치는 운영 기능과 분리하고 기본적으로 비활성화합니다.

재현 절차, HTTP 응답, 로그, DB 상태, 테스트 결과를 확인한 뒤 수정합니다.

Web, Backend, App, 운영 진단, AI 실험을 각각 별도의 Branch와 Pull Request로 관리합니다.

• 자연어 회전·이동·교체 표현 확대
• 모호한 요청을 위한 상호작용형 후보 선택
• 실제 촬영 Room 업로드 안정화
• 가구 디자인 Variant 확대
• 추천 근거와 설명 제공
• Hybrid AI Placement 실험 및 평가
• 실제 제품 Catalog 연동
• 사용자 인증 및 Room 공유
• 3D 성능과 모바일 경험 최적화

각 저장소의 세부 실행 방법은 Repository 내부 문서를 확인해주세요.

# Web
cd RoomFit-Web
npm install
npm run dev

# Backend
cd RoomFit-Backend
./gradlew bootRun

iOS App은 Xcode에서 RoomFit.xcodeproj를 열고, RoomPlan을 지원하는 실제 기기에서 실행합니다.

최신 기준 Branch 확인
        ↓
작업별 Branch 생성
        ↓
코드와 회귀 테스트 작성
        ↓
Draft Pull Request
        ↓
자동 테스트·Preview Smoke
        ↓
Review 및 수정
        ↓
승인 후 Merge·Deploy
        ↓
Production Smoke Test

Branch prefix:

feat/
fix/
test/
chore/
experiment/

API Key, DB 접속 정보, Client ID, 실제 방 전체 JSON, Base64 Thumbnail과 같은 민감 정보는 Repository에 커밋하지 않습니다.