기술 문서 작성자 - 평이한 언어 프로젝트 문서용

# FORME.md - [프로젝트 이름] 완전 정복 가이드 ## 1. 큰 그림 (프로젝트 개요) [여기에 3-4문장의 요약을 작성하세요 - 기술적 지식이 없는 사람도 이해할 수 있게] ### 이 프로젝트가 해결하는 문제 [문제 정의와 대상 사용자를 간단히 설명] ### 사용자 여정 [사용자가 이 시스템을 어떻게 사용하는지 일상적인 언어로 설명] ### 비유로 이해하기 [전체 시스템을 레스토랑, 우체국 등에 비유한 설명] --- ## 2. 기술 아키텍처 - 설계도 ### 시스템 구조도 ``` [사용자 브라우저] → [프론트엔드 서버] → [API 서버] → [데이터베이스] ↓ ↓ [정적 파일 저장소] [외부 서비스 (결제, 이메일 등)] ``` ### 각 층별 투어 **프론트엔드 (레스토랑의 홀)** - 사용자가 직접 보는 부분입니다. 메뉴판(화면)을 보여주고, 주문을 받고, 결과를 전달합니다. **API 서버 (주방)** - 실제 작업이 일어나는 곳입니다. 홀에서 주문이 들어오면 여기서 처리하고, 필요한 재료를 창고(데이터베이스)에서 찾습니다. **데이터베이스 (창고/파일 캐비닛)** - 모든 정보가 저장되는 곳입니다. 고객 정보, 주문 내역, 재고 등이 여기에 보관됩니다. **외부 서비스 (외부 업체)** - 결제 대행사, 이메일 발송 서비스 등 외부에 의존하는 기능들입니다. ### 왜 이런 선택을 했나? [각 아키텍처 결정에 대한 설명 - "이걸 선택한 이유는...", "대안은... 이었지만..."] ### 특별하거나 영리한 설계 [개발자가 만든 독특한 해결책이나 영리한 설계 포인트] --- ## 3. 코드베이스 구조 - 파일 정리 시스템 ### 폴더 구조 ``` 프로젝트 루트/ ├── src/ # 실제 코드가 사는 곳 │ ├── components/ # 화면 구성 요소 (레고 블록) │ ├── pages/ # 페이지 단위 코드 │ ├── api/ # 서버 API 코드 │ └── utils/ # 공용 도구 함수 ├── public/ # 이미지, 폰트 등 정적 파일 ├── config/ # 설정 파일들 └── tests/ # 테스트 코드 ``` ### 주요 폴더 설명 **src/components/** - 화면의 작은 조각들입니다. 버튼, 입력창, 카드 등이 여기 있습니다. 이 폴더를 열어야 할 때: 새로운 UI 요소를 만들거나 수정할 때. **src/pages/** - 실제 페이지 단위입니다. "홈페이지", "로그인 페이지" 등이 여기 있습니다. 이 폴더를 열어야 할 때: 특정 페이지의 동작을 바꿀 때. **src/api/** - 서버와 통신하는 코드입니다. 이 폴더를 열어야 할 때: 데이터를 주고받는 방식을 바꿀 때. ### 이름 규칙 주의사항 [비직관적인 네이밍 규칙이 있다면 설명] ### 시작점 (엔트리 포인트) [프로젝트가 시작되는 파일들 - 예: main.tsx, index.js 등] --- ## 4. 연결과 데이터 흐름 - 시스템 내 통신 방법 ### 핵심 동작 1: [예: 사용자 가입] 사용자가 "가입하기" 버튼을 클릭하면: 1. [파일명]의 함수가 실행됩니다 - 종을 울리는 것과 같습니다 2. 이 신호가 [API 경로]로 전송됩니다 - 주방에 주문이 접수됩니다 3. 주방(서버)은 [데이터베이스]에 사용자 정보가 이미 있는지 확인합니다 4. 없으면 새 사용자로 등록하고, 있으면 "이미 가입된 이메일입니다"라는 응답을 보냅니다 5. 성공 시 환영 이메일이 [이메일 서비스]를 통해 발송됩니다 ### 핵심 동작 2: [예: 주문 생성] [위와 같은 형식으로 상세 설명] ### 외부 서비스 연결 - **결제 서비스**: [서비스명]을 통해 결제를 처리합니다. 이 서비스가 다운되면 결제가 불가능하지만, 주문 자체는 받을 수 있습니다. - **이메일 서비스**: [서비스명]을 사용합니다. 실패해도 핵심 기능에는 영향이 없습니다. ### 인증 흐름 (사용자 확인) [로그인/인증 과정을 비유를 통해 설명] --- ## 5. 기술 선택 - 도구 상자 | 기술 | 이 프로젝트에서 하는 일 | 왜 이걸 선택했나 | 주의할 점 | |------|----------------------|----------------|----------| | [기술명] | [한 문장 설명] | [대안 대비 선택 이유] | [제한사항/비용] | | [기술명] | [한 문장 설명] | [대안 대비 선택 이유] | [제한사항/비용] | | [기술명] | [한 문장 설명] | [대안 대비 선택 이유] | [제한사항/비용] | --- ## 6. 환경 및 설정 ### 환경 변수 | 변수명 | 역할 (쉬운 언어로) | 어디에 연결되는지 | |--------|-------------------|-----------------| | `DATABASE_URL` | 데이터베이스 주소 - 창고 위치 | 데이터베이스 서비스 | | `API_KEY` | 외부 서비스 인증 키 | 해당 외부 서비스 | | `JWT_SECRET` | 사용자 인증 토큰 암호화 키 | 인증 시스템 | ### 환경 구분 - **개발(Development)**: 로컬 컴퓨터에서 테스트하는 환경. 실제 데이터 대신 가짜 데이터 사용. - **스테이징(Staging)**: 프로덕션과 동일한 환경에서 최종 테스트하는 단계. - **프로덕션(Production)**: 실제 사용자가 사용하는 환경. ### 변경 시 주의사항 "[X]를 변경하려면 [Y]를 수정해야 합니다. 하지만 [Z]에 영향이 가니 주의하세요." ### 보안 키 관리 [어떤 키가 어떤 서비스에 연결되는지 - 실제 값은 절대 포함하지 않음] --- ## 7. 교훈 - 개발 과정의 이야기 ### 버그와 수정 **버그 1: [제목]** - **증상**: [무슨 일이 벌어졌나] - **원인**: [쉽게 설명한 원인] - **해결책**: [어떻게 고쳤나] - **재발 방지**: [앞으로 어떻게 피할 수 있나] **버그 2: [제목]** [같은 형식으로 작성] ### 함정과 지뢉 - **겉보기엔 쉬워 보이지만 실제로는 복잡한 것들** - [예: "사용자 비밀번호 변경 기능은 단순해 보이지만, 실제로는 세션 관리, 토큰 갱신, 보안 로그 등 여러 시스템이 연관됩니다."] - **"[X]를 변경하면 [Y]와 [Z]에도 영향이 갑니다"** - **기술 부채**: [시간 압박으로 미룬 작업들] ### 발견한 것들 - **새로 시도한 기술/방법**: [무엇을 시도했고 결과가 어땠나] - **잘 된 것과 안 된 것**: [성공한 시도와 실패한 시도] - **처음부터 다시 한다면**: [개선할 점] ### 엔지니어링 지혜 - **이 프로젝트에서 검증된 모범 사례** - **신뢰할 수 있는 패턴** - **경험 많은 엔지니어의 사고 방식** --- ## 8. 빠른 참조 카드 ### 로컬에서 실행하기 1. [의존성 설치]: `npm install` 또는 `yarn install` 2. [환경 변수 설정]: `.env` 파일 생성 및 설정 3. [데이터베이스 설정]: `npm run db:migrate` 4. [개발 서버 실행]: `npm run dev` 5. [브라우저에서 확인]: `http://localhost:3000` ### 주요 URL - **프로덕션**: [URL] - **스테이징**: [URL] - **관리자 패널**: [URL] - **API 문서**: [URL] ### 문제 발생 시 연락처 - **프론트엔드 이슈**: [담당자/팀] - **백엔드 이슈**: [담당자/팀] - **인프라 이슈**: [담당자/팀] - **긴급 연락**: [연락처] ### 자주 사용하는 명령어 | 명령어 | 용도 | |--------|------| | `npm run dev` | 개발 서버 실행 | | `npm test` | 테스트 실행 | | `npm run build` | 프로덕션 빌드 | | `npm run lint` | 코드 스타일 검사 | | [기타] | [설명] | --- *이 문서는 [프로젝트 이름]을 처음 접하는 모든 사람이 시스템을 이해하고, 문제를 해결하고, 자신 있게 기여할 수 있도록 작성되었습니다.*