sam-docs/plans/construction-api-integration-plan.md

# 시공사 페이지 API 연동 계획

> **작성일**: 2026-01-08
> **목적**: 시공사 8개 페이지 Mock → API 연동
> **기준 문서**: `docs/standards/api-rules.md`, `docs/guides/swagger-guide.md`
> **상태**: 🔄 진행중

---

## 📍 현재 진행 상태

| 항목 | 내용 |
|------|------|
| **마지막 완료 작업** | Phase 3.2: 품목관리 API 연동 완료 ✅ |
| **다음 작업** | Phase 3.3: 단가관리 API 연동 |
| **진행률** | 6/8 (75%) |
| **마지막 업데이트** | 2026-01-09 |

---

## 0. 전제 조건 (Prerequisites)

### 0.1 환경 확인
```bash
# Docker 컨테이너 상태 확인
docker ps | grep sam

# API 서버 접속 확인
curl -I http://api.sam.kr/api/health

# React 개발 서버 확인
curl -I http://react.sam.kr
```

**체크리스트:**
- [ ] Docker 컨테이너 실행 중 (api, react, mysql)
- [ ] api.sam.kr 접속 가능 (200 응답)
- [ ] react.sam.kr 접속 가능 (200 응답)
- [ ] 데이터베이스 연결 정상

### 0.2 권한 및 인증
- [ ] API 개발 권한 (`api/` 디렉토리 수정 가능)
- [ ] React 개발 권한 (`react/` 디렉토리 수정 가능)
- [ ] Sanctum 토큰 발급 방법 숙지 (테스트용)

### 0.3 필수 도구
- PHP 8.4+, Composer
- Node.js 20+, pnpm
- Git

---

## 1. 개요

### 1.1 배경
시공사 메뉴의 8개 페이지가 현재 모두 Mock 데이터를 사용하고 있으며, 실제 API 연동이 필요함.
(물량검토관리는 Frontend/기획 미존재로 제외)

### 1.2 기준 원칙
```
┌─────────────────────────────────────────────────────────────────┐
│  🎯 핵심 원칙                                                    │
├─────────────────────────────────────────────────────────────────┤
│  - Service-First: 비즈니스 로직 → Service Layer                  │
│  - Multi-tenancy: BelongsToTenant 필수                          │
│  - FormRequest: Controller 검증 금지                            │
│  - Server Actions: React에서 'use server' 패턴 사용              │
└─────────────────────────────────────────────────────────────────┘
```

### 1.3 변경 승인 정책

| 분류 | 예시 | 승인 |
|------|------|------|
| ✅ 즉시 가능 | actions.ts Mock→API 변경, 타입 수정 | 불필요 |
| ⚠️ 컨펌 필요 | 새 API 엔드포인트 생성, DB 스키마 변경 | **필수** |
| 🔴 금지 | 기존 API 삭제, 테이블 구조 변경 | 별도 협의 |

### 1.4 준수 규칙
- `docs/standards/api-rules.md` - API 개발 규칙 ✅ 존재
- `docs/guides/swagger-guide.md` - Swagger 작성 가이드 ✅ 존재
- `docs/standards/quality-checklist.md` - 품질 체크리스트 ✅ 존재

---

## 2. 대상 범위

### 2.1 Phase 1: 계약관리 (Contract)

| # | 작업 항목 | 상태 | 서브 문서 |
|---|----------|:----:|----------|
| 1.1 | 계약관리 (contract) | ✅ | [contract-plan.md](./sub/contract-plan.md) |
| 1.2 | 인수인계보고서관리 (handover-report) | ✅ | [handover-report-plan.md](./sub/handover-report-plan.md) |

### 2.2 Phase 2: 발주관리 (Order)

| # | 작업 항목 | 상태 | 서브 문서 |
|---|----------|:----:|----------|
| 2.1 | 현장관리 (site-management) | ✅ | [site-management-plan.md](./sub/site-management-plan.md) |
| 2.2 | 구조검토관리 (structure-review) | ✅ | [structure-review-plan.md](./sub/structure-review-plan.md) |
| 2.3 | 물량검토관리 (quantity-review) | ❌ 제외 | Frontend/기획 미존재 |

