네이버 스마트스토어와 쿠팡의 상품·주문·정산을 한 화면에서 관리하는 데스크톱 앱입니다. Tauri v2 + Rust 백엔드에 로컬 SQLite를 쓰고, 마켓 판매자 API를 직접 호출합니다.
라이선스 주의 — 상업적 이용 금지 이 소프트웨어는 PolyForm Noncommercial License 1.0.0으로 배포됩니다. 개인 학습·연구·비영리 목적으로만 사용할 수 있으며, 판매·재판매·유료 서비스·사내 상업 활동을 포함한 모든 상업적 이용이 허용되지 않습니다. OSI 기준의 오픈소스 라이선스가 아닙니다. 상업적 이용을 원하면 저작권자(johunsang@gmail.com)에게 별도 허락을 받아야 합니다.
Required Notice: Copyright 나루 (johunsang@gmail.com)— 재배포 시 이 줄과 라이선스를 함께 전달해야 합니다(NOTICE).
AI 비서에게 말로 지시하면 상품 수집·상세페이지 생성·주문 조회가 이어집니다.
전체 영상(37초, 소리 포함): docs/media/smartku-promo.mp4
여러 사업자·여러 마켓 계정을 하나의 앱에서 다룹니다.
| 영역 | 할 수 있는 일 |
|---|---|
| 원본 상품 | 상품 1건을 원본으로 두고 마켓별 이름·가격·카테고리·옵션을 따로 관리 |
| 마켓 등록 | 스마트스토어·쿠팡에 상품등록 API로 실제 등록, 등록 전 페이로드 미리보기·검증. 쿠팡은 해외구매대행 등록(AGENT_BUY·통관부호·인보이스) 지원 |
| 상품 수집 | 마켓에 이미 올라간 상품을 목록·상세로 가져와 원본으로 전환 |
| 가격·재고 | 마켓별 판매가 조정률, 재고 반영, 판매중지·재개, 실제 마켓 값과 비교 |
| 주문 | 최근 주문 수집(계정·주문번호 기준 중복 제거), 발주확인·발송처리·반품/취소 조회 |
| 정산 | 쿠팡 매출내역·지급내역 조회와 요약 |
| 카테고리 | 마켓 카테고리 수집, 네이버↔쿠팡 카테고리 연결표 |
| 이미지 | 보관함, 자르기·리사이즈·여백 제거, 상세페이지 조립, 공개 URL 발급(선택: 본인 Cloudflare R2) |
| AI 비서 | Codex CLI 연동 — 상세페이지 생성, 상품 정리, 일괄 조작 명령(미리보기 후 적용) |
| 도매매 수집 | 도매매 OpenAPI로 위탁 상품을 검색·가져오기(사입·위탁 소싱) |
지원 마켓: 스마트스토어, 쿠팡. (11번가는 코드에 흔적만 남은 지원 종료 상태입니다.)
배포된 설치 파일은 제공하지 않습니다. 소스를 받아 직접 빌드해서 쓰는 방식입니다. 아래 순서를 그대로 따라가면 됩니다. 처음이면 30분~1시간 정도 걸립니다(대부분 빌드 대기 시간).
| 도구 | 버전 | 확인 명령 |
|---|---|---|
| Rust | 1.77.2 이상 | rustc --version |
| Node.js | 18 이상 | node --version |
| Git | 아무 버전 | git --version |
디스크 여유 공간은 약 5GB 필요합니다(Rust 의존성 컴파일 산출물이 큽니다).
macOS
# 1. Xcode Command Line Tools (컴파일러)
xcode-select --install
# 2. Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
# 3. Node.js — Homebrew가 있으면
brew install node
# 없으면 https://nodejs.org 에서 LTS 설치 파일을 받아 설치Apple Silicon(M1~)과 Intel 모두 지원합니다.
Windows
# 1. Microsoft C++ Build Tools
# https://visualstudio.microsoft.com/visual-cpp-build-tools/ 에서 설치
# 설치 시 "C++를 사용한 데스크톱 개발" 워크로드를 반드시 선택
# 2. WebView2 런타임
# Windows 11에는 이미 있습니다. Windows 10이면 아래에서 설치
# https://developer.microsoft.com/microsoft-edge/webview2/
# 3. Rust — https://rustup.rs 에서 rustup-init.exe 실행
# 4. Node.js — https://nodejs.org 에서 LTS 설치설치 후 PowerShell을 새로 열어야 명령이 인식됩니다.
Linux (Ubuntu / Debian)
sudo apt update
sudo apt install -y \
libwebkit2gtk-4.1-dev build-essential curl wget file \
libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
# Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejsUbuntu 22.04 이하는 libwebkit2gtk-4.1-dev 대신 libwebkit2gtk-4.0-dev를 써야 할 수 있습니다.
Linux (Fedora)
sudo dnf install -y \
webkit2gtk4.1-devel openssl-devel curl wget file \
libappindicator-gtk3-devel librsvg2-devel
sudo dnf group install -y "C Development Tools and Libraries"
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
sudo dnf install -y nodejsLinux (Arch)
sudo pacman -Syu --needed \
webkit2gtk-4.1 base-devel curl wget file openssl \
libappindicator-gtk3 librsvg nodejs npm rustup
rustup default stablegit clone https://github.com/johunsang/smartku.git
cd smartku
npm installnpm install은 Tauri CLI만 받으므로 금방 끝납니다.
npm run dev첫 실행은 Rust 의존성을 전부 컴파일하므로 10~30분 걸립니다. 이후 실행은 수십 초입니다. 컴파일이 끝나면 앱 창이 자동으로 열립니다.
진행이 멈춘 것처럼 보여도 컴파일 중입니다. 중간에 끊지 마세요. 외장 디스크에서 작업한다면
CARGO_INCREMENTAL=0 npm run dev가 더 빠를 수 있습니다.
실제로 설치해서 쓰려면 배포 빌드를 합니다.
npm run build산출물은 src-tauri/target/release/bundle/ 아래에 생깁니다.
| 플랫폼 | 산출물 | 설치 방법 |
|---|---|---|
| macOS | dmg/스마트쿠_0.1.1_aarch64.dmg |
더블클릭 → 앱을 Applications로 드래그 |
| macOS | macos/스마트쿠.app |
그대로 실행하거나 Applications로 복사 |
| Windows | msi/스마트쿠_0.1.1_x64_en-US.msi |
더블클릭해서 설치 |
| Windows | nsis/스마트쿠_0.1.1_x64-setup.exe |
더블클릭해서 설치 |
| Linux | deb/스마트쿠_0.1.1_amd64.deb |
sudo dpkg -i <파일> |
| Linux | appimage/스마트쿠_0.1.1_amd64.AppImage |
chmod +x 후 실행 |
빌드는 자신의 운영체제용만 만들어집니다. Windows용 파일을 만들려면 Windows에서 빌드해야 합니다.
빌드한 앱은 코드 서명이 되어 있지 않아 운영체제가 경고를 띄웁니다. 아래처럼 통과시킵니다.
macOS — "확인되지 않은 개발자" 경고
앱을 우클릭 → 열기 → 열기를 누르면 한 번만 확인하고 이후로는 그냥 열립니다.
그래도 "손상되었기 때문에 열 수 없습니다"가 뜨면 격리 속성을 지웁니다.
xattr -cr /Applications/스마트쿠.appWindows — "Windows의 PC 보호" 경고
추가 정보 → 실행을 누르면 설치가 진행됩니다.
Linux — AppImage가 실행되지 않을 때
chmod +x 스마트쿠_0.1.1_amd64.AppImage
./스마트쿠_0.1.1_amd64.AppImageFUSE 오류가 나면 sudo apt install libfuse2를 설치합니다.
앱이 열리면 로그인 없이 바로 들어갑니다. 이어서 초기 설정에서 마켓 계정을 연결하세요.
| 환경변수 | 용도 | 기본값 |
|---|---|---|
SMARTKU_SERVICE_API_URL |
자체 인증·라이선스 서버를 붙일 때 | 없음(기능 비활성) |
자동 업데이트 설정은 들어 있지 않습니다. 배포 채널을 운영하려면 Tauri 업데이터 문서를 보고 서명키와 엔드포인트를 직접 구성하세요.
| 증상 | 원인과 해결 |
|---|---|
error: linker 'cc' not found |
컴파일러가 없습니다. macOS는 xcode-select --install, Linux는 build-essential 설치 |
failed to run custom build command for 'openssl-sys' |
Linux에서 libssl-dev(Fedora는 openssl-devel) 설치 |
error: failed to select a version ... requires rustc 1.77.2 |
Rust가 낮습니다. rustup update stable |
Package webkit2gtk-4.1 was not found |
Linux 패키지 이름이 다릅니다. -4.0-dev 버전으로 시도 |
Windows에서 link.exe 오류 |
C++ Build Tools 설치 시 "C++를 사용한 데스크톱 개발" 워크로드를 선택했는지 확인 |
| 빌드가 매우 느림 | 정상입니다(첫 빌드 10~30분). 외장 디스크면 CARGO_INCREMENTAL=0 사용 |
| 앱은 열리는데 창이 흰 화면 | dist/index.html이 있는지 확인. git status로 파일 누락 여부 점검 |
npm run dev가 앱을 못 찾음 |
저장소 최상위(package.json이 있는 곳)에서 실행했는지 확인 |
그래도 안 되면 실행한 명령, 전체 오류 메시지, 운영체제와 버전(rustc --version, node --version)을 적어
이슈로 남겨 주세요.
앱을 처음 켜면 로그인 없이 바로 들어갑니다. 설정 화면에서 아래를 채우면 기능이 하나씩 열립니다.
마켓연동 탭에서 사업자를 만들고 계정을 추가합니다.
| 마켓 | 필요한 값 | 발급처 |
|---|---|---|
| 스마트스토어 | client_id, client_secret, 리프 카테고리 ID, A/S 전화번호 |
커머스API센터 |
| 쿠팡 | access_key, secret_key, vendor_id, vendor_user_id |
쿠팡 WING 판매자 API |
자격증명은 이 컴퓨터의 로컬 DB에만 저장되며 외부로 전송되지 않습니다.
이미지 공개 URL 발급과 여러 컴퓨터 간 DB 동기화에 씁니다. 본인 Cloudflare 계정이 필요합니다. 설정하지 않으면 앱은 로컬 전용으로 동작합니다.
- R2 버킷 + 공개 URL(또는 커스텀 도메인)
- Account ID / Access Key / Secret Key, 또는 로컬에 로그인된
wrangler사용
Codex CLI가 설치·로그인돼 있어야 합니다. 설정에서 모델과 리즈닝 강도를 고를 수 있습니다.
위탁 소싱을 쓸 때만 설정에 API 키를 넣습니다.
dist/index.html 단일 파일 프런트엔드 (바닐라 JS, 빌드 단계 없음)
dist/image-editor-utils.js 이미지 계산 유틸 (브라우저·Node 공용, 테스트 대상)
src-tauri/src/
lib.rs Tauri 커맨드, 앱 상태, 부팅·동기화 루프
db.rs SQLite 스키마·마이그레이션
markets/
naver.rs 스마트스토어 판매자 API
coupang.rs 쿠팡 WING 판매자 API (HMAC 서명)
domeme.rs 도매매(위탁 소싱) OpenAPI
mod.rs 마켓 디스패치 + 공통 규칙
detail_html.rs 상세페이지 HTML 정리·이미지 표준화
cloudflare.rs R2/D1 (선택, 본인 계정)
ai.rs Codex CLI 연동
test/ 프런트엔드 Node 테스트
docs/ 기능 명세·API 메모·테스트 인벤토리
설계 원칙
- 업무 데이터는 로컬 SQLite가 원본입니다. 클라우드는 선택적 백업·동기화입니다.
- 주문 개인정보(
orders)는 원격 스냅샷에서 항상 제거됩니다. - 마켓 API 호출 전에 필수값을 먼저 검증해 잘못된 요청을 보내지 않습니다.
- 파괴적 작업(일괄 변경, 삭제, 복원)은 미리보기 → 확인 2단계입니다.
빌드 없이 검증할 수 있습니다.
# Rust 단위·통합 테스트
cargo test --manifest-path src-tauri/Cargo.toml --lib
# 프런트엔드 테스트 + 문법 검사
npm run check:frontend
# 컴파일 검사만 (바이너리 생성 없음)
cargo check --manifest-path src-tauri/Cargo.toml테스트는 네트워크와 실계정 없이 전부 통과해야 합니다. 어떤 테스트가 어떤 요구사항을 덮는지는
docs/unit-test-inventory.md에 표로 정리돼 있습니다.
| 항목 | 경로 |
|---|---|
| 업무 DB | <앱 데이터 폴더>/smartku.db |
| 설정 | <앱 데이터 폴더>/settings.json |
| 이미지 보관함 | <앱 데이터 폴더>/images/ (설정에서 변경 가능) |
| 자동 백업 | <앱 데이터 폴더>/backups/ (최근 8개 유지) |
앱 데이터 폴더는 macOS ~/Library/Application Support/com.smartku.app/,
Windows %APPDATA%\com.smartku.app\입니다.
DB 파일을 그대로 복사하면 백업이 되고, 앱의 복구본으로 복원 기능으로 되돌릴 수 있습니다.
| 문서 | 내용 |
|---|---|
docs/functional-specification.md |
기능 요구사항 100개 (ID 기준) |
docs/unit-test-inventory.md |
테스트 ↔ 요구사항 대응표, 커버리지 현황 |
docs/api-naver.md |
스마트스토어 API 실연동 메모 |
docs/api-coupang.md |
쿠팡 API 실연동 메모 |
DESIGN.md |
UI 디자인 규칙 |
CONTRIBUTING.md |
개발·기여 방법 |
이슈와 PR을 환영합니다. CONTRIBUTING.md를 먼저 읽어 주세요.
기여한 코드에도 같은 비상업 라이선스가 적용됩니다.
마켓 판매자 API를 직접 호출해 실제 상품 등록·가격 변경·판매 상태 변경을 수행합니다. 잘못 사용하면 실제 판매 중인 상품에 영향을 줄 수 있습니다. 각 마켓의 이용약관과 API 정책을 지키는 것은 사용자 책임입니다. 이 소프트웨어는 어떤 보증도 제공하지 않습니다(LICENSE.md 참조).