refactor: [docs] 팀별 폴더 구조 재편 (공유/개발/프론트/기획)

- 개발팀 전용 폴더 dev/ 생성 (standards, guides, quickstart, changes, deploys, data, history, dev_plans 이동) - 프론트엔드 전용 폴더 frontend/ 생성 (api/ → frontend/api-specs/) - 기획팀 폴더 requests/ 생성 - plans/ → dev/dev_plans/ 이름 변경 - README.md 신규 (사람용 안내), INDEX.md 재작성 (Claude Code용) - resources.md 신규 (노션 링크용, assets/brochure 이관 예정) - CURRENT_WORKS.md 삭제, TODO.md → dev/ 이동 - 전체 참조 경로 업데이트 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 16:46:03 +09:00
parent 7e1daca81b
commit db63fcff85
440 changed files with 407 additions and 460 deletions
--- a/dev/changes/20250108_order_management_phase1.md
+++ b/dev/changes/20250108_order_management_phase1.md
@@ -0,0 +1,94 @@
+# 변경 내용 요약
+
+**날짜:** 2025-01-08
+**작업자:** Claude Code
+**이슈:** Order Management API Phase 1.1
+
+## 📋 변경 개요
+수주관리(Order Management) API의 기본 CRUD 및 상태 관리 기능을 구현했습니다.
+WorkOrderService/Controller 패턴을 참고하여 SAM API 규칙을 준수하는 OrderService와 OrderController를 생성했습니다.
+
+## 📁 수정/추가된 파일
+
+### 신규 생성 (7개)
+- `app/Services/OrderService.php` - 수주 비즈니스 로직 서비스
+- `app/Http/Controllers/Api/V1/OrderController.php` - 수주 API 컨트롤러
+- `app/Http/Requests/Order/StoreOrderRequest.php` - 생성 요청 검증
+- `app/Http/Requests/Order/UpdateOrderRequest.php` - 수정 요청 검증
+- `app/Http/Requests/Order/UpdateOrderStatusRequest.php` - 상태 변경 요청 검증
+- `app/Swagger/v1/OrderApi.php` - Swagger API 문서
+
+### 수정 (5개)
+- `routes/api.php` - OrderController import 및 라우트 추가
+- `lang/ko/message.php` - 수주 관련 메시지 키 추가
+- `lang/en/message.php` - 수주 관련 메시지 키 추가
+- `lang/ko/error.php` - 수주 에러 메시지 키 추가
+- `lang/en/error.php` - 수주 에러 메시지 키 추가
+
+## 🔧 상세 변경 사항
+
+### 1. OrderService
+**기능:**
+- `index()` - 목록 조회 (검색/필터링/페이징)
+- `stats()` - 통계 조회 (상태별 건수/금액)
+- `show()` - 단건 조회
+- `store()` - 생성 (수주번호 자동생성)
+- `update()` - 수정 (완료/취소 상태 수정 불가)
+- `destroy()` - 삭제 (진행중/완료 상태 삭제 불가)
+- `updateStatus()` - 상태 변경 (전환 규칙 검증)
+
+**내부 메서드:**
+- `validateStatusTransition()` - 상태 전환 규칙 검증
+- `calculateItemAmounts()` - 품목 금액 계산 (공급가, 세액, 합계)
+- `generateOrderNo()` - 수주번호 자동 생성 (ORD{YYYYMMDD}{0001})
+
+### 2. OrderController
+**엔드포인트:**
+- `GET /api/v1/orders` - 목록 조회
+- `GET /api/v1/orders/stats` - 통계 조회
+- `POST /api/v1/orders` - 생성
+- `GET /api/v1/orders/{id}` - 단건 조회
+- `PUT /api/v1/orders/{id}` - 수정
+- `DELETE /api/v1/orders/{id}` - 삭제
+- `PATCH /api/v1/orders/{id}/status` - 상태 변경
+
+### 3. FormRequest 클래스
+**StoreOrderRequest:**
+- 주문유형, 카테고리, 거래처 정보, 금액, 배송, 품목 배열 검증
+
+**UpdateOrderRequest:**
+- Store와 유사하나 order_no 제외 (수정 불가)
+
+**UpdateOrderStatusRequest:**
+- status 필드만 검증 (Rule::in 사용)
+
+### 4. 상태 전환 규칙
+```
+DRAFT → CONFIRMED, CANCELLED
+CONFIRMED → IN_PROGRESS, CANCELLED
+IN_PROGRESS → COMPLETED, CANCELLED
+COMPLETED → (변경 불가)
+CANCELLED → DRAFT (복구 가능)
+```
+
+### 5. Swagger 문서
+**스키마:**
+- Order, OrderItem, OrderPagination, OrderStats
+- OrderCreateRequest, OrderUpdateRequest, OrderItemRequest, OrderStatusRequest
+
+## ✅ 검증 완료 항목
+- [x] Pint 코드 스타일 검사 (6개 파일 자동 수정)
+- [x] Swagger 문서 생성 (`php artisan l5-swagger:generate`)
+- [x] Service-First 아키텍처 준수
+- [x] FormRequest 검증 패턴 사용
+- [x] i18n 메시지 키 사용
+- [x] Multi-tenancy (BelongsToTenant) 지원
+- [x] 감사 로그 컬럼 (created_by, updated_by, deleted_by)
+
+## ⚠️ 배포 시 주의사항
+- Order 모델은 기존에 이미 존재함 (마이그레이션 불필요)
+- Swagger UI에서 API 테스트 가능: http://api.sam.kr/api-docs/index.html
+
+## 🔗 관련 문서
+- 계획 문서: `docs/dev_plans/order-management-plan.md`
+- 참고 패턴: `app/Services/WorkOrderService.php`, `app/Http/Controllers/Api/V1/WorkOrderController.php`
--- a/dev/changes/20251111_admin_tenant_selector.md
+++ b/dev/changes/20251111_admin_tenant_selector.md
@@ -0,0 +1,237 @@
+# 변경 내용 요약
+
+**날짜:** 2025-11-11 14:50
+**작업자:** Claude Code
+**이슈:** SAM Admin 테넌트 컨텍스트 전환 시스템 구현
+
+## 📋 변경 개요
+
+SAM Admin 시스템에 테넌트 컨텍스트 전환 기능을 추가했습니다. Admin 사용자가 "전체 보기" 모드와 특정 테넌트 필터링 모드를 자유롭게 전환할 수 있습니다.
+
+**주요 기능:**
+- TenantSelectorWidget: 전체 보기/특정 테넌트 선택 드롭다운
+- AppliesTenantScope Trait: 모든 Resource에 자동 테넌트 필터링 적용
+- 통계 표시: 현재 컨텍스트에 따른 사용자/제품 수 표시
+- 컨텍스트 알림: 현재 보고 있는 테넌트 정보 시각적 표시
+
+## 🔧 사용된 도구
+
+**네이티브 도구:**
+- **Read**: 기존 파일 분석 (12회)
+- **Edit**: 파일 수정 (9회)
+- **Write**: 신규 파일 생성 (2회)
+- **Bash**: Laravel Pint 실행, 타임스탬프 생성
+
+## 📁 수정된 파일
+
+**신규 파일 생성 (1개):**
+1. `admin/app/Filament/Concerns/AppliesTenantScope.php` - 테넌트 필터링 Trait
+
+**기존 파일 수정 (11개):**
+2. `admin/app/Filament/Widgets/TenantSelectorWidget.php` - 전체 보기 옵션 추가
+3. `admin/resources/views/filament/widgets/tenant-selector.blade.php` - UI 개선
+4. `admin/app/Filament/Resources/Products/ProductResource.php` - Trait 적용
+5. `admin/app/Filament/Resources/MaterialResource.php` - Trait 적용
+6. `admin/app/Filament/Resources/CategoryResource.php` - Trait 적용
+7. `admin/app/Filament/Resources/ClientResource.php` - Trait 적용
+8. `admin/app/Filament/Resources/EstimateResource.php` - Trait 적용
+9. `admin/app/Filament/Resources/ProductComponentResource.php` - Trait 적용
+10. `admin/app/Filament/Resources/ClassificationResource.php` - Trait 적용
+11. `admin/app/Filament/Resources/Menus/MenuResource.php` - Trait 적용
+12. `admin/app/Filament/Resources/Categories/CategoryResource.php` - Trait 적용
+
+## 🔧 상세 변경 사항
+
+### 1. AppliesTenantScope Trait 생성
+
+**파일:** `admin/app/Filament/Concerns/AppliesTenantScope.php`
+
+**기능:**
+```php
+trait AppliesTenantScope
+{
+    protected static ?string $tenantColumn = 'tenant_id';
+
+    public static function getEloquentQuery(): Builder
+    {
+        $query = parent::getEloquentQuery();
+        $selectedTenantId = Session::get('selected_tenant_id');
+
+        // "전체 보기" 모드가 아닌 경우에만 필터 적용
+        if ($selectedTenantId !== null && $selectedTenantId !== 'all') {
+            $tenantColumn = static::$tenantColumn ?? 'tenant_id';
+            $query->where($tenantColumn, $selectedTenantId);
+        }
+
+        return $query;
+    }
+}
+```
+
+**특징:**
+- Session 기반 테넌트 컨텍스트 관리
+- "전체 보기" 모드에서는 필터 미적용
+- 커스텀 tenant_id 컬럼명 지원 (`$tenantColumn` 오버라이드 가능)
+- 모든 Filament Resource에 재사용 가능
+
+---
+
+### 2. TenantSelectorWidget 개선
+
+**파일:** `admin/app/Filament/Widgets/TenantSelectorWidget.php`
+
+**추가된 기능:**
+- `isViewingAll()`: 전체 보기 모드 여부 확인
+- `getTenantStats()`: 현재 컨텍스트에 따른 통계 계산
+- `updatedSelectedTenantId()`: 테넌트 변경 시 Session 관리 및 페이지 리로드
+
+**변경 후:**
+```php
+public function updatedSelectedTenantId($value)
+{
+    if ($value === 'all') {
+        Session::forget('selected_tenant_id');
+    } else {
+        Session::put('selected_tenant_id', $value);
+    }
+
+    $this->dispatch('tenant-changed');
+}
+
+public function getTenantStats()
+{
+    $tenantId = Session::get('selected_tenant_id');
+
+    if ($tenantId) {
+        // 특정 테넌트 통계
+        return [
+            'users' => User::whereHas('tenantsMembership', function ($q) use ($tenantId) {
+                $q->where('tenants.id', $tenantId);
+            })->count(),
+            'products' => Product::where('tenant_id', $tenantId)->count(),
+        ];
+    }
+
+    // 전체 통계
+    return [
+        'users' => User::count(),
+        'products' => Product::count(),
+        'tenants' => Tenant::active()->count(),
+    ];
+}
+```
+
+---
+
+### 3. TenantSelector Blade 템플릿 개선
+
+**파일:** `admin/resources/views/filament/widgets/tenant-selector.blade.php`
+
+**추가된 UI 요소:**
+```blade
+{{-- 테넌트 선택 드롭다운 --}}
+<select wire:model.live="selectedTenantId">
+    <option value="all">🌐 전체 보기</option>
+    <option disabled>──────────</option>
+    @foreach($this->getTenants() as $tenant)
+        <option value="{{ $tenant->id }}">
+            {{ $tenant->company_name }} ({{ $tenant->code }})
+        </option>
+    @endforeach
+</select>
+
+{{-- 통계 표시 --}}
+<div class="grid grid-cols-3 gap-4">
+    @if($this->isViewingAll())
+        <div>테넌트: {{ number_format($stats['tenants']) }}</div>
+    @endif
+    <div>사용자: {{ number_format($stats['users']) }}</div>
+    <div>제품: {{ number_format($stats['products']) }}</div>
+</div>
+
+{{-- 컨텍스트 알림 --}}
+@if(!$this->isViewingAll())
+    <div class="bg-blue-50 dark:bg-blue-900/20">
+        현재 '<strong>{{ $this->getCurrentTenant()->company_name }}</strong>'의 데이터를 보고 있습니다
+    </div>
+@endif
+```
+
+---
+
+### 4. Resource에 Trait 적용
+
+**적용된 Resource (9개):**
+1. ProductResource - 제품
+2. MaterialResource - 자재
+3. CategoryResource - 카테고리 (2곳)
+4. ClientResource - 거래처
+5. EstimateResource - 견적
+6. ProductComponentResource - 제품 구성요소
+7. ClassificationResource - 분류
+8. MenuResource - 메뉴
+
+**적용 패턴:**
+```php
+use App\Filament\Concerns\AppliesTenantScope;
+
+class ProductResource extends Resource
+{
+    use AppliesTenantScope;
+
+    // ... 기존 코드
+}
+```
+
+**효과:**
+- Session의 `selected_tenant_id`에 따라 자동으로 `where('tenant_id', $selectedTenantId)` 필터 적용
+- "전체 보기" 모드에서는 모든 테넌트 데이터 표시
+- 코드 중복 제거 (각 Resource에서 개별 구현 불필요)
+
+---
+
+## ✅ 테스트 체크리스트
+
+- [x] Laravel Pint 실행 (12개 파일, 11개 스타일 이슈 자동 수정)
+- [x] PHP 문법 오류 확인 (오류 없음)
+- [ ] 로컬 서버 실행 및 테넌트 선택 위젯 확인
+- [ ] "전체 보기" → 모든 데이터 표시 확인
+- [ ] 특정 테넌트 선택 → 해당 테넌트 데이터만 표시 확인
+- [ ] 통계 표시 정확성 확인
+- [ ] 제품/자재/카테고리 등 각 Resource에서 필터링 동작 확인
+- [ ] 테넌트 전환 시 페이지 자동 리로드 확인
+
+## ⚠️ 배포 시 주의사항
+
+1. **Session 기반 컨텍스트**: Redis/Database 세션 사용 권장 (파일 세션은 다중 서버 환경에서 동기화 문제 발생 가능)
+2. **Widget 등록 필요**: `AdminPanelProvider`에 `TenantSelectorWidget` 등록 확인
+3. **BelongsToTenant 모델만 적용**: `tenant_id` 컬럼이 없는 모델(User, Role, Permission 등)에는 Trait 미적용
+4. **커스텀 컬럼명**: `tenant_id`가 아닌 다른 컬럼명 사용 시 Resource에서 `$tenantColumn` 오버라이드 필요
+5. **권한 검증**: Admin 사용자만 "전체 보기" 접근 가능하도록 권한 추가 검토 필요
+
+## 🔗 관련 문서
+
+- 이전 작업: `docs/changes/20251111_admin_users_improvement.md`
+- CLAUDE.md: `/Users/hskwon/Works/@KD_SAM/SAM/CLAUDE.md`
+
+---
+
+## 📊 작업 통계
+
+- **수정된 파일**: 11개
+- **신규 파일**: 1개
+- **총 변경 라인 수**: 약 150줄
+- **작업 시간**: 약 30분
+- **검증 완료**: ✅ 문법, 로직, 코드 스타일
+
+## 🚀 다음 단계
+
+**Optional 추가 기능:**
+- Header에 현재 테넌트 배지 표시 (Filament Navigation 커스터마이징)
+- Tenant별 권한 제어 (특정 Tenant에만 접근 가능한 사용자)
+- Tenant 전환 이력 로그 (`audit_logs`에 기록)
+
+**Phase 2: 동적 필드 시스템 구현** (이전 계획 연기분)
+- Admin 기본 필드 관리 (`setting_field_defs`)
+- Tenant 오버로드 필드 (`tenant_field_settings`)
+- ViewUser Infolist에 동적 필드 섹션 추가 (Filament v4 방식)
--- a/dev/changes/20251111_admin_users_improvement.md
+++ b/dev/changes/20251111_admin_users_improvement.md
@@ -0,0 +1,204 @@
+# 변경 내용 요약
+
+**날짜:** 2025-11-11 13:54
+**작업자:** Claude Code
+**이슈:** SAM Admin 운영 관리 시스템 개선 - Phase 1
+
+## 📋 변경 개요
+
+SAM Admin 시스템의 사용자 페이지를 단순 CRUD에서 운영 관리 시스템으로 개선했습니다.
+
+**주요 개선 사항:**
+- 사용자 테이블에 테넌트, 부서, 역할 정보 컬럼 추가
+- RelationManager 3개 추가 (부서, 역할, 권한 관리)
+- N+1 쿼리 문제 해결 (Eager Loading 적용)
+- ~~사용자 상세 페이지 Infolist 구현~~ (Filament v4 호환성 이슈로 Phase 2로 연기)
+
+## 🔧 사용된 도구
+
+**MCP 서버:**
+- **Sequential Thinking**: 복잡도 분석, 의존성 파악, 작업 계획 수립
+- **Context7**: Filament v3 Infolist API 공식 문서 참조
+
+**네이티브 도구:**
+- **Read**: 기존 파일 분석 (8회)
+- **Edit**: 파일 수정 (5회)
+- **Write**: 신규 파일 생성 (4회)
+- **Bash**: Laravel Pint 실행, 타임스탬프 생성
+
+## 📁 수정된 파일
+
+**기존 파일 수정 (5개):**
+1. `admin/app/Models/Members/User.php` - departments, primaryDepartment 관계 추가
+2. `admin/app/Filament/Resources/Users/Tables/UsersTable.php` - 컬럼 4개, 필터 3개 추가
+3. `admin/app/Filament/Resources/Users/Pages/ViewUser.php` - Infolist 4개 섹션 구현
+4. `admin/app/Filament/Resources/Users/UserResource.php` - RelationManager 3개 등록
+5. `admin/app/Filament/Resources/Users/Pages/ListUsers.php` - Eager Loading 추가 (N+1 해결)
+
+**신규 파일 생성 (3개):**
+6. `admin/app/Filament/Resources/Users/RelationManagers/RolesRelationManager.php`
+7. `admin/app/Filament/Resources/Users/RelationManagers/PermissionsRelationManager.php`
+8. `admin/app/Filament/Resources/Users/RelationManagers/DepartmentsRelationManager.php`
+
+## 🔧 상세 변경 사항
+
+### 1. User 모델 - departments 관계 추가
+
+**파일:** `admin/app/Models/Members/User.php`
+
+**변경 후:**
+```php
+/**
+ * 소속 부서 (N:N)
+ */
+public function departments()
+{
+    return $this->belongsToMany(\App\Models\Tenants\Department::class, 'department_user')
+        ->withPivot(['tenant_id', 'is_primary', 'joined_at', 'left_at'])
+        ->withTimestamps()
+        ->wherePivotNull('deleted_at');
+}
+
+/**
+ * 주 부서 (is_primary = 1)
+ */
+public function primaryDepartment()
+{
+    return $this->belongsToMany(\App\Models\Tenants\Department::class, 'department_user')
+        ->withPivot(['tenant_id', 'is_primary', 'joined_at', 'left_at'])
+        ->withTimestamps()
+        ->wherePivot('is_primary', 1)
+        ->wherePivotNull('deleted_at')
+        ->limit(1);
+}
+```
+
+**이유:** Admin 및 API에서 사용자-부서 관계를 조회하기 위해 필요
+
+---
+
+### 2. UsersTable - 컬럼 및 필터 추가
+
+**파일:** `admin/app/Filament/Resources/Users/Tables/UsersTable.php`
+
+**추가된 컬럼:**
+- `tenantsMembership.name` - 테넌트 목록 (badge 형식)
+- `primaryDepartment.name` - 주 부서
+- `roles.name` - 역할 목록 (badge 형식)
+- `permissions_count` - 직접 부여된 권한 수
+
+**추가된 필터:**
+- `has_tenants` - 테넌트 연결 여부
+- `role` - 역할별 필터 (다중 선택 가능)
+- `department` - 부서별 필터 (다중 선택 가능)
+
+**이유:** 사용자 목록에서 테넌트, 부서, 역할 정보를 한눈에 파악하기 위해
+
+---
+
+### 3. ViewUser - Infolist 구현 (Filament v4 호환성 이슈로 보류)
+
+**파일:** `admin/app/Filament/Resources/Users/Pages/ViewUser.php`
+
+**상태:** 기본 View 페이지 유지
+
+**이유:**
+- Filament v4에서 Infolist API가 변경됨 (`Filament\Infolists\Infolist` → `Filament\Schemas\Schema`)
+- Context7로 조회한 문서가 v3 기준이었음
+- 호환성 에러 발생: `Could not check compatibility between ViewUser::infolist(Infolist): Infolist and ViewRecord::infolist(Schema): Schema`
+
+**해결:**
+- ViewUser를 기본 구현으로 되돌림
+- Infolist 기능은 Phase 2에서 Filament v4 방식으로 재구현 예정
+
+**TODO (Phase 2):**
+- Filament v4 방식으로 Infolist 재구현
+- Admin 기본 필드 (`setting_field_defs` 기반 동적 표시)
+- Tenant 추가 필드 (`tenant_field_settings` 기반 동적 표시)
+
+---
+
+### 4. RelationManagers 생성
+
+**파일:**
+- `RolesRelationManager.php`
+- `PermissionsRelationManager.php`
+- `DepartmentsRelationManager.php`
+
+**기능:**
+- **역할 관리**: 역할 추가/제거, 역할별 권한 수 표시
+- **권한 관리**: 직접 권한 추가/제거 (다중 선택 가능)
+- **부서 관리**: 부서 배정/해제, 주 부서 설정, 배정일/해제일 관리
+
+**이유:** 사용자 페이지에서 직접 역할, 권한, 부서를 관리하기 위해
+
+---
+
+### 5. ListUsers - N+1 쿼리 해결
+
+**파일:** `admin/app/Filament/Resources/Users/Pages/ListUsers.php`
+
+**변경 후:**
+```php
+protected function getTableQuery(): Builder
+{
+    return parent::getTableQuery()
+        ->with([
+            'tenantsMembership',
+            'departments' => function ($query) {
+                $query->wherePivot('is_primary', 1)->limit(1);
+            },
+            'roles',
+        ])
+        ->withCount('permissions');
+}
+```
+
+**이유:** UsersTable에서 관계 컬럼 사용 시 발생하는 N+1 쿼리 문제 해결
+
+---
+
+## ✅ 테스트 체크리스트
+
+- [x] Laravel Pint 실행 (12개 파일 스타일 이슈 자동 수정)
+- [x] PHP 문법 오류 확인 (오류 없음)
+- [ ] 로컬 서버 실행 및 사용자 목록 페이지 확인
+- [ ] 사용자 상세 페이지 Infolist 확인
+- [ ] RelationManager 동작 확인 (부서, 역할, 권한 추가/제거)
+- [ ] N+1 쿼리 개선 효과 확인 (Laravel Debugbar)
+- [ ] 필터 동작 확인 (테넌트, 역할, 부서)
+
+## ⚠️ 배포 시 주의사항
+
+1. **DB 마이그레이션 불필요**: 기존 테이블 활용, 스키마 변경 없음
+2. **Shared 모델 수정**: `Members/User.php`는 api 프로젝트에서도 사용되므로 영향 확인 필요
+3. **Spatie Permission 가드**: User 모델의 `guard_name = 'api'` 설정 유지 필요
+4. **동적 필드 (Phase 2)**: `setting_field_defs`, `tenant_field_settings` 기반 동적 필드는 추후 구현
+
+## 🔗 관련 문서
+
+- 계획 문서: `/Users/hskwon/Works/@KD_SAM/SAM/claudedocs/SAM/admin_improvement_plan.md`
+- Filament v3 Infolist: https://filamentphp.com/docs/3.x/infolists
+- Spatie Permission: https://spatie.be/docs/laravel-permission
+
+---
+
+## 📊 작업 통계
+
+- **수정된 파일**: 5개
+- **신규 파일**: 3개
+- **총 변경 라인 수**: 약 350줄
+- **작업 시간**: 약 1시간
+- **검증 완료**: ✅ 문법, 로직, 보안, 성능
+
+## 🚀 다음 단계
+
+**Phase 2: 동적 필드 시스템 구현**
+- Admin 기본 필드 관리 (`setting_field_defs`)
+- Tenant 오버로드 필드 (`tenant_field_settings`)
+- ViewUser Infolist에 동적 필드 섹션 추가
+
+**Phase 3: 기타 운영 관리 페이지**
+- 테넌트 관리 페이지 개선
+- 역할 & 권한 관리 페이지
+- 부서 관리 페이지 (계층 구조 트리 뷰)
--- a/dev/changes/20251215_items-api-files-fix.md
+++ b/dev/changes/20251215_items-api-files-fix.md
@@ -0,0 +1,300 @@
+# Items API files 배열 에러 수정
+
+## 날짜
+2025-12-15
+
+## 문제
+`PUT /api/v1/items/{id}` 요청 시 500 에러 발생
+```
+"Array to string conversion"
+```
+
+## 원인 분석
+1. API 요청에서 `files` 배열이 전송됨:
+```json
+{
+  "files": {
+    "drawing": [{
+      "id": 5,
+      "file_name": "IMG_2163.png",
+      "file_path": "287/items/2025/12/ec3483f4152d1eb1.png"
+    }]
+  }
+}
+```
+
+2. `ItemsService::getKnownFields()`의 `$apiFields`에 `files`가 없어서 동적 필드로 인식됨
+
+3. `extractDynamicOptions()`에서 `files`가 "알려지지 않은 필드"로 추출됨
+
+4. `$product->update($data)` 호출 시 `files` 배열이 그대로 전달되어 DB 저장 시 에러 발생
+
+## 수정 파일
+`api/app/Services/ItemsService.php`
+
+## 수정 내용
+
+### 1. getKnownFields() 메서드 (라인 36-37)
+```php
+// 수정 전
+$apiFields = ['item_type', 'type_code', 'bom', 'product_type'];
+
+// 수정 후
+$apiFields = ['item_type', 'type_code', 'bom', 'product_type', 'files'];
+```
+
+### 2. updateProduct() 메서드 (라인 729-730)
+```php
+// 수정 전
+unset($data['item_type']);
+
+// 수정 후
+unset($data['item_type'], $data['files']);
+```
+
+### 3. updateMaterial() 메서드 (라인 771-772)
+```php
+// 수정 전
+unset($data['item_type'], $data['code']);
+
+// 수정 후
+unset($data['item_type'], $data['code'], $data['files']);
+```
+
+## 적용 체크리스트
+- [x] `getKnownFields()` - `$apiFields`에 `'files'` 추가
+- [x] `updateProduct()` - `unset()`에 `$data['files']` 추가
+- [x] `updateMaterial()` - `unset()`에 `$data['files']` 추가
+
+## 커밋 정보
+```
+c68c280 fix: Items API 수정 시 files 배열로 인한 500 에러 수정
+```
+
+## 관련 파일
+- `api/app/Http/Controllers/Api/V1/ItemsController.php`
+- `api/app/Http/Controllers/Api/V1/ItemsFileController.php`
+
+---
+
+# ItemsFileController delete 메서드 타입 에러 수정
+
+## 날짜
+2025-12-15
+
+## 문제
+`DELETE /api/v1/items/{id}/files/{fileId}` 요청 시 타입 에러 발생
+```
+Argument #2 ($fileId) must be of type int, string given
+```
+
+## 원인 분석
+Laravel 라우트 파라미터는 기본적으로 string으로 전달되는데, 컨트롤러 메서드에서 `int` 타입힌트를 사용하여 에러 발생
+
+## 수정 파일
+`api/app/Http/Controllers/Api/V1/ItemsFileController.php`
+
+## 수정 내용
+
+### delete() 메서드 (라인 157-159)
+```php
+// 수정 전
+public function delete(int $id, int $fileId, Request $request)
+{
+    return ApiResponse::handle(function () use ($id, $fileId, $request) {
+
+// 수정 후
+public function delete(int $id, mixed $fileId, Request $request)
+{
+    $fileId = (int) $fileId;
+
+    return ApiResponse::handle(function () use ($id, $fileId, $request) {
+```
+
+## 적용 체크리스트
+- [x] `delete()` 메서드 - `$fileId` 파라미터 타입을 `mixed`로 변경
+- [x] `delete()` 메서드 - 내부에서 `$fileId = (int) $fileId;` 캐스팅 추가
+
+## 커밋 정보
+```
+1040ce0 fix: ItemsFileController delete 메서드 타입 에러 수정
+```
+
+---
+
+# ItemsFileController userId null 처리
+
+## 날짜
+2025-12-15
+
+## 문제
+`DELETE /api/v1/items/{id}/files/{fileId}` 요청 시 500 에러 발생
+```
+softDeleteFile(): Argument #1 ($userId) must be of type int, null given
+```
+
+## 원인 분석
+- `auth()->id()`가 `null`을 반환
+- API 키 인증만 사용하고 Sanctum 토큰 인증이 없는 경우 발생
+- `softDeleteFile(int $userId)` 메서드에 null 전달 시 타입 에러
+
+## 수정 파일
+`api/app/Http/Controllers/Api/V1/ItemsFileController.php`
+
+## 수정 내용
+
+### 1. upload() 메서드 (라인 77)
+```php
+// 수정 전
+$userId = auth()->id();
+
+// 수정 후
+$userId = auth()->id() ?? app('api_user');
+```
+
+### 2. delete() 메서드 (라인 163)
+```php
+// 수정 전
+$userId = auth()->id();
+
+// 수정 후
+$userId = auth()->id() ?? app('api_user');
+```
+
+## 적용 체크리스트
+- [x] `upload()` 메서드 - `auth()->id() ?? app('api_user')` 변경
+- [x] `delete()` 메서드 - `auth()->id() ?? app('api_user')` 변경
+
+## 커밋 정보
+```
+22abb99 fix: ItemsFileController userId null 처리 추가
+```
+
+---
+
+# ItemsFileController 파일 삭제 로직 일원화
+
+## 날짜
+2025-12-15
+
+## 문제
+- `upload()` 메서드의 파일 교체 삭제와 `delete()` 메서드의 파일 삭제 로직이 분리되어 있음
+- userId 캐스팅이 일관되지 않음 (upload에만 int 캐스팅 적용)
+- 관리 포인트가 2곳으로 분산
+
+## 수정 파일
+`api/app/Http/Controllers/Api/V1/ItemsFileController.php`
+
+## 수정 내용
+
+### 1. deleteFile() private 메서드 추가 (라인 195-199)
+```php
+// 추가
+private function deleteFile(File $file): void
+{
+    $userId = (int) (auth()->id() ?? app('api_user'));
+    $file->softDeleteFile($userId);
+}
+```
+
+### 2. upload() 메서드 - 기존 파일 교체 시 (라인 98-100)
+```php
+// 수정 전
+if ($existingFile) {
+    $existingFile->softDeleteFile($userId);
+    $replaced = true;
+}
+
+// 수정 후
+if ($existingFile) {
+    $this->deleteFile($existingFile);
+    $replaced = true;
+}
+```
+
+### 3. delete() 메서드 (라인 180-181)
+```php
+// 수정 전
+$userId = auth()->id() ?? app('api_user');
+...
+$file->softDeleteFile($userId);
+
+// 수정 후
+// $userId 변수 제거
+$this->deleteFile($file);
+```
+
+## 적용 체크리스트
+- [x] `deleteFile()` private 메서드 추가
+- [x] `upload()` 메서드 - `$this->deleteFile($existingFile)` 사용
+- [x] `delete()` 메서드 - `$userId` 변수 제거, `$this->deleteFile($file)` 사용
+
+## 커밋 정보
+```
+dea414b refactor: ItemsFileController 파일 삭제 로직 일원화
+```
+
+---
+
+# ItemsFileController 파일 다운로드 URL 수정
+
+## 날짜
+2025-12-15
+
+## 문제
+파일 다운로드 시 인증 오류 발생
+- 생성되는 URL: `/api/v1/files/download/{base64_path}` (라우트 없음)
+- 실제 라우트: `/api/v1/files/{id}/download`
+
+## 수정 파일
+`api/app/Http/Controllers/Api/V1/ItemsFileController.php`
+
+## 수정 내용
+
+### 1. getFileUrl() 메서드 (라인 244-247)
+```php
+// 수정 전
+private function getFileUrl(string $filePath): string
+{
+    return url('/api/v1/files/download/'.base64_encode($filePath));
+}
+
+// 수정 후
+private function getFileUrl(int $fileId): string
+{
+    return url("/api/v1/files/{$fileId}/download");
+}
+```
+
+### 2. formatFileResponse() 메서드 (라인 232)
+```php
+// 수정 전
+'file_url' => $this->getFileUrl($file->file_path),
+
+// 수정 후
+'file_url' => $this->getFileUrl($file->id),
+```
+
+### 3. upload() 응답 (라인 142)
+```php
+// 수정 전
+'file_url' => $this->getFileUrl($filePath),
+
+// 수정 후
+'file_url' => $this->getFileUrl($file->id),
+```
+
+## 적용 체크리스트
+- [x] `getFileUrl()` 메서드 - 파라미터를 `string $filePath` → `int $fileId`로 변경
+- [x] `getFileUrl()` 메서드 - URL 형식을 `/api/v1/files/{id}/download`로 변경
+- [x] `formatFileResponse()` - `$this->getFileUrl($file->id)` 사용
+- [x] `upload()` 응답 - `$this->getFileUrl($file->id)` 사용
+
+## 프론트엔드 참고
+- 다운로드 요청 시 **API 키 헤더 필수** (`X-API-Key` 또는 설정된 헤더)
+- 기존 FileStorageController의 download 라우트 활용
+
+## 커밋 정보
+```
+98262ed fix: ItemsFileController 파일 다운로드 URL을 file_id 기반으로 변경
+```
--- a/dev/changes/20251225_employee_user_linkage.md
+++ b/dev/changes/20251225_employee_user_linkage.md
@@ -0,0 +1,78 @@
+# 변경 내용 요약
+
+**날짜:** 2025-12-25
+**작업자:** Claude Code
+**이슈:** employee-user-linkage-plan.md 구현
+
+## 📋 변경 개요
+사원-회원 연결 기능의 핵심 API 구현:
+- 사원 전용 등록 (시스템 계정 없이)
+- 계정 해제 기능 (revokeAccount)
+
+## 📁 수정된 파일
+
+### 1. api/app/Services/EmployeeService.php
+- **store()**: password 생성 로직 수정 - `create_account=false`면 password=NULL 허용
+- **revokeAccount()**: 신규 메서드 추가 - 시스템 계정 해제 (password=NULL, 토큰 무효화)
+
+### 2. api/app/Http/Controllers/Api/V1/EmployeeController.php
+- **revokeAccount()**: 신규 액션 추가
+- **createAccount()**: 응답 메시지 i18n 키로 변경
+
+### 3. api/routes/api.php
+- `POST /employees/{id}/revoke-account` 라우트 추가
+
+### 4. api/lang/ko/employee.php (신규)
+- 사원 관련 메시지 키 정의
+
+### 5. api/lang/en/employee.php (신규)
+- 영문 메시지 키 정의
+
+## 🔧 상세 변경 사항
+
+### 1. EmployeeService::store() 수정
+
+**변경 전:**
+```php
+'password' => Hash::make($data['password'] ?? Str::random(16)),
+```
+
+**변경 후:**
+```php
+$password = null;
+$createAccount = $data['create_account'] ?? false;
+if ($createAccount && ! empty($data['password'])) {
+    $password = Hash::make($data['password']);
+}
+// ...
+'password' => $password,
+```
+
+**이유:** 사원 전용 등록 지원 (로그인 불가)
+
+### 2. EmployeeService::revokeAccount() 추가
+
+```php
+public function revokeAccount(int $id): TenantUserProfile
+{
+    // tenant_id 격리 적용
+    // password=NULL로 설정 (로그인 불가)
+    // 기존 토큰 무효화
+}
+```
+
+**이유:** 시스템 계정 해제 기능
+
+## ✅ 테스트 체크리스트
+- [x] PHP 문법 검사 통과
+- [x] Pint 코드 포맷 통과
+- [x] 라우트 등록 확인
+- [ ] Swagger 문서 작성 (추후)
+- [ ] API 통합 테스트 (추후)
+
+## ⚠️ 배포 시 주의사항
+- users.password 컬럼이 nullable인지 확인 필요
+- 기존 사원 데이터에 영향 없음
+
+## 🔗 관련 문서
+- docs/dev_plans/employee-user-linkage-plan.md
--- a/dev/changes/20251230_react_fcm_push_notification.md
+++ b/dev/changes/20251230_react_fcm_push_notification.md
@@ -0,0 +1,95 @@
+# 변경 내용 요약
+
+**날짜:** 2025-12-30 14:30
+**작업자:** Claude Code
+**관련 문서:** docs/dev_plans/react-fcm-push-notification-plan.md
+
+## 📋 변경 개요
+
+React 프로젝트에 FCM 푸시 알림 기능 추가. Capacitor 네이티브 앱(iOS/Android)에서 dev.sam.kr 웹뷰 로드 시 푸시 알림을 지원합니다.
+
+- 포팅 원본: `mng/public/js/fcm.js`
+- 백엔드 API 변경 없음 (기존 `/push/*` 엔드포인트 재사용)
+
+## 📁 수정된 파일
+
+### 신규 생성 (4개)
+| 파일 | 용량 | 용도 |
+|------|------|------|
+| `react/src/lib/capacitor/fcm.ts` | 9.1KB | FCM 핵심 로직 (토큰 관리, 알림 처리) |
+| `react/src/hooks/useFCM.ts` | 3.3KB | React 훅 (sonner 토스트 연동) |
+| `react/src/contexts/FCMProvider.tsx` | 1.8KB | 앱 전역 FCM 초기화 Provider |
+| `react/public/sounds/*.wav` | 1.6MB | 알림 사운드 (mng에서 복사) |
+
+### 수정 (2개)
+| 파일 | 변경 내용 |
+|------|----------|
+| `react/src/app/[locale]/(protected)/layout.tsx` | FCMProvider 추가 |
+| `react/src/lib/auth/logout.ts` | 로그아웃 시 FCM 토큰 해제 연동 |
+
+### 의존성 추가 (3개)
+| 패키지 | 버전 | 용도 |
+|--------|------|------|
+| @capacitor/core | ^8.0.0 | Capacitor 코어 |
+| @capacitor/push-notifications | ^8.0.0 | 푸시 알림 플러그인 |
+| @capacitor/app | ^8.0.0 | 앱 상태 감지 |
+
+## 🔧 상세 변경 사항
+
+### 1. FCM 유틸리티 (fcm.ts)
+
+**주요 함수:**
+- `initializeFCM()`: FCM 초기화 (권한 요청, 토큰 발급, 리스너 등록)
+- `unregisterFCMToken()`: 토큰 해제 (로그아웃 시)
+- `isCapacitorNative()`: 네이티브 환경 체크
+
+**특징:**
+- Next.js 프록시 패턴 사용 (`/api/proxy/v1/push/*`)
+- HttpOnly 쿠키 자동 포함 (credentials: 'include')
+- 포그라운드 알림 콜백 지원
+
+### 2. useFCM 훅
+
+**기능:**
+- 로그인 상태에서 자동 FCM 초기화
+- 포그라운드 알림 → sonner 토스트
+- 알림 타입별 스타일 (error, warning, success, info)
+
+### 3. FCMProvider
+
+**위치:** `(protected)/layout.tsx`
+- RootProvider 안에서 FCM 초기화
+- 인증된 페이지에서만 동작
+
+### 4. 로그아웃 연동
+
+**logout.ts 변경:**
+```typescript
+// 4. FCM 토큰 해제 (Capacitor 네이티브 앱에서만 실행)
+if (isCapacitorNative()) {
+  await unregisterFCMToken();
+  console.log('[Logout] FCM token unregistered');
+}
+```
+
+## ✅ 테스트 체크리스트
+
+- [ ] Capacitor 앱에서 dev.sam.kr 로드 확인
+- [ ] 로그인 후 FCM 토큰 등록 확인 (콘솔 로그)
+- [ ] 포그라운드 알림 수신 → sonner 토스트 표시
+- [ ] 알림 사운드 재생 확인
+- [ ] 알림 클릭 → URL 이동 확인
+- [ ] 로그아웃 → FCM 토큰 해제 확인
+- [ ] 웹 브라우저에서는 FCM 로직 스킵 확인
+
+## ⚠️ 배포 시 주의사항
+
+1. **iOS**: Xcode에서 Push Notification Capability 활성화 필요
+2. **Android**: google-services.json 설정 확인
+3. **프록시**: `/api/proxy/v1/push/*` 라우트 존재 확인
+
+## 🔗 관련 문서
+
+- [FCM 연동 계획](../plans/react-fcm-push-notification-plan.md)
+- [Capacitor Push Notifications](https://capacitorjs.com/docs/apis/push-notifications)
+- [mng/public/js/fcm.js](../../mng/public/js/fcm.js) (포팅 원본)
--- a/dev/changes/20260102_quote_bom_calculation_api.md
+++ b/dev/changes/20260102_quote_bom_calculation_api.md
@@ -0,0 +1,136 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-02
+**작업자:** Claude Code
+**작업명:** 견적 산출 API 개발 - Phase 1.1 API 계산 로직 구현
+
+## 📋 변경 개요
+MNG FormulaEvaluatorService의 BOM 기반 견적 계산 로직을 API에서 호출할 수 있는 엔드포인트를 구현했습니다. 완제품 코드와 입력 변수를 받아 품목/단가/금액을 자동 계산하며, 10단계 디버깅 정보를 제공합니다.
+
+## 📁 수정된 파일
+
+### 신규 파일
+- `api/app/Http/Requests/Quote/QuoteBomCalculateRequest.php` - BOM 계산용 FormRequest
+
+### 수정된 파일
+- `api/app/Services/Quote/QuoteCalculationService.php` - calculateBom 메서드 추가
+- `api/app/Http/Controllers/Api/V1/QuoteController.php` - calculateBom 액션 추가
+- `api/routes/api.php` - /calculate/bom 라우트 추가
+- `api/app/Swagger/v1/QuoteApi.php` - 스키마 및 엔드포인트 문서 추가
+
+## 🔧 상세 변경 사항
+
+### 1. QuoteBomCalculateRequest.php (신규)
+**목적:** BOM 기반 견적 계산 요청 검증
+
+**주요 기능:**
+- 필수 입력: `finished_goods_code`, `W0`, `H0`
+- 선택 입력: `QTY`, `PC`, `GT`, `MP`, `CT`, `WS`, `INSP`, `debug`
+- `getInputVariables()`: 서비스용 입력 변수 배열 반환
+
+### 2. QuoteCalculationService.php
+**변경 전:** BOM 계산 메서드 없음
+
+**변경 후:**
+```php
+public function calculateBom(string $finishedGoodsCode, array $inputs, bool $debug = false): array
+{
+    $tenantId = $this->tenantId();
+    $result = $this->formulaEvaluator->calculateBomWithDebug(
+        $finishedGoodsCode,
+        $inputs,
+        $tenantId
+    );
+    if (! $debug && isset($result['debug_steps'])) {
+        unset($result['debug_steps']);
+    }
+    return $result;
+}
+```
+
+**이유:** API에서 MNG FormulaEvaluatorService의 calculateBomWithDebug를 호출할 수 있도록 브릿지 메서드 추가
+
+### 3. QuoteController.php
+**변경 후:**
+```php
+public function calculateBom(QuoteBomCalculateRequest $request)
+{
+    return ApiResponse::handle(function () use ($request) {
+        return $this->calculationService->calculateBom(
+            $request->finished_goods_code,
+            $request->getInputVariables(),
+            $request->boolean('debug', false)
+        );
+    }, __('message.quote.calculated'));
+}
+```
+
+**이유:** REST API 엔드포인트 제공
+
+### 4. routes/api.php
+**추가된 라우트:**
+```php
+Route::post('/calculate/bom', [QuoteController::class, 'calculateBom'])->name('v1.quotes.calculate-bom');
+```
+
+### 5. QuoteApi.php (Swagger)
+**추가된 스키마:**
+- `QuoteBomCalculateRequest` - 요청 스키마
+- `QuoteBomCalculationResult` - 응답 스키마
+
+**추가된 엔드포인트:**
+- `POST /api/v1/quotes/calculate/bom` - BOM 기반 자동산출 (10단계 디버깅)
+
+## ✅ 테스트 체크리스트
+- [x] PHP 문법 검사 통과
+- [x] Pint 코드 스타일 검사 통과
+- [x] 라우트 등록 확인
+- [x] 서비스 로직 검증 (tinker)
+- [x] Swagger 문서 생성 확인
+- [ ] 실제 API 호출 테스트 (Docker 환경 필요)
+
+## ⚠️ 배포 시 주의사항
+- 특이사항 없음
+- 기존 API에 영향 없음 (신규 엔드포인트 추가)
+
+## 🔗 관련 문서
+- 계획 문서: `docs/dev_plans/quote-calculation-api-plan.md`
+- FormulaEvaluatorService: `api/app/Services/Quote/FormulaEvaluatorService.php`
+
+## 📊 API 사용 예시
+
+### 요청
+```bash
+curl -X POST "http://api.sam.kr/api/v1/quotes/calculate/bom" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "finished_goods_code": "SC-1000",
+    "W0": 3000,
+    "H0": 2500,
+    "QTY": 1,
+    "PC": "SCREEN",
+    "GT": "wall",
+    "MP": "single",
+    "CT": "basic",
+    "debug": true
+  }'
+```
+
+### 응답
+```json
+{
+  "success": true,
+  "message": "견적이 산출되었습니다.",
+  "data": {
+    "success": true,
+    "finished_goods": {"code": "SC-1000", "name": "전동스크린 1000형"},
+    "variables": {"W0": 3000, "H0": 2500, "W1": 3100, "H1": 2650, "M": 8.215, "K": 12.5},
+    "items": [...],
+    "grouped_items": {...},
+    "subtotals": {"material": 500000, "labor": 100000, "install": 50000},
+    "grand_total": 650000,
+    "debug_steps": [...]
+  }
+}
+```
--- a/dev/changes/20260109_handover_report_api_integration.md
+++ b/dev/changes/20260109_handover_report_api_integration.md
@@ -0,0 +1,81 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-09
+**작업자:** Claude Code
+**이슈:** Phase 1.2 인수인계보고서관리 Frontend API 연동
+
+## 📋 변경 개요
+
+인수인계보고서관리(Handover Report) Frontend의 actions.ts를 Mock 데이터에서 실제 API 연동으로 변환했습니다.
+
+## 📁 수정된 파일
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `react/src/components/business/construction/handover-report/actions.ts` | Mock → API 완전 변환 |
+| `docs/dev_plans/sub/handover-report-plan.md` | 진행 상태 업데이트 |
+
+## 🔧 상세 변경 사항
+
+### 1. actions.ts 완전 재작성 (499줄)
+
+**제거된 코드:**
+- `MOCK_REPORTS` 배열 (7개 목업 데이터)
+- `MOCK_REPORT_DETAILS` 객체 (상세 목업 데이터)
+- 모든 목업 기반 로직
+
+**추가된 코드:**
+
+#### 헬퍼 함수
+```typescript
+// API 요청 헬퍼 (쿠키 기반 인증)
+async function apiRequest<T>(endpoint, options): Promise<ApiResult<T>>
+
+// 타입 변환 함수들
+function transformHandoverReport(apiData): HandoverReport
+function transformHandoverReportDetail(apiData): HandoverReportDetail
+function transformToApiRequest(data): Record<string, unknown>
+```
+
+#### API 연동 함수
+| 함수명 | HTTP Method | Endpoint | 용도 |
+|--------|-------------|----------|------|
+| `getHandoverReportList` | GET | `/construction/handover-reports` | 목록 조회 |
+| `getHandoverReportStats` | GET | `/construction/handover-reports/stats` | 통계 조회 |
+| `getHandoverReportDetail` | GET | `/construction/handover-reports/{id}` | 상세 조회 |
+| `createHandoverReport` | POST | `/construction/handover-reports` | 등록 (신규) |
+| `updateHandoverReport` | PUT | `/construction/handover-reports/{id}` | 수정 |
+| `deleteHandoverReport` | DELETE | `/construction/handover-reports/{id}` | 삭제 |
+| `deleteHandoverReports` | DELETE | `/construction/handover-reports/bulk` | 일괄 삭제 |
+
+#### 타입 변환 매핑
+- `snake_case` (API) ↔ `camelCase` (Frontend)
+- 중첩 객체 처리: `managers`, `items`, `external_equipment_cost`
+- null 안전 처리 및 기본값 설정
+
+### 2. handover-report-plan.md 업데이트
+
+- 상태: ⏳ 대기 → 🔄 진행중
+- Frontend 작업 상태 갱신
+- 마지막 업데이트 날짜 변경
+
+## ✅ 검증 결과
+
+- [x] TypeScript 타입 검사: 오류 없음
+- [x] ESLint 검사: 오류 없음
+- [x] 타입 정합성: types.ts와 완전 일치
+
+## ⚠️ 알려진 이슈 (별도 작업 필요)
+
+`HandoverReportListClient.tsx`에 기존 타입 불일치 존재:
+- `partnerId` - HandoverReport 타입에 없음
+- `contractManagerId` - HandoverReport 타입에 없음
+- `constructionPMId` - HandoverReport 타입에 없음
+
+→ 이번 작업 범위 외, 별도 수정 필요
+
+## 🔗 관련 문서
+
+- [상위 계획](../plans/construction-api-integration-plan.md)
+- [세부 계획](../plans/sub/handover-report-plan.md)
+- [API 백엔드](../../api/app/Services/Construction/HandoverReportService.php)
--- a/dev/changes/20260122_card_transaction_dashboard_api.md
+++ b/dev/changes/20260122_card_transaction_dashboard_api.md
@@ -0,0 +1,75 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-22
+**작업자:** Claude Code
+**계획 문서:** docs/dev_plans/card-management-section-plan.md
+**Phase:** 1.1 카드 거래 대시보드 API 개발
+
+## 📋 변경 개요
+CEO 대시보드 카드/가지급금 관리 섹션(cm1)의 모달 팝업용 카드 거래 대시보드 API 엔드포인트 신규 추가.
+기존 summary API를 확장하여 월별 추이, 사용자별 비율, 최근 거래 목록을 포함한 상세 데이터 제공.
+
+## 📁 수정된 파일
+- `api/app/Services/CardTransactionService.php` - dashboard() 메서드 및 헬퍼 메서드 추가
+- `api/app/Http/Controllers/Api/V1/CardTransactionController.php` - dashboard() 액션 추가
+- `api/routes/api.php` - /dashboard 라우트 등록
+- `api/app/Swagger/v1/CardTransactionApi.php` - 대시보드 스키마 및 엔드포인트 문서화
+
+## 🔧 상세 변경 사항
+
+### 1. CardTransactionService.php
+**신규 메서드:**
+- `dashboard()` - 대시보드 전체 데이터 반환
+- `getMonthTotal()` - 특정 기간 카드 사용액 합계 (private)
+- `getMonthlyTrend()` - 최근 N개월 월별 추이 (private)
+- `getUserRatio()` - 사용자별 카드 사용 비율 (private)
+- `getRecentTransactions()` - 최근 거래 목록 (private)
+
+**응답 구조:**
+```php
+[
+    'summary' => [
+        'current_month_total' => float,
+        'previous_month_total' => float,
+        'change_rate' => float,
+        'unprocessed_count' => int,
+    ],
+    'monthly_trend' => [...],
+    'user_ratio' => [...],
+    'recent_transactions' => [...],
+]
+```
+
+### 2. CardTransactionController.php
+**신규 액션:**
+```php
+public function dashboard(): JsonResponse
+```
+
+### 3. api/routes/api.php
+**신규 라우트:**
+```php
+Route::get('/dashboard', [CardTransactionController::class, 'dashboard'])
+    ->name('v1.card-transactions.dashboard');
+```
+
+### 4. CardTransactionApi.php (Swagger)
+**신규 스키마:**
+- `CardTransactionDashboard` - 대시보드 응답 전체 구조
+
+**신규 엔드포인트:**
+- `GET /api/v1/card-transactions/dashboard`
+
+## ✅ 테스트 체크리스트
+- [x] Pint 코드 스타일 검증 통과
+- [x] 라우트 등록 확인 (php artisan route:list)
+- [x] Swagger 문서 생성 완료
+- [ ] API 호출 테스트 (Swagger UI)
+- [ ] 프론트엔드 연동 테스트
+
+## ⚠️ 배포 시 주의사항
+특이사항 없음 (DB 스키마 변경 없음)
+
+## 🔗 관련 문서
+- 계획 문서: `docs/dev_plans/card-management-section-plan.md`
+- 기존 API 문서: `api/app/Swagger/v1/CardTransactionApi.php`
--- a/dev/changes/20260122_loan_dashboard_api.md
+++ b/dev/changes/20260122_loan_dashboard_api.md
@@ -0,0 +1,83 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-22
+**작업자:** Claude Code
+**계획 문서:** docs/dev_plans/card-management-section-plan.md
+**Phase:** 1.2 가지급금 대시보드 API 개발
+
+## 📋 변경 개요
+CEO 대시보드 카드/가지급금 관리 섹션(cm2)의 모달 팝업용 가지급금 대시보드 API 엔드포인트 신규 추가.
+기존 summary 및 calculateInterest 로직을 활용하여 요약 데이터(미정산 총액, 인정이자, 미정산 건수)와 최근 가지급금 목록을 제공.
+
+## 📁 수정된 파일
+- `api/app/Services/LoanService.php` - dashboard() 메서드 추가
+- `api/app/Http/Controllers/Api/V1/LoanController.php` - dashboard() 액션 추가
+- `api/routes/api.php` - /dashboard 라우트 등록
+- `api/app/Swagger/v1/LoanApi.php` - 대시보드 스키마 및 엔드포인트 문서화
+
+## 🔧 상세 변경 사항
+
+### 1. LoanService.php
+**신규 메서드:**
+- `dashboard()` - 대시보드 전체 데이터 반환
+  - 기존 `summary()` 호출하여 미정산 총액, 건수 획득
+  - 기존 `calculateInterest()` 호출하여 인정이자 계산
+  - 가지급금 목록 (최근 10건, 미정산 우선 정렬)
+
+**응답 구조:**
+```php
+[
+    'summary' => [
+        'total_outstanding' => float,      // 미정산 가지급금 총액
+        'recognized_interest' => float,    // 인정이자 (연 4.6%)
+        'outstanding_count' => int,        // 미정산 건수
+    ],
+    'loans' => [
+        [
+            'id' => int,
+            'loan_date' => string,         // Y-m-d
+            'user_name' => string,
+            'category' => string,          // 카드/계좌
+            'amount' => float,
+            'status' => string,            // outstanding/settled/partial
+            'content' => string,           // 목적
+        ],
+        // ... 최대 10건
+    ],
+]
+```
+
+### 2. LoanController.php
+**신규 액션:**
+```php
+public function dashboard(): JsonResponse
+```
+
+### 3. api/routes/api.php
+**신규 라우트:**
+```php
+Route::get('/dashboard', [LoanController::class, 'dashboard'])
+    ->name('v1.loans.dashboard');
+```
+
+### 4. LoanApi.php (Swagger)
+**신규 스키마:**
+- `LoanDashboard` - 대시보드 응답 전체 구조
+
+**신규 엔드포인트:**
+- `GET /api/v1/loans/dashboard`
+
+## ✅ 테스트 체크리스트
+- [x] Pint 코드 스타일 검증 통과
+- [x] 라우트 등록 확인 (php artisan route:list)
+- [x] Swagger 문서 생성 완료
+- [ ] API 호출 테스트 (Swagger UI)
+- [ ] 프론트엔드 연동 테스트
+
+## ⚠️ 배포 시 주의사항
+특이사항 없음 (DB 스키마 변경 없음)
+
+## 🔗 관련 문서
+- 계획 문서: `docs/dev_plans/card-management-section-plan.md`
+- Phase 1.1 변경: `docs/changes/20260122_card_transaction_dashboard_api.md`
+- 기존 API 문서: `api/app/Swagger/v1/LoanApi.php`
--- a/dev/changes/20260122_tax_simulation_api.md
+++ b/dev/changes/20260122_tax_simulation_api.md
@@ -0,0 +1,104 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-22
+**작업자:** Claude Code
+**계획 문서:** docs/dev_plans/card-management-section-plan.md
+**Phase:** 1.3 세금 시뮬레이션 API 개발
+
+## 📋 변경 개요
+CEO 대시보드 카드/가지급금 관리 섹션(cm2)의 세금 시뮬레이션 API 엔드포인트 신규 추가.
+가지급금으로 인한 법인세 및 소득세 추가 부담을 시뮬레이션하여 세금 비교 분석 데이터 제공.
+
+## 📁 수정된 파일
+- `api/app/Services/LoanService.php` - taxSimulation() 메서드 추가
+- `api/app/Http/Controllers/Api/V1/LoanController.php` - taxSimulation() 액션 추가
+- `api/routes/api.php` - /tax-simulation 라우트 등록
+- `api/app/Swagger/v1/LoanApi.php` - LoanTaxSimulation 스키마 및 엔드포인트 문서화
+
+## 🔧 상세 변경 사항
+
+### 1. LoanService.php
+**신규 메서드:**
+- `taxSimulation(int $year)` - 세금 시뮬레이션 데이터 반환
+  - 기존 `summary()` 호출하여 미정산 가지급금 총액 획득
+  - 기존 `calculateInterest()` 호출하여 인정이자 계산
+  - 법인세 비교 (가지급금 유무에 따른 세금 차이)
+  - 소득세 비교 (대표이사 상여처분 시나리오)
+
+**응답 구조:**
+```php
+[
+    'year' => int,                          // 시뮬레이션 연도
+    'loan_summary' => [
+        'total_outstanding' => float,       // 가지급금 잔액
+        'recognized_interest' => float,     // 인정이자
+        'interest_rate' => float,           // 이자율 (4.6%)
+    ],
+    'corporate_tax' => [                    // 법인세 비교
+        'without_loan' => [
+            'taxable_income' => float,
+            'tax_amount' => float,
+        ],
+        'with_loan' => [
+            'taxable_income' => float,      // 인정이자
+            'tax_amount' => float,          // 인정이자 × 19%
+        ],
+        'difference' => float,              // 추가 법인세
+        'rate_info' => string,              // "법인세 19% 적용"
+    ],
+    'income_tax' => [                       // 소득세 비교
+        'without_loan' => [
+            'taxable_income' => float,
+            'tax_rate' => string,
+            'tax_amount' => float,
+        ],
+        'with_loan' => [
+            'taxable_income' => float,
+            'tax_rate' => string,           // "35%"
+            'tax_amount' => float,
+        ],
+        'difference' => float,
+        'breakdown' => [
+            'income_tax' => float,          // 소득세 (35%)
+            'local_tax' => float,           // 지방소득세 (소득세의 10%)
+            'insurance' => float,           // 4대보험 추정 (9%)
+        ],
+    ],
+]
+```
+
+### 2. LoanController.php
+**신규 액션:**
+```php
+public function taxSimulation(LoanCalculateInterestRequest $request): JsonResponse
+```
+
+### 3. api/routes/api.php
+**신규 라우트:**
+```php
+Route::get('/tax-simulation', [LoanController::class, 'taxSimulation'])
+    ->name('v1.loans.tax-simulation');
+```
+
+### 4. LoanApi.php (Swagger)
+**신규 스키마:**
+- `LoanTaxSimulation` - 세금 시뮬레이션 응답 전체 구조
+
+**신규 엔드포인트:**
+- `GET /api/v1/loans/tax-simulation?year={year}`
+
+## ✅ 테스트 체크리스트
+- [x] Pint 코드 스타일 검증 통과
+- [x] 라우트 등록 확인 (php artisan route:list)
+- [x] Swagger 문서 생성 완료
+- [ ] API 호출 테스트 (Swagger UI)
+- [ ] 프론트엔드 연동 테스트
+
+## ⚠️ 배포 시 주의사항
+특이사항 없음 (DB 스키마 변경 없음)
+
+## 🔗 관련 문서
+- 계획 문서: `docs/dev_plans/card-management-section-plan.md`
+- Phase 1.1 변경: `docs/changes/20260122_card_transaction_dashboard_api.md`
+- Phase 1.2 변경: `docs/changes/20260122_loan_dashboard_api.md`
+- 기존 API 문서: `api/app/Swagger/v1/LoanApi.php`
--- a/dev/changes/20260126_quote_v2_test_detail_api.md
+++ b/dev/changes/20260126_quote_v2_test_detail_api.md
@@ -0,0 +1,141 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-26
+**작업자:** Claude Code
+**관련 계획:** docs/dev_plans/quote-management-url-migration-plan.md (Step 1.3, 1.4)
+
+## 📋 변경 개요
+V2 견적 상세/수정 테스트 페이지(test/[id])에서 Mock 데이터를 실제 API 연동으로 변경
+
+## 📁 수정된 파일
+- `react/src/app/[locale]/(protected)/sales/quote-management/test/[id]/page.tsx` - API 연동 구현
+
+## 🔧 상세 변경 사항
+
+### 1. Import 추가
+```typescript
+import { getQuoteById, updateQuote } from "@/components/quotes/actions";
+import { transformApiToV2, transformV2ToApi } from "@/components/quotes/types";
+```
+
+### 2. MOCK_DATA 제거
+- 65줄의 하드코딩된 테스트 데이터 제거
+
+### 3. useEffect 수정 (데이터 로드)
+
+**변경 전:**
+```typescript
+useEffect(() => {
+  const loadQuote = async () => {
+    setIsLoading(true);
+    try {
+      await new Promise((resolve) => setTimeout(resolve, 500));  // Mock delay
+      setQuote({ ...MOCK_DATA, id: quoteId });
+    } catch (error) {
+      toast.error("견적 정보를 불러오는데 실패했습니다.");
+      router.push("/sales/quote-management");
+    } finally {
+      setIsLoading(false);
+    }
+  };
+  loadQuote();
+}, [quoteId, router]);
+```
+
+**변경 후:**
+```typescript
+useEffect(() => {
+  const loadQuote = async () => {
+    setIsLoading(true);
+    try {
+      const result = await getQuoteById(quoteId);
+
+      if (!result.success || !result.data) {
+        toast.error(result.error || "견적 정보를 불러오는데 실패했습니다.");
+        router.push("/sales/quote-management");
+        return;
+      }
+
+      // API 응답을 V2 폼 데이터로 변환
+      const v2Data = transformApiToV2(result.data);
+      setQuote(v2Data);
+    } catch (error) {
+      toast.error("견적 정보를 불러오는데 실패했습니다.");
+      router.push("/sales/quote-management");
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  if (quoteId) {
+    loadQuote();
+  }
+}, [quoteId, router]);
+```
+
+### 4. handleSave 수정 (수정 저장)
+
+**변경 전:**
+```typescript
+const handleSave = useCallback(async (data: QuoteFormDataV2, saveType: "temporary" | "final") => {
+  setIsSaving(true);
+  try {
+    console.log("[테스트] 수정 데이터:", data);
+    await new Promise((resolve) => setTimeout(resolve, 1000));  // Mock delay
+    toast.success(`[테스트] ${saveType === "temporary" ? "임시" : "최종"} 저장 완료`);
+    if (saveType === "final") {
+      router.push(`/sales/quote-management/test/${quoteId}`);
+    }
+  } catch (error) {
+    toast.error("저장 중 오류가 발생했습니다.");
+  } finally {
+    setIsSaving(false);
+  }
+}, [router, quoteId]);
+```
+
+**변경 후:**
+```typescript
+const handleSave = useCallback(async (data: QuoteFormDataV2, saveType: "temporary" | "final") => {
+  setIsSaving(true);
+  try {
+    // V2 폼 데이터를 API 형식으로 변환
+    const updatedData = { ...data, status: saveType };
+    const apiData = transformV2ToApi(updatedData);
+
+    // API 호출
+    const result = await updateQuote(quoteId, apiData);
+
+    if (!result.success) {
+      toast.error(result.error || "저장 중 오류가 발생했습니다.");
+      return;
+    }
+
+    toast.success(`${saveType === "temporary" ? "임시" : "최종"} 저장 완료`);
+
+    // 저장 후 view 모드로 전환
+    router.push(`/sales/quote-management/test/${quoteId}`);
+  } catch (error) {
+    toast.error("저장 중 오류가 발생했습니다.");
+  } finally {
+    setIsSaving(false);
+  }
+}, [router, quoteId]);
+```
+
+## ✅ Phase 1 완료
+- [x] Step 1.1: V2 데이터 변환 함수 구현
+- [x] Step 1.2: test-new 페이지 API 연동 (createQuote)
+- [x] Step 1.3: test/[id] 상세 페이지 API 연동 (getQuoteById)
+- [x] Step 1.4: test/[id] 수정 API 연동 (updateQuote)
+
+## 🔜 다음 작업 (Phase 2)
+- [ ] Step 2.1: test-new → new 경로 변경
+- [ ] Step 2.2: test/[id] → [id] 경로 통합
+- [ ] Step 2.3: 기존 V1 페이지 처리 결정
+
+## 🔗 관련 문서
+- 계획 문서: `docs/dev_plans/quote-management-url-migration-plan.md`
+- Step 1.1 변경 내역: `docs/changes/20260126_quote_v2_transform_functions.md`
+- Step 1.2 변경 내역: `docs/changes/20260126_quote_v2_test_new_api.md`
+- V2 컴포넌트: `react/src/components/quotes/QuoteRegistrationV2.tsx`
--- a/dev/changes/20260126_quote_v2_test_new_api.md
+++ b/dev/changes/20260126_quote_v2_test_new_api.md
@@ -0,0 +1,81 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-26
+**작업자:** Claude Code
+**관련 계획:** docs/dev_plans/quote-management-url-migration-plan.md (Step 1.2)
+
+## 📋 변경 개요
+V2 견적 등록 테스트 페이지(test-new)에서 Mock 저장을 실제 API 연동으로 변경
+
+## 📁 수정된 파일
+- `react/src/app/[locale]/(protected)/sales/quote-management/test-new/page.tsx` - API 연동 구현
+
+## 🔧 상세 변경 사항
+
+### 1. Import 추가
+```typescript
+import { createQuote } from '@/components/quotes/actions';
+import { transformV2ToApi } from '@/components/quotes/types';
+```
+
+### 2. handleSave 함수 수정
+
+**변경 전:**
+```typescript
+const handleSave = useCallback(async (data: QuoteFormDataV2, saveType: 'temporary' | 'final') => {
+  setIsSaving(true);
+  try {
+    // TODO: API 연동 시 실제 저장 로직 구현
+    console.log('[테스트] 저장 데이터:', data);
+    await new Promise((resolve) => setTimeout(resolve, 1000));  // Mock delay
+    toast.success(`[테스트] ${saveType === 'temporary' ? '임시' : '최종'} 저장 완료`);
+    if (saveType === 'final') {
+      router.push('/sales/quote-management/test/1');  // 하드코딩된 ID
+    }
+  } catch (error) {
+    toast.error('저장 중 오류가 발생했습니다.');
+  } finally {
+    setIsSaving(false);
+  }
+}, [router]);
+```
+
+**변경 후:**
+```typescript
+const handleSave = useCallback(async (data: QuoteFormDataV2, saveType: 'temporary' | 'final') => {
+  setIsSaving(true);
+  try {
+    // V2 폼 데이터를 API 형식으로 변환
+    const updatedData = { ...data, status: saveType };
+    const apiData = transformV2ToApi(updatedData);
+
+    // API 호출
+    const result = await createQuote(apiData);
+
+    if (!result.success) {
+      toast.error(result.error || '저장 중 오류가 발생했습니다.');
+      return;
+    }
+
+    toast.success(`${saveType === 'temporary' ? '임시' : '최종'} 저장 완료`);
+
+    // 저장 후 상세 페이지로 이동 (실제 생성된 ID 사용)
+    if (result.data?.id) {
+      router.push(`/sales/quote-management/test/${result.data.id}`);
+    }
+  } catch (error) {
+    toast.error('저장 중 오류가 발생했습니다.');
+  } finally {
+    setIsSaving(false);
+  }
+}, [router]);
+```
+
+## ✅ 다음 작업 (Phase 1.3~1.4)
+- [ ] test/[id] 상세 페이지 API 연동 (getQuoteById)
+- [ ] test/[id] 수정 API 연동 (updateQuote)
+
+## 🔗 관련 문서
+- 계획 문서: `docs/dev_plans/quote-management-url-migration-plan.md`
+- Step 1.1 변경 내역: `docs/changes/20260126_quote_v2_transform_functions.md`
+- V2 컴포넌트: `react/src/components/quotes/QuoteRegistrationV2.tsx`
--- a/dev/changes/20260126_quote_v2_transform_functions.md
+++ b/dev/changes/20260126_quote_v2_transform_functions.md
@@ -0,0 +1,86 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-26
+**작업자:** Claude Code
+**관련 계획:** docs/dev_plans/quote-management-url-migration-plan.md (Step 1.1)
+
+## 📋 변경 개요
+V2 견적 컴포넌트(QuoteRegistrationV2)에서 사용할 데이터 변환 함수 구현
+- `transformV2ToApi`: V2 폼 데이터 → API 요청 형식
+- `transformApiToV2`: API 응답 → V2 폼 데이터
+
+## 📁 수정된 파일
+- `react/src/components/quotes/types.ts` - V2 타입 정의 및 변환 함수 추가
+
+## 🔧 상세 변경 사항
+
+### 1. LocationItem 인터페이스 추가
+발주 개소 항목의 데이터 구조 정의
+
+```typescript
+export interface LocationItem {
+  id: string;
+  floor: string;           // 층
+  code: string;            // 부호
+  openWidth: number;       // 가로 (오픈사이즈 W)
+  openHeight: number;      // 세로 (오픈사이즈 H)
+  productCode: string;     // 제품코드
+  productName: string;     // 제품명
+  quantity: number;        // 수량
+  guideRailType: string;   // 가이드레일 설치 유형
+  motorPower: string;      // 모터 전원
+  controller: string;      // 연동제어기
+  wingSize: number;        // 마구리 날개치수
+  inspectionFee: number;   // 검사비
+  // 계산 결과 (선택)
+  unitPrice?: number;
+  totalPrice?: number;
+  bomResult?: BomCalculationResult;
+}
+```
+
+### 2. QuoteFormDataV2 인터페이스 추가
+V2 컴포넌트용 폼 데이터 구조
+
+```typescript
+export interface QuoteFormDataV2 {
+  id?: string;
+  registrationDate: string;
+  writer: string;
+  clientId: string;
+  clientName: string;
+  siteName: string;
+  manager: string;
+  contact: string;
+  dueDate: string;
+  remarks: string;
+  status: 'draft' | 'temporary' | 'final';
+  locations: LocationItem[];  // V1의 items[] 대신 locations[] 사용
+}
+```
+
+### 3. transformV2ToApi 함수 구현
+V2 폼 데이터를 API 요청 형식으로 변환
+
+**핵심 로직:**
+1. `locations[]` → `calculation_inputs.items[]` (폼 복원용)
+2. BOM 결과가 있으면 자재 상세를 `items[]`에 포함
+3. 없으면 완제품 기준으로 `items[]` 생성
+4. status 매핑: `final` → `finalized`, 나머지 → `draft`
+
+### 4. transformApiToV2 함수 구현
+API 응답을 V2 폼 데이터로 변환
+
+**핵심 로직:**
+1. `calculation_inputs.items[]` → `locations[]` 복원
+2. 관련 BOM 자재에서 금액 계산
+3. status 매핑: `finalized/converted` → `final`, 나머지 → `draft`
+
+## ✅ 다음 작업 (Phase 1.2~1.4)
+- [ ] test-new 페이지 API 연동 (createQuote)
+- [ ] test/[id] 상세 페이지 API 연동 (getQuoteById)
+- [ ] test/[id] 수정 API 연동 (updateQuote)
+
+## 🔗 관련 문서
+- 계획 문서: `docs/dev_plans/quote-management-url-migration-plan.md`
+- V2 컴포넌트: `react/src/components/quotes/QuoteRegistrationV2.tsx`
--- a/dev/changes/20260126_quote_v2_writer_auth_fix.md
+++ b/dev/changes/20260126_quote_v2_writer_auth_fix.md
@@ -0,0 +1,76 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-26
+**작업자:** Claude Code
+**관련 계획:** docs/dev_plans/quote-management-url-migration-plan.md (Phase 1 버그 수정)
+
+## 📋 변경 개요
+V2 견적 등록 컴포넌트에서 작성자 필드가 "드미트리"로 하드코딩된 버그 수정
+
+## 📁 수정된 파일
+- `react/src/components/quotes/QuoteRegistrationV2.tsx` - 로그인 사용자 정보 연동
+
+## 🔧 상세 변경 사항
+
+### 1. Import 추가
+```typescript
+import { useAuth } from "@/contexts/AuthContext";
+```
+
+### 2. INITIAL_FORM_DATA 수정
+
+**변경 전:**
+```typescript
+const INITIAL_FORM_DATA: QuoteFormDataV2 = {
+  registrationDate: new Date().toISOString().split("T")[0],
+  writer: "드미트리", // TODO: 로그인 사용자 정보
+  // ...
+};
+```
+
+**변경 후:**
+```typescript
+const INITIAL_FORM_DATA: QuoteFormDataV2 = {
+  registrationDate: new Date().toISOString().split("T")[0],
+  writer: "", // useAuth()에서 currentUser.name으로 설정됨
+  // ...
+};
+```
+
+### 3. useAuth 훅 사용
+```typescript
+export function QuoteRegistrationV2({ ... }) {
+  // 인증 정보
+  const { currentUser } = useAuth();
+
+  // 상태 초기화 시 currentUser.name 사용
+  const [formData, setFormData] = useState<QuoteFormDataV2>(() => {
+    const data = initialData || INITIAL_FORM_DATA;
+    // create 모드에서 writer가 비어있으면 현재 사용자명으로 설정
+    if (mode === "create" && !data.writer && currentUser?.name) {
+      return { ...data, writer: currentUser.name };
+    }
+    return data;
+  });
+  // ...
+}
+```
+
+### 4. useEffect로 지연 로딩 처리
+```typescript
+// 작성자 자동 설정 (create 모드에서 currentUser 로드 시)
+useEffect(() => {
+  if (mode === "create" && !formData.writer && currentUser?.name) {
+    setFormData((prev) => ({ ...prev, writer: currentUser.name }));
+  }
+}, [mode, currentUser?.name, formData.writer]);
+```
+
+## ✅ 동작 방식
+1. **초기 렌더링**: useState 초기화 시 currentUser.name 사용
+2. **지연 로딩**: currentUser가 나중에 로드되면 useEffect로 writer 업데이트
+3. **edit/view 모드**: initialData의 writer 값 유지 (덮어쓰지 않음)
+
+## 🔗 관련 문서
+- 계획 문서: `docs/dev_plans/quote-management-url-migration-plan.md`
+- AuthContext: `react/src/contexts/AuthContext.tsx`
--- a/dev/changes/20260128_document_management_phase1_1.md
+++ b/dev/changes/20260128_document_management_phase1_1.md
@@ -0,0 +1,106 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-28
+**작업자:** Claude Code
+**작업명:** 문서 관리 시스템 Phase 1.1 - 마이그레이션 파일 생성
+
+## 📋 변경 개요
+
+문서 관리 시스템의 데이터베이스 스키마를 구현했습니다.
+- 4개 테이블 신규 생성 (documents, document_approvals, document_data, document_attachments)
+- SAM API 개발 규칙 준수 (tenant_id, 감사 컬럼, softDeletes, comment)
+
+## 📁 추가된 파일
+
+| 파일 | 설명 |
+|------|------|
+| `api/database/migrations/2026_01_28_200000_create_documents_table.php` | 문서 관리 테이블 마이그레이션 |
+
+## 🔧 상세 변경 사항
+
+### 1. documents 테이블 (16 컬럼)
+실제 문서 정보를 저장하는 메인 테이블
+
+| 컬럼 | 타입 | 설명 |
+|------|------|------|
+| id | bigint | PK |
+| tenant_id | bigint | 테넌트 ID (FK) |
+| template_id | bigint | 템플릿 ID (FK → document_templates) |
+| document_no | varchar(50) | 문서번호 |
+| title | varchar(255) | 문서 제목 |
+| status | enum | DRAFT/PENDING/APPROVED/REJECTED/CANCELLED |
+| linkable_type | varchar(100) | 연결 모델 타입 (다형성) |
+| linkable_id | bigint | 연결 모델 ID |
+| submitted_at | timestamp | 결재 요청일 |
+| completed_at | timestamp | 결재 완료일 |
+| created_by | bigint | 생성자 ID |
+| updated_by | bigint | 수정자 ID |
+| deleted_by | bigint | 삭제자 ID |
+| created_at | timestamp | 생성일 |
+| updated_at | timestamp | 수정일 |
+| deleted_at | timestamp | 삭제일 (Soft Delete) |
+
+### 2. document_approvals 테이블 (12 컬럼)
+문서 결재 정보 저장
+
+| 컬럼 | 타입 | 설명 |
+|------|------|------|
+| id | bigint | PK |
+| document_id | bigint | 문서 ID (FK) |
+| user_id | bigint | 결재자 ID (FK) |
+| step | tinyint | 결재 순서 |
+| role | varchar(50) | 역할 (작성/검토/승인) |
+| status | enum | PENDING/APPROVED/REJECTED |
+| comment | text | 결재 의견 |
+| acted_at | timestamp | 결재 처리일 |
+| created_by | bigint | 생성자 ID |
+| updated_by | bigint | 수정자 ID |
+| created_at | timestamp | 생성일 |
+| updated_at | timestamp | 수정일 |
+
+### 3. document_data 테이블 (9 컬럼)
+문서 데이터 저장 (EAV 패턴)
+
+| 컬럼 | 타입 | 설명 |
+|------|------|------|
+| id | bigint | PK |
+| document_id | bigint | 문서 ID (FK) |
+| section_id | bigint | 섹션 ID |
+| column_id | bigint | 컬럼 ID |
+| row_index | smallint | 행 인덱스 |
+| field_key | varchar(100) | 필드 키 |
+| field_value | text | 필드 값 |
+| created_at | timestamp | 생성일 |
+| updated_at | timestamp | 수정일 |
+
+### 4. document_attachments 테이블 (8 컬럼)
+문서 첨부파일 연결
+
+| 컬럼 | 타입 | 설명 |
+|------|------|------|
+| id | bigint | PK |
+| document_id | bigint | 문서 ID (FK) |
+| file_id | bigint | 파일 ID (FK → files) |
+| attachment_type | varchar(50) | 첨부 유형 |
+| description | varchar(255) | 설명 |
+| created_by | bigint | 생성자 ID |
+| created_at | timestamp | 생성일 |
+| updated_at | timestamp | 수정일 |
+
+## ✅ 검증 결과
+
+| 시나리오 | 예상 결과 | 실제 결과 | 상태 |
+|----------|----------|----------|:----:|
+| 마이그레이션 실행 | 4개 테이블 생성 | 4개 테이블 생성 | ✅ |
+| PHP 문법 검사 | 오류 없음 | 오류 없음 | ✅ |
+| Pint 포맷팅 | 통과 | 1개 스타일 수정 후 통과 | ✅ |
+| SAM 규칙 준수 | 모든 규칙 적용 | 모든 규칙 적용 | ✅ |
+
+## 🔗 관련 문서
+
+- 계획 문서: `docs/dev_plans/document-management-system-plan.md`
+- 다음 작업: Phase 1.2 - 모델 생성 (Document, DocumentApproval, DocumentData, DocumentAttachment)
+
+## ⚠️ 배포 시 주의사항
+
+특이사항 없음 (마이그레이션은 이미 실행됨)
--- a/dev/changes/20260128_document_management_phase1_5.md
+++ b/dev/changes/20260128_document_management_phase1_5.md
@@ -0,0 +1,59 @@
+# 변경 내용 요약
+
+**날짜:** 2026-01-28
+**작업자:** Claude
+**Phase:** 1.5 - Service 생성
+
+## 📋 변경 개요
+문서 관리 시스템의 DocumentService 클래스를 생성하여 문서 CRUD 및 결재 워크플로우 비즈니스 로직을 구현했습니다.
+
+## 📁 수정된 파일
+- `app/Services/DocumentService.php` (신규) - 문서 관리 서비스
+
+## 🔧 상세 변경 사항
+
+### 1. DocumentService 구현
+
+**주요 기능:**
+
+#### 문서 목록/상세
+- `list(array $params)` - 페이징, 필터링, 검색 지원
+- `show(int $id)` - 상세 조회 (템플릿, 결재선, 데이터, 첨부파일 포함)
+
+#### 문서 생성/수정/삭제
+- `create(array $data)` - 문서 생성 (결재선, 데이터, 첨부파일 포함)
+- `update(int $id, array $data)` - 문서 수정 (반려 상태 → DRAFT 전환)
+- `destroy(int $id)` - 문서 삭제 (DRAFT 상태만 가능)
+
+#### 결재 처리
+- `submit(int $id)` - 결재 요청 (DRAFT → PENDING)
+- `approve(int $id, ?string $comment)` - 결재 승인
+- `reject(int $id, string $comment)` - 결재 반려
+- `cancel(int $id)` - 결재 취소/회수 (작성자만)
+
+#### 헬퍼 메서드
+- `generateDocumentNo()` - 문서번호 생성 (DOC-YYYYMMDD-NNNN)
+- `createApprovals()` - 결재선 생성
+- `saveDocumentData()` - 문서 데이터 저장 (EAV)
+- `attachFiles()` - 첨부파일 연결
+
+**구현 특징:**
+- Service-First 아키텍처 준수
+- Multi-tenancy 지원 (tenantId() 필터링)
+- DB 트랜잭션 처리
+- 순차 결재 로직 (이전 단계 완료 확인)
+- i18n 에러 메시지 키 사용
+
+## ✅ 테스트 체크리스트
+- [x] PHP 문법 검사 통과
+- [x] Service 클래스 로드 성공
+- [x] Pint 포맷팅 완료
+- [ ] API 통합 테스트 (Phase 1.6 이후)
+
+## ⚠️ 배포 시 주의사항
+특이사항 없음
+
+## 🔗 관련 문서
+- Phase 1.1: 마이그레이션 (`20260128_document_management_phase1_1.md`)
+- Phase 1.2: 모델 생성 (별도 문서 없음, 커밋 참조)
+- 계획 문서: `docs/dev_plans/document-management-system-plan.md`
--- a/dev/changes/20260128_kd_items_migration_phase1.md
+++ b/dev/changes/20260128_kd_items_migration_phase1.md
@@ -0,0 +1,69 @@
+# 변경 내용 요약 - 경동기업 품목/단가 마이그레이션 Phase 1.0
+
+**날짜:** 2026-01-28
+**작업자:** Claude Code
+**관련 문서:** docs/dev_plans/kd-items-migration-plan.md
+
+## 📋 변경 개요
+
+경동기업(tenant_id=287) 레거시 DB(chandj)에서 SAM DB(samdb)로 품목/단가 데이터 마이그레이션을 위한 Seeder 생성
+
+## 📁 추가된 파일
+
+| 파일 | 설명 |
+|------|------|
+| `api/database/seeders/Kyungdong/KyungdongItemSeeder.php` | 경동기업 품목/단가 마이그레이션 Seeder |
+
+## 🔧 상세 변경 사항
+
+### 1. KyungdongItemSeeder.php 생성
+
+**기능:**
+- chandj.KDunitprice (601건) → samdb.items 마이그레이션
+- items 기반 → samdb.prices 마이그레이션
+- 기존 tenant_id=287 데이터 삭제 후 재생성
+
+**주요 로직:**
+```php
+// item_div → item_type 매핑
+'[제품]' => 'FG'   // 완제품
+'[상품]' => 'FG'   // 완제품
+'[반제품]' => 'PT' // 부품
+'[부재료]' => 'SM' // 부자재
+'[원재료]' => 'RM' // 원자재
+'[무형상품]' => 'CS' // 소모품
+```
+
+**발견된 이슈 및 해결:**
+- 레거시 DB의 `is_deleted` 컬럼이 `0`이 아닌 `NULL`로 활성 상태 표시
+- `where('is_deleted', 0)` → `whereNull('is_deleted')` 수정
+
+## ✅ 실행 방법
+
+```bash
+# Docker 컨테이너 내부에서 실행
+docker exec sam-api-1 php artisan db:seed --class="Database\\Seeders\\Kyungdong\\KyungdongItemSeeder"
+
+# 또는 Docker 환경에서 직접 실행
+cd /var/www/html && php artisan db:seed --class="Database\\Seeders\\Kyungdong\\KyungdongItemSeeder"
+```
+
+## 📊 예상 결과
+
+| 테이블 | 작업 | 예상 건수 |
+|--------|------|----------|
+| items | DELETE (기존) | ~10,472건 |
+| items | INSERT (신규) | ~601건 |
+| prices | DELETE (기존) | ~86건 |
+| prices | INSERT (신규) | ~601건 |
+
+## ⚠️ 주의사항
+
+1. **기존 데이터 삭제됨**: tenant_id=287의 모든 items, prices 삭제
+2. **실행 전 백업 권장**: 중요 데이터는 백업 후 실행
+3. **Docker 환경 필수**: chandj DB 연결은 Docker 내부에서만 가능 (sam-mysql-1 호스트명)
+
+## 🔗 관련 문서
+
+- [kd-items-migration-plan.md](../plans/kd-items-migration-plan.md) - 전체 마이그레이션 계획
+- [kd-orders-migration-plan.md](../plans/kd-orders-migration-plan.md) - 입고/재고/주문 마이그레이션 (연관)
--- a/dev/changes/20260128_kd_items_migration_phase3.md
+++ b/dev/changes/20260128_kd_items_migration_phase3.md
@@ -0,0 +1,105 @@
+# 변경 내용 요약 - 경동기업 품목/단가 마이그레이션 Phase 3
+
+**날짜:** 2026-01-28
+**작업자:** Claude Code
+**관련 문서:** docs/dev_plans/kd-items-migration-plan.md
+
+## 📋 변경 개요
+
+경동기업(tenant_id=287) 레거시 DB(chandj)의 price_* 테이블에서 누락된 품목을 SAM DB(samdb)로 추가 마이그레이션
+
+## 📁 수정된 파일
+
+| 파일 | 설명 |
+|------|------|
+| `api/database/seeders/Kyungdong/KyungdongItemSeeder.php` | Phase 3.1, 3.2 메서드 추가 |
+| `docs/dev_plans/kd-items-migration-plan.md` | Phase 3 완료 상태 업데이트 |
+
+## 🔧 상세 변경 사항
+
+### 1. KyungdongItemSeeder.php 확장
+
+**Phase 3.1: migratePriceMotor()**
+- price_motor JSON에서 KDunitprice에 없는 품목 추가
+- 220V/380V 모터는 스킵 (KDunitprice에 "KD모터*Kg단상/삼상"으로 존재)
+- 추가 항목 (13건):
+  - PM-020~PM-032: 제어기 (6P~18P, 20회선~100회선)
+  - PM-033~PM-035: 방화/방범 콘트롤박스, 스위치
+
+**Phase 3.2: migratePriceRawMaterials()**
+- price_raw_materials JSON에서 KDunitprice에 없는 품목 추가
+- 추가 항목 (4건):
+  - RM-007: 신설비상문 (3x2 300*200)
+  - RM-008~RM-009: 제연커튼 (연기차단원단, 불투명)
+  - RM-010~RM-011: 화이바원단, 와이어원단
+
+**중복 확인 로직:**
+```php
+// 기존 품목명과 비교하여 중복 제외
+$existingItemNames = DB::table('items')
+    ->where('tenant_id', $tenantId)
+    ->pluck('name')
+    ->map(fn($n) => mb_strtolower($n))
+    ->toArray();
+
+// 품목명이 이미 존재하면 스킵
+if (in_array(mb_strtolower($itemName), $existingItemNames)) {
+    continue;
+}
+```
+
+### 2. Phase 3 분석 결과
+
+**price_* 테이블 분석 (10개):**
+
+| 테이블 | 역할 | 처리 |
+|--------|------|------|
+| price_motor | 모터/제어기 단가 | ✅ 누락 품목 추가 (13건) |
+| price_raw_materials | 원자재 단가 | ✅ 누락 품목 추가 (4건) |
+| price_shaft | 감기샤프트 계산 참조 | ⏭️ 스킵 (품목 마스터 아님) |
+| price_pipe | 파이프 계산 참조 | ⏭️ 스킵 (품목 마스터 아님) |
+| price_angle | 앵글 계산 참조 | ⏭️ 스킵 (품목 마스터 아님) |
+| price_bend | 절곡 계산 참조 | ⏭️ 스킵 (품목 마스터 아님) |
+| price_pole | 폴 계산 참조 | ⏭️ 스킵 (품목 마스터 아님) |
+| price_screenplate | 스크린플레이트 계산 참조 | ⏭️ 스킵 (품목 마스터 아님) |
+| price_smokeban | 연기차단 계산 참조 | ⏭️ 스킵 (품목 마스터 아님) |
+| price_etc | 기타 | ⏭️ 스킵 (비활성) |
+
+## ✅ 실행 방법
+
+```bash
+# Docker 컨테이너 내부에서 실행
+docker exec sam-api-1 php artisan db:seed --class="Database\\Seeders\\Kyungdong\\KyungdongItemSeeder"
+
+# 또는 Docker 환경에서 직접 실행
+cd /var/www/html && php artisan db:seed --class="Database\\Seeders\\Kyungdong\\KyungdongItemSeeder"
+```
+
+## 📊 최종 결과
+
+| 테이블 | Phase 1~2 | Phase 3 추가 | 최종 |
+|--------|-----------|-------------|------|
+| items | 634건 | +17건 | **651건** |
+| prices | 634건 | +17건 | **651건** |
+| BOM (items.bom) | 18건 | 0건 | **18건** |
+
+**item_type별 분포:**
+| item_type | 건수 |
+|-----------|------|
+| FG (완제품) | 100건 |
+| PT (부품) | 110건 |
+| SM (부자재) | 256건 |
+| RM (원자재) | 108건 |
+| CS (소모품) | 77건 |
+
+## ⚠️ 주의사항
+
+1. **기존 데이터 유지**: Phase 3는 기존 데이터를 삭제하지 않고 누락 품목만 추가
+2. **Seeder 재실행 시**: 전체 Seeder는 idempotent (삭제 후 재생성) 방식
+3. **코드 형식**: PM-XXX (price_motor), RM-XXX (price_raw_materials)
+
+## 🔗 관련 문서
+
+- [kd-items-migration-plan.md](../plans/kd-items-migration-plan.md) - 전체 마이그레이션 계획
+- [20260128_kd_items_migration_phase1.md](./20260128_kd_items_migration_phase1.md) - Phase 1 변경 내용
+- [kd-orders-migration-plan.md](../plans/kd-orders-migration-plan.md) - 입고/재고/주문 마이그레이션 (연관)
--- a/dev/changes/20260205_sus_inspection_template.md
+++ b/dev/changes/20260205_sus_inspection_template.md
@@ -0,0 +1,106 @@
+# 변경 내용 요약
+
+**날짜:** 2026-02-05
+**작업자:** Claude Code
+**관련 계획:** docs/dev_plans/incoming-inspection-templates-plan.md
+
+## 📋 변경 개요
+5130 레거시 수입검사 양식 전환 작업 - Phase 1 완료
+- 13개 수입검사 양식 생성 (id:18-30)
+- 테이블 컬럼 구조 추가 (미리보기 기능 정상화)
+- MNG UI 테스트 완료
+
+## 📁 수정된 파일/데이터
+
+### 데이터베이스 변경
+- `document_templates` - 13건 INSERT (id:18-30)
+- `document_template_section_fields` - 8건씩 INSERT (template_id:18-30)
+- `document_template_columns` - 84건 INSERT (7개 컬럼 × 12개 템플릿 19-30)
+
+### 문서 변경
+- `docs/dev_plans/incoming-inspection-templates-plan.md` - 진행 상태 업데이트
+
+## 🔧 상세 변경 사항
+
+### 1. SUS 절곡판 수입검사 양식 생성 (id:19)
+
+**생성된 데이터:**
+```json
+{
+  "id": 19,
+  "tenant_id": 287,
+  "name": "SUS 절곡판 수입검사",
+  "category": "수입검사",
+  "title": "수입검사 성적서",
+  "company_name": "경동산업",
+  "footer_remark_label": "비고 / 부적합 내용",
+  "footer_judgement_label": "종합판정",
+  "footer_judgement_options": ["적합", "부적합"],
+  "is_active": 1,
+  "linked_item_ids": [14172, 14173, 14174, 14175, 14176, 14177, 14178, 14179, 14180, 14181, 14182]
+}
+```
+
+### 2. 필드 구조 (EGI 양식에서 복사)
+
+| sort_order | field_key | label | field_type |
+|------------|-----------|-------|------------|
+| 0 | category | 구분 | text |
+| 1 | item | 검사항목 | text |
+| 2 | standard | 검사 기준/범위 | text_with_criteria |
+| 3 | tolerance | 공차/범위 | json_tolerance |
+| 4 | method | 검사방식 | select_api |
+| 5 | measurement_type | 측정유형 | select |
+| 6 | frequency | 검사주기 | composite_frequency |
+| 7 | regulation | 관련규정 | text |
+
+### 3. 연결된 품목 (11건)
+
+| ID | 품목명 |
+|----|--------|
+| 14172 | sus1.2*1219*2438 |
+| 14173 | sus1.2*1219*3000 |
+| 14174 | sus1.2t*1219*4000 |
+| 14175 | sus1.5*1219*2438 |
+| 14176 | sus1.5*1219*3000 |
+| 14177 | sus1.5*1219*4000 |
+| 14178 | sus1.2*1219*c |
+| 14179 | sus1.5*1219*2500 |
+| 14180 | sus1.2*1219*4230 |
+| 14181 | sus1.2*1219*3000 P/L |
+| 14182 | sus1.2*1219*2500 |
+
+### 4. 테이블 컬럼 구조 추가 (템플릿 19-30)
+
+미리보기 기능이 동작하려면 `document_template_columns` 테이블에 컬럼 정의가 필요합니다.
+템플릿 18(EGI)의 컬럼 구조를 복사하여 12개 템플릿(19-30)에 적용했습니다.
+
+| sort_order | label | column_type | width |
+|------------|-------|-------------|-------|
+| 0 | NO | text | 50px |
+| 1 | 검사항목 | text | 120px |
+| 2 | 검사기준 | text | 150px |
+| 3 | 검사방식 | text | 100px |
+| 4 | 검사주기 | text | 100px |
+| 5 | 측정치 | complex | 240px |
+| 6 | 판정 (적/부) | select | 80px |
+
+**측정치 컬럼 sub_labels:** `["n1", "n2", "n3"]`
+
+## ✅ 테스트 체크리스트
+- [x] 양식 생성 확인 (id:18-30, 총 13개)
+- [x] 필드 8개 복사 확인 (각 템플릿별)
+- [x] 품목 연결 확인 (EGI, SUS 등)
+- [x] MNG UI 양식 편집 테스트 ✅
+- [x] **MNG UI 미리보기 테스트 ✅** (컬럼 추가 후 정상 동작)
+- [ ] React resolve API 테스트
+
+## ⚠️ 후속 작업
+1. ~~EGI 양식(id:18)에 품목 연결 필요~~ → 완료
+2. ~~Phase 1 나머지 양식 생성~~ → 완료 (13개 양식)
+3. MNG UI에서 검사항목 데이터 입력 필요
+4. React resolve API 테스트
+
+## 🔗 관련 문서
+- 계획 문서: `docs/dev_plans/incoming-inspection-templates-plan.md`
+- 레거시 참조: `5130/instock/i_SUSplate.php`