상태값 형식 충돌로 저장이 멈출 때 확인할 필드와 수정 순서

상태값 형식 충돌로 저장이 멈출 때 확인할 필드와 수정 순서

저장 버튼을 누른 뒤 화면이 멈추거나 “유효하지 않은 값” 오류가 나오면 상태 코드가 전달되는 경로부터 확인해야 합니다. 화면에서는 선택이 정상으로 보여도 서버 모델이나 데이터베이스 컬럼이 다른 자료형을 기대하면 저장 단계에서 처리가 중단될 수 있습니다. 특히 숫자 상태 코드, 문자열 상태명, 열거형 값이 한 흐름에 섞이면 조회는 되는데 수정만 실패하는 사례가 생깁니다. 먼저 오류가 화면 입력 단계인지, API 요청 단계인지, DB 저장 단계인지 분리하면 불필요한 수정 범위를 줄일 수 있습니다. 긴급하게 업무가 멈춘 경우에는 010-6833-8119 로 오류 화면과 발생 시각을 함께 전달하는 편이 빠릅니다.

요청값과 컬럼 형식을 먼저 맞춰 보는 진단

첫 점검은 실제로 전송된 상태값과 시스템이 기대한 자료형을 나란히 보는 일입니다. 매향동 STATUS_DATATYPE_MISALIGNMENT처럼 상태값 형식이 맞지 않는 문제는 단순히 값 하나가 틀린 경우보다, 변환 책임이 어느 구간에 있는지 불명확할 때 반복되기 쉽습니다. 오류 화면만 보지 말고 브라우저 개발자 도구의 요청 페이로드, 서버 로그, DB 컬럼 정의를 함께 확인해야 합니다.

예를 들어 DB의 status_code가 정수형인데 요청 JSON에는 "status": "2"처럼 문자열이 들어갈 수 있습니다. 서버가 문자열을 정수로 바꾸도록 작성되어 있다면 저장될 수 있지만, 엄격한 유효성 검사나 ORM 모델 검증을 거치면 형변환 오류로 멈출 수 있습니다. 반대로 컬럼이 문자형인데 숫자만 받도록 설계된 API가 있으면 같은 문제가 반대 방향으로 발생합니다.

로그에는 대체로 실제 전달값, 기대 자료형, 오류가 발생한 엔드포인트나 쿼리 위치가 남습니다. “status must be integer”, “invalid enum value”, “cannot convert null” 같은 메시지가 있다면 값 자체보다 해당 값이 지나간 변환 경계를 표시해 두는 것이 중요합니다. 프런트엔드에서 변환할지, 서버에서 통일할지, DB 제약으로 막을지를 한 번에 정하지 말고 현재 코드의 책임 위치부터 확인합니다.

enum 매핑과 기존 레코드가 만드는 숨은 충돌

상태값이 enum 으로 관리되는 환경에서는 숫자와 문자 차이 외에도 대소문자, 공백, 표기 방식이 저장 실패를 만듭니다. 예를 들어 허용값이 WAITING, PROCESSING, DONE인데 요청값이 waiting 또는 DONE 로 들어오면 화면상 의미는 같아도 서버 비교에서 탈락할 수 있습니다. 새 버전에서 상태명을 바꾼 뒤 구버전 화면이나 연동 프로그램이 이전 코드를 보내는 경우도 점검 대상입니다.

기본값 역시 놓치기 쉬운 부분입니다. 신규 등록 시 상태값을 비워 두면 서버가 기본 상태를 넣는지, DB가 기본값을 넣는지, 둘 다 넣지 않아 null 오류가 나는지 확인해야 합니다. API 문서에는 선택값으로 보이지만 DB 컬럼은 null 을 허용하지 않는 구조라면 등록 단계에서만 실패할 수 있습니다.

운영 중인 데이터의 자료형이나 enum 구성을 바꾸기 전에는 기존 레코드를 반드시 조회해야 합니다. 과거에 사용하던 폐기 코드가 남아 있는지, 숫자 코드와 문자 코드가 섞여 있는지, 외부 연동이 어떤 값을 전송하는지 확인하지 않고 일괄 변환하면 조회 화면이나 통계 처리까지 영향을 받을 수 있습니다. 백업본을 확보한 뒤 영향 범위를 조회하고, 변환 대상·제외 대상·되돌림 기준을 포함한 마이그레이션 계획을 세우는 순서가 안전합니다.

저장 실패를 줄이는 수정·검증 절차

