sam-docs/projects/api-integration/WORKFLOW.md

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. 세션 라이프사이클

세션 시작

# 1. Serena 메모리 확인
serena.list_memories()
serena.read_memory("api-integration-state")

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

작업 중

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

세션 종료 전

# 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. 해결 및 기록
   └── 해결 방법, 변경 파일 기록

이슈 문서 템플릿

# 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 메모리 저장
• 커밋 (승인 후)

---

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