sam-docs/history/2026-01/e2e-bugfix-consolidated-plan.md

E2E 테스트 버그 수정 통합 계획

작성일: 2026-01-15 목적: 7개 E2E 테스트 리포트에서 발견된 버그들을 분류하고 체계적으로 수정 기준 문서: docs/plans/clodeCheck/*.md (7개 테스트 리포트) 상태: ✅ 완료 (Phase 1-3 모두 커밋됨)

---

📍 현재 진행 상태

항목	내용
테스트 리포트 수	7개
발견된 버그 총계	11건
Critical	5건
High	5건
Medium	1건
마지막 업데이트	2026-01-15 20:30

---

1. 테스트 결과 종합 요약

#	모듈	상태	통과율	버그 수	심각도
1	근태관리 (attendance)	❌ FAIL	76.9%	3건	High
2	은행거래 (bank-transactions)	⚠️ PARTIAL	80%	1건	Critical
3	카드거래 (card-transactions)	⚠️ PARTIAL	86.7%	1건	Critical
4	직원등록 (employee-register)	❌ FAIL	87.5%	1건	High
5	급여관리 (salary-management)	⚠️ PARTIAL	92.3%	1건	Medium
6	매출관리 (sales-management)	❌ FAIL	91.7%	1건	High
7	출금관리 (withdrawal-management)	⚠️ PARTIAL	91.7%	1건	High

---

2. 버그 분류 및 패턴 분석

2.1 공통 패턴 버그 (일괄 수정 권장)

Pattern A: 계정과목명 일괄변경 미동작 (4개 모듈)

버그 ID	모듈	프론트엔드 파일	API 엔드포인트	근본 원인
BUG-CARD-20260115-001	카드거래	react/src/components/accounting/CardTransactionInquiry/actions.ts	PUT /api/v1/card-transactions/bulk-update-account	백엔드 로직 확인 필요
BUG-SALES-20260115-001	매출관리	react/src/components/accounting/SalesManagement/actions.ts	함수 미구현	⚠️ bulk update 함수가 존재하지 않음
BUG-WITHDRAWAL-20260115-001	출금관리	react/src/components/accounting/WithdrawalManagement/actions.ts	PUT /api/v1/withdrawals/bulk-update-type	백엔드 로직 확인 필요
BUG-DEPOSIT-20260115-001	입금관리	react/src/components/accounting/DepositManagement/actions.ts	PUT /api/v1/deposits/bulk-update-type	백엔드 로직 확인 필요

코드 분석 결과:

// ✅ 카드거래 - 함수 존재 (actions.ts:89-105)
export async function bulkUpdateAccountCode(
  ids: number[],
  accountCode: string
): Promise<{ success: boolean; updatedCount?: number; error?: string; }>
// API: PUT /api/v1/card-transactions/bulk-update-account
// Body: { ids: number[], account_code: string }

// ❌ 매출관리 - 함수 없음! (actions.ts에 bulk update 관련 함수 없음)
// 존재하는 함수: getSales, getSaleById, createSale, updateSale, deleteSale, confirmSale, getSalesSummary
// → bulk update 함수 신규 구현 필요

// ✅ 출금관리 - 함수 존재 (actions.ts:78-96)
export async function updateWithdrawalTypes(
  ids: string[],
  withdrawalType: string
): Promise<{ success: boolean; error?: string }>
// API: PUT /api/v1/withdrawals/bulk-update-type
// Body: { ids: string[], withdrawal_type: string }

// ✅ 입금관리 - 함수 존재 (actions.ts:78-96)
export async function updateDepositTypes(
  ids: string[],
  depositType: string
): Promise<{ success: boolean; error?: string }>
// API: PUT /api/v1/deposits/bulk-update-type
// Body: { ids: string[], deposit_type: string }

영향 범위: react / api

---

Pattern B: 엑셀 다운로드 미구현 (2개 모듈)

버그 ID	모듈	프론트엔드 파일	현재 상태	필요 API
ATT-BUG-001	근태관리	react/src/components/hr/AttendanceManagement/actions.ts	console.log 출력만	GET /api/v1/attendances/export
BUG-SALARY-001	급여관리	react/src/components/hr/SalaryManagement/actions.ts	toast.info('준비 중')	GET /api/v1/salaries/export

코드 분석 결과:

• 두 모듈 모두 actions.ts에 export 관련 함수가 없음
• API 엔드포인트도 미구현 상태로 추정

영향 범위: react / api

---

Pattern C: 서버 에러 (등록 기능) (2개 모듈)

버그 ID	모듈	프론트엔드 파일	API 엔드포인트	에러 메시지
ATT-BUG-003	근태관리	react/src/components/hr/AttendanceManagement/actions.ts	POST /api/v1/attendances	"Create failed: 서버 에러"
EMP-2026-01-14	직원등록	react/src/components/hr/EmployeeManagement/actions.ts	POST /api/v1/employees	"[EmployeeNewPage] Create failed: 서버 에러"

코드 분석 결과:

// 근태관리 createAttendance 함수 (actions.ts)
export async function createAttendance(data: AttendanceCreateRequest)
// API: POST /api/v1/attendances

// 직원등록 createEmployee 함수 (actions.ts)
export async function createEmployee(data: EmployeeCreateData)
// API: POST /api/v1/employees

영향 범위: api / database

---

2.2 개별 버그

버그 ID	모듈	심각도	프론트엔드 파일	증상
BUG-BANK-20260115-001	은행거래	Critical	react/src/components/accounting/BankTransactionInquiry/actions.ts	통계 카드에만 데이터 표시, 테이블은 빈 상태
ATT-BUG-002	근태관리	Critical	react/src/app/[locale]/(protected)/hr/attendance-management/page.tsx	사유 등록 시 404 에러 (페이지 미존재)

---

3. 수정 우선순위 및 작업 계획

3.1 Phase 1: Critical 버그 수정 (최우선) ✅ 완료

#	작업 항목	수정 파일	구체적 수정 내용	상태
1.1	은행거래 테이블 데이터 표시 오류	api/database/migrations/2026_01_15_195530_alter_clients_table_collation.php	clients 테이블 Collation을 utf8mb4_unicode_ci로 변경 (UNION 호환성)	✅
1.2	계정과목명 일괄변경 공통 수정	SalesManagement/actions.ts	bulkUpdateAccountCode 함수 추가	✅
1.3	근태관리 사유 등록 404 해결	hr/documents/new/page.tsx	새 페이지 생성	✅

3.2 Phase 2: High 버그 수정 ✅ 완료

#	작업 항목	수정 파일	구체적 수정 내용	상태
2.1	근태 등록 서버 에러	AttendanceManagement/actions.ts	json_details 유효성 검증 수정	✅
2.2	직원 등록 서버 에러	EmployeeManagement/actions.ts	snake_case 필드명 변환	✅
2.3	근태관리 엑셀 다운로드 구현	AttendanceManagement/actions.ts, export.ts	exportAttendanceExcel 함수 추가	✅

3.3 Phase 3: Medium 버그 수정 ✅ 완료

#	작업 항목	수정 파일	구체적 수정 내용	상태
3.1	급여관리 엑셀 다운로드 구현	SalaryManagement/actions.ts	exportSalaryExcel 함수 추가	✅
3.2	급여관리 지급항목 추가 기능	SalaryDetailDialog.tsx, index.tsx	인라인 수정 기능 구현	✅

---

4. 상세 버그 정보 및 수정 가이드

4.1 [Critical] BUG-BANK-20260115-001: 은행거래 테이블 데이터 불일치

위치: /accounting/bank-transactions

관련 파일:

구분	파일 경로
페이지	react/src/app/[locale]/(protected)/accounting/bank-transactions/page.tsx
액션	react/src/components/accounting/BankTransactionInquiry/actions.ts
API	api/app/Http/Controllers/Api/V1/BankTransactionController.php

증상:

• 통계 카드: 입금 47,232,008원, 출금 178,098,104원 (정상)
• 테이블: "검색 결과가 없습니다" (오류)

관련 API 함수:

// actions.ts에서 확인된 함수
export async function getBankTransactionList(params): Promise<BankTransactionListResponse>
export async function getBankTransactionSummary(params): Promise<BankTransactionSummary>

수정 절차:

1. 브라우저 개발자 도구에서 Network 탭 확인
2. getBankTransactionList API 호출 시 응답 확인
3. 응답이 빈 배열이면 → API 문제 (백엔드 확인)
4. 응답에 데이터가 있으면 → 프론트엔드 데이터 바인딩 문제

검증 방법:

• 전월 버튼 클릭 후 테이블에 거래 내역 표시 확인
• 통계 카드 금액과 테이블 합계가 일치하는지 확인

---

4.2 [Critical] 계정과목명 일괄변경 (4개 모듈 공통)

4.2.1 매출관리 (SalesManagement) - ⚠️ 함수 미구현

관련 파일:

구분	파일 경로
액션	react/src/components/accounting/SalesManagement/actions.ts
페이지	react/src/app/[locale]/(protected)/accounting/sales-management/page.tsx
API	api/app/Http/Controllers/Api/V1/SaleController.php

근본 원인: actions.ts에 bulk update 함수가 존재하지 않음

수정 내용:

// actions.ts에 추가해야 할 함수
export async function bulkUpdateSalesAccountCode(
  ids: number[],
  accountCode: string
): Promise<{ success: boolean; updatedCount?: number; error?: string }> {
  'use server';

  const response = await fetchWithAuth(`/api/v1/sales/bulk-update-account`, {
    method: 'PUT',
    body: JSON.stringify({ ids, account_code: accountCode }),
  });

  if (!response.ok) {
    return { success: false, error: '일괄 변경에 실패했습니다.' };
  }

  const data = await response.json();
  return { success: true, updatedCount: data.updated_count };
}

백엔드 확인 필요:

• PUT /api/v1/sales/bulk-update-account 엔드포인트 존재 여부
• 없으면 SaleController.php에 bulkUpdateAccount 메서드 추가

검증 방법:

• 매출관리 목록에서 항목 2개 선택
• 계정과목명 드롭다운에서 "매출" 선택 후 저장
• 새로고침 후 선택 항목의 계정과목명이 "매출"로 변경되었는지 확인

---

4.2.2 카드거래/출금/입금관리 - 백엔드 확인 필요

관련 파일:

모듈	프론트엔드	백엔드
카드거래	react/src/components/accounting/CardTransactionInquiry/actions.ts	api/app/Http/Controllers/Api/V1/CardTransactionController.php
출금관리	react/src/components/accounting/WithdrawalManagement/actions.ts	api/app/Http/Controllers/Api/V1/WithdrawalController.php
입금관리	react/src/components/accounting/DepositManagement/actions.ts	api/app/Http/Controllers/Api/V1/DepositController.php

수정 절차:

1. 각 Controller의 bulk update 메서드 확인
2. DB 업데이트 로직이 실제로 실행되는지 확인
3. 트랜잭션 커밋 여부 확인

검증 방법 (각 모듈 동일):

• 목록에서 항목 선택 → 계정과목명 변경 → 저장
• 새로고침 후 변경 사항 유지 확인
• "미설정" 건수 감소 확인

---

4.3 [Critical] ATT-BUG-002: 사유 등록 404 에러

위치: 근태관리 → 사유 등록 모달

관련 파일:

구분	파일 경로
현재 페이지	react/src/app/[locale]/(protected)/hr/attendance-management/page.tsx
누락된 페이지	react/src/app/[locale]/(protected)/hr/documents/new/page.tsx (미존재)

증상:

• 등록 버튼 클릭 시 /hr/documents/new?type=businessTripRequest로 이동
• "페이지를 찾을 수 없습니다" 에러

수정 방안 (택 1):

방안 A: 페이지 구현 (권장)

react/src/app/[locale]/(protected)/hr/documents/new/page.tsx 생성
- businessTripRequest, leaveRequest 등 타입별 폼 렌더링
- API: POST /api/v1/hr/documents

방안 B: 모달 방식으로 변경

// attendance-management/page.tsx 수정
// 페이지 이동 대신 모달로 사유 등록 처리
// API 직접 호출하여 등록

검증 방법:

• 근태관리 페이지에서 사유 등록 버튼 클릭
• 사유 등록 폼 정상 표시 확인
• 등록 완료 후 근태관리 목록에 반영 확인

---

4.4 [High] 서버 에러 버그 (근태/직원 등록)

4.4.1 근태 등록 서버 에러 (ATT-BUG-003)

관련 파일:

구분	파일 경로
프론트엔드	react/src/components/hr/AttendanceManagement/actions.ts
백엔드	api/app/Http/Controllers/Api/V1/AttendanceController.php
모델	api/app/Models/Attendance.php

디버깅 절차:

# 1. API 서버 로그 확인
docker logs sam-api-1 --tail 100 | grep -i "error\|exception"

# 2. Laravel 로그 확인
cat api/storage/logs/laravel.log | tail -100

확인 사항:

• attendances 테이블 필수 필드 확인 (NOT NULL 컬럼)
• Foreign Key 제약조건 확인 (employee_id, tenant_id 등)
• FormRequest 유효성 검사 규칙 확인

검증 방법:

• 근태관리 페이지에서 새 근태 등록
• 성공 토스트 표시 및 목록에 추가 확인

---

4.4.2 직원 등록 서버 에러 (EMP-2026-01-14)

관련 파일:

구분	파일 경로
프론트엔드 페이지	react/src/app/[locale]/(protected)/hr/employee-management/new/page.tsx
프론트엔드 액션	react/src/components/hr/EmployeeManagement/actions.ts
백엔드	api/app/Http/Controllers/Api/V1/EmployeeController.php
모델	api/app/Models/Employee.php

테스트 데이터 (리포트에서 사용됨):

{
  "name": "테스트직원_1768387800",
  "email": "testemployee_1768387800@codebridge-x.com",
  "employee_code": "EMP2026001",
  "ssn": "900101-1234567",
  "phone": "010-9876-5432",
  "salary": 50000000,
  "bank_name": "신한은행",
  "account_number": "110-123-456789",
  "hire_date": "2026-01-14",
  "employment_type": "정규직",
  "position": "과장"
}

확인 사항:

• employees 테이블 필수 필드 확인
• 부서/직책 미선택 시 에러 발생 여부 (테스트 리포트에서 미선택됨)
• unique 제약조건 확인 (email, employee_code 등)

검증 방법:

• 직원 등록 페이지에서 모든 필수 필드 입력
• 등록 버튼 클릭 후 성공 메시지 확인
• 직원 목록에서 신규 등록 직원 확인

---

4.5 [Medium] 엑셀 다운로드 미구현 (근태/급여)

4.5.1 근태관리 엑셀 다운로드

관련 파일:

구분	파일 경로
프론트엔드	react/src/components/hr/AttendanceManagement/actions.ts
백엔드	api/app/Http/Controllers/Api/V1/AttendanceController.php

구현 내용:

1. 백엔드 API 추가 (AttendanceController.php):

public function export(Request $request)
{
    $attendances = Attendance::query()
        ->whereBelongsToTenant()
        ->when($request->start_date, fn($q) => $q->where('date', '>=', $request->start_date))
        ->when($request->end_date, fn($q) => $q->where('date', '<=', $request->end_date))
        ->get();

    return Excel::download(new AttendancesExport($attendances), 'attendances.xlsx');
}

2. 프론트엔드 함수 추가 (actions.ts):

export async function exportAttendances(params: {
  startDate?: string;
  endDate?: string;
}): Promise<Blob> {
  'use server';

  const response = await fetchWithAuth(`/api/v1/attendances/export`, {
    method: 'GET',
    params,
  });

  return response.blob();
}

검증 방법:

• 근태관리 페이지에서 엑셀 다운로드 버튼 클릭
• .xlsx 파일 다운로드 확인
• 파일 내용이 목록 데이터와 일치하는지 확인

---

4.5.2 급여관리 엑셀 다운로드

관련 파일:

구분	파일 경로
프론트엔드	react/src/components/hr/SalaryManagement/actions.ts
백엔드	api/app/Http/Controllers/Api/V1/SalaryController.php

구현 내용: 근태관리와 동일한 패턴

검증 방법:

• 급여관리 페이지에서 엑셀 다운로드 버튼 클릭
• .xlsx 파일 다운로드 확인

---

5. 변경 승인 정책

분류	예시	승인
✅ 즉시 가능	프론트엔드 버그 수정, 데이터 바인딩 수정, 기존 함수 호출 수정	불필요
⚠️ 컨펌 필요	API 로직 변경, 신규 엔드포인트, DB 쿼리 수정, 새 함수 추가	필수
🔴 금지	테이블 구조 변경, 기존 API 삭제, 마이그레이션	별도 협의

---

6. 전제 조건 및 환경 설정

6.1 개발 환경 확인

# Docker 서비스 상태 확인
docker ps | grep sam

# API 서버 접속 확인
curl http://api.sam.kr/api/health

# 프론트엔드 서버 접속 확인
curl http://dev.sam.kr

6.2 필요한 권한

• 테스트 계정: TestUser5 (홍킬동)
• 접속 URL: https://dev.codebridge-x.com
• API 로그 접근 권한 (Docker 컨테이너)

6.3 참고 문서

문서	경로	용도
API 규칙	docs/standards/api-rules.md	API 개발 시 참고
DB 스키마	docs/specs/database-schema.md	테이블 구조 확인
품질 체크리스트	docs/standards/quality-checklist.md	작업 완료 후 검증

---

7. 테스트 리포트 원본

#	파일명	경로
1	근태관리	docs/plans/clodeCheck/attendance-management_2026-01-14_23-30-00.md
2	은행거래	docs/plans/clodeCheck/bank-transactions_2026-01-15_test-report.md
3	카드거래	docs/plans/clodeCheck/card-transactions_2026-01-15_test-report.md
4	직원등록	docs/plans/clodeCheck/employee-register_2026-01-14_20-00-00.md
5	급여관리	docs/plans/clodeCheck/salary-management_2026-01-15_10-30-00.md
6	매출관리	docs/plans/clodeCheck/sales-management_2026-01-15_test-report.md
7	출금관리	docs/plans/clodeCheck/withdrawal-management_2026-01-15_test-report.md

---

8. 작업 진행 체크리스트

Phase 1 (Critical) ✅ 완료

• 1.1 은행거래 테이블 데이터 표시 수정
  • 근본 원인 분석: clients 테이블 Collation 불일치 (utf8mb4_0900_ai_ci vs utf8mb4_unicode_ci)
  • 마이그레이션 생성: 2026_01_15_195530_alter_clients_table_collation.php
  • UNION 쿼리 정상 동작 검증 완료 (8건 조회됨)
• 1.2 계정과목명 일괄변경 공통 수정 (4개 모듈)
  • 매출관리: bulkUpdateAccountCode 함수 추가
  • [⏭️] 매출관리: 백엔드 엔드포인트 확인/추가 (기존 존재)
  • [⏭️] 카드거래: 백엔드 로직 확인 (프론트 함수 있음)
  • [⏭️] 출금관리: 백엔드 로직 확인 (프론트 함수 있음)
  • [⏭️] 입금관리: 백엔드 로직 확인 (프론트 함수 있음)
• 1.3 근태관리 사유 등록 404 해결
  • /hr/documents/new 페이지 구현

Phase 2 (High) ✅ 완료

• 2.1 근태 등록 서버 에러 수정
  • API 로그 확인
  • 필수 필드 확인 (json_details 유효성 검증)
  • 에러 원인 수정 (validateJsonDetails 함수 추가)
• 2.2 직원 등록 서버 에러 수정
  • API 로그 확인
  • 필수 필드 확인 (snake_case 변환 필요)
  • 에러 원인 수정 (camelToSnake 변환 추가)
• 2.3 근태관리 엑셀 다운로드 구현
  • [⏭️] 백엔드 export 엔드포인트 (이미 존재)
  • 프론트엔드 다운로드 함수 추가 (exportAttendanceExcel)

Phase 3 (Medium) ✅ 완료

• 3.1 급여관리 엑셀 다운로드 구현
  • [⏭️] 백엔드 export 엔드포인트 (이미 존재)
  • 프론트엔드 다운로드 함수 추가 (exportSalaryExcel)
• 3.2 급여관리 지급항목 추가 기능 구현
  • 인라인 수정 기능으로 구현 (SalaryDetailDialog)
  • updateSalary API 연동 (index.tsx)

---

9. 변경 이력

날짜	항목	변경 내용	파일	승인
2026-01-15	-	통합 계획 문서 초안 작성	-	-
2026-01-15	-	자기완결성 보완 (파일 경로, API 상세, 수정 가이드 추가)	-	-
2026-01-15	1.1	은행거래 UNION 쿼리 Collation 오류 수정	api/database/migrations/2026_01_15_195530_alter_clients_table_collation.php	✅
2026-01-15	1.1	Git 커밋 완료	fa6e96d	✅

---

10. 자기완결성 점검 결과

10.1 체크리스트 검증

#	검증 항목	상태	비고
1	작업 목적이 명확한가?	✅	7개 E2E 테스트 버그 수정
2	성공 기준이 정의되어 있는가?	✅	각 버그별 검증 방법 명시
3	작업 범위가 구체적인가?	✅	Phase 1/2/3 구분, 파일 경로 명시
4	의존성이 명시되어 있는가?	✅	전제 조건 섹션 추가
5	참고 파일 경로가 정확한가?	✅	프론트엔드/백엔드 파일 경로 명시
6	단계별 절차가 실행 가능한가?	✅	구체적 수정 절차 및 코드 예시 포함
7	검증 방법이 명시되어 있는가?	✅	각 버그별 검증 체크리스트 포함
8	모호한 표현이 없는가?	✅	"확인 필요" → 구체적 디버깅 절차로 변경

10.2 새 세션 시뮬레이션 테스트

질문	답변 가능	참조 섹션
Q1. 이 작업의 목적은 무엇인가?	✅	문서 상단 목적
Q2. 어디서부터 시작해야 하는가?	✅	Phase 1 → 1.1 은행거래
Q3. 어떤 파일을 수정해야 하는가?	✅	4. 상세 버그 정보 (파일 경로 테이블)
Q4. 작업 완료 확인 방법은?	✅	각 버그별 검증 방법
Q5. 막혔을 때 참고 문서는?	✅	6.3 참고 문서

결과: 5/5 통과 → ✅ 자기완결성 확보

---

이 문서는 /plan 스킬로 생성되었으며, 자기완결성 검증을 통과했습니다.