백엔드 계약 문서 동기화하고 DTO 파서 정합성 확장

doc/stock_approval_system_spec_v4.md

@@ -21,6 +21,7 @@
 - 트랜잭션에는 **여러 고객사**를 연결할 수 있음(역할 없음).
 - 모든 직원은 **그룹**에 속하며(`employees.group_id`), 그룹-메뉴 권한(`group_menu_permissions`)으로 메뉴별 CRUD 가능 여부가 결정됨.
 - 고객사는 **유형**을 `is_partner`/`is_general` 플래그로 구분하며 둘 중 하나 이상이 true여야 함(기본: 일반 true, 파트너 false).
+- 고객사는 담당자 이름(`contact_name`)을 별도 관리하며 고객 응답에 항상 포함.
 - 반복되는 결재 라인은 **결재 템플릿**으로 저장 후 호출하여 재사용 가능.
 - 모든 삭제는 **소프트 삭제**(`is_deleted=true`)이며, 삭제 시 `is_active=false`로 내림.
 
@@ -100,6 +101,8 @@ zipcodes ||--o{ customers : addressed
 | created_at | 생성일시 | timestamp | - | now() | Y |  |  |  |
 | updated_at | 변경일시 | timestamp | - | now() | Y |  |  |  |
 
+> `zipcodes` 테이블이 우편번호 마스터를 보유하며, 참조 측 테이블은 `zipcode_id` → `zipcodes.id` FK만 저장한다. 응답 시에는 FK를 통해 조회한 우편번호 요약 정보를 포함한다.
+
 ---
 
 ### 3.2 `warehouses` (창고)
@@ -112,7 +115,7 @@ zipcodes ||--o{ customers : addressed
 | id | 창고ID | bigint | - | identity | Y | Y | Y | - |
 | warehouse_code | 창고코드 | varchar | 30 | - | Y | (부분유니크: is_deleted=false) | N | - |
 | warehouse_name | 창고명 | varchar | 100 | - | Y |  |  |  |
-| zipcode | 우편번호 | varchar | 5 | - | N |  |  | zipcodes.zipcode |
+| zipcode_id | 우편번호ID | bigint | - | - | N |  |  | zipcodes.id |
 | address_detail | 상세주소 | varchar | 200 | - | N |  |  | - |
 | note | 비고 | text | - | - | N |  |  | - |
 | is_active | 사용여부 | boolean | - | true | Y |  |  |  |
@@ -132,11 +135,12 @@ zipcodes ||--o{ customers : addressed
 | id | 고객사ID | bigint | - | identity | Y | Y | Y | - |
 | customer_code | 고객사코드 | varchar | 30 | - | Y | (부분유니크: is_deleted=false) | N | - |
 | customer_name | 고객사명 | varchar | 100 | - | Y |  |  |  |
+| contact_name | 담당자명 | varchar | 100 | - | N |  |  | - |
 | is_partner | 파트너여부 | boolean | - | false | Y |  |  | - |
 | is_general | 일반여부 | boolean | - | true | Y |  |  | - |
 | email | 이메일 | varchar | 100 | - | N |  |  | - |
 | mobile_no | 모바일번호 | varchar | 20 | - | N |  |  | - |
-| zipcode | 우편번호 | varchar | 5 | - | N |  |  | zipcodes.zipcode |
+| zipcode_id | 우편번호ID | bigint | - | - | N |  |  | zipcodes.id |
 | address_detail | 상세주소 | varchar | 200 | - | N |  |  | - |
 | note | 비고 | text | - | - | N |  |  | - |
 | is_active | 사용여부 | boolean | - | true | Y |  |  |  |
@@ -144,6 +148,10 @@ zipcodes ||--o{ customers : addressed
 | created_at | 생성일시 | timestamp | - | now() | Y |  |  |  |
 | updated_at | 변경일시 | timestamp | - | now() | Y |  |  |  |
 
+> `contact_name`은 고객사의 대표 연락 창구로 사용하는 담당자 실명. 필수는 아니며 미입력 시 `null` 저장.
+
+> 고객/창고 모두 `zipcode_id`를 통해 `zipcodes.id`와 연결하며, API 응답은 FK가 가리키는 `zipcodes` 행에서 필요한 우편번호 메타 정보를 추출해 제공한다.
+
 ---
 
 ### 3.4 `employees` (사원)
@@ -174,7 +182,8 @@ zipcodes ||--o{ customers : addressed
 
 | 영문필드명 | 한글필드명 | 타입 | 길이 | 기본값 | NOT NULL | UNIQUE | PK | FK |
 |---|---|---|---|---|---|---|---|---|
-| zipcode | 우편번호 | varchar | 5 | - | Y | Y | Y | - |
+| id | 우편번호ID | bigint | - | identity | Y | Y | Y | - |
+| zipcode | 우편번호 | varchar | 5 | - | Y |  | N | - |
 | sido | 시도 | varchar | 50 | - | Y |  |  | - |
 | sido_eng | 시도영문 | varchar | 100 | - | N |  |  | - |
 | sigungu | 시군구 | varchar | 100 | - | Y |  |  | - |
@@ -207,7 +216,7 @@ zipcodes ||--o{ customers : addressed
 | created_at | 생성일시 | timestamp | - | now() | Y |  |  |  |
 | updated_at | 변경일시 | timestamp | - | now() | Y |  |  |  |
 
-> 도로명 주소 데이터와 매핑되는 5자리 우편번호 기준. `zipcode`가 PK이며 외부 데이터 동기화를 위한 `zipcode_serial_no`를 포함.
+> 도로명 주소 데이터와 매핑되는 5자리 우편번호 기준. `id`는 내부용 서러겟 PK이며, `zipcode`는 동일 코드가 여러 주소 행에 등장할 수 있다.
 
 ---
 
@@ -380,6 +389,7 @@ zipcodes ||--o{ customers : addressed
 | updated_at | 변경일시 | timestamp | - | now() | Y |  |  |  |
 
 > 주의: **벤더ID 없음**. 벤더 정보는 라인의 `product_id`가 가리키는 `products.vendor_id`로 파생.
+> 목록 조회는 `customer_id` 쿼리 파라미터를 지원해 특정 고객이 연결된 트랜잭션만 필터링할 수 있다. (2024-10 갱신)
 
 ---
 
@@ -583,8 +593,6 @@ zipcodes ||--o{ customers : addressed
 - `employees.group_id` → `groups.id`
 - `group_menu_permissions.group_id` → `groups.id`
 - `group_menu_permissions.menu_id` → `menus.id`
-- `warehouses.zipcode` → `zipcodes.zipcode`
-- `customers.zipcode` → `zipcodes.zipcode`
 - `products.vendor_id` → `vendors.id`
 - `products.uom_id` → `uoms.id`
 - `stock_transactions.warehouse_id` → `warehouses.id`
@@ -628,7 +636,7 @@ zipcodes ||--o{ customers : addressed
 
 ## 6) 인덱스/유니크 권장
 - 부분 유니크(또는 복합 유니크)로 소프트 삭제와 공존:  
-  - `vendors(vendor_code)`, `warehouses(warehouse_code)`, `customers(customer_code)`, `employees(employee_no)`, `menus(menu_code)`, `groups(group_name)`, `zipcodes(zipcode)`, `products(product_code)`, `stock_transactions(transaction_no)`, `approvals(approval_no)`  
+  - `vendors(vendor_code)`, `warehouses(warehouse_code)`, `customers(customer_code)`, `employees(employee_no)`, `menus(menu_code)`, `groups(group_name)`, `products(product_code)`, `stock_transactions(transaction_no)`, `approvals(approval_no)`  
   - `group_menu_permissions(group_id, menu_id, is_deleted)`
   - `approvals(transaction_id)` — 미삭제 조건에서 1:1 보장  
   - `transaction_lines(transaction_id, line_no, is_deleted)`