wiki: Topic_Blog 신규 문서 일괄 추가 + ASTRA 성장 자산 동기화
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,68 @@
|
||||
---
|
||||
id: pattern-background-task
|
||||
title: "Background Task Pattern"
|
||||
category: "Pattern_Mobile"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["background task", "백그라운드 작업", "scheduled job", "watcher", "cron", "WorkManager"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.86
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["pattern", "mobile", "background", "scheduling", "platform-independent"]
|
||||
raw_sources: ["일반 모바일/클라이언트 공학 지식", "AstraAI/src/features/*/watcher, src/extension.ts (적용 예)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[Background Task Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
백그라운드 작업은 "사용자 상호작용 밖에서 주기적/지연 작업을 실행" 하는 패턴으로, OS 제약(배터리/킬)과 *재진입·중복 실행 방지*를 고려하지 않으면 자원을 낭비하거나 데이터를 손상시킨다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **스케줄링:** interval/cron/조건(충전 중·Wi-Fi) 트리거.
|
||||
2. **수명관리:** 등록한 작업은 dispose 가능해야(누수 방지).
|
||||
3. **재진입 방지:** 이전 실행이 안 끝났으면 skip/큐.
|
||||
4. **멱등성:** 중복 실행에도 안전.
|
||||
5. **OS 제약:** 모바일은 OS 가 백그라운드를 제한(WorkManager/BGTask).
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** 동기화/정리/알림/사전계산을 사용자 흐름 밖에서.
|
||||
- **사용 조건:** 스케줄러; 작업을 작게 분할; 취소/정리 가능.
|
||||
- **장점:** 응답성(무거운 일을 뒤로), 자동화, 유휴 활용.
|
||||
- **단점:** 디버깅 난해, OS 킬/제약, 중복/경쟁 위험.
|
||||
- **대안:** 포그라운드 처리, 서버측 작업(클라 부담↓), 푸시 트리거.
|
||||
- **실패 사례:** dispose 누락으로 타이머 누수; 재진입으로 중복 실행; 무거운 작업을 메인 스레드; OS 제약 무시로 실행 안 됨; 실패 무한 재시도.
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
const handle = scheduleInterval(ms, async () => {
|
||||
if (running) return; running = true # 재진입 방지
|
||||
try { await doWork() /*멱등, 작게*/ } finally { running = false }
|
||||
})
|
||||
register(handle) # dispose 가능하게 등록 → 종료 시 정리
|
||||
```
|
||||
적용 예: AstraAI 의 stocksWatcher/dailyBriefing/growthCycle/sleepDigest 워처가 interval 로 돌고 disposable 을 `context.subscriptions` 에 등록해 종료 시 정리([[VSCode 확장 구조와 생명주기]]).
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
모바일에선 OS 가 백그라운드를 강하게 제한 — "정확한 시각 보장" 을 가정하면 깨진다. 중요 작업은 서버 푸시로 트리거하는 것이 안전.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI 워처들(KST 스케줄, dispose 등록).
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[Background Worker Pattern]], [[Async Concurrency Pattern]], [[Push Notification Pattern]], [[모바일 개발 가이드]]
|
||||
- **참조 맥락:** 작은 모델이 주기/지연 작업을 설계할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 백그라운드 작업 지식(WorkManager/BGTaskScheduler)
|
||||
- [S2] AstraAI/src/features/*/watcher, extension.ts — 적용 예
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
id: pattern-local-storage
|
||||
title: "Local Storage Pattern"
|
||||
category: "Pattern_Mobile"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["local storage", "로컬 저장 패턴", "key-value", "sqlite", "secure storage"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.86
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["pattern", "mobile", "storage", "persistence", "platform-independent"]
|
||||
raw_sources: ["일반 모바일/클라이언트 공학 지식", "AstraAI/src/core/services.ts, eventSourcedStore.ts (적용 예)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[Local Storage Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
로컬 저장은 "데이터 성격에 맞는 매체를 고르는 것" 이 핵심 — 소량 설정은 key-value, 구조화 데이터는 SQLite, 민감정보는 보안 저장소, 대용량 파일은 파일시스템. 한 매체에 다 넣으면 성능·보안이 무너진다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **key-value(prefs):** 작은 설정/플래그.
|
||||
2. **임베디드 DB(SQLite/Realm):** 구조화/쿼리 데이터.
|
||||
3. **보안 저장소(Keychain/Keystore):** 토큰/비밀.
|
||||
4. **파일시스템:** 이미지/대용량/캐시.
|
||||
5. **마이그레이션:** 스키마 버전 관리.
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** 앱이 디바이스에 데이터를 보존해야 할 때.
|
||||
- **사용 조건:** 데이터 성격 분류; 용량/보안 요구 파악.
|
||||
- **장점:** 오프라인, 빠른 접근, 네트워크 절약.
|
||||
- **단점:** 디바이스 한정, 백업/동기화 별도, 보안 책임.
|
||||
- **대안:** 서버 저장(동기화 필요), 캐시만(휘발).
|
||||
- **실패 사례:** 토큰을 평문 prefs 에(보안 사고); 대용량을 key-value 에(성능); 마이그레이션 없어 업데이트 시 크래시; 캐시와 영구 데이터 혼동.
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
prefs.set('theme', v) # 소량 설정
|
||||
secureStore.set('token', t) # 민감정보 (Keychain/Keystore)
|
||||
db.exec('INSERT ...') # 구조화 데이터
|
||||
fs.write(path, blob) # 대용량
|
||||
onUpgrade(old, new): migrate(old→new) # 스키마 버전
|
||||
```
|
||||
적용 예: AstraAI 는 설정=VS Code config/secrets, 지식=Markdown 파일, 이벤트=JSONL — *데이터 성격별 매체 분리* 원칙을 그대로([[ADR-0005 파일 기반 저장 채택]]).
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"전부 SQLite" 나 "전부 key-value" 는 안티패턴 — 성격별 분리가 원칙. 민감정보는 *반드시* 보안 저장소.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI secrets(토큰) + 파일(지식) + JSONL(이벤트).
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[Offline Sync Pattern]], [[Caching Pattern]], [[이벤트 소싱 스토어 패턴]], [[모바일 개발 가이드]]
|
||||
- **참조 맥락:** 작은 모델이 클라이언트 저장을 설계할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 모바일 저장 지식
|
||||
- [S2] AstraAI/src/core/services.ts, extension.ts(secrets), eventSourcedStore.ts — 적용 예
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
id: pattern-navigation
|
||||
title: "Navigation Pattern"
|
||||
category: "Pattern_Mobile"
|
||||
status: "draft"
|
||||
verification_status: "conceptual"
|
||||
canonical_id: ""
|
||||
aliases: ["navigation", "내비게이션 패턴", "routing", "deep link", "navigation stack"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.83
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["pattern", "mobile", "navigation", "routing", "platform-independent"]
|
||||
raw_sources: ["일반 모바일/프런트엔드 공학 지식"]
|
||||
applied_in: []
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[Navigation Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
내비게이션은 "화면 간 이동과 스택/상태를 관리" 하는 패턴으로, *경로를 선언적·직렬화 가능*하게 두고 딥링크/뒤로가기/상태 복원을 1급으로 다뤄야 한다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **선언적 라우트:** URL/route 로 화면을 표현(직렬화 가능).
|
||||
2. **스택/탭/드로어:** 내비 구조 유형.
|
||||
3. **딥링크:** 외부에서 특정 화면 직접 진입.
|
||||
4. **파라미터 전달:** 라우트 인자 + 타입 안전.
|
||||
5. **상태 복원:** 프로세스 죽어도 내비 상태 복구.
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** 다화면 앱의 이동/히스토리/딥링크 관리.
|
||||
- **사용 조건:** 라우트 정의; 화면 식별자; 인자 직렬화.
|
||||
- **장점:** 일관된 이동, 딥링크, 뒤로가기, 테스트성.
|
||||
- **단점:** 설정 복잡, 깊은 스택 메모리, 타입 안전 관리.
|
||||
- **대안:** 단일 화면(소규모), 조건부 렌더(상태 기반), 코디네이터 패턴.
|
||||
- **실패 사례:** 객체를 라우트 인자로 직접(직렬화 불가/딥링크 깨짐); 스택 누수(화면 안 떼어냄); 뒤로가기 상태 불일치; 딥링크 시 부모 스택 없어 길 잃음.
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
routes = { '/home': Home, '/item/:id': ItemDetail } # 선언적 + 직렬화 가능 인자
|
||||
navigate('/item/42') # id 만 전달(객체 X)
|
||||
deepLink('myapp://item/42') -> rebuild stack [Home, ItemDetail]
|
||||
restore(savedNavState) # 프로세스 복원
|
||||
```
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"상태로 화면 전환" vs "라우터" — 작은 앱은 상태 조건부가 단순하나, 딥링크/히스토리가 필요하면 선언적 라우터가 필수.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
일반 모바일/SPA. (AstraAI 는 패널 기반이라 직접 사례 없음 — 화면 식별/복원 원리는 동일.)
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[State Management Pattern]], [[React State Pattern]], [[모바일 개발 가이드]]
|
||||
- **참조 맥락:** 작은 모델이 다화면 앱의 이동을 설계할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 내비게이션/라우팅 지식
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
id: pattern-offline-sync
|
||||
title: "Offline Sync Pattern"
|
||||
category: "Pattern_Mobile"
|
||||
status: "draft"
|
||||
verification_status: "conceptual"
|
||||
canonical_id: ""
|
||||
aliases: ["offline sync", "오프라인 동기화", "optimistic update", "conflict resolution", "outbox"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.85
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["pattern", "mobile", "offline", "sync", "platform-independent"]
|
||||
raw_sources: ["일반 모바일 공학 지식", "AstraAI/src/features/_shared/eventSourcedStore.ts (개념 유사)"]
|
||||
applied_in: []
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[Offline Sync Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
오프라인 동기화는 "네트워크 없이도 로컬에서 동작하고, 연결되면 변경을 *큐로 모아 동기화*하며 충돌을 해소" 하는 패턴으로, 핵심 난제는 동기화 자체가 아니라 **충돌 해소(conflict resolution)** 다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **로컬 우선 저장:** 모든 쓰기를 먼저 로컬에.
|
||||
2. **outbox(변경 큐):** 미동기 변경을 append-only 로 쌓아 연결 시 전송.
|
||||
3. **낙관적 업데이트:** UI 는 즉시 반영, 실패 시 롤백.
|
||||
4. **충돌 해소:** last-write-wins / 버전 벡터 / 병합 / 사용자 선택.
|
||||
5. **멱등성:** 재전송에도 안전하도록 변경에 고유 id.
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** 불안정/없는 네트워크에서도 앱이 동작해야 할 때.
|
||||
- **사용 조건:** 로컬 저장소; 변경을 식별/순서화 가능; 서버 동기 API.
|
||||
- **장점:** 오프라인 사용성, 빠른 반응(낙관적), 복원력.
|
||||
- **단점:** 충돌 해소 복잡, 데이터 일관성 약화, 디버깅 난해.
|
||||
- **대안:** 온라인 전용(단순), CRDT(자동 병합, 복잡), 서버 권위(충돌 시 서버 우선).
|
||||
- **실패 사례:** 멱등 키 없어 중복 적용; LWW 로 사용자 데이터 유실; outbox 순서 꼬임; 낙관적 업데이트 롤백 누락으로 유령 데이터.
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
write(op): localDB.apply(op); outbox.append({id:uuid, op, ts}) # 로컬 우선 + 큐
|
||||
onOnline: for op in outbox: try{ server.apply(op) /*멱등*/; outbox.remove(op) } catch{ retry }
|
||||
onPull: merge(serverChanges, local, resolve=versionVector|userChoice)
|
||||
```
|
||||
개념 유사: AstraAI 의 append-only 이벤트([[이벤트 소싱 스토어 패턴]])가 outbox 와 같은 구조 — 변경을 줄로 쌓고 재생/전송.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
LWW 는 간단하지만 데이터 손실 위험 — 협업/중요 데이터엔 버전 벡터/CRDT 또는 사용자 충돌 해소가 안전.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
일반 모바일 앱(노트/메신저). AstraAI 는 단일 로컬이라 동기화는 불필요하나 outbox 구조는 동일.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[Local Storage Pattern]], [[Background Task Pattern]], [[이벤트 소싱 스토어 패턴]], [[모바일 개발 가이드]]
|
||||
- **참조 맥락:** 작은 모델이 오프라인 가능 앱을 설계할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 오프라인 동기화 지식(outbox, CRDT)
|
||||
- [S2] AstraAI/src/features/_shared/eventSourcedStore.ts — 구조 유사
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: pattern-push-notification
|
||||
title: "Push Notification Pattern"
|
||||
category: "Pattern_Mobile"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["push notification", "푸시 알림", "FCM", "APNs", "notification"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.84
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["pattern", "mobile", "push", "notification", "platform-independent"]
|
||||
raw_sources: ["일반 모바일 공학 지식", "AstraAI/src/integrations/telegram/*, src/features/briefing/* (유사 예)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[Push Notification Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
푸시 알림은 "서버가 디바이스로 비동기 메시지를 밀어 넣는" 패턴으로, 토큰 수명 관리·전달 보장 없음·사용자 동의·과알림 피로를 다루지 못하면 오히려 이탈을 부른다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **디바이스 토큰:** 앱이 FCM/APNs 토큰 등록, 서버 저장(만료/갱신).
|
||||
2. **전송:** 서버→게이트웨이(FCM/APNs)→디바이스.
|
||||
3. **전달 비보장:** best-effort — 중요 데이터는 알림 본문 말고 동기화로.
|
||||
4. **동의/채널:** 권한 요청, 카테고리별 on/off.
|
||||
5. **딥링크:** 탭 시 해당 화면으로.
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** 서버 이벤트를 사용자에게 즉시 알릴 때.
|
||||
- **사용 조건:** 게이트웨이 연동; 토큰 저장; 사용자 동의.
|
||||
- **장점:** 재참여, 실시간 알림, 백그라운드 트리거.
|
||||
- **단점:** 전달 비보장, 토큰 만료, 권한 거부 시 무력, 과알림 피로.
|
||||
- **대안:** 인앱 알림, 폴링(배터리↑), 이메일/SMS.
|
||||
- **실패 사례:** 만료 토큰으로 전송 실패; 알림 본문에만 중요 데이터(미수신 시 유실); 과알림으로 권한 철회; 딥링크 없어 탭 후 길 잃음.
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
onAppStart: token = registerForPush(); server.saveToken(userId, token)
|
||||
server.onEvent: send(FCM/APNs, token, { title, body, data:{deeplink} }) # best-effort
|
||||
onReceive: showNotification ; onTap: navigate(data.deeplink)
|
||||
onTokenRefresh: server.updateToken(...)
|
||||
```
|
||||
유사 예: AstraAI 의 Telegram 리포트/daily briefing 이 "서버측 이벤트→사용자 채널 푸시" 구조([[Background Task Pattern]] 워처가 트리거). 전달 비보장 가정도 동일.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
알림을 "전달된다" 고 가정하면 안 된다 — 중요 상태는 서버에 두고 알림은 *유도* 만. 과알림은 가장 흔한 이탈 원인.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI Telegram 알림(리포트/브리핑).
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[Background Task Pattern]], [[API Client Pattern]], [[모바일 개발 가이드]]
|
||||
- **참조 맥락:** 작은 모델이 알림 기능을 설계할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 푸시(FCM/APNs) 지식
|
||||
- [S2] AstraAI/src/integrations/telegram/*, features/briefing/* — 유사 예
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
Reference in New Issue
Block a user