SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(construction): 건설관리 API 연동 계획 진행상황 업데이트

Browse Source 
- Phase 2.1 현장관리: ✅ 완료
- Phase 2.2 구조검토관리: ✅ 완료
- Phase 2.3 물량검토관리: ⏳ 다음 작업
- 진행률: 4/9 (44%)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
권혁성
2026-01-09 21:31:50 +09:00
parent e861b74830
commit ced073e79b
1 changed files with 475 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

475
plans/construction-api-integration-plan.md Normal file
View File

@@ -0,0 +1,475 @@
# 시공사 페이지 API 연동 계획
> **작성일**: 2026-01-08
> **목적**: 시공사 9개 페이지 Mock → API 연동
> **기준 문서**: `docs/standards/api-rules.md`, `docs/guides/swagger-guide.md`
> **상태**: 🔄 진행중
---
## 📍 현재 진행 상태
| 항목 | 내용 |
|------|------|
| **마지막 완료 작업** | Phase 2.2: 구조검토관리 API 연동 완료 ✅ |
| **다음 작업** | Phase 2.3: 물량검토관리 API 연동 |
| **진행률** | 4/9 (44%) |
| **마지막 업데이트** | 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 배경
시공사 메뉴의 9개 페이지가 현재 모두 Mock 데이터를 사용하고 있으며, 실제 API 연동이 필요함.
### 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) | ⏳ | [quantity-review-plan.md](./sub/quantity-review-plan.md) |
### 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` | 🟡 중간 | 물량검토관리 |
| 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 전체 완료 조건
- [ ] 9개 페이지 모두 API 연동 완료 (1/9)
- [ ] 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/ | ✅ |
---
## 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*