# 음성 메모 — 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 등) 비교.