내부통제 AX 실습 교재

1-01 · 거래처 변경 데이터 연결하기

1. 실습 목표

student/00-starter에서 앱과 CSV 6종을 확인한 뒤, 공통 앱 셸·내비게이션을 만들고 vendor_changes.csv 30건을 읽는 모집단 API를 연결합니다. 입력 원본과 연결 키를 먼저 확인해야 행 번호나 이름으로 잘못 결합한 결과를 막을 수 있습니다.

2. 시작 지점

  • 시작 체크포인트: student/00-starter
  • 화면: 실습 준비 완료와 health 상태만 있는 최소 시작 화면
  • 입력: input/day-1 CSV 6종과 assets/scenario 기준 자료
  • 시작 화면에서 health 응답과 CSV 6종의 위치를 확인합니다.

3. 구현 범위 및 요구사항

환경과 입력 원본 확인

  • 최초 설치와 npm run check, GET /api/health를 실행합니다.
  • 자료는 change_id, vendor_id, request_id, 사용자 ID와 계좌 토큰으로 연결합니다.
  • control-card.md의 R-01–R-04와 case-matrix.xlsx의 규칙·사례 판정을 대조합니다.
  • CHG-2608-023은 승인 행이 없다는 사실을 원본에서 확인합니다.

공통 앱 셸과 모집단 화면

  • 사이드바·업무 단계·페이지 제목·현재 진행 상태를 표시하는 최소 셸을 먼저 만듭니다.
  • 모집단 메뉴에서 로딩·성공·오류·다시 시도 상태를 구분합니다.
  • 모집단 API가 연결되면 로딩·빈 결과·오류를 구분해 30건과 첫·마지막 change_id를 표시합니다.

CSV 모집단 연결

  • 헤더를 제외한 30행을 파일 순서대로 읽고 업무 식별자는 change_id를 사용합니다.
  • 파일 없음, 헤더 불일치, 중복 change_id와 읽기 실패를 정상으로 바꾸지 않습니다.
  • 입력 파일을 실행 중 생성·보정·덮어쓰지 않습니다.

입력 원본 보존

CSV 6종, 기준 자료와 실제 회사자료는 수정하거나 대체하지 않습니다.

4. 실습 프롬프트

Claude Code에 붙여 넣을 프롬프트
거래처 변경 CSV 전체를 기존 웹앱의 모집단 API와 화면에 연결해 주세요.
 
현재 앱에는 기본 화면만 있고 거래처 변경 요청은 아직 연결되어 있지 않습니다. `CLAUDE.md`, `assets/scenario`와 `input/day-1`의 CSV 6종을 먼저 살펴보고 실행 방법, 각 파일의 역할과 연결 키를 파악해 주세요.
 
구현이 끝나면 사용자가 모집단 메뉴에서 거래처 변경 요청 전체를 입력 파일의 순서대로 확인할 수 있어야 합니다. 기존 프로젝트 구조와 화면 스타일을 그대로 사용해 주세요.
 
- CSV 헤더와 `change_id`를 기준으로 한 모집단 로더 구현
- 파일 순서를 유지하는 모집단 조회 API 추가
- 기존 앱 셸과 내비게이션을 활용한 모집단 목록 화면 연결
- 로딩, 빈 결과, 오류와 다시 시도 상태 구분
- 파일 없음, 헤더 불일치, 중복 ID와 읽기 실패에 대한 명확한 오류 처리
- 입력 CSV와 이후 단계의 판정·저장 기능 변경 금지
 
기존 검사 명령과 모집단 API 호출 1회만 확인해 주세요. 구현 후에는 변경 파일, 실제 API와 화면 동작, 검사 통과 여부와 남은 위험만 간단히 알려 주세요.

5. 예상 결과

Success

  • 체크포인트: student/01-population-ready
  • GET /api/health 정상
  • 모집단 30, 첫 사례 CHG-2608-001, 마지막 사례 CHG-2608-030
  • CHG-2608-023 승인 행 없음 확인

직접 확인할 결과

  1. 00-starter의 최소 시작 화면에서 공통 앱 셸과 업무 단계 내비게이션이 보입니다.
  2. 모집단을 불러오는 동안 로딩 상태를 확인합니다.
  3. 성공하면 30건 목록, 첫 CHG-2608-001, 마지막 CHG-2608-030을 확인합니다.
  4. 백엔드를 잠시 중지해 오류 상태를 확인한 뒤 다시 실행하고 다시 시도합니다.

6. 대표 실패 사례 및 복구

Failure

  • 헤더를 세어 31건이 되거나 오류 행을 버려 29건이 됨
  • 다른 작업 폴더의 상대 경로를 읽음
  • CSV를 Excel로 다시 저장해 값이나 인코딩을 바꿈

Info

입력을 고치지 말고 실행 위치와 실제 경로를 대조합니다. 원본이 바뀌었다면 starter 복구 절차로 돌아갑니다.

7. 다음 실습

30건을 유지한 채 입력 오류와 통제 결과를 구분하는 기능을 구현합니다.