# Sync 도움말 — Design

날짜: 2026-05-10
대상 버전: v0.3.4 (또는 v0.4.0 통합 시 Cut G 안에 포함)
선행 의존: v0.3.0 Cut E (양방향 sync), v0.3.3 (configure-sync ENOENT hotfix)

## 배경

v0.3.0 Cut E 가 양방향 sync (configure UI + ConflictModal + auto-sync timer) 를 도입했지만, 사용자에게 노출되는 도움말은 다음 세 곳 모두 부족 또는 부재:

- **SettingsPage > 동기화 저장소**: URL 입력 + 저장/연결 테스트 + 자동 sync 토글만 있음. 무엇이 어떻게 동작하는지 안내 0.
- **ConflictModal**: "내 것 사용 (local)" / "원격 사용 (remote)" 버튼만 노출, 각 옵션의 의미·결과 미설명. 사용자는 추측에 의존.
- **README "원격 백업 (F6-L2)" 섹션**: v0.2.1 MVP 시점 기준 (트레이 "지금 동기화" + 수동 `git init`). Cut E 의 Configure UI / ConflictModal / auto-sync timer 미반영 — 사용자가 따라하면 어긋남.

다기기 (Mac + Windows) sync dogfood 는 본인 + 사내 베타 10인의 핵심 가치 검증인데, conflict 시나리오에 막혔을 때 도움말이 없어 사용자가 직접 git 내부 동작을 추측해야 하는 상태.

## 목표

git 기반 sync 의 정상 동작·이상 시나리오·복구 절차를 사용자가 막힌 순간에 바로 찾을 수 있게 만든다.

비목표:

- 'both' choice (v0.3.1+ deferred) 도움말
- 다국어 (앱 한국어 only)
- 스크린샷·GIF (텍스트만으로 충분)
- README 외 docs/sync-guide.md 별도 파일 (in-app 이 메인, README 가 보조 — 별도 파일 발견성 ↓)

## 표면 (3개)

### 1. SyncHelpModal — 신규 컴포넌트

**위치**: `src/renderer/inbox/components/SyncHelpModal.tsx`

**진입점**:

- `SyncSection.tsx`: URL 입력 row 옆에 "도움말" 버튼 추가 → 클릭 시 modal open
- `ConflictModal.tsx`: 각 옵션 설명 옆 "자세히 보기 →" 링크 → SyncHelpModal open + "메인 conflict" 섹션으로 스크롤

**구조**: `ConflictModal` 패턴 재사용 (overlay + 닫기 버튼 + scrollable body). 4 섹션 (단순 anchor jump — 좌측 nav 미도입, modal 무게 ↓):

1. **메인 conflict** — 편집/편집, 삭제/편집, AI 결과 충돌 3 케이스 + 각 결정 트리
2. **자동 처리** — fetch+rebase, 첫 sync 순서, push 순서 ("내가 안 해도 되는 일")
3. **Silent risk** — 시계 어긋남(NTP), 결합 실패 silent, dogfood 주의
4. **Setup/인증** — URL 형식 (SSH vs HTTPS), 인증 helper, 연결 실패 troubleshoot

**Close**: ESC + 우상단 X + overlay 클릭 (ConflictModal 패턴 일치).

### 2. ConflictModal 갱신

**현재**: 각 conflict path 에 대해 "내 것 사용 (local)" / "원격 사용 (remote)" 버튼만.

**변경**: 각 옵션 라벨 아래 1-2 줄 inline 설명 + "자세히 보기 →" 링크.

```text
내 것 사용 (local)
  이 기기의 변경을 보존하고 원격의 같은 노트 변경을 폐기.
  자세히 보기 →

원격 사용 (remote)
  원격 (다른 기기 또는 백업) 의 변경을 가져오고 내 변경을 폐기.
  자세히 보기 →
```

"자세히 보기" 클릭 → SyncHelpModal open (메인 conflict 섹션 anchor).

### 3. README "원격 백업 (F6-L2)" 섹션 통째 재작성

**현재 (line 193-223)**: v0.2.1 MVP 기준 stale.

**신규 헤더**: "## 동기화 (Git, F21 Cut E)"

**하위 절**:

- 일회 설정 — Settings > 동기화 저장소 UI 안내 (트레이 "지금 동기화" 안내 제거 — 현재 UI 와 다름)
  - URL 형식 명확화: `git@host:user/repo.git` (SSH) 또는 `https://host/owner/repo.git` (HTTPS). v0.3.3 dogfood 에서 발견된 `git@https://` 혼합 오류 사례 명시
- 일상 사용 — auto-sync 주기 / 수동 트리거 / 충돌 시 ConflictModal 안내
- 충돌 해결 — local/remote 결정 트리 (in-app SyncHelpModal 과 같은 내용)
- Silent risk — 시계 어긋남, 동시 수정 회피
- Troubleshoot — push 실패 / 인증 실패 / 첫 sync 순서

