docs: Windows msi 빌드 팀원 가이드 — 준비물·서버 주소·빌드·설치·핫키·막힐 때

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-22 20:39:43 +09:00
parent acb6cefbcc
commit 823292cbb6
2 changed files with 81 additions and 0 deletions
@@ -0,0 +1,80 @@
+# Windows 설치본(msi) 만들기 — 팀원용 가이드
+
+우리 팀 서버(20.200.170.37) 에 붙는 CodeAssist 앱을 Windows PC 에서 빌드하는 순서. 2026-09-22 기준, 앱 버전 0.1.4.
+전부 PowerShell 에서 (Git Bash 는 Rust 링커가 꼬임 — 아래 "막히면").
+
+## 0. 한 번만 깔 것
+
+| 뭐 | 어디서 | 확인 |
+|---|---|---|
+| Git | https://git-scm.com | `git --version` |
+| Node.js 22 LTS | https://nodejs.org | `node --version` → v22.x |
+| Rust (rustup, MSVC) | https://rustup.rs → `rustup-init.exe` 기본값으로 | `cargo --version` |
+| Visual Studio Build Tools | https://visualstudio.microsoft.com/visual-cpp-build-tools/ → **"C++ 데스크톱 개발"** 워크로드 체크 | Rust 가 링크할 때 필요 |
+| WebView2 런타임 | Win11 은 기본 있음. Win10 은 https://developer.microsoft.com/microsoft-edge/webview2/ | 없으면 앱 창이 안 뜸 |
+
+## 1. 코드 받기
+
+```powershell
+git clone https://git.sqnotes.com/20260807_OPENCODE_TEMP/CODE_ASSISTANT.git
+cd CODE_ASSISTANT
+git pull   # 이미 받아뒀으면
+```
+
+## 2. 서버 주소 넣기 (파일 하나)
+
+`2_frontend\.env.production` 파일을 **새로 만들고** 아래 한 줄만:
+
+```
+VITE_API_BASE_URL=http://20.200.170.37:8080/api/v1
+```
+
+이 파일은 git 에 안 올라감(PC 마다 다름). 고객사용을 만들 땐 이 주소만 고객사 서버로 바꿔서 빌드하면 됨.
+
+## 3. 빌드
+
+```powershell
+cd 2_frontend
+npm ci
+
+cd ..\4_rust_tauri
+npm ci
+npx tauri build
+```
+
+처음엔 Rust 크레이트 컴파일 때문에 10~15분. 두 번째부턴 1~2분.
+
+**결과물**: `4_rust_tauri\src-tauri\target\release\bundle\`
+- `msi\CodeAssist_0.1.4_x64_en-US.msi` ← 이걸 배포
+- `nsis\CodeAssist_0.1.4_x64-setup.exe` (같은 내용, exe 설치본)
+
+## 4. 설치하고 확인
+
+1. msi 더블클릭 → 설치 → 트레이에 CodeAssist 아이콘.
+2. 창 열리면 로그인: `admin@codeassist.local` / `test1234` (또는 `guest@codeassist.local` / 같은 비번).
+3. 아무 질문이나 하나 보내서 답이 오면 끝.
+
+핫키:
+
+| 키 | 뭐 |
+|---|---|
+| Ctrl+Alt+W | 챗 열기/숨기기 |
+| Ctrl+Alt+Q | 스니펫 팔레트 (Enter = 직전 앱에 붙여넣기) |
+| Ctrl+Alt+A | 맨 앞 창 통째 캡처 → 새 대화 |
+| Ctrl+Alt+S | 드래그 영역 캡처 → 새 대화 |
+| Ctrl+Alt+Z | 맨 앞 창 캡처 → 마지막 대화에 이어서 |
+| Ctrl+Alt+X | 드래그 영역 캡처 → 마지막 대화에 이어서 |
+
+## 막히면
+
+- **`link.exe` 어쩌고 하며 실패** → Git Bash 에서 돌린 것. PowerShell 로.
+- **`error: linker 'link.exe' not found`** → Build Tools 의 "C++ 데스크톱 개발" 이 안 깔린 것. 깔고 PowerShell 새로 열기.
+- **설치했는데 옛 버전 그대로** → Windows 는 같은 버전 msi 를 건너뜀. `4_rust_tauri\src-tauri\tauri.conf.json` 과 `Cargo.toml` 의 version 을 올리고(예: 0.1.5) 다시 빌드. 올린 건 커밋해서 푸시.
+- **로그인이 안 됨 / 화면이 빈 채로** → `.env.production` 을 안 만들었거나 오타. 2번 다시. 그리고 브라우저에서 `http://20.200.170.37:8080/api/v1/health` 가 열리는지 확인(사내망이면 방화벽).
+- **핫키가 안 먹음** → 다른 프로그램이 같은 키를 먼저 잡은 것. 트레이 아이콘 우클릭 → 열기 로는 됨.
+- **답변이 안 오고 error** → 서버 쪽 문제. 관측 화면 `http://20.200.170.37:6006` 에서 트레이스 확인하거나 나한테.
+
+## 참고
+
+- 맥 빌드본은 `.env.production` 외에 `src-tauri/Info.plist`(http 허용) 가 필요한데 이미 repo 에 있음. Windows 는 무관.
+- 빌드 결과물(`target/`, `dist/`)은 git 에 안 올림. msi 만 팀 채널로 공유.
@@ -23,3 +23,4 @@
 | 18:34 | 오늘 정리: docs/orders/20260922.md(한 것·다음 할 일·접속 메모) 작성, 양쪽 git 전부 push |
 | 20:32 | 우리 서버(20.200.170.37:8080) 앱 빌드 준비 — 8080·6006 바깥에서 200 확인, .env.production 에 서버 API 주소, 빌드 결과에 박히는 것·CORS(tauri origin) 허용 확인. 서버 테스트 계정 t@x.com 삭제(세션 2개 포함). 버전 0.1.4 로 올려 맥 빌드 |
 | 20:36 | 맥 빌드 앱이 서버에 요청을 못 보내던 원인 — macOS ATS 가 http 차단. src-tauri/Info.plist 에 NSAllowsArbitraryLoads 넣어 재빌드, 앱 요청이 서버 로그에 찍히는 것 확인(0.1.4 dmg) |
+| 20:39 | Windows msi 빌드 팀원 가이드(docs/tech/windows-build-guide.md) — 준비물·.env.production·빌드·설치·핫키표·막힐 때. 맥 크로스 빌드는 접음 |