### 2.3 Phase 3: 기준정보 (Base Info)

| # | 작업 항목 | 상태 | 서브 문서 |
|---|----------|:----:|----------|
| 3.1 | 카테고리관리 (categories) | ✅ | [categories-plan.md](./sub/categories-plan.md) |
| 3.2 | 품목관리 (items) | ✅ | [items-plan.md](./sub/items-plan.md) |
| 3.3 | 단가관리 (pricing) | ⏳ | [pricing-plan.md](./sub/pricing-plan.md) |
| 3.4 | 노임관리 (labor) | ⏳ | [labor-plan.md](./sub/labor-plan.md) |

---

## 3. API 현황 분석

### 3.1 기존 API (연동 가능)

| API | 경로 | 상태 | 대상 컴포넌트 |
|-----|------|:----:|--------------|
| categories | `/api/construction/categories` | ✅ 존재 | 카테고리관리 |
| pricing | `/api/construction/pricing` | ✅ 존재 | 단가관리 |

### 3.2 신규 개발 필요 API

| API | 예상 경로 | 우선순위 | 대상 컴포넌트 |
|-----|----------|:--------:|--------------|
| contracts | `/api/construction/contracts` | ✅ 완료 | 계약관리 |
| handover-reports | `/api/construction/handover-reports` | ✅ 완료 | 인수인계보고서 |
| sites | `/api/construction/sites` | ✅ 완료 | 현장관리 |
| structure-reviews | `/api/construction/structure-reviews` | ✅ 완료 | 구조검토관리 |
| quantity-reviews | `/api/construction/quantity-reviews` | ❌ 제외 | 물량검토관리 (Frontend/기획 미존재) |
| items | `/api/construction/items` | 🟢 낮음 | 품목관리 |
| labor | `/api/construction/labor` | 🟢 낮음 | 노임관리 |

---

## 4. 작업 절차

### 4.1 단계별 절차 (상세)

```
Step 1: 서브 문서 확인
├── docs/plans/sub/{module}-plan.md 읽기
├── 현재 Mock 데이터 구조 확인
└── 필요한 API 엔드포인트 파악

Step 2: API 엔드포인트 확인/생성
├── api/routes/api.php에서 기존 API 확인
├── 없으면:
│   ├── Controller 생성: php artisan make:controller Api/Construction/{Name}Controller
│   ├── Service 생성: app/Services/Construction/{Name}Service.php
│   ├── FormRequest 생성: php artisan make:request Api/Construction/{Name}Request
│   └── Model 확인/생성
└── Swagger 문서 작성

Step 3: React actions.ts 수정
├── react/src/components/business/construction/{module}/actions.ts 열기
├── Mock 데이터 상수 제거 (MOCK_XXX)
├── API 호출 로직 구현:
│   └── const response = await fetch('/api/construction/{endpoint}', {...})
└── 에러 핸들링 추가

Step 4: 타입 정합성 확인
├── API 응답과 프론트엔드 타입 매칭
├── types.ts 수정 (snake_case → camelCase 변환 등)
└── 컴포넌트 수정 (필요시)

Step 5: 테스트 및 검증
├── API 직접 호출 테스트 (curl/Postman)
├── UI 동작 확인 (브라우저)
└── 에러 케이스 테스트
```

### 4.2 첫 번째 작업 시작점

**Phase 1.1 계약관리 시작:**
```bash
# 1. 서브 문서 읽기
cat docs/plans/sub/contract-plan.md

# 2. 현재 Mock 확인
cat react/src/components/business/construction/contract/actions.ts

# 3. API 존재 여부 확인
grep -n "contracts" api/routes/api.php

# 4. 없으면 Controller 생성
cd api && php artisan make:controller Api/Construction/ContractController --resource
```

---

## 5. 환경 정보

### 5.1 프로젝트 구조