수정은 입력 검증, 서버 변환, DB 제약조건을 각각의 역할로 나누어 진행하는 편이 좋습니다. 화면에서는 사용자가 선택할 수 있는 상태 목록을 제한하고, 서버에서는 들어온 값의 자료형과 허용 목록을 검증합니다. DB는 마지막 단계에서 잘못된 값이 쌓이지 않도록 컬럼 형식과 제약조건으로 보호합니다. 어느 한 단계만 느슨하게 두면 다른 경로로 잘못된 상태값이 유입될 수 있습니다.

서버에서 문자열 숫자를 정수로 바꾸기로 했다면 변환 실패 시의 응답도 정해야 합니다. 무조건 0 이나 기본 상태로 바꾸면 저장은 되더라도 업무 상태가 잘못 기록될 수 있습니다. 변환할 수 없는 값은 원인 확인이 가능한 오류 메시지와 함께 거부하고, 정상적인 값만 명시적으로 저장하도록 구성하는 방식이 재발 방지에 유리합니다.

수정 뒤에는 정상 상태값만 시험하지 말고 아래처럼 경계 조건을 포함해 재현 테스트를 진행합니다.

• 정상 코드: 현재 화면에서 선택 가능한 상태값
• 빈값과 null: 필수 입력 여부 및 기본값 적용 확인
• 잘못된 코드: 허용 목록 밖의 숫자·문자 입력
• 표기 차이: 대소문자, 앞뒤 공백, 문자열 숫자
• 구버전 코드: 이전 프로그램이나 연동 서비스가 보내던 값

테스트마다 요청값, 서버 응답 코드, 실제 저장 결과를 비교해야 합니다. 응답은 성공인데 DB에 값이 바뀌지 않았다면 트랜잭션 롤백, 후처리 예외, 다른 테이블의 제약조건도 확인해야 합니다. 반대로 저장은 됐지만 조회 화면에서 상태명이 비어 보이면 enum 표시 매핑이나 화면 렌더링 단계의 문제일 가능성이 있습니다.

현장 접근 여부를 정하는 기준

장비 내부 프로그램에서만 오류가 재현되거나 사내망 DB에 외부 접근이 제한된 경우에는 현장 점검 조건을 먼저 정리합니다. 매향동 일정은 장비 접근이 필요한지, 오류가 재현되는 업무 시간인지에 따라 조율할 수 있습니다. 출장 점검은 09:00~18:00 서울·경기·인천·세종에서 가능하며, 원격 점검은 새벽 시간을 제외하고 오류 화면·로그·테스트 계정 접근 여부를 바탕으로 우선 진단합니다.

오류가 반복되기 전에 남길 정보

동일한 상태 변경에서 저장 실패가 반복되면 임의로 여러 번 저장을 시도하기보다 발생 조건을 남기는 편이 좋습니다. 오류 화면 캡처, 요청·응답 로그, 사용 중인 프로그램 버전, 발생 시각, 입력한 상태값, 정상 처리되던 이전 상태를 확보하면 원인 구간을 빠르게 좁힐 수 있습니다. 특히 수정 전후의 요청값과 응답을 함께 남겨 두면 문자열 유입인지 enum 변환 누락인지 분리해 검증할 수 있습니다.

상태 코드 문제는 값 하나를 바꾸는 것으로 끝나지 않을 수 있습니다. 컬럼 정의, API 계약, 애플리케이션 모델, 기존 데이터가 같은 기준을 사용하도록 정리하고 재현 테스트 결과까지 기록해야 저장 중단 조건을 차단할 수 있습니다.

점검 문의는 동네형컴퓨터 010-6833-8119 또는 https://udns.kr/에서 접수할 수 있습니다.

자주 묻는 질문

상태값 자료형 불일치는 왜 저장 오류로 이어지나요?

입력값의 자료형이 서버 모델 또는 DB 컬럼이 기대하는 형식과 다르면 형변환이나 유효성 검사 과정에서 처리가 중단될 수 있습니다. 숫자형, 문자열, enum 중 어느 형식을 기준으로 삼는지 모든 구간에서 맞춰야 합니다.

숫자로 보이는 상태 코드를 문자로 보내도 문제가 없나요?

서버가 문자열을 숫자로 바꾸도록 설계되어 있다면 처리할 수 있습니다. 다만 변환 규칙이 없거나 enum 비교를 엄격하게 사용하면 저장 실패, 잘못된 상태 분기, 기본값 처리 오류로 이어질 수 있습니다.

원격 점검으로 원인을 찾을 수 있나요?

오류 재현 화면, 요청·응답 로그, 프로그램 설정, 테스트 가능한 계정이 준비되어 있다면 요청값과 데이터 구조를 우선 확인할 수 있습니다. DB 구조 변경이나 사내 보안망 접근이 필요한 작업은 접근 권한과 현장 조건을 별도로 검토합니다.