기술 진단 보고서 견본 · 가상 시스템 기준
외주 개발사가 만든 커머스 플랫폼을 오픈 직전에 6일 동안 점검했다고 가정하고 쓴 보고서 견본입니다. 시스템, 코드 경로, 수치, 발견 사항은 모두 가상이며, 실제 보고서는 받은 소스와 설정으로 채웁니다.
오픈 전 항목 7건을 고치고 항목마다 적은 "고친 뒤 확인" 방법으로 다시 돌려 통과하면, 예정대로 오픈해도 됩니다. 그중 치명 2건은 결제 금액과 출고가 실제로 어긋나는 문제라 가장 먼저 고칩니다. 오픈 후 항목 3건은 2주와 1개월 일정에 넣습니다.
주문 하나가 결제, 출고, 매출 반영까지 지나가는 길을 따라 문제를 찾았습니다. 항목을 누르면 아래 발견 사항으로 이동합니다.
위험도와 고칠 시점으로 걸러 볼 수 있습니다. 제목을 누르면 근거, 영향, 재현 방법, 권고, 고친 뒤 확인 방법이 펼쳐집니다. 외주 개발사가 이 내용만 보고 바로 고칠 수 있게 씁니다.
api/src/payment/payment.service.ts의 confirmPayment()가 주문 상태 읽기, PG 결제 조회, 상태를 "결제 완료"로 바꾸기를 잠금이나 조건 없이 따로 실행합니다. PG 웹훅(/webhooks/pg)과 앱의 완료 복귀(/orders/{id}/pay/complete)가 모두 이 함수를 부르고, 상태를 바꾼 직후 WMS 출고 지시를 보냅니다.UPDATE orders SET status = 'PAID' WHERE id = ? AND status = 'PENDING' 같은 조건부 갱신으로 바꾸고, 바뀐 행이 0건이면 이미 처리된 주문으로 보고 끝냅니다. 출고 지시는 같은 트랜잭션에서 출고 대기 테이블에 기록하고, 별도 작업이 주문 번호를 중복 방지 키로 붙여 WMS에 보냅니다.POST /api/v1/orders/{id}/pay가 요청 본문의 amount로 PG에 승인을 요청하고, 서버에 저장된 주문 금액과 비교하지 않습니다. PG 승인 응답의 금액도 대조하지 않습니다.amount를 100으로 바꿔 보냅니다.app/src/network/client.ts)이 10초 안에 응답이 없으면 POST 요청도 2번까지 다시 보냅니다. 서버의 주문 생성에는 같은 요청을 알아보는 키가 없습니다.api/src/wms/wms.client.ts의 HTTP 호출에 연결·응답 시간 제한이 없습니다. 실패하면 logger.error만 남기고 주문 상태는 "출고 요청"으로 바뀝니다.createOrder()가 한 트랜잭션 안에서 재고 차감, PG 결제 준비 요청, 알림톡 발송 요청까지 기다립니다. DB 연결 풀은 서버당 10개, 서버는 2대입니다.config/production.yml에 운영 DB 접속 정보가 있습니다. 지금 파일에서는 지웠지만 저장소 기록에 남아 있습니다. IAM 사용자 3개가 관리자 권한이고 MFA가 꺼져 있습니다.orders 테이블에 (status, created_at) 인덱스가 없어 관리자 주문 목록이 매번 전체를 읽습니다. 지금 테스트 데이터 3만 건에서는 0.4초입니다.(status, created_at) 인덱스를 추가하고, 기본 조회 기간을 최근 30일로 둡니다.이 조건에 맞는 항목이 없습니다.
수치는 모두 예시입니다. 실제 보고서에는 직접 재현했거나 코드와 설정으로 확인한 것만 발견 사항으로 적고, 추정은 추정이라고 따로 표시합니다.
공고의 점검 범위를 여덟 영역으로 나눴습니다. 영역마다 무엇을 어떤 방법으로 보는지 정해 두고 6일 안에 모두 봅니다.
| 영역 | 보는 것 | 방법 |
|---|---|---|
| 아키텍처 | 웹·앱, API 서버, 작업 큐, DB, 외부 연동의 구성과 장애가 번지는 경로 | 소스와 AWS 구성으로 구성도를 그리고, 주문부터 결제, 출고, 매출, 취소·환불·반품까지 핵심 흐름을 따라갑니다 |
| 주문·결제 트랜잭션과 예외 처리 | 트랜잭션 범위, 실패했을 때 되돌리기, 결제 금액 검증, 주문 상태 전이 | 코드를 읽고, 테스트 환경에서 결제 실패와 중간 오류를 일부러 일으켜 봅니다 |
| 중복 방지 | 중복 결제, 중복 주문, 중복 출고, 웹훅 재전송 | 같은 요청을 동시에, 반복해서 보내 결과가 한 번만 생기는지 봅니다 |
| WMS·ERP·결제 연동 | 시간 제한, 재시도, 중복 방지 키, 처리 순서, 실패 건 보관, 대사 | 테스트 환경에서 연동 상대가 느려지거나 끊긴 상황을 만들어 데이터가 빠지거나 두 번 생기는지 봅니다 |
| 앱의 API 호출 | 자동 재시도, 네트워크가 끊긴 뒤 다시 보내기, 앱 버전이 섞일 때의 API 호환 | 앱의 네트워크 코드와 API 명세를 대조하고, 느린 응답을 만들어 앱 동작을 봅니다 |
| 주문 폭주 | 서버·DB 병목, 연결 풀, 느린 쿼리, 오토스케일링 | 정해 주신 시간대에 검증 환경에서 주문 시나리오로 부하 시험을 하고, 느린 쿼리 로그와 실행 계획을 봅니다 |
| 백업·복구 | 백업 주기와 보존 기간, 시점 복원, 이미지 저장소, 복구 절차 | 최근 백업을 운영과 분리된 임시 DB로 복원해 걸린 시간과 주문·결제 건수를 맞춰 봅니다 |
| 기본 보안 | 권한, 비밀값, 로그의 개인정보, 관리자 경로, 보안 그룹 | IAM·보안 그룹 설정, 저장소 기록 검색, 로그 표본을 봅니다 |
계약 즉시 시작합니다. 치명 항목은 보고서를 기다리지 않고 찾은 날 바로 알립니다.
위험도는 일어났을 때의 피해와 일어날 가능성을 함께 보고 정합니다. 고칠 시점은 오픈 일정에 맞춰 붙입니다.
| 위험도 | 기준 | 고칠 시점 |
|---|---|---|
| 치명 | 지금 조건 그대로 돈, 주문, 출고 데이터가 틀어지거나 개인정보가 밖으로 나갈 수 있음 | 오픈 전 |
| 높음 | 주문 폭주, 연동 지연·장애, 계정 유출 같은 조건이 생기면 위와 같은 결과로 이어지거나 서비스가 멈춤 | 오픈 전 |
| 중간 | 정산 오차, 복구 지연, 개인정보 보관 기준 위반처럼 운영 부담이 쌓이는 문제 | 오픈 후 2주 안 |
| 낮음 | 데이터가 늘었을 때의 성능, 유지보수 편의 | 오픈 후 1개월 안 계획 |
PDF와 편집할 수 있는 문서로 함께 드립니다.
소스, 연동 구조, 서버 정보는 이 원칙으로만 다룹니다.