docs(memos): iOS Shortcuts guide for voice memo upload

docs/voice_memo_shortcuts.md

@@ -0,0 +1,89 @@
+# 음성 메모 — iOS Shortcuts 가이드
+
+**Endpoint**: `POST https://document.hyungi.net/api/memos/voice` (multipart/form-data)
+**인증**: Bearer JWT (단기 access token, 1시간). 만료 시 web 로그인 후 token 재복사.
+**제한**: 10분 / 50MB. m4a/mp3/wav/webm/ogg/opus/aac.
+**플로우**: 업로드 → STT (faster-whisper) → 자동 분류 (4B Gemma triage) → `/memos` inbox 노출.
+
+장기 service token 발급 endpoint 는 PR-2C 안 포함 X — 1–2주 운영 후 끊김 빈도 보고 별 PR 결정 (plan v9 Memo Intake Upgrade 백로그).
+
+## 1. JWT access token 복사
+
+1. 데스크탑/모바일 브라우저에서 `https://document.hyungi.net/login` 로그인 + TOTP (활성 시)
+2. 개발자 도구 콘솔에서 다음 명령 1줄 — access_token 출력
+   ```js
+   // Memo Intake Upgrade 임시 패턴 — service token PR 도입 전까지만
+   localStorage.getItem('access_token') ??
+     // 또는 fetch refresh 후 res.access_token (refresh cookie 유효 시)
+     (await (await fetch('/api/auth/refresh', {method:'POST',credentials:'include'})).json()).access_token
+   ```
+3. 출력된 긴 문자열 (eyJ...) 을 Shortcuts 에 입력 (다음 단계)
+
+> 1시간 후 만료. iOS Shortcut 사용 중 401 발생 시 token 다시 복사 + Shortcut 의 Text action 값 갱신.
+
+## 2. iOS Shortcuts 만들기 (Apple Watch + iPhone 공용)
+
+iPhone 의 단축어 (Shortcuts) 앱에서 새 단축어 생성:
+
+### 단축어 이름
+`메모 녹음` (또는 임의)
+
+### Action 1: Dictate Text (받아쓰기 텍스트) 또는 Record Audio (오디오 녹음)
+
+**옵션 A — Whisper STT 사용 (권장, 한국어 정확도 ↑)**:
+- `Record Audio` action 추가
+  - Audio Quality: `Normal` (m4a 4kbps 정도, 충분)
+  - Start Recording: `On Tap`
+  - Stop Recording: `On Tap`
+
+**옵션 B — iOS native 받아쓰기 (간단, 정확도 보통)**:
+- `Dictate Text` action 추가 + 결과를 본문에 직접 넣어 `POST /api/memos/` (text endpoint) 호출
+
+이 가이드는 옵션 A (Whisper STT 경유) 기준.
+
+### Action 2: Get Contents of URL
+
+- URL: `https://document.hyungi.net/api/memos/voice`
+- Method: `POST`
+- Headers:
+  - `Authorization`: `Bearer <위 1단계 토큰>` (Text action 으로 분리해두면 갱신 편함)
+- Request Body: `Form`
+  - `audio`: 위 Action 1 의 출력 (Recorded Audio File)
+  - `recorded_at` (옵션): `Current Date` → `Format Date` → ISO 8601
+  - `device_hint` (옵션): `apple_watch` 또는 `iphone`
+
+### Action 3: Show Result (옵션)
+
+- 결과 JSON 의 `id` 확인 (메모 inbox 에 들어갔는지)
+
+### Apple Watch 노출
+
+- 단축어 이름이 `메모 녹음` 이면 Siri 로 "Hey Siri, 메모 녹음" 호출 시 Watch 에서 실행
+- 또는 단축어 앱의 별 표시 → Watch 의 단축어 앱 첫 화면에 고정
+
+## 3. 동작 확인
+
+녹음 후 1–수분 안에:
+
+1. `https://document.hyungi.net/memos` 진입
+2. 최상단에 새 메모 카드 (🎙️ 음성 배지 + audio player)
+3. STT 완료 후 카드 본문에 변환 텍스트 + AI 분류 배지 (task/calendar/activity/reference/note 중 하나)
+4. AI 추천이 task/일정/활동이면 4 버튼 표시 — 1-click 으로 events 승급
+
+## 4. 트러블슈팅
+
+| 증상 | 원인 / 조치 |
+|---|---|
+| 401 응답 | JWT 만료 → web 에서 다시 복사 |
+| 413 응답 | 50MB 초과 → 녹음 시간 단축 또는 quality 낮춤 |
+| 415 응답 | Content-Type 또는 확장자 미지원 → m4a/mp3 사용 |
+| 503 응답 | NAS 쓰기 실패 (드물게) → 1–2분 후 재시도 |
+| 메모는 생겼는데 본문 비어 있음 | STT 처리 중 (5분 polling). `stt-service` 컨테이너 health 확인 |
+| AI 분류 배지 안 나타남 | classify worker 가 아직 큐 처리 안 함. `processing_queue` stage=classify pending 확인 |
+
+## 5. 운영 1–2주 후 결정 사항
+
+- **service token 발급 endpoint 신설**: 단기 access token 만료가 자주 끊기면 별 PR.
+- **frontend mic widget**: 브라우저 직접 녹음 진입점 추가 (현재는 iOS Shortcuts 만).
+- **녹음 자동 정리**: 음성 메모 인입 빈도가 높아지면 archive 정책 또는 NAS 폴더 size 모니터링.
+- **STT 한국어 정확도 평가**: sample 5건 사용자 평가 후 large-v3 vs 다른 모델 (whisper-v3-turbo 등) 비교.