docs(10_Wiki): 위키 구조 정리 — 언어 튜토리얼 카테고리 폴더 제거 + 신규 자산 동기화
Topic_CSS/Topic_HTML/Topic_JavaScript/Topic_Prompt/Topic_Comfyui 등 기존 카테고리 폴더를 정리하고, Topic_Graphic/Dev 등 신규 산출물과 Topics 내부 세션/메모리 기록을 동기화.
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: pattern-architecture-separation
|
||||
title: "Architecture Separation Pattern"
|
||||
category: "Pattern_CrossCutting"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["layering", "아키텍처 분리", "관심사 분리", "separation of concerns", "layered architecture", "ports and adapters"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.88
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["pattern", "cross-cutting", "architecture", "layering", "platform-independent"]
|
||||
raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src 구조 (적용 예)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[Architecture Separation Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
아키텍처 분리는 "**관심사를 계층/모듈로 나누고, 의존은 한 방향(안정적인 쪽으로)으로만 흐르게**" 하는 것으로, 플랫폼이 달라도 UI/도메인/인프라를 섞지 않는 것이 유지보수의 토대다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **계층:** 인프라(core) → 역량(lib/도메인 서비스) → 기능(features) → 조립(entry). 위가 아래에 의존.
|
||||
2. **관심사 분리:** UI / 도메인 로직 / I/O 를 섞지 않는다.
|
||||
3. **의존성 역전:** 도메인이 인프라 *인터페이스* 에 의존, 구현은 주입.
|
||||
4. **경계(ports & adapters):** 외부(DB/API/UI)는 어댑터로, 핵심은 순수.
|
||||
5. **단일 책임:** 한 모듈은 한 가지 변경 이유.
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** 코드가 커지며 UI/로직/I/O 가 엉켜 변경이 두려울 때.
|
||||
- **사용 조건:** 책임 경계를 식별 가능; 인터페이스로 추상화 가능.
|
||||
- **장점:** 변경 격리, 테스트성(핵심 순수), 교체 용이(어댑터), 병렬 작업.
|
||||
- **단점:** 초기 보일러플레이트, 과한 계층은 오버헤드("얇은 래퍼 지옥").
|
||||
- **대안:** 모놀리식 단순 구조(소규모), 수직 슬라이스(기능별 풀스택), 모듈러 모놀리스.
|
||||
- **실패 사례:** UI 에 비즈니스 로직 혼입; 도메인이 DB/프레임워크에 직접 의존(교체 불가); 순환 의존; 계층 우회(아래가 위 호출).
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
features/ -> lib/도메인서비스 -> core/인프라 # 단방향 의존
|
||||
domain depends on interface (IRepo, IAIService) # 의존성 역전
|
||||
adapter implements interface (FileRepo, AIService)
|
||||
entrypoint wires them (composition root) # 조립은 한 곳
|
||||
```
|
||||
적용 예: AstraAI 계층(core/lib/memory/retrieval/intelligence/features) + 인터페이스 서비스([[AstraAI 아키텍처 개요]], [[의존성 주입과 서비스 인터페이스]], [[모듈 시스템과 프로젝트 구성]]).
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
계층이 많을수록 격리는 좋아지나 단순 변경도 여러 파일을 거친다 — 규모에 맞춰라. 흐름 가독성을 위해 *골격은 한 곳에* 남기는 절충도 유효([[ADR-0010 오케스트레이터 골격 모듈추출]]).
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI 전체 폴더 계층 + DI.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[Repository Pattern]], [[Plugin Architecture Pattern]], [[Data Flow Pattern]], [[프로젝트 독립 설계 원칙]]
|
||||
- **참조 맥락:** 작은 모델이 새 프로젝트의 폴더/계층 구조를 잡을 때 1차 원리.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 계층화/관심사 분리 지식(Clean/Hexagonal)
|
||||
- [S2] AstraAI/src 구조 — 적용 예
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
id: pattern-async-concurrency
|
||||
title: "Async Concurrency Pattern"
|
||||
category: "Pattern_CrossCutting"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["async pattern", "비동기 패턴", "concurrency", "cancellation", "debounce", "throttle"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.89
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["pattern", "cross-cutting", "async", "concurrency", "platform-independent"]
|
||||
raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/core/* (적용 예)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[Async Concurrency Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
비동기 처리는 모든 플랫폼이 공유하는 핵심이며, 안전의 3축은 "**취소 가능(cancellation) · 자원 폭주 방지(제한) · 경쟁 상태 제어(직렬화)**" 다 — UI 멈춤·메모리 폭주·갱신 손실이 여기서 갈린다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **취소:** AbortSignal/토큰으로 진행 중 작업 중단(타임아웃+사용자 취소 결합).
|
||||
2. **동시성 제한:** 큐/세마포어로 동시 실행 수 상한.
|
||||
3. **직렬화:** 공유 자원은 락/뮤텍스로 한 번에 하나.
|
||||
4. **debounce/throttle:** 빈번 이벤트(입력/스크롤)를 솎아냄.
|
||||
5. **병렬 vs 순차:** 독립이면 병렬(all), 의존이면 순차, 부분실패 허용이면 allSettled.
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** I/O·네트워크·장시간 작업이 UI/자원에 영향 줄 때.
|
||||
- **사용 조건:** 취소 신호 전파 가능; 작업 단위 분리 가능.
|
||||
- **장점:** 반응성 유지, 자원 안정, 데이터 일관.
|
||||
- **단점:** 복잡도↑, 콜백/Promise 추론 어려움, 취소 누락 시 좀비 작업.
|
||||
- **대안:** 동기(작은 작업), 워커/스레드(CPU 바운드), 큐 시스템(분산).
|
||||
- **실패 사례:** 취소 미전파로 좀비 fetch; Promise.all 부분 실패로 전체 손실; 무한 병렬 OOM; 락 미해제 데드락; forEach+async 로 미대기.
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
signal = combine(userAbort, timeout(ms)) # 취소 = 사용자 OR 타임아웃
|
||||
await fetch(url, { signal })
|
||||
await queue.enqueue(task) # 동시성 상한
|
||||
release = await lock.acquire(id); try{...} finally{ release() } # 직렬화
|
||||
onInput = debounce(handler, 200) # 이벤트 솎기
|
||||
results = await Promise.allSettled(tasks) # 부분 실패 허용
|
||||
```
|
||||
적용 예: [[비동기 프로그래밍 Promise async await]], [[동시성 제어 Lock Queue Transaction]], [[AITRAIN 동시성 제어]].
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"병렬이 빠르다" 는 자원 한도 내에서만 참 — 한도를 넘으면 스왑/OOM 으로 더 느려진다([[ADR-0004 순차 디스패치 채택]]).
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI services(AbortSignal), lock/queue.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[Background Worker Pattern]], [[Background Task Pattern]], [[Error Handling Pattern]]
|
||||
- **참조 맥락:** 작은 모델이 어떤 플랫폼이든 비동기 코드를 쓸 때 1차 원리.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 비동기/동시성 지식
|
||||
- [S2] AstraAI/src/core/services.ts, lock.ts, queue.ts — 적용 예
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
id: pattern-caching
|
||||
title: "Caching Pattern"
|
||||
category: "Pattern_CrossCutting"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["caching", "캐싱", "memoization", "TTL", "invalidation", "mtime cache"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.88
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["pattern", "cross-cutting", "caching", "performance", "platform-independent"]
|
||||
raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/retrieval/scoring.ts, src/lib/mtimeFileCache.ts (적용 예)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[Caching Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
캐싱은 "비싼 계산/조회 결과를 저장해 재사용" 하는 보편 최적화이며, 어려운 것은 캐싱 자체가 아니라 "**언제 무효화(invalidation)하느냐**" 다 — stale 데이터는 성능보다 더 큰 버그를 만든다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **memoization:** 같은 입력→같은 출력을 키로 저장.
|
||||
2. **무효화 전략:** TTL(시간), 버전/해시, 변경 감지(mtime), 수동.
|
||||
3. **캐시 키 설계:** 입력을 정확히 식별(누락 시 잘못된 hit).
|
||||
4. **용량 제한:** LRU/상한으로 무한 증가 방지.
|
||||
5. **계층:** 메모리→디스크→원격, 가까울수록 빠름.
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** 동일 계산/조회가 반복되고 비용이 클 때, 결과가 자주 안 바뀔 때.
|
||||
- **사용 조건:** 결정적 입력→출력; 무효화 신호 존재; 메모리/디스크 여유.
|
||||
- **장점:** 지연·비용 대폭↓, 부하 완화.
|
||||
- **단점:** stale 위험, 메모리 사용, 무효화 복잡, 캐시 키 버그.
|
||||
- **대안:** 매번 계산(정확성 우선), 사전 계산(배치), 증분 갱신.
|
||||
- **실패 사례:** 무효화 누락으로 옛 데이터 제공; 키 충돌로 잘못된 hit; 무한 증가 OOM; 변경 감지 누락(mtime 미갱신).
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
# memoization + 용량 제한
|
||||
if cache.has(key): return cache.get(key)
|
||||
val = expensive(input); if cache.size >= LIMIT: cache.clear(); cache.set(key, val)
|
||||
|
||||
# 변경 감지 무효화 (파일)
|
||||
if file.mtime != cached.mtime: cached = reindex(file) # 변경된 파일만 재계산
|
||||
```
|
||||
적용 예: AstraAI 의 TOKEN_CACHE(토크나이저 memoization, 상한 시 clear) + mtime 키 brain 인덱스(변경 없는 파일 재토큰화 회피) [S2]. RAG 의 dense/sparse 인덱스도 캐시.
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"캐시하면 빠르다" 의 이면은 "무효화를 틀리면 조용히 틀린 답" — Phil Karlton 의 "캐시 무효화는 컴퓨터 과학의 2대 난제". 변경 감지(mtime/해시)가 TTL 보다 정확할 때가 많다.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI 토큰 캐시 + mtime 인덱스([[TF-IDF 이중언어 스코어링]], [[RAG 검색 파이프라인]]).
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[Local Storage Pattern]], [[API Client Pattern]], [[RAG Pattern]], [[소프트웨어 실패 라이브러리]]
|
||||
- **참조 맥락:** 작은 모델이 성능 최적화를 할 때 무효화 전략과 함께 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 캐싱 공학 지식
|
||||
- [S2] AstraAI/src/retrieval/scoring.ts(TOKEN_CACHE), brainIndex/mtimeFileCache — 적용 예
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
id: pattern-data-flow
|
||||
title: "Data Flow Pattern"
|
||||
category: "Pattern_CrossCutting"
|
||||
status: "draft"
|
||||
verification_status: "conceptual"
|
||||
canonical_id: ""
|
||||
aliases: ["data flow", "데이터 흐름", "pipeline", "transform", "boundary normalization"]
|
||||
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", "cross-cutting", "data-flow", "pipeline", "platform-independent"]
|
||||
raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/retrieval/*, src/features/providers/* (적용 예)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[Data Flow Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
데이터 흐름 설계의 핵심은 "**경계에서 정규화하고(입력 검증·형식 통일), 내부는 단일 형태로 다루며, 변환을 작은 순수 단계의 파이프라인으로**" 만드는 것이다 — 그러면 어디서 무엇이 변하는지 추적된다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **경계 정규화:** 외부 입력(API/파일/사용자)을 들어오자마자 내부 표준 형태로 변환·검증.
|
||||
2. **단일 내부 모델:** 내부는 하나의 형태만 — 분기/특수처리를 가장자리로.
|
||||
3. **파이프라인:** 변환을 작은 순수 단계로 연결(test 가능).
|
||||
4. **출력 정규화:** 다양한 백엔드를 같은 출력 형식으로(예: SSE).
|
||||
5. **불변 전달:** 단계 간 데이터를 변형 대신 새 값 생성.
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** 이질적 소스/싱크가 많고 변환 단계가 여러 개일 때.
|
||||
- **사용 조건:** 표준 내부 모델 정의 가능; 단계 분해 가능.
|
||||
- **장점:** 추적성, 테스트성(순수 단계), 소스/싱크 추가 용이, 버그 격리.
|
||||
- **단점:** 변환 레이어 비용, 과한 추상화는 오버헤드.
|
||||
- **대안:** 직접 결합(소규모), 스트림 처리(대용량), 이벤트 버스(느슨 결합).
|
||||
- **실패 사례:** 경계 검증 누락으로 내부에 오염 전파; 내부에 외부 형식 누수(공급자별 분기 산재); 가변 전달로 단계 간 부작용.
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
internal = normalizeAtBoundary(externalInput) # 들어올 때 1회 정규화 + 검증
|
||||
result = stage3(stage2(stage1(internal))) # 작은 순수 단계 파이프라인
|
||||
output = toStandardFormat(result) # 나갈 때 형식 통일 (예: SSE)
|
||||
```
|
||||
적용 예: [[LLM 프로바이더 추상화]](공급자별 입력 정규화→공통 SSE 출력), [[RAG 검색 파이프라인]](tokenize→score→fuse→budget).
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
경계 정규화는 비용이지만, 생략하면 특수처리가 코드 전체로 번진다 — "차이는 가장자리에서 흡수" 원칙([[AITRAIN 프로바이더 추상화]]).
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI provider 어댑터, retrieval 파이프라인.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[State Management Pattern]], [[Repository Pattern]], [[API Client Pattern]], [[Architecture Separation Pattern]]
|
||||
- **참조 맥락:** 작은 모델이 입출력 변환이 많은 코드를 설계할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 데이터 흐름/파이프라인 지식
|
||||
- [S2] AstraAI/src/retrieval/*, features/providers/* — 적용 예
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
id: pattern-error-handling
|
||||
title: "Error Handling Pattern"
|
||||
category: "Pattern_CrossCutting"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["error handling", "오류 처리 패턴", "graceful degradation", "result type", "retry", "fallback"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.89
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["pattern", "cross-cutting", "error-handling", "resilience", "platform-independent"]
|
||||
raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/core/* (적용 예)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[Error Handling Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
견고한 오류 처리는 "**실패를 분류하고(복구 가능/불가), 흔한 실패는 결과값으로·예외는 진짜 예외에, 부가 작업 실패는 본류를 막지 않게, 사용자에겐 행동 지침으로 번역**" 하는 것이다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **분류:** 복구 가능(재시도/폴백) vs 불가(즉시 실패) vs 부가(무시).
|
||||
2. **결과 타입 vs 예외:** 흔한 실패는 `{ok,error}` 유니온, 계약 위반은 throw.
|
||||
3. **재시도/폴백:** 일시 오류는 backoff 재시도, 대안 경로 폴백.
|
||||
4. **graceful degradation:** 핵심은 살리고 부가만 끈다(이유 주석 필수).
|
||||
5. **사용자 번역:** 기술 에러→무엇을 하면 되는지.
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** I/O·네트워크·외부 의존이 있는 모든 코드.
|
||||
- **사용 조건:** 실패 유형을 구분 가능; 복구/대안 전략 존재.
|
||||
- **장점:** 복원력, 디버깅 용이, UX 개선, 부분 장애 격리.
|
||||
- **단점:** 코드량↑, 잘못된 삼킴은 버그 은폐.
|
||||
- **대안:** 크래시-온리(빠른 실패+재시작), 서킷 브레이커(연속 실패 차단).
|
||||
- **실패 사례:** 무음 빈 catch 로 실패 은폐; `||` 로 0/'' 삼킴; 무한 재시도; 사용자에게 raw 스택 노출; 부가 실패가 본류 중단.
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
result = op() -> { ok:true, val } | { ok:false, error } # 흔한 실패는 유니온
|
||||
for engine in engines: try { return call(engine) } catch { last=e } # 폴백
|
||||
try { sideEffect() } catch { /* 부가 — 본류 안 막음(이유 주석) */ }
|
||||
showUser(translate(error)) # 행동 지침으로 번역
|
||||
catch (e) { err = e instanceof Error ? e : new Error(String(e)) } # 정규화
|
||||
```
|
||||
적용 예: [[에러 처리와 커스텀 에러]](G1Error 계층, ErrorTranslator, 보상 트랜잭션), [[LLM 프로바이더 추상화]](엔진 폴백).
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
"모든 에러를 잡아라" 와 "빠르게 실패하라" 의 균형 — 복구 불가·계약 위반은 던지고, 일시·부가만 흡수. 빈 catch 는 *부가 작업 + 이유 주석* 일 때만.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI errors/errorHandler/transaction/services.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[Async Concurrency Pattern]], [[API Client Pattern]], [[소프트웨어 실패 라이브러리]], [[안티패턴 카탈로그]]
|
||||
- **참조 맥락:** 작은 모델이 어떤 플랫폼이든 실패 경로를 작성할 때 1차 원리.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 오류 처리/복원력 지식
|
||||
- [S2] AstraAI/src/core/errors.ts, errorHandler.ts, transaction.ts, services.ts — 적용 예
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: pattern-state-management
|
||||
title: "State Management Pattern"
|
||||
category: "Pattern_CrossCutting"
|
||||
status: "draft"
|
||||
verification_status: "conceptual"
|
||||
canonical_id: ""
|
||||
aliases: ["state management", "상태 관리", "single source of truth", "unidirectional data flow"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.88
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["pattern", "cross-cutting", "state", "platform-independent"]
|
||||
raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/sidebar/managers/* (적용 예)"]
|
||||
applied_in: ["AstraAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[State Management Pattern]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
상태 관리의 본질은 플랫폼(웹/모바일/데스크탑)을 막론하고 "**단일 진실 원천(Single Source of Truth) + 단방향 데이터 흐름 + 명시적 변경**" 으로, 상태가 흩어지고 양방향으로 얽힐수록 버그가 기하급수로 는다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **Single Source of Truth:** 같은 데이터를 한 곳에만 둔다(중복 상태 = 동기화 버그).
|
||||
2. **단방향 흐름:** 상태→뷰 렌더, 이벤트→상태 변경(역류 금지).
|
||||
3. **파생 상태 vs 원천 상태:** 계산 가능한 건 저장하지 말고 derive.
|
||||
4. **로컬 vs 전역:** 한 컴포넌트만 쓰면 로컬, 여러 곳이 공유하면 전역(끌어올림).
|
||||
5. **불변 업데이트:** 상태를 *교체* 로 갱신해 변경 추적/되돌리기 용이.
|
||||
|
||||
## 📖 세부 내용 (Details · 패턴 명세)
|
||||
- **Problem (언제 쓰나):** UI/세션/도메인 상태가 여러 곳에서 읽고 쓰일 때.
|
||||
- **사용 조건:** 상태 소유자를 정할 수 있을 때; 변경 경로를 한정할 수 있을 때.
|
||||
- **장점:** 예측 가능, 디버깅 용이(변경 추적), 동기화 버그↓, 테스트 용이.
|
||||
- **단점:** 보일러플레이트, 과한 전역화는 결합↑, 작은 앱엔 과설계.
|
||||
- **대안:** 로컬 상태만(소규모), 서버 상태를 진실로(react-query류), 이벤트 소싱(이력 필요 시).
|
||||
- **실패 사례:** 같은 데이터를 두 곳에 저장→불일치; 파생값을 저장→stale; 컴포넌트가 부모 상태 직접 변경(역류); 전역 store 에 모든 걸 넣어 결합 폭증.
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```text
|
||||
state = SingleStore(initial)
|
||||
view = render(state) # 상태 → 뷰
|
||||
onEvent(e): state = reducer(state, e) # 이벤트 → 새 상태(불변 교체) → 재렌더
|
||||
derived = useMemo(() => compute(state))# 파생은 저장 말고 계산
|
||||
```
|
||||
적용 예: AstraAI 의 sessionStateStore/chatSessionStore 등 manager 가 상태 소유, webview 는 메시지로만 변경 요청([[VSCode 확장 구조와 생명주기]]).
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
전역 상태 라이브러리(Redux 등)가 항상 답은 아니다 — 서버 상태는 캐시 라이브러리에, UI 지역 상태는 로컬에, 진짜 공유 도메인 상태만 전역에.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
AstraAI sidebar managers(상태 소유 + 메시지 변경).
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[패턴 카탈로그 인덱스]]
|
||||
- **관련 개념:** [[Data Flow Pattern]], [[React State Pattern]], [[Caching Pattern]], [[프로젝트 독립 설계 원칙]]
|
||||
- **참조 맥락:** 작은 모델이 어떤 플랫폼이든 UI/앱 상태를 설계할 때 1차 원리.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] 일반 상태 관리 공학 지식
|
||||
- [S2] AstraAI/src/sidebar/managers/* — 적용 예
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
|
||||
Reference in New Issue
Block a user