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

시공사 페이지 API 연동 계획

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

---

📍 현재 진행 상태

항목	내용
마지막 완료 작업	Phase 3.4: 노임관리 API 연동 완료 ✅
다음 작업	🎉 전체 완료
진행률	8/8 (100%)
마지막 업데이트	2026-01-12

---

0. 전제 조건 (Prerequisites)

0.1 환경 확인

# 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
1.2	인수인계보고서관리 (handover-report)	✅	handover-report-plan.md

2.2 Phase 2: 발주관리 (Order)

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

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

#	작업 항목	상태	서브 문서
3.1	카테고리관리 (categories)	✅	categories-plan.md
3.2	품목관리 (items)	✅	items-plan.md
3.3	단가관리 (pricing)	✅	pricing-plan.md
3.4	노임관리 (labor)	✅	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 계약관리 시작:

# 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)

# 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 새 세션 시작 시

# 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 세션 종료 시

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

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

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

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

// 세션 시작 시 로드
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/	✅
2026-01-09	3.3	단가관리 Backend API 보완 (stats, bulkDestroy 추가)	api/	✅

---

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	✅ 완료
1.2	인수인계보고서	./sub/handover-report-plan.md	❌ 신규
2.1	현장관리	./sub/site-management-plan.md	⚠️ 확인필요
2.2	구조검토관리	./sub/structure-review-plan.md	❌ 신규
2.3	발주관리	./sub/order-management-plan.md	❌ 신규
3.1	카테고리관리	./sub/categories-plan.md	✅ 존재
3.2	품목관리	./sub/items-plan.md	❌ 신규
3.3	단가관리	./sub/pricing-plan.md	✅ 존재
3.4	노임관리	./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