From 4cac7eb7f285da5a662c58595d007bff827697b6 Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Tue, 27 Jan 2026 09:42:39 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=9B=90=EC=B9=99=20=EB=AC=B8=EC=84=9C?= =?UTF-8?q?=20=EA=B0=95=ED=99=94=20-=20DB=20=EC=8A=A4=ED=82=A4=EB=A7=88=20?= =?UTF-8?q?=ED=99=95=EC=9D=B8=20=ED=95=84=EC=88=98,=20=EA=B3=84=ED=9A=8D?= =?UTF-8?q?=20=EB=AC=B8=EC=84=9C=20=EC=A6=89=EC=8B=9C=20archive=20?= =?UTF-8?q?=EC=9D=B4=EB=8F=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 311_백엔드_구조_원칙.md: 구현 전 실제 DB 스키마 확인 필수 체크리스트 추가 - 312_문서_작성_원칙.md: 계획 문서 완료 시 즉시 archive 이동 원칙 강화 --- .../311_백엔드_구조_원칙.md | 18 +++++++++++++++--- .../312_문서_작성_원칙.md | 3 ++- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/book/300_architecture/311_백엔드_구조_원칙.md b/book/300_architecture/311_백엔드_구조_원칙.md index b2cce10..eefb1b7 100644 --- a/book/300_architecture/311_백엔드_구조_원칙.md +++ b/book/300_architecture/311_백엔드_구조_원칙.md @@ -162,9 +162,17 @@ utils - ❌ Supabase 쿼리 체이닝에서 컬럼명과 예약어 충돌 시 직접 사용 (Python 로직으로 처리) - ❌ 프로덕션에서 더미/목 데이터 생성 및 사용 (`random`, `mock`, `dummy` 데이터 생성 금지) -## 6-1. DB 스키마 변경 시 동기화 필수 +## 6-1. DB 스키마 확인 및 변경 시 동기화 필수 -**핵심 원칙**: ORM 모델, DDL, Repository 코드를 동시에 수정해야 함 +**핵심 원칙**: 구현 전 실제 DB 스키마 확인 필수, ORM 모델, DDL, Repository 코드를 동시에 수정해야 함 + +### 구현 전 필수 확인 사항 +1. **실제 DB 스키마 확인**: `information_schema.columns` 조회 또는 DDL 스크립트 확인 + - 계획 문서의 스키마와 실제 DB 스키마 불일치 가능성 있음 + - 컬럼 존재 여부, 타입, nullable 여부 확인 +2. **기존 마이그레이션 스크립트 확인**: `scripts/` 디렉토리의 DDL 파일 확인 + - 최소 버전(minimal) 스크립트와 전체 버전 스크립트 차이 확인 + - 실제 적용된 스크립트 확인 ### 필수 동기화 항목 1. **ORM 모델** (`state/{도메인}_repository.py` 또는 `models/{도메인}_model.py`) @@ -173,14 +181,17 @@ utils - CREATE TABLE, ALTER TABLE 문 3. **Repository 코드** (`state/{도메인}_repository.py`) - INSERT/UPDATE 시 필드 처리 로직 + - SELECT 쿼리에서 실제 존재하는 컬럼만 조회 ### 체크리스트 +- [ ] **구현 전 실제 DB 스키마 확인 완료** (information_schema 또는 DDL 스크립트) - [ ] ORM 모델 수정 완료 - [ ] DDL 수정 완료 (기존 DB 마이그레이션 스크립트 작성) -- [ ] Repository 코드 수정 완료 (`.get()` 사용 등) +- [ ] Repository 코드 수정 완료 (실제 존재하는 컬럼만 사용) - [ ] 테스트 작성 및 검증 완료 ### 교훈 +- 구현 전 스키마 확인 없이 계획 문서 기반으로 쿼리 작성 시 컬럼 없음 에러 발생 - 한 곳만 수정 시 런타임 에러(KeyError 등) 또는 스키마 불일치 발생 - 스키마 변경 시 3곳(ORM/DDL/Repository) 동시 점검 필수 @@ -208,6 +219,7 @@ utils - [ ] 순환 import 가능성은 없는가? - [ ] 핵심 파일은 500줄 이하로 유지할 수 있는가? - [ ] 중복 코드는 utils/로 추출할 수 있는가? +- [ ] **DB 관련 작업 시 실제 DB 스키마 확인 완료** (구현 전 필수) - [ ] DB 스키마 변경 시 ORM/DDL/Repository 동시 수정 확인 - [ ] Supabase 쿼리에서 컬럼명과 예약어 충돌 시 Python 로직으로 처리했는가? - [ ] LLM 호출 횟수 계산 및 최적화 검토 diff --git a/book/300_architecture/312_문서_작성_원칙.md b/book/300_architecture/312_문서_작성_원칙.md index 863909a..95fba88 100644 --- a/book/300_architecture/312_문서_작성_원칙.md +++ b/book/300_architecture/312_문서_작성_원칙.md @@ -47,8 +47,9 @@ **용도**: 미래 계획, 아이디어만 (아직 구현 안 됨) **규칙** (⚠️ **핵심 원칙 - 절대 위반 금지**): -- **구현 완료 시 `journey/plans/archive/`로 이동** (필수) - `plans/`에는 미구현 계획만 남김 +- **구현 완료 시 즉시 `journey/plans/archive/`로 이동** (필수, 지연 금지) - `plans/`에는 미구현 계획만 남김 - **모든 구현 완료 섹션은 즉시 삭제** - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체 (상세 완료 사항 나열 금지) +- **배포/테스트 완료 후 바로 archive 이동** - troubleshooting 문서 작성과 동시에 또는 그 직후 즉시 처리 - **구현 코드 파일 금지** - SQL 마이그레이션 파일(.sql), 코드 파일(.py, .js 등) 등 실제 구현 파일은 `plans/`에 두지 않고 해당 서비스 코드베이스에 위치 - **명확한 행동강령만 기록** - 불확실한 표현("예상", "가능", "고려", "검토", "추후", "나중", "필요시", "선택", "옵션", "또는", "아마", "것 같", "추정") 금지 - **여지가 있는 내용은 아이디어 폴더로 이동** - 불확실한 아이디어는 `journey/ideas/`에 기록