tst-claude-code-samples/.taskmaster/specs/1_backend_api.md

Phase 1, Task 1: Backend API & Database Pseudocode

이 문서는 AIROUM 랜딩 페이지의 백엔드 API 및 데이터베이스 로직을 정의합니다.

• 언어/프레임워크: Python / Flask
• 데이터베이스: SQLite

---

1. 데이터베이스 모델 (database.py 또는 models.py)

1.1. Inquiry 모델 정의

• INQUIRIES 테이블에 매핑될 데이터 구조를 정의합니다.

CLASS Inquiry:
    id: INTEGER (Primary Key, Auto-increment)
    name: STRING(50) (Not Null)
    email: STRING(100) (Not Null, Indexed)
    phone: STRING(20) (Nullable)
    message: TEXT (Not Null)
    created_at: DATETIME (Not Null, Default: current time)

1.2. 데이터베이스 초기화 함수

• 애플리케이션 시작 시 데이터베이스 파일과 테이블을 생성하는 로직입니다.

FUNCTION initialize_database():
    // 데이터베이스 연결 (파일이 없으면 생성됨)
    db_connection = connect_to("airoum.db")

    // 'INQUIRIES' 테이블이 존재하는지 확인
    IF NOT table_exists("INQUIRIES", db_connection):
        // 테이블 생성 SQL 실행
        EXECUTE SQL `
            CREATE TABLE INQUIRIES (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                name VARCHAR(50) NOT NULL,
                email VARCHAR(100) NOT NULL,
                phone VARCHAR(20),
                message TEXT NOT NULL,
                created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
            );
        `
        // email 컬럼에 인덱스 생성
        EXECUTE SQL `CREATE INDEX idx_email ON INQUIRIES (email);`
        // TEST: 'INQUIRIES' 테이블이 명세서대로 정확히 생성되는지 확인
        // TEST: 'idx_email' 인덱스가 email 컬럼에 생성되는지 확인

    CLOSE db_connection

---

2. API 로직 (app.py)

2.1. API 엔드포인트: 문의 등록

• POST /api/inquiry 요청을 처리하는 메인 로직입니다.

// Flask 애플리케이션 및 라우트 설정
ROUTE "/api/inquiry" with METHODS ["POST"]
FUNCTION handle_inquiry_submission():
    // 1. 요청 데이터 가져오기
    request_data = get_json_from_request()
    // TEST: 요청의 Content-Type이 'application/json'이 아닐 경우 415 에러를 반환하는지 확인

    IF request_data IS NULL:
        RETURN response_json({"status": "error", "message": "Invalid JSON format"}, status_code=400)
        // TEST: 요청 본문이 비어있거나 유효한 JSON이 아닐 경우 400 에러를 반환하는지 확인

    // 2. 입력 데이터 추출 및 유효성 검사
    name = request_data.get("name")
    email = request_data.get("email")
    phone = request_data.get("phone") // 선택적 필드
    message = request_data.get("message")

    errors = validate_inquiry(name, email, message)
    // TEST: 유효성 검사 함수가 올바르게 호출되는지 확인

    // 3. 유효성 검사 결과에 따른 분기 처리
    IF errors IS NOT EMPTY:
        // 유효성 검사 실패 시
        error_response = {
            "status": "error",
            "message": "입력값을 확인해주세요.",
            "errors": errors
        }
        RETURN response_json(error_response, status_code=400)
        // TEST: 유효성 검사 실패 시, 400 상태 코드와 함께 정확한 오류 메시지를 반환하는지 확인
    ELSE:
        // 유효성 검사 성공 시
        TRY:
            // 4. 데이터베이스에 저장
            db_connection = connect_to("airoum.db")
            EXECUTE SQL `
                INSERT INTO INQUIRIES (name, email, phone, message)
                VALUES (?, ?, ?, ?);
            ` WITH (name, email, phone, message)
            COMMIT transaction
            CLOSE db_connection
            // TEST: 유효한 데이터가 DB에 성공적으로 저장되는지 확인

            // 5. 성공 응답 반환
            success_response = {
                "status": "success",
                "message": "문의가 성공적으로 접수되었습니다."
            }
            RETURN response_json(success_response, status_code=201)
            // TEST: 성공적으로 데이터 저장 후 201 상태 코드와 성공 메시지를 반환하는지 확인

        CATCH DatabaseError as e:
            // 데이터베이스 오류 발생 시
            LOG_ERROR("Database error occurred: " + e)
            server_error_response = {
                "status": "error",
                "message": "서버 내부 오류가 발생했습니다."
            }
            RETURN response_json(server_error_response, status_code=500)
            // TEST: 데이터베이스 연결 또는 INSERT 실패 시 500 에러를 반환하는지 확인
        END TRY
    END IF

2.2. 유효성 검사 헬퍼 함수

• handle_inquiry_submission에서 사용할 입력값 검증 로직입니다.

FUNCTION validate_inquiry(name, email, message):
    errors = {}

    // 이름 검사
    IF name IS NULL OR name IS EMPTY:
        errors["name"] = "이름은 필수 항목입니다."
        // TEST: 이름이 null이거나 비어있을 때 오류를 반환하는지 확인

    // 이메일 검사
    IF email IS NULL OR email IS EMPTY:
        errors["email"] = "이메일은 필수 항목입니다."
        // TEST: 이메일이 null이거나 비어있을 때 오류를 반환하는지 확인
    ELSE IF is_valid_email_format(email) IS FALSE:
        errors["email"] = "올바른 이메일 형식이 아닙니다."
        // TEST: 이메일 형식이 유효하지 않을 때 오류를 반환하는지 확인 (e.g., 'test@test', 'test.com')

    // 문의 내용 검사
    IF message IS NULL OR message IS EMPTY:
        errors["message"] = "문의 내용은 필수 항목입니다."
        // TEST: 문의 내용이 null이거나 비어있을 때 오류를 반환하는지 확인

    RETURN errors