# API Integration Workflow

> 작업 프로세스 정의 및 간소화 가이드

---

## 1. 작업 유형별 프로세스

### 1.1 단일 작업 (code-workflow 5단계)
**적용**: 1-2개 파일 수정, 중요 변경

```
분석 → 수정 → 검증 → 정리 → 커밋
```

1. **분석**: 변경 대상 파일 확인, 영향 범위 파악
2. **수정**: 코드 변경 실행
3. **검증**: 린트, 타입체크, 테스트
4. **정리**: 코드 정리, 임시 파일 제거
5. **커밋**: 변경사항 커밋 (승인 후)

### 1.2 배치 작업 (간소화 프로세스)
**적용**: 여러 파일 유사 수정, 대량 작업

```
배치 분석 → 배치 계획 승인 → 순차 수정 → 전체 검증 → 배치 커밋
```

1. **배치 분석**: 여러 파일 한번에 분석
2. **배치 계획 승인**: 전체 계획 한번만 승인
3. **순차 수정**: 개별 파일 수정 (개별 승인 생략)
4. **전체 검증**: 모든 수정 완료 후 검증
5. **배치 커밋**: 기능 단위로 커밋

### 1.3 반복 작업 (템플릿 프로세스)
**적용**: 동일 패턴 다수 적용

```
패턴 정의 → 승인 → 일괄 적용 → 검증 → 커밋
```

1. **패턴 정의**: 변경 패턴 정의 (예: API URL 교체)
2. **승인**: 패턴 적용 승인
3. **일괄 적용**: 모든 대상에 패턴 적용
4. **검증**: 결과 확인
5. **커밋**: 변경사항 커밋

---

## 2. 승인 필요 지점

### 반드시 승인 필요
| 작업 | 승인 시점 |
|------|----------|
| 파일 생성/삭제 | 작업 전 |
| API 엔드포인트 수정 | 계획 단계 |
| 테이블 구조 변경 | 계획 단계 |
| 커밋 | 커밋 직전 |

### 승인 생략 가능
| 작업 | 조건 |
|------|------|
| 배치 수정 내 개별 파일 | 배치 계획 승인 후 |
| 문서 업데이트 | PROGRESS.md, 로그 등 |
| 린트/포맷팅 | 자동 수정 |

---

## 3. 세션 라이프사이클

### 세션 시작
```bash
# 1. Serena 메모리 확인
serena.list_memories()
serena.read_memory("api-integration-state")

# 2. PROGRESS.md 확인
# 3. "다음 액션"부터 재개
```

### 작업 중
```bash
# 마일스톤마다 업데이트
- PROGRESS.md 체크리스트 업데이트
- 중요 결정사항 기록
- serena.write_memory() (선택)
```

### 세션 종료 전
```bash
# 1. PROGRESS.md 최종 업데이트
# 2. Serena 메모리 저장
serena.write_memory("api-integration-state", {
  current_phase: "phase-3",
  current_task: "매핑 매트릭스 작성",
  next_action: "거래처 API 매핑",
  last_updated: "2025-12-20 15:30"
})

# 3. /clear 또는 세션 종료
```

---

## 4. 연동 작업 상세 프로세스

### 4.1 API 매핑 작업
```
1. React 페이지 확인
   └── 어떤 데이터가 필요한지 파악

2. API 엔드포인트 검색
   └── 기존 API 중 맞는 것 찾기

3. 매핑 결정
   ├── 완벽 일치 → 바로 연동
   ├── 부분 일치 → API 수정 필요
   └── 없음 → 신규 개발 필요

4. 문서화
   └── mapping-matrix.md 업데이트
```

### 4.2 연동 작업
```
1. React 코드 확인
   └── API 호출 위치, 데이터 구조

2. API 응답 확인
   └── Swagger 또는 실제 호출

3. 불일치 해결
   ├── React 수정 (API 구조가 맞는 경우)
   └── API 수정 (React 요구사항 우선)

4. 테스트
   └── 화면에서 동작 확인

5. 로깅
   └── integration-log.md 업데이트
```

---

## 5. 이슈 처리 프로세스

### 이슈 발견 시
```
1. 이슈 문서 생성
   └── phase-4-integration/issues/ISSUE-XXX.md

2. 이슈 분류
   ├── 🔴 Critical: 기능 작동 불가
   ├── 🟡 Major: 기능 일부 제한
   └── 🟢 Minor: 개선 사항

3. 해결 및 기록
   └── 해결 방법, 변경 파일 기록
```

### 이슈 문서 템플릿
```markdown
# ISSUE-XXX: [이슈 제목]

## 상태: 🔴 Open / 🟢 Resolved

## 설명
[이슈 상세 설명]

## 재현 방법
1. ...
2. ...

## 원인
[원인 분석]

## 해결 방법
[해결 방법]

## 변경 파일
- [ ] file1.ts
- [ ] file2.php
```

---

## 6. 커밋 메시지 규칙

### 형식
```
[프로젝트] 타입: 제목

본문 (선택)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
```

### 타입
| 타입 | 설명 |
|------|------|
| feat | 새 기능 |
| fix | 버그 수정 |
| refactor | 리팩토링 |
| docs | 문서 |
| chore | 기타 |

### 예시
```
[API] feat: items API 응답에 category 정보 추가

- ItemService에서 category eager loading
- ItemResource에 category 필드 추가

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
```

---

## 7. 도구 활용

### MCP 서버
| 서버 | 용도 |
|------|------|
| Sequential Thinking | 복잡한 분석, 설계 |
| Serena | 메모리, 심볼 검색 |
| Context7 | 공식 문서 참조 |

### SuperClaude 페르소나
| 페르소나 | 용도 |
|----------|------|
| backend-architect | API 설계, 구현 |
| frontend-architect | React 구조 |
| quality-engineer | 테스트, 검증 |

---

## 8. 체크리스트

### 작업 시작 전
- [ ] PROGRESS.md 확인
- [ ] 현재 Phase 파악
- [ ] 다음 액션 확인

### 작업 중
- [ ] 체크리스트 업데이트
- [ ] 이슈 발생 시 문서화
- [ ] 변경사항 로깅

### 작업 완료 후
- [ ] PROGRESS.md 업데이트
- [ ] Serena 메모리 저장
- [ ] 커밋 (승인 후)

---

*이 문서는 작업 효율성을 위해 필요 시 업데이트됩니다.*