DealChat 프로젝트 AI 코딩 가이드

이 문서는 DealChat 프로젝트에서 AI 어시스턴트(GenAI)가 코드를 작성하고 수정할 때 반드시 준수해야 하는 **Ground Rules(기본 규칙)**입니다. AI에게 작업을 지시할 때 "README.md를 참고해서 작성해줘"라고 멘션하면 아래 규칙들이 적용되어 훨씬 경제적이고 정확한 응답을 얻을 수 있습니다.

---

1. 프로젝트 주요 기술 스택

• 프론트엔드: HTML5, Vanilla JavaScript, 전역 CSS (style.css 등)
• 백엔드/DB: Supabase (PostgreSQL 기반)
• 특징: React, Vue 등 프레임워크를 사용하지 않고 순수 JS로 DOM을 조작합니다.
• 주요 라이브러리: jQuery, Chart.js, Swiper, noUiSlider 등 (추가 라이브러리도 임의로 설치하지 않고 프로젝트 내 기존 방식을 따름)

2. 파일 분할 및 500줄 초과 방지 원칙 (Max 500-Line Rule)

하나의 JavaScript나 HTML 파일이 무거워져(예: 1,000줄 이상) AI 컨텍스트가 부족해지거나 유지보수가 힘들어지는 것을 방지하기 위해 모든 파일은 최대 500줄을 넘기지 않는 것을 원칙으로 합니다. (외부 라이브러리 파일은 예외)

AI는 파일이 길어질 조짐이 보이거나, 신규 기능을 추가할 때 아래의 로직 분할 가이드를 따라 코드를 정리해야 합니다.

⚠️ 기존 레거시(Legacy) 코드와의 충돌 해결 (점진적 리팩토링)

방대하게 작성되어 있는 기존 코드(예: 1,000줄이 넘어가는 레거시 파일)에 사소한 버그 수정 지시가 떨어졌을 때, 이 "500줄 원칙"이나 "렌더링/스타일 최적화 규칙"을 무리하게 강제 적용하지 않습니다.

• 사소한 단건 수정: 파일이 아무리 길어도 마음대로 전체 구조를 쪼개지 말고, 기존 작성된 레거시 코드의 문맥과 로직(단점 포함)을 최대한 존중하여 필요한 부분만 안전하게 수정합니다.
• 점진적 및 명시적 리팩토링: 대규모 신규 로직을 추가하거나, 사용자가 명시적으로 "파일을 쪼개서 리팩토링 해줘"라고 요청한 경우에 한하여 이 엄격한 규칙들을 전면 적용합니다.

💡 JS 파일 로직 분할 가이드

페이지 이름이 dealbook_companies일 때 메인 로직이 길어진다면 다음과 같이 분리 및 모듈화합니다.

1. API/DB 통신 계층 분리 (APIcallFunction.js 활용 또는 *_api.js 생성)
   • 데이터 Fetching(마이바티스 형태나 Supabase .select()) 전용 함수로 빼고, 비즈니스 로직에는 순수 데이터만 리턴하도록 만듭니다.
2. UI 렌더링 계층 분리 (*_render.js)
   • 복잡한 카드 폼이나 리스트의 HTML Template Literal 생성 코드는 별도 파일이나 함수로 뽑아냅니다.
3. 이벤트 리스너 및 유틸리티 (*_events.js, helpers.js)
   • 각 필터 버튼 클릭, 모달 제어 함수 등은 유틸이나 이벤트 전용 코드로 분리합니다.
4. HTML 파일 모듈화
   • Header, Footer, 공통 Auth 모달 등은 중복 코드로 남기지 않고, 기존 header_loader.js, footer_loader.js, modal_loader.js 등을 이용해 동적으로 렌더링합니다.

---

3. 핵심 코딩 컨벤션 (AI 필수 준수 사항)

3.1 CSS 및 스타일링

• 인라인 스타일 금지: HTML 태그에 직접 style="..." 속성을 작성하거나 <style> 태그를 남발하지 않습니다.
• 전역 CSS 활용 지향: 모든 커스텀 스타일은 css/style.css 의 적절한 주석 블록 (e.g., /* ── Shared Items ── */) 아래에 클래스로 정의하여 적용합니다.

3.2 DOM 조작 성능 최적화 (단일 렌더링)

• 반복 렌더링 금지: 배열 데이터를 뷰에 뿌릴 때 forEach 내부에서 DOM에 .append()를 연속 제어하지 마세요.
• 개선 방식: Map이나 배열에 해당 HTML 구조(String)를 담은 후 join('') 하여, 반복문 종료 후 컨테이너 .innerHTML에 딱 1번만 할당합니다.

3.3 예외 처리(Error Handling) 체계 의무화

• DB 예외 처리: Supabase API 등 외부 호출 시 (await supabase...) 반드시 try/catch 블록으로 예외를 처리하여 애플리케이션 크래쉬를 방지하세요.
• 파싱 예외 처리: 로컬 변수인 localStorage 접근 후 JSON.parse()를 실행할 때는 가비지 데이터나 null을 대비해 반드시 try/catch 처리를 해야 합니다. (참고: js/auth_utils.js)

3.4 보안 코딩 원칙

• 사용자 입력값이나 파라미터를 그대로 HTML 속성(onclick, URL 등)에 주입하지 마세요. (예: onclick="location.href='${returnUrl}'"은 인젝션 위험이 있으므로 addEventListener로 안전하게 리다이렉트를 처리합니다.)

---

4. 디렉토리 구조 요약

• /html: 페이지 단위 마크업
• /css: 디폴트 및 공통 CSS 에셋 (style.css 우선 적용)
• /js: 페이지/컴포넌트별 자바스크립트 소스.
• /supabase, SQL 파일 (schema.sql, schema_v2.sql): 주요 DB 마이그레이션 백업