docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거

Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
2026-07-05 00:33:48 +09:00
parent 1cfd3bbb56
commit 9148c358d0
6455 changed files with 1 additions and 86875 deletions
@@ -0,0 +1,301 @@
+---
+id: wiki-2026-0508-hexagonal-architecture
+title: Hexagonal Architecture
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [hexagonal, ports and adapters, clean architecture, onion architecture, Cockburn]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.96
+verification_status: applied
+tags: [architecture, hexagonal, ports-adapters, clean-architecture, ddd, software-design]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: TypeScript / Python / Java
+  applicable_to: [Backend, DDD, Testable]
+---
+
+# Hexagonal Architecture (Ports and Adapters)
+
+## 매 한 줄
+> **"매 core domain 의 의 의 outside infrastructure 의 separate"**. Alistair Cockburn 2005. 매 inside (domain) → 매 ports (interfaces) → 매 adapters (DB, HTTP, ...). 매 testability + 매 swappable infrastructure 의 핵심. 매 vs Clean Architecture (Uncle Bob): 매 same idea.
+
+## 매 핵심
+
+### 매 layers
+- **Core domain**: 매 entity, value object, business rule.
+- **Application** (use case): 매 orchestration.
+- **Ports**: 매 interface (input port = use case interface, output port = repo interface).
+- **Adapters**:
+  - **Driving** (primary): HTTP controller, CLI.
+  - **Driven** (secondary): DB repo, email gateway.
+
+### 매 dependency rule
+- 매 Outer 매 Inner 의 depend.
+- 매 Inner 매 Outer 의 know X (DI).
+- 매 모든 dependency 매 inward.
+
+### 매 응용
+1. **Backend service**.
+2. **Domain-rich app**.
+3. **Testable codebase**.
+4. **Multi-frontend** (web + mobile + CLI).
+
+### 매 vs others
+- **Clean Architecture** (Uncle Bob): 매 same idea, 매 different name.
+- **Onion**: 매 layer 의 emphasize.
+- **CQRS**: 매 read/write 의 separate, 매 hexagonal 와 compatible.
+
+## 💻 패턴
+
+### TypeScript (NestJS-style)
+```typescript
+// 매 1. Domain (innermost)
+export class Order {
+  constructor(public id: string, public items: Item[], private status: 'NEW' | 'PLACED') {}
+  
+  place() {
+    if (this.items.length === 0) throw new Error('Empty order');
+    this.status = 'PLACED';
+  }
+}
+
+// 매 2. Port (interface)
+export interface OrderRepository {
+  save(order: Order): Promise<void>;
+  findById(id: string): Promise<Order | null>;
+}
+
+// 매 3. Use case (application)
+export class PlaceOrderUseCase {
+  constructor(private orderRepo: OrderRepository, private payments: PaymentGateway) {}
+  
+  async execute(orderId: string) {
+    const order = await this.orderRepo.findById(orderId);
+    if (!order) throw new Error('Not found');
+    order.place();
+    await this.payments.charge(order);
+    await this.orderRepo.save(order);
+  }
+}
+
+// 매 4. Adapter (driven — Postgres)
+export class PostgresOrderRepo implements OrderRepository {
+  async save(order: Order) {
+    await db.query('INSERT INTO orders ...', [...]);
+  }
+  async findById(id: string) {
+    const row = await db.query('SELECT * FROM orders WHERE id = $1', [id]);
+    return row ? toDomain(row) : null;
+  }
+}
+
+// 매 5. Adapter (driving — HTTP)
+@Controller('orders')
+export class OrderController {
+  constructor(private placeOrder: PlaceOrderUseCase) {}
+  
+  @Post(':id/place')
+  async place(@Param('id') id: string) {
+    await this.placeOrder.execute(id);
+    return { status: 'placed' };
+  }
+}
+```
+
+### Folder structure
+```
+src/
+├── domain/
+│   ├── order.ts
+│   └── ports/
+│       ├── order-repository.ts
+│       └── payment-gateway.ts
+├── application/
+│   └── place-order.use-case.ts
+├── infrastructure/
+│   ├── persistence/
+│   │   └── postgres-order-repo.ts
+│   ├── http/
+│   │   └── order-controller.ts
+│   └── external/
+│       └── stripe-payment-gateway.ts
+└── main.ts  ← wire everything
+```
+
+### DI wiring (composition root)
+```typescript
+const orderRepo = new PostgresOrderRepo(db);
+const payments = new StripePaymentGateway(stripeKey);
+const placeOrder = new PlaceOrderUseCase(orderRepo, payments);
+const controller = new OrderController(placeOrder);
+```
+
+### Test (no DB)
+```typescript
+// 매 in-memory adapter for fast test
+class InMemoryOrderRepo implements OrderRepository {
+  private store = new Map<string, Order>();
+  async save(o: Order) { this.store.set(o.id, o); }
+  async findById(id: string) { return this.store.get(id) ?? null; }
+}
+
+class FakePayments implements PaymentGateway {
+  async charge(o: Order) { /* no-op */ }
+}
+
+it('places order', async () => {
+  const repo = new InMemoryOrderRepo();
+  await repo.save(new Order('1', [item], 'NEW'));
+  const uc = new PlaceOrderUseCase(repo, new FakePayments());
+  await uc.execute('1');
+  expect((await repo.findById('1'))!.status).toBe('PLACED');
+});
+```
+
+### Python (FastAPI)
+```python
+# 매 domain
+class Order:
+    def __init__(self, id, items): self.id, self.items = id, items
+    def place(self): self.status = 'placed'
+
+# 매 port
+from abc import ABC, abstractmethod
+class OrderRepository(ABC):
+    @abstractmethod
+    async def save(self, o: Order): pass
+    @abstractmethod
+    async def find_by_id(self, id: str) -> Order: pass
+
+# 매 use case
+class PlaceOrder:
+    def __init__(self, repo: OrderRepository, payments):
+        self.repo = repo; self.payments = payments
+    async def execute(self, order_id):
+        order = await self.repo.find_by_id(order_id)
+        order.place()
+        await self.payments.charge(order)
+        await self.repo.save(order)
+
+# 매 adapter (HTTP)
+@app.post('/orders/{id}/place')
+async def place(id: str, uc: PlaceOrder = Depends(get_use_case)):
+    await uc.execute(id)
+    return {'status': 'placed'}
+```
+
+### Java (Spring)
+```java
+// 매 domain
+public class Order {
+    public void place() { ... }
+}
+
+// 매 port
+public interface OrderRepository {
+    void save(Order order);
+    Optional<Order> findById(String id);
+}
+
+// 매 use case
+@Service
+public class PlaceOrderUseCase {
+    private final OrderRepository orderRepo;
+    private final PaymentGateway payments;
+    
+    public PlaceOrderUseCase(OrderRepository r, PaymentGateway p) {
+        this.orderRepo = r; this.payments = p;
+    }
+    
+    public void execute(String id) {
+        Order order = orderRepo.findById(id).orElseThrow();
+        order.place();
+        payments.charge(order);
+        orderRepo.save(order);
+    }
+}
+```
+
+### Anti-corruption layer
+```typescript
+// 매 external API → 매 domain DTO
+class StripeAdapter implements PaymentGateway {
+  async charge(order: Order) {
+    const stripeRequest = this.toStripeFormat(order);
+    const stripeResp = await this.stripe.charges.create(stripeRequest);
+    if (stripeResp.status !== 'succeeded') throw new PaymentFailed();
+  }
+  
+  private toStripeFormat(order: Order) {
+    // 매 isolate domain from Stripe schema
+    return { amount: order.totalCents(), currency: 'usd', ... };
+  }
+}
+```
+
+### Multiple adapters (frontend)
+```typescript
+// 매 same use case — 매 web + mobile + CLI
+const useCase = new PlaceOrderUseCase(repo, payments);
+new HttpAdapter(useCase).listen(3000);
+new GraphQLAdapter(useCase).listen(4000);
+new CliAdapter(useCase).run();
+```
+
+### Eval architecture (lint check)
+```javascript
+// 매 ESLint rule: 매 domain 매 infrastructure 의 import X
+{
+  rules: {
+    'import/no-restricted-paths': ['error', {
+      zones: [
+        { target: 'src/domain', from: 'src/infrastructure' },
+        { target: 'src/application', from: 'src/infrastructure' },
+      ],
+    }],
+  }
+}
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| Domain-rich service | Hexagonal |
+| CRUD-only | Lighter (no full hex) |
+| Multi-frontend | Hexagonal benefit ↑ |
+| Long-lived | Worth the upfront |
+| Throwaway | Skip |
+
+**기본값**: 매 domain-rich = hexagonal + 매 lint enforced + 매 in-memory test adapter + 매 composition root + 매 anti-corruption layer for external.
+
+## 🔗 Graph
+- 부모: [[Architecture]]
+- 변형: [[Clean-Architecture]] · [[Onion-Architecture]]
+- 응용: [[Domain-Driven-Design]] · [[CQRS]] · [[Testability]]
+- Adjacent: [[Encapsulation-of-Domain-Invariants]] · [[Dependency_Injection_(DI)|Dependency-Injection]] · [[Anti-Corruption-Layer]]
+
+## 🤖 LLM 활용
+**언제**: 매 backend service. 매 domain-rich. 매 long-lived.
+**언제 X**: 매 simple CRUD. 매 prototype.
+
+## ❌ 안티패턴
+- **Anemic domain**: 매 domain has no logic.
+- **Leak infrastructure into domain**: 매 violate dependency rule.
+- **Single-impl interfaces**: 매 over-abstraction.
+- **No lint enforcement**: 매 architecture decay.
+- **Skip composition root**: 매 wiring chaos.
+
+## 🧪 검증 / 중복
+- Verified (Cockburn 2005, Uncle Bob Clean Architecture).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-04-20 | Auto |
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — layers + 매 TS / Python / Java / lint / ACL code |