A. 용어집 (초보자용)
| 용어 | 의미 |
|---|---|
| API | 프로그램이 데이터를 주고받을 수 있도록 정해둔 URL 규칙 모음 |
| 백엔드 / 서버 | 휴대폰이 아닌 클라우드에서 돌아가는 시스템의 일부 |
| 코드베이스 | 프로젝트의 모든 소스 코드 |
| 크로스플랫폼 | 여러 운영체제용 앱을 하나의 코드로 만드는 것 |
| D1 | Cloudflare의 서버리스 SQL 데이터베이스 |
| 배포 | 사용자가 소프트웨어에 접근할 수 있게 공개하는 것 |
| LLM | 대형 언어 모델 — 텍스트를 이해하고 생성하는 AI(예: Nemotron) |
| OTA 업데이트 | 스토어 심사 없이 설치된 앱을 무선으로 업데이트 |
| OpenRouter | 수많은 AI 모델을 하나의 API로 연결해주는 게이트웨이 서비스 |
| PWA | 프로그레시브 웹 앱 — 설치 가능하고 오프라인도 되는 웹 앱 |
| 서버리스 | 함수만 작성하면 제공자가 실행하고 확장 — 서버 관리 불필요 |
| Worker | Cloudflare의 서버리스 함수 |
B. 강사 사전 준비 체크리스트
- 워크숍 하루 전에 전체 흐름을 직접 끝까지 테스트 (Wi-Fi, 계정, 키 확인)
- 공용 OpenRouter 키를 미리 만들어 백업으로 준비 (무료 모델이므로 충전 불필요)
- API 규약 표와 데이터 모델을 한 페이지 핸드아웃으로 인쇄
- 대비책 준비: 기계가 고장 난 참가자를 위해 완성된 앱의 Expo Snack 링크 미리 제작
- 교실 Wi-Fi가 기기 간 통신(Expo Go)을 허용하는지 확인 — 안 되면
--tunnel을 대안으로 - 실습 시간 동안 OpenRouter 상태 페이지를 열어두기
C. 흔한 초보자 실수 & 해결법
| 에러 메시지 | 원인 | 해결법 |
|---|---|---|
command not found: node | Node.js 미설치 / 터미널 재시작 안 함 | Node LTS 설치, 터미널 재시작 |
| Expo Go 연결 안 됨 | 다른 Wi-Fi 네트워크 | 같은 네트워크 연결, 또는 --tunnel 사용 |
D1_ERROR: no such table | 스키마를 현재 D1 환경에 적용하지 않음 | 로컬은 npx wrangler d1 execute mindlog-db --local --file=./schema.sql, 배포 DB는 --remote 사용 |
| OpenRouter 401 | API 키 누락/오류 | 로컬은 server/.dev.vars, 배포는 npx wrangler secret put OPENROUTER_API_KEY를 확인 |
| OpenRouter 429 | 무료 모델 사용량 한도 초과 | 잠시 후 재시도, 또는 OpenRouter 대시보드에서 상태 확인 |
| 텍스트 모델에 음성을 보냈더니 400 | nemotron-3.5-lightning은 text→text 모델 | 음성은 OPENROUTER_AUDIO_MODEL과 input_audio 형식을 사용 |
| 마이크 무응답 | 이전에 권한 거부함 | Expo Go 앱 데이터 삭제 / 재설치 후 권한 수락 |
Cannot read properties of null (reading 'edgesOut') | 지원 종료된 Node 23 + npm peer 의존성 및 create-cloudflare 중단 | Node 24 LTS로 교체. 실패 폴더를 보관용으로 이름 변경한 뒤 4.3.2의 npm init 최소 구성 또는 백엔드 스타터 ZIP 사용 |
D. 더 읽을 거리
- Expo 공식 문서 — docs.expo.dev
- Cloudflare Workers 문서 — developers.cloudflare.com/workers
- OpenRouter 모델 카탈로그 — openrouter.ai/models
- Claude Code 문서 — docs.anthropic.com/en/docs/claude-code
- Apple App Store 심사 지침 & Google Play 정책 센터 (스토어 제출 전 필독)