docs: 규칙 및 원칙 문서 체계 추가

- standards/ 폴더 추가 (코딩 규칙: 네이밍, 스타일) - rules/ 폴더 추가 (비즈니스 규칙: 검증, 도메인 로직) - principles/ 폴더 추가 (설계 원칙: 아키텍처, API 설계) - INDEX.md에 규칙 및 원칙 섹션 추가 - 각 폴더에 README.md 생성
2025-12-05 17:57:47 +09:00
parent 08a8259313
commit 02a27f2bba
8 changed files with 886 additions and 26 deletions
--- a/client-api-analysis.md
+++ b/client-api-analysis.md
@@ -96,36 +96,124 @@ protected $fillable = [

 ## 4. 백엔드 수정 요청 사항

-### 4.1 Client 모델 필드 추가 요청
+### 4.1 1차 필드 추가 ✅ 완료 (2025-12-04)

-```markdown
-## 백엔드 API 수정 요청
+| 필드명 | 타입 | 설명 | 상태 |
+|--------|------|------|------|
+| `business_no` | string(20) | 사업자등록번호 | ✅ 추가됨 |
+| `business_type` | string(50) | 업태 | ✅ 추가됨 |
+| `business_item` | string(100) | 업종 | ✅ 추가됨 |

-### 파일 위치
-`app/Models/Orders/Client.php` - Client 모델
+---

-### 현재 문제
-프론트엔드에서 사용하는 사업자 정보 필드가 백엔드에 없음
+### 4.2 🚨 2차 필드 추가 요청 (sam-design 기준) - 2025-12-04

-### 수정 요청
-다음 필드를 Client 모델에 추가:
+> **참고**: `sam-design/src/components/ClientRegistration.tsx` 기준으로 UI 구현 필요
+> 현재 백엔드 API에 누락된 필드들 추가 요청

+#### 섹션 1: 기본 정보 추가 필드
+| 필드명 | 타입 | 설명 | nullable | 비고 |
+|--------|------|------|----------|------|
+| `client_type` | enum('매입','매출','매입매출') | 거래처 유형 | NO | 기본값 '매입' |
+
+#### 섹션 2: 연락처 정보 추가 필드
 | 필드명 | 타입 | 설명 | nullable |
 |--------|------|------|----------|
-| `business_no` | string(20) | 사업자등록번호 | nullable |
-| `business_type` | string(50) | 업태 | nullable |
-| `business_item` | string(100) | 업종 | nullable |
+| `mobile` | string(20) | 모바일 번호 | YES |
+| `fax` | string(20) | 팩스 번호 | YES |
+
+#### 섹션 3: 담당자 정보 추가 필드
+| 필드명 | 타입 | 설명 | nullable |
+|--------|------|------|----------|
+| `manager_name` | string(50) | 담당자명 | YES |
+| `manager_tel` | string(20) | 담당자 전화 | YES |
+| `system_manager` | string(50) | 시스템 관리자 | YES |
+
+#### 섹션 4: 발주처 설정 추가 필드
+| 필드명 | 타입 | 설명 | nullable |
+|--------|------|------|----------|
+| `account_id` | string(50) | 계정 ID | YES |
+| `account_password` | string(255) | 비밀번호 (암호화) | YES |
+| `purchase_payment_day` | string(20) | 매입 결제일 | YES |
+| `sales_payment_day` | string(20) | 매출 결제일 | YES |
+
+#### 섹션 5: 약정 세금 추가 필드
+| 필드명 | 타입 | 설명 | nullable |
+|--------|------|------|----------|
+| `tax_agreement` | boolean | 세금 약정 여부 | YES |
+| `tax_amount` | decimal(15,2) | 약정 금액 | YES |
+| `tax_start_date` | date | 약정 시작일 | YES |
+| `tax_end_date` | date | 약정 종료일 | YES |
+
+#### 섹션 6: 악성채권 정보 추가 필드
+| 필드명 | 타입 | 설명 | nullable |
+|--------|------|------|----------|
+| `bad_debt` | boolean | 악성채권 여부 | YES |
+| `bad_debt_amount` | decimal(15,2) | 악성채권 금액 | YES |
+| `bad_debt_receive_date` | date | 채권 발생일 | YES |
+| `bad_debt_end_date` | date | 채권 만료일 | YES |
+| `bad_debt_progress` | enum('협의중','소송중','회수완료','대손처리') | 진행 상태 | YES |
+
+#### 섹션 7: 기타 정보 추가 필드
+| 필드명 | 타입 | 설명 | nullable |
+|--------|------|------|----------|
+| `memo` | text | 메모 | YES |
+
+---
+
+### 4.3 마이그레이션 예시

-### 마이그레이션 예시
 ```sql
-ALTER TABLE clients ADD COLUMN business_no VARCHAR(20) NULL;
-ALTER TABLE clients ADD COLUMN business_type VARCHAR(50) NULL;
-ALTER TABLE clients ADD COLUMN business_item VARCHAR(100) NULL;
-```
+-- 기본 정보
+ALTER TABLE clients ADD COLUMN client_type ENUM('매입','매출','매입매출') DEFAULT '매입';
+
+-- 연락처 정보
+ALTER TABLE clients ADD COLUMN mobile VARCHAR(20) NULL;
+ALTER TABLE clients ADD COLUMN fax VARCHAR(20) NULL;
+
+-- 담당자 정보
+ALTER TABLE clients ADD COLUMN manager_name VARCHAR(50) NULL;
+ALTER TABLE clients ADD COLUMN manager_tel VARCHAR(20) NULL;
+ALTER TABLE clients ADD COLUMN system_manager VARCHAR(50) NULL;
+
+-- 발주처 설정
+ALTER TABLE clients ADD COLUMN account_id VARCHAR(50) NULL;
+ALTER TABLE clients ADD COLUMN account_password VARCHAR(255) NULL;
+ALTER TABLE clients ADD COLUMN purchase_payment_day VARCHAR(20) NULL;
+ALTER TABLE clients ADD COLUMN sales_payment_day VARCHAR(20) NULL;
+
+-- 약정 세금
+ALTER TABLE clients ADD COLUMN tax_agreement TINYINT(1) DEFAULT 0;
+ALTER TABLE clients ADD COLUMN tax_amount DECIMAL(15,2) NULL;
+ALTER TABLE clients ADD COLUMN tax_start_date DATE NULL;
+ALTER TABLE clients ADD COLUMN tax_end_date DATE NULL;
+
+-- 악성채권 정보
+ALTER TABLE clients ADD COLUMN bad_debt TINYINT(1) DEFAULT 0;
+ALTER TABLE clients ADD COLUMN bad_debt_amount DECIMAL(15,2) NULL;
+ALTER TABLE clients ADD COLUMN bad_debt_receive_date DATE NULL;
+ALTER TABLE clients ADD COLUMN bad_debt_end_date DATE NULL;
+ALTER TABLE clients ADD COLUMN bad_debt_progress ENUM('협의중','소송중','회수완료','대손처리') NULL;
+
+-- 기타 정보
+ALTER TABLE clients ADD COLUMN memo TEXT NULL;
 ```

 ---

+### 4.4 수정 필요 파일 목록
+
+| 파일 | 수정 내용 |
+|------|----------|
+| `app/Models/Orders/Client.php` | fillable에 새 필드 추가, casts 설정 |
+| `database/migrations/xxxx_add_client_extended_fields.php` | 마이그레이션 생성 |
+| `app/Services/ClientService.php` | 새 필드 처리 로직 추가 |
+| `app/Http/Requests/Client/ClientStoreRequest.php` | 유효성 검증 규칙 추가 |
+| `app/Http/Requests/Client/ClientUpdateRequest.php` | 유효성 검증 규칙 추가 |
+| `app/Swagger/v1/ClientApi.php` | API 문서 업데이트 |
+
+---
+
 ## 5. 프론트엔드 API 연동 구현 계획

 ### 5.1 필요한 작업
--- a/front/[API-2025-12-04]
+++ b/front/[API-2025-12-04]
@@ -187,7 +187,15 @@ interface QuoteRevision {
 | `GET` | `/api/v1/quotes/{id}/document/calculation` | 산출내역서 PDF | |
 | `GET` | `/api/v1/quotes/{id}/document/purchase-order` | 발주서 PDF | |

-### 3.5 견적번호 생성
+### 3.5 문서 발송 API ⭐ 신규 요청
+
+| Method | Endpoint | 설명 | 비고 |
+|--------|----------|------|------|
+| `POST` | `/api/v1/quotes/{id}/send/email` | 이메일 발송 | 첨부파일 포함 |
+| `POST` | `/api/v1/quotes/{id}/send/fax` | 팩스 발송 | 팩스 서비스 연동 |
+| `POST` | `/api/v1/quotes/{id}/send/kakao` | 카카오톡 발송 | 알림톡/친구톡 |
+
+### 3.6 견적번호 생성

 | Method | Endpoint | 설명 | 비고 |
 |--------|----------|------|------|
@@ -530,10 +538,76 @@ sort_order: 'asc' | 'desc'

 ---

-## 7. 프론트엔드 연동 계획
+## 7. 프론트엔드 구현 현황 (2025-12-04 업데이트)
+
+### 7.1 구현 완료된 파일
+
+| 파일 | 설명 | 상태 |
+|------|------|------|
+| `quote-management/page.tsx` | 견적 목록 페이지 | ✅ 완료 (샘플 데이터) |
+| `quote-management/new/page.tsx` | 견적 등록 페이지 | ✅ 완료 |
+| `quote-management/[id]/page.tsx` | 견적 상세 페이지 | ✅ 완료 |
+| `quote-management/[id]/edit/page.tsx` | 견적 수정 페이지 | ✅ 완료 |
+| `components/quotes/QuoteRegistration.tsx` | 견적 등록/수정 컴포넌트 | ✅ 완료 |
+| `components/quotes/QuoteDocument.tsx` | 견적서 문서 컴포넌트 | ✅ 완료 |
+| `components/quotes/QuoteCalculationReport.tsx` | 산출내역서 문서 컴포넌트 | ✅ 완료 |
+| `components/quotes/PurchaseOrderDocument.tsx` | 발주서 문서 컴포넌트 | ✅ 완료 |
+
+### 7.2 UI 기능 구현 현황
+
+| 기능 | 상태 | 비고 |
+|------|------|------|
+| 견적 목록 조회 | ✅ UI 완료 | 샘플 데이터, API 연동 필요 |
+| 견적 검색/필터 | ✅ UI 완료 | 로컬 필터링, API 연동 필요 |
+| 견적 등록 폼 | ✅ UI 완료 | API 연동 필요 |
+| 견적 상세 페이지 | ✅ UI 완료 | API 연동 필요 |
+| 견적 수정 폼 | ✅ UI 완료 | API 연동 필요 |
+| 견적 삭제 | ✅ UI 완료 | 로컬 상태, API 연동 필요 |
+| 견적 일괄 삭제 | ✅ UI 완료 | 로컬 상태, API 연동 필요 |
+| 자동 견적 산출 | ⏳ 버튼만 | 백엔드 수식 엔진 필요 |
+| 발주처 선택 | ⏳ 샘플 데이터 | `/api/v1/clients` 연동 필요 |
+| 현장 선택 | ⏳ 샘플 데이터 | 발주처 연동 후 현장 API 필요 |
+| 제품 선택 | ⏳ 샘플 데이터 | `/api/v1/item-masters` 연동 필요 |
+| **견적서 모달** | ✅ UI 완료 | PDF/이메일/팩스/카톡 버튼, **발송 API 필요** |
+| **산출내역서 모달** | ✅ UI 완료 | PDF/이메일/팩스/카톡 버튼, **발송 API 필요** |
+| **발주서 모달** | ✅ UI 완료 | PDF/이메일/팩스/카톡 버튼, **발송 API 필요** |
+| 최종확정 버튼 | ✅ UI 완료 | API 연동 필요 |
+
+### 7.3 견적 등록/수정 폼 필드 (구현 완료)
+
+**기본 정보 섹션:**
+- 등록일 (readonly, 오늘 날짜)
+- 작성자 (readonly, 로그인 사용자)
+- 발주처 선택 * (필수)
+- 현장명 (발주처 선택 시 연동)
+- 발주 담당자
+- 연락처
+- 납기일
+- 비고
+
+**자동 견적 산출 섹션 (동적 항목):**
+- 층수
+- 부호
+- 제품 카테고리 (PC) *
+- 제품명 *
+- 오픈사이즈 (W0) *
+- 오픈사이즈 (H0) *
+- 가이드레일 설치 유형 (GT) *
+- 모터 전원 (MP) *
+- 연동제어기 (CT) *
+- 수량 (QTY) *
+- 마구리 날개치수 (WS)
+- 검사비 (INSP)
+
+**기능:**
+- 견적 항목 추가/복사/삭제
+- 자동 견적 산출 버튼
+- 샘플 데이터 생성 버튼
+
+### 7.4 다음 단계 (API 연동)

-### 7.1 useQuoteList 훅 (목록)
 ```typescript
+// useQuoteList 훅 (목록)
 const {
  quotes,
  pagination,
@@ -542,10 +616,8 @@ const {
  deleteQuote,
  bulkDelete
 } = useQuoteList();
-```

-### 7.2 useQuote 훅 (단건 CRUD)
-```typescript
+// useQuote 훅 (단건 CRUD)
 const {
  quote,
  isLoading,
@@ -555,10 +627,8 @@ const {
  finalizeQuote,
  convertToOrder
 } = useQuote();
-```

-### 7.3 useQuoteCalculation 훅 (자동 산출)
-```typescript
+// useQuoteCalculation 훅 (자동 산출)
 const {
  calculationResult,
  isCalculating,