## 콘텐츠 분배

| 시나리오 | SyncHelpModal | ConflictModal inline | README |
|---|---|---|---|
| 편집/편집 conflict | 결정 트리 (어떤 변경이 더 최신인지 / 둘 다 보존하려면 사후 수동 병합) | 1줄 + "자세히" 링크 | 상세 + 예시 |
| 삭제/편집 | 케이스 설명 (삭제 측이 'remote' 면 trash 로 이동, 편집 측이 'local' 이면 trash 취소) | (해당 없음 — path 가 같음) | 케이스 설명 |
| AI 결과 충돌 | "재처리 권장" — local/remote 한쪽 선택 후 AI 재실행 권장 | (해당 없음) | 케이스 설명 |
| fetch+rebase 자동 | "내가 안 해도 되는 일" 단원 | — | 동일 |
| 첫 sync 순서 | "Mac 먼저 push → Windows pull 후 push" | — | 동일 |
| 시계 어긋남 (NTP) | "두 기기 동시 수정 회피", `chrony` / Windows time sync 점검 안내 | — | 동일 |
| Setup/URL 형식 | SSH/HTTPS 예시, `git@https://` 같은 혼합 형식 거부 사례 | — | 동일 + 인증 helper 안내 |
| 인증 실패 | "OS credential helper 점검", token URL embed 우회 옵션 | — | 동일 |

## 변경 파일

**신규**:

- `src/renderer/inbox/components/SyncHelpModal.tsx`
- `tests/unit/SyncHelpModal.test.tsx`

**수정**:

- `src/renderer/inbox/components/settings/SyncSection.tsx` — "도움말" 버튼 추가 (URL row 옆)
- `src/renderer/inbox/components/ConflictModal.tsx` — 각 옵션 inline 설명 + "자세히" 링크
- `tests/unit/ConflictModal.test.tsx` — inline 설명 / 링크 클릭 시 SyncHelpModal open 회귀
- `tests/unit/SyncSection.test.tsx` — 도움말 버튼 클릭 → SyncHelpModal open 회귀
- `README.md` — "원격 백업 (F6-L2)" 섹션 line 193-223 통째 재작성

## 게이트

- `SyncHelpModal.test.tsx` 신규 — 4 섹션 렌더링, close (ESC/X/overlay), anchor jump
- `ConflictModal.test.tsx` 회귀 — inline 설명 표시, "자세히" 링크 → SyncHelpModal open
- `SyncSection.test.tsx` 회귀 — 도움말 버튼 → SyncHelpModal open
- typecheck 0
- 단위 +6~8 (SyncHelpModal 4 + ConflictModal 회귀 1 + SyncSection 회귀 1)
- e2e 미수행 (UI-only, 기존 capture/onboarding flow 무관)

## Risk

- **콘텐츠 정확성**: AI 결과 충돌 / 시계 어긋남 같은 시나리오는 dogfood 미경험 (v0.3.3 까지 1 dogfood 발견). 도움말이 실제 사용자 경험과 어긋날 risk → 1주 dogfood soak 후 도움말 텍스트 1차 갱신 필수
- **README 와 in-app 의 중복 maintain**: 두 곳에 같은 내용. 정합성 깨질 risk → 우선순위는 in-app (사용자가 보는 위치). README 는 보조
- **'both' choice 부재 안내**: v0.3.1+ deferred 인데 사용자가 "왜 둘 다 보존이 없냐" 질문 가능 → 도움말에 "현재 미지원, 사후 수동 병합" 명시
- **콘텐츠 길이**: SyncHelpModal 4 섹션이 길어지면 modal 자체가 무거워짐 → 각 섹션 200 자 이내 + README 가 상세. modal 은 "막힌 순간 결정 트리" 우선

## 비포함 / Deferred

- 'both' choice 도움말 (Cut E 정책 deferred)
- 다국어 (앱 한국어 only)
- 스크린샷 / GIF
- 별도 docs/sync-guide.md (README + in-app 으로 충분)
- ConflictModal 의 diff 시각 개선 (별개 task, 본 도움말 cut 의 scope 외)
- 도움말 검색 기능 (4 섹션, 짧음)

## How to apply

- v0.3.4 patch 또는 Cut G 안에 통합. 단독 cut 으로 갈 경우 v0.3.4 — 데이터/마이그레이션 변경 0
- dogfood 1주 soak 후 도움말 텍스트 정합성 1차 갱신 (실제 사용자 경험과 어긋난 부분 보강)
- ConflictModal 의 inline 설명은 "자세히 보기" 링크 한 번이 SyncHelpModal 메인 conflict 섹션 anchor 로 점프 — anchor id 명명: `#main-conflict`, `#auto`, `#silent`, `#setup`
