From ced073e79bd39a8379efc512ac81de3ad528f037 Mon Sep 17 00:00:00 2001 From: kent Date: Fri, 9 Jan 2026 21:31:50 +0900 Subject: [PATCH] =?UTF-8?q?docs(construction):=20=EA=B1=B4=EC=84=A4?= =?UTF-8?q?=EA=B4=80=EB=A6=AC=20API=20=EC=97=B0=EB=8F=99=20=EA=B3=84?= =?UTF-8?q?=ED=9A=8D=20=EC=A7=84=ED=96=89=EC=83=81=ED=99=A9=20=EC=97=85?= =?UTF-8?q?=EB=8D=B0=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Phase 2.1 현장관리: ✅ 완료 - Phase 2.2 구조검토관리: ✅ 완료 - Phase 2.3 물량검토관리: ⏳ 다음 작업 - 진행률: 4/9 (44%) Co-Authored-By: Claude Opus 4.5 --- plans/construction-api-integration-plan.md | 475 +++++++++++++++++++++ 1 file changed, 475 insertions(+) create mode 100644 plans/construction-api-integration-plan.md diff --git a/plans/construction-api-integration-plan.md b/plans/construction-api-integration-plan.md new file mode 100644 index 0000000..dc66c1f --- /dev/null +++ b/plans/construction-api-integration-plan.md @@ -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* \ No newline at end of file