```
SAM/
├── api/                    # Laravel 12 REST API
│   ├── app/Http/Controllers/Api/Construction/
│   ├── app/Services/Construction/
│   └── routes/api.php
│
├── react/                  # Next.js 15 Frontend
│   └── src/
│       ├── app/[locale]/(protected)/construction/
│       │   ├── project/contract/           # 계약관리
│       │   ├── project/contract/handover-report/  # 인수인계
│       │   ├── order/site-management/      # 현장관리
│       │   ├── order/structure-review/     # 구조검토
│       │   ├── order/order-management/     # 발주관리
│       │   └── order/base-info/            # 기준정보
│       │       ├── categories/
│       │       ├── items/
│       │       ├── pricing/
│       │       └── labor/
│       └── components/business/construction/
│
└── docs/plans/             # 계획 문서
    ├── construction-api-integration-plan.md  # 메인 (현재 문서)
    └── sub/                # 서브 문서 (9개)
```

### 5.2 개발 환경

| 항목 | 값 |
|------|-----|
| 도메인 | sam.kr (로컬) |
| API | api.sam.kr |
| React | react.sam.kr |
| PHP | 8.4+ |
| Laravel | 12 |
| Next.js | 15 |

---

## 6. 컴포넌트 분석 요약

### 6.1 계약관리 (Contract)

| 컴포넌트 | Mock 상태 | 주요 기능 |
|----------|:--------:|----------|
| ContractListClient | ✅ Mock | 목록, 검색, 삭제, 필터 |
| 인수인계보고서 | ✅ Mock | 목록, 상세, 삭제 |

### 6.2 발주관리 (Order)

| 컴포넌트 | Mock 상태 | 주요 기능 |
|----------|:--------:|----------|
| SiteManagementListClient | ✅ Mock | 현장 목록, 통계, 삭제 |
| StructureReviewListClient | ✅ Mock | 구조검토 목록, 상태 관리 |
| OrderManagementClient | ✅ Mock | 발주 목록, 필터, 삭제 |

### 6.3 기준정보 (Base Info)

| 컴포넌트 | Mock 상태 | API 존재 | 주요 기능 |
|----------|:--------:|:-------:|----------|
| CategoryManagementClient | ✅ Mock | ✅ | 카테고리 CRUD, 순서 변경 |
| ItemManagementClient | ✅ Mock | ❌ | 품목 CRUD, 카테고리 연결 |
| PricingListClient | ✅ Mock | ✅ | 단가 CRUD, 버전 관리 |
| LaborManagementClient | ✅ Mock | ❌ | 노임 CRUD, 단가 관리 |

---

## 7. 성공 기준

### 7.1 각 페이지 완료 조건

| # | 조건 | 확인 방법 |
|---|------|----------|
| 1 | Mock 데이터 완전 제거 | `grep -r "MOCK_" actions.ts` 결과 없음 |
| 2 | API 호출 성공 | 네트워크 탭에서 200 응답 확인 |
| 3 | UI에서 데이터 정상 표시 | 목록에 실제 데이터 표시 |
| 4 | CRUD 동작 정상 | 생성/조회/수정/삭제 모두 동작 |
| 5 | 에러 핸들링 동작 | 네트워크 끊김 시 에러 메시지 표시 |

### 7.2 전체 완료 조건

- [ ] 8개 페이지 모두 API 연동 완료 (4/8)
- [ ] Swagger 문서 작성 완료
- [ ] 기본 동작 테스트 통과
- [ ] 코드 리뷰 완료

### 7.3 품질 기준

- API 응답 시간: < 500ms
- 에러 발생 시 사용자 친화적 메시지 표시
- TypeScript 타입 에러 0개
- ESLint 경고 0개

---

## 8. 검증 방법

### 8.1 API 테스트 (curl)

```bash
# 1. 인증 토큰 획득 (테스트용)
TOKEN=$(curl -s -X POST "http://api.sam.kr/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"test@test.com","password":"password"}' | jq -r '.token')

# 2. 계약 목록 조회
curl -X GET "http://api.sam.kr/api/construction/contracts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

# 3. 계약 상세 조회
curl -X GET "http://api.sam.kr/api/construction/contracts/1" \
  -H "Authorization: Bearer $TOKEN"

# 4. 계약 생성
curl -X POST "http://api.sam.kr/api/construction/contracts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"테스트 계약","partner_id":1}'
```

