# Autonomy Studio LMS

Autonomy Studio LMS의 학생용 데스크톱 애플리케이션입니다. Electron 기반으로 동작하며, 학습 워크스페이스에서 ROS 2/NAV2 모듈 설치와 실행, 코드 편집, Git 연동, 터미널, 맵 및 시각화를 제공합니다.

로컬 PC 시뮬레이션과 원격 플랫폼 워크스페이스를 모두 지원합니다.

## 주요 기능

- 강좌, 학습 단계, 모듈 기반 워크스페이스 관리
- 로컬 및 원격 플랫폼의 모듈 설치, 빌드, 실행, 종료
- 코드 편집기, Git 소스 제어, 내장 터미널
- ROS 토픽 연결 상태와 모듈 간 발행/구독 관계 확인
- 2D/3D SLAM 맵 저장 및 주행 시각화
- Docker 기반 ROS 런타임과 SLAM ROS 브리지 관리
- 원격 플랫폼 에이전트와 연동한 워크스페이스 및 교보재 제어

## 프로젝트 구조

```text
src/
  main/                 Electron main process, Docker/워크스페이스/원격 제어
  preload/              renderer에 노출하는 IPC API
  renderer/src/         React 사용자 인터페이스
resources/
  slam-ros-bridge/      SLAM 및 시각화용 ROS 브리지
  bin/                  패키징에 포함되는 실행 파일
  licenses/             배포 라이선스
```

## 요구 사항

- Node.js와 npm
- Docker Engine
- Git
- Linux AppImage 패키징 시 필요한 시스템 의존성

GPU 가속을 사용할 경우에는 NVIDIA 드라이버 외에 Docker용 NVIDIA Container Toolkit이 필요합니다. GPU 가속은 Docker 컨테이너에 `--gpus all` 옵션을 전달하므로, Docker 런타임이 GPU를 인식하지 못하면 모듈 실행이 실패합니다.

## 개발 환경 실행

```bash
cp .env.example .env
npm ci
npm run dev
```

renderer 개발 서버는 기본적으로 `5176` 포트를 사용합니다.

## 환경 변수

`.env.example`을 복사해 로컬 환경에 맞게 설정합니다.

| 변수 | 설명 |
| --- | --- |
| `VITE_API_BASE_URL` | LMS 백엔드 API 주소 |
| `VITE_LAUNCHER_API_BASE_URL` | 런처/플랫폼 API 주소 |
| `LOCAL_AUTOWARE_BRIDGE_IMAGE` | 로컬 Autoware ROS 브리지 이미지 |
| `LOCAL_NAV2_BRIDGE_IMAGE` | 로컬 NAV2 ROS 브리지 이미지 |
| `LOCAL_NAV2_RUNTIME_IMAGE` | 로컬 NAV2 런타임 이미지 |
| `LOCAL_SLAM_BRIDGE_IMAGE` | 로컬 SLAM ROS 브리지 이미지 |
| `LOCAL_SLAM_RUNTIME_IMAGE` | 로컬 SLAM 런타임 이미지 |
| `JETSON_AGENT_URL` | 원격 Jetson 에이전트 주소 |
| `JETSON_AGENT_TOKEN` | 원격 Jetson 에이전트 인증 토큰 |
| `JETSON_AUTOWARE_BRIDGE_IMAGE` | 원격 Autoware ROS 브리지 이미지 |
| `JETSON_NAV2_BRIDGE_IMAGE` | 원격 NAV2 ROS 브리지 이미지 |
| `JETSON_NAV2_RUNTIME_IMAGE` | 원격 NAV2 런타임 이미지 |

`VITE_` 접두사 변수는 renderer 번들에 포함됩니다. 운영 AppImage를 만들 때는 운영 API 주소로 빌드해야 하며, 토큰이나 비밀번호 같은 민감한 값은 `VITE_` 변수에 넣으면 안 됩니다.

예시:

```bash
VITE_API_BASE_URL=https://workspace.autonomystudio.net/lms-api/api \
VITE_LAUNCHER_API_BASE_URL=https://portal-api.autonomystudio.net/api \
npm run build:linux
```

## 빌드

```bash
# Electron main, preload, renderer 빌드
npm run build

# Linux AppImage 생성
npm run build:linux
```

패키징 결과물은 `dist/`에 생성됩니다. AppImage에는 아이콘, SLAM ROS 브리지, 실행 도구, 라이선스 리소스가 함께 포함됩니다.

운영 배포용 AppImage는 관리자 웹의 빌드 변수와 동일한 API 주소, 동일한 소스 커밋을 기준으로 빌드해야 합니다. Kubernetes의 LMS 웹 배포 환경 변수는 Electron AppImage에 런타임으로 주입되지 않습니다.

## 워크스페이스와 맵

모듈, 빌드 결과물, 저장 맵은 선택한 사용자 워크스페이스 루트 아래에 관리됩니다. SLAM 맵은 기본적으로 다음 경로에 저장됩니다.

```text
<workspace>/maps
```

앱은 해당 워크스페이스를 Docker 컨테이너의 `/workspace`로 마운트하고, SLAM 브리지에는 `SAVED_MAPS_PATH=/workspace/maps`를 전달합니다.

## GPU 가속

GPU 가속을 켠 상태에서 다음과 비슷한 오류가 발생하면 Docker GPU 런타임이 설정되지 않은 상태입니다.

```text
failed to discover GPU vendor from CDI
```

NVIDIA Container Toolkit을 설치하고 Docker를 재시작한 뒤 아래 명령이 정상 동작하는지 확인합니다.

```bash
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
```

GPU 설정이 준비되지 않은 PC에서는 앱 설정에서 GPU 가속을 끈 상태로 사용합니다.

## 로그와 문제 확인

- 앱 renderer 로그는 Electron의 사용자 로그 경로에 `renderer.log`로 기록됩니다.
- 모듈 실행 실패는 워크스페이스 화면의 모듈 로그와 Docker 컨테이너 로그를 함께 확인합니다.
- 원격 플랫폼 문제는 에이전트 상태, Tailscale/Headscale 연결, ROS Domain ID, 원격 Docker 이미지를 순서대로 점검합니다.

## 보안 유의 사항

- `.env`는 저장소에 커밋하지 않습니다.
- 에이전트 토큰, API 키, 인증 정보는 빌드 변수 또는 별도 비밀 저장소로 관리합니다.
- 운영 배포 전에는 API 주소와 원격 런타임 이미지 태그가 대상 환경과 일치하는지 확인합니다.