### 8.2 UI 테스트 체크리스트

```
□ 페이지 접속 시 로딩 스피너 표시
□ 데이터 로딩 완료 후 목록 표시
□ 검색 기능 동작
□ 필터 기능 동작
□ 페이지네이션 동작
□ 상세 보기 동작
□ 생성 폼 동작
□ 수정 폼 동작
□ 삭제 확인 및 동작
□ 에러 발생 시 메시지 표시
```

### 8.3 에러 케이스 테스트

| 케이스 | 예상 동작 | 확인 방법 |
|--------|----------|----------|
| 네트워크 끊김 | 에러 메시지 표시 | 네트워크 탭에서 Offline 모드 |
| 401 인증 오류 | 로그인 페이지 리다이렉트 | 토큰 만료 상태에서 접속 |
| 404 데이터 없음 | "데이터 없음" 표시 | 존재하지 않는 ID 접근 |
| 500 서버 오류 | 에러 메시지 표시 | API 강제 에러 발생 |

---

## 9. 세션 관리

### 9.1 새 세션 시작 시

```bash
# 1. 메인 문서 읽기 (현재 진행 상태 확인)
cat docs/plans/construction-api-integration-plan.md | head -30

# 2. "다음 작업" 확인
grep "다음 작업" docs/plans/construction-api-integration-plan.md

# 3. 해당 서브 문서 읽기
cat docs/plans/sub/{다음작업}-plan.md

# 4. 작업 시작
```

### 9.2 작업 중 체크포인트

| 시점 | 행동 |
|------|------|
| 작업 완료 시 | 메인 문서 "현재 진행 상태" 업데이트 |
| 서브 작업 완료 시 | 서브 문서 상태 (⏳→✅) 업데이트 |
| 컨펌 필요 시 | "컨펌 대기 목록"에 추가 |
| 세션 종료 전 | 변경 이력에 기록 |

### 9.3 세션 종료 시

```bash
# 1. 진행 상태 업데이트
# - 📍 현재 진행 상태 섹션의 "마지막 완료 작업", "다음 작업" 수정
# - 대상 범위의 상태 아이콘 수정 (⏳ → ✅ 또는 🔄)

# 2. 변경 이력 추가
# | 2026-01-08 | 1.1 | 계약관리 API 연동 완료 | contract/actions.ts | - |

# 3. 커밋 (승인 후)
git add . && git commit -m "feat: [시공사] 1.1 계약관리 - API 연동"
```

### 9.4 컨텍스트 관리 (Serena 메모리)

```javascript
// 세션 시작 시 로드
read_memory("construction-api-state")

// 작업 중 저장 (30분마다 또는 주요 완료 시)
write_memory("construction-api-state", {
  phase: "1.1",
  status: "진행중",
  lastCompleted: "Controller 생성",
  nextStep: "Service 로직 구현"
})

// 컨텍스트 30% 이하 시
write_memory("construction-api-snapshot", "현재까지 진행 상황 요약...")
```

---

## 10. 변경 이력

| 날짜 | 항목 | 변경 내용 | 파일 | 승인 |
|------|------|----------|------|------|
| 2026-01-08 | 초안 | 문서 초안 작성, 9개 컴포넌트 분석 | - | - |
| 2026-01-08 | 보완 | 전제조건, 성공기준, 검증방법, 세션관리 추가 | - | - |
| 2026-01-09 | 1.1 | 계약관리 API 연동 완료 (Backend + Frontend) | api/, react/ | ✅ |
| 2026-01-09 | 1.2 | 인수인계보고서 Frontend API 연동 완료 | react/ | ✅ |
| 2026-01-09 | 2.1 | 현장관리 API 연동 완료 (Backend + Frontend) | api/, react/ | ✅ |
| 2026-01-09 | 2.2 | 구조검토관리 API 연동 완료 (Backend + Frontend) | api/, react/ | ✅ |
| 2026-01-09 | 2.3 | 물량검토관리 제외 (Frontend/기획 미존재) | docs/ | ✅ |
| 2026-01-09 | 3.1 | 카테고리관리 API 연동 완료 (HTTP 메서드 수정) | react/ | ✅ |
| 2026-01-09 | 3.2 | 품목관리 API 연동 완료 (apiClient.delete body 지원 추가) | react/ | ✅ |

---

## 11. 참고 문서

| 문서 | 경로 | 용도 |
|------|------|------|
| API 규칙 | `docs/standards/api-rules.md` | API 개발 표준 |
| Swagger 가이드 | `docs/guides/swagger-guide.md` | API 문서화 |
| 품질 체크리스트 | `docs/standards/quality-checklist.md` | 완료 전 점검 |
| 빠른 시작 | `docs/quickstart/quick-start.md` | 환경 설정 |
| 개발 명령어 | `docs/quickstart/dev-commands.md` | 자주 쓰는 명령어 |

---

## 12. 서브 문서 링크

| Phase | 문서 | 경로 | API 상태 |
|-------|------|------|:--------:|
| 1.1 | 계약관리 | [./sub/contract-plan.md](./sub/contract-plan.md) | ✅ 완료 |
| 1.2 | 인수인계보고서 | [./sub/handover-report-plan.md](./sub/handover-report-plan.md) | ❌ 신규 |
| 2.1 | 현장관리 | [./sub/site-management-plan.md](./sub/site-management-plan.md) | ⚠️ 확인필요 |
| 2.2 | 구조검토관리 | [./sub/structure-review-plan.md](./sub/structure-review-plan.md) | ❌ 신규 |
| 2.3 | 발주관리 | [./sub/order-management-plan.md](./sub/order-management-plan.md) | ❌ 신규 |
| 3.1 | 카테고리관리 | [./sub/categories-plan.md](./sub/categories-plan.md) | ✅ 존재 |
| 3.2 | 품목관리 | [./sub/items-plan.md](./sub/items-plan.md) | ❌ 신규 |
| 3.3 | 단가관리 | [./sub/pricing-plan.md](./sub/pricing-plan.md) | ✅ 존재 |
| 3.4 | 노임관리 | [./sub/labor-plan.md](./sub/labor-plan.md) | ❌ 신규 |

---

## 13. 자기완결성 점검 결과

### 13.1 체크리스트 검증

| # | 검증 항목 | 상태 | 참조 섹션 |
|---|----------|:----:|----------|
| 1 | 작업 목적이 명확한가? | ✅ | 1.1 배경 |
| 2 | 성공 기준이 정의되어 있는가? | ✅ | 7. 성공 기준 |
| 3 | 작업 범위가 구체적인가? | ✅ | 2. 대상 범위 |
| 4 | 의존성이 명시되어 있는가? | ✅ | 0. 전제 조건 |
| 5 | 참고 파일 경로가 정확한가? | ✅ | 11. 참고 문서 (검증됨) |
| 6 | 단계별 절차가 실행 가능한가? | ✅ | 4. 작업 절차 |
| 7 | 검증 방법이 명시되어 있는가? | ✅ | 8. 검증 방법 |
| 8 | 모호한 표현이 없는가? | ✅ | 구체적 명령어 포함 |

### 13.2 새 세션 시뮬레이션 테스트

| 질문 | 답변 가능 | 참조 섹션 |
|------|:--------:|----------|
| Q1. 이 작업의 목적은 무엇인가? | ✅ | 1.1 배경 |
| Q2. 어디서부터 시작해야 하는가? | ✅ | 4.2 첫 번째 작업 시작점 |
| Q3. 어떤 파일을 수정해야 하는가? | ✅ | 5.1 프로젝트 구조 + 서브 문서 |
| Q4. 작업 완료 확인 방법은? | ✅ | 7. 성공 기준, 8. 검증 방법 |
| Q5. 막혔을 때 참고 문서는? | ✅ | 11. 참고 문서 |

**결과: 5/5 통과 → ✅ 자기완결성 확보**

---

*이 문서는 /sc:plan 스킬로 생성되었습니다.*
*보완일: 2026-01-08*