# Databases ## PostgreSQL DB 목록 | DB명 | 용도 | | --- | --- | | `itemcode_db` | 상품코드, 단품/세트 구성, 채널 ↔ 사내 코드 매칭 | | `orderlist_db` | 주문 수집·분석·관리 (구 `orderlist_app`) | | `return_db` | 반품·교환·CS 데이터 | | `expense_db` | 개인경비 / 법인카드 사용내역 / 정산 | | `cupang_db` | 쿠팡 밀크런 출고 묶음 / 출고 라인 / 입고센터 / 박스 입수량 규칙 | | `malaysia_stock_db` | 말레이시아 창고 재고관리 — 창고/아이템/세트 BOM/입출고 이력/일일 재고조사 | | `cafe24_db` | 카페24 연동 — OAuth 토큰/상품 캐시/상세페이지 버전/예약/감사·API 로그 | | `performance_db` | 실적(쇼핑몰 통합 매출) — 쇼핑몰 설정/수수료율 이력/API 인증정보(암호문)/연결 상태/매출 사건/동기화 기록 | | `inout_db` | 입출고 관리 — 공장/발주 담당·입고 담당/발주서·발주 품목/입고·입고 품목/상품 정보(단가·무게·은 함유량, 004)/모듈 설정(물류센터 이메일)·입고 요청 메일 기록(005) (2026-10-16, 앱 계정 `inout_app`, `INOUT_DB_URL`, 초기화 `scripts/sql/inout_db_init.sql`, 상세 `docs/INOUT_MODULE.md`) | --- ## 명명 규칙 자산관리 전용 `asset_db` / 앱 계정 `asset_app` / 소유자 `postgres`. 테이블 `assets`, `asset_reports`, `asset_events`, `asset_photos`, `asset_monitor_links`. 원본 XML과 검증된 사진을 DB에 보존한다. 수퍼 관리자 삭제는 `assets.deleted_at/deleted_by` 표시로 처리한다. 기존 설치 추가 마이그레이션은 `scripts/sql/asset_db_002_photos_monitors.sql`. `ASSET_DB_URL`, 초기화 `scripts/sql/asset_db_init.sql`(사용자가 서버에서 직접 실행). 백업 권장: 매일 `/var/backups/postgres/asset_db_YYYY-MM-DD.dump`. 상세 설치·권한·업무 규칙은 [ASSET_MODULE.md](ASSET_MODULE.md). - 모든 DB 이름은 **소문자 + 언더스코어**, **`_db`로 끝낸다**. - ✅ `inventory_db`, `cs_db` - ❌ `inventoryApp`, `cs-database` - 신규 DB 생성은 **서버 실행 명령을 제공하고 사용자가 직접 진행한다** (사용자 지시: 2026-10-06). 대상·현재 상태·백업 확인과 생성 후 권한·연결 검증 명령을 함께 제공한다. 기존 DB 삭제·덮어쓰기는 별도 승인을 받는다. - 신규 DB 생성 시 함께 정리할 항목: - 용도와 책임 모듈 - 소유자(OWNER) 계정 - 백업 주기와 위치 - `.env`의 연결 정보 변수명 --- ## 레거시 이름 매핑 | 예전 이름 | 현재 기준 | | --- | --- | | `orderlist_app` | `orderlist_db` | 코드/문서/설정에서 `orderlist_app`을 발견하면 `orderlist_db`로 수정한다 (수정 전 영향 범위 확인). --- ## DB 작업 원칙 1. **작업 전 백업 우선**. 백업 없는 변경은 진행하지 않는다. 2. 테이블 owner, 권한, sequence 권한을 확인한다. 3. 운영 DB의 `DROP`, `TRUNCATE`, 조건 없는 대량 `DELETE/UPDATE`는 **사용자 확인 없이 실행 금지**. 4. 스키마 변경은 마이그레이션 스크립트(`scripts/` 또는 alembic 등)로 관리한다. 5. 운영 DB와 개발 DB의 접속 정보를 혼동하지 않는다 (`.env`로 분리). --- ## 위험 명령 (사용자 승인 필수) | 명령 | 비고 | | --- | --- | | `DROP DATABASE` | 복구 불가. 백업 없으면 절대 실행 금지 | | `DROP TABLE` / `DROP SCHEMA` | 의존 객체 확인 필수 | | `TRUNCATE` | FK CASCADE 시 광범위 삭제 위험 | | 조건 없는 `DELETE` / `UPDATE` | `WHERE` 없는 문 차단 | | `docker volume rm ` | 운영 데이터 영구 손실 | | `docker compose down -v` | 볼륨까지 제거. 운영에서 금지 | 실행 전 반드시: 1. 백업 확인 (`pg_dump`, 컨테이너 외부 마운트) 2. 영향 범위 설명 3. 사용자 명시 승인 --- ## 자주 쓰는 점검 명령 ```bash # 컨테이너/네트워크 docker ps docker network ls docker inspect # DB 목록 / 접속 sudo -u postgres psql -l docker exec -it psql -U postgres -l # 특정 DB 접속 docker exec -it psql -U -d itemcode_db # 테이블/권한 확인 \dt \dn+ \du \z ``` --- ## expense_db 스키마 / 초기화 DDL: `scripts/sql/expense_db_init.sql` (멱등). DB·역할·테이블·인덱스·트리거를 한 번에 생성. ### 테이블 `expense_items` | 컬럼 | 타입 | 비고 | | --- | --- | --- | | `id` | TEXT PK | 12자 hex (uuid4 앞 12자) | | `owner` | TEXT | 소유자 email (소문자) | | `spent_at` | DATE | 사용일 | | `category` | TEXT | 식대/교통/숙박/비품/접대/통신/기타 | | `method` | TEXT | 법인카드/개인지출/현금 | | `merchant` | TEXT | 가맹점 | | `amount` | BIGINT | 원 단위, ≥ 0 | | `memo` | TEXT | 비고 | | `status` | TEXT | 작성중/제출/승인/반려/정산완료 | | `approver_email` | TEXT | 결재자 email (승인/반려/정산 시 기록) | | `decided_at` | TIMESTAMPTZ | 결재 시점 | | `reject_reason` | TEXT | 반려 사유 | | `created_at` / `updated_at` | TIMESTAMPTZ | 트리거로 자동 갱신 | 인덱스: `(owner, spent_at DESC)`, `(status)`, `(created_at DESC)`. ### 테이블 `expense_attachments` 영수증/기타파일 메타데이터. 실제 파일은 `DATA_DIR/uploads/expense/{item_id}/` 에 저장. | 컬럼 | 타입 | 비고 | | --- | --- | --- | | `id` | TEXT PK | 12자 hex | | `item_id` | TEXT FK | `expense_items(id)` ON DELETE CASCADE | | `owner` | TEXT | 업로드한 사용자 email | | `kind` | TEXT | `receipt` 또는 `other` (CHECK) | | `filename` | TEXT | 원본 파일명 | | `stored_path` | TEXT | 디스크 경로 (절대) | | `content_type` | TEXT | MIME | | `size_bytes` | BIGINT | 바이트 | | `uploaded_at` | TIMESTAMPTZ | 업로드 시각 | 인덱스: `(item_id)`. ### 결재 워크플로 ``` 작성중 ─submit──▶ 제출 ─approve──▶ 승인 ─settle──▶ 정산완료 ▲ │ └─revert/reject──┴─reject──▶ 반려 ─revert──▶ 작성중 ``` - `submit`/`revert`: owner 본인 - `approve`/`reject`/`settle`: `expense_approver` 또는 `admin` - 첨부 추가/항목 수정/삭제: `작성중` 또는 `반려` 상태에서만 ### 마이그레이션 기존 운영 DB 에 신규 컬럼/테이블 적용: ```bash docker exec -i postgres-db psql -U postgres -d expense_db \ < scripts/sql/expense_db_002_workflow_attachments.sql ``` 신규 설치는 `expense_db_init.sql` 하나로 충분 (둘 다 멱등). ### 운영 서버 초기화 (1회) ```bash # 1) 비밀번호 변수 준비 (셸 히스토리에 남지 않게 환경변수 사용) read -s -p "expense_app password: " APP_PWD; echo # 2) PostgreSQL 컨테이너에 DDL 적용 docker exec -i postgres-db psql -U postgres \ -v app_password="$APP_PWD" \ < scripts/sql/expense_db_init.sql # 3) main-app .env 에 EXPENSE_DB_URL 추가 # EXPENSE_DB_URL=postgresql://expense_app:@postgres-db:5432/expense_db # 4) main-app 재기동 docker compose up -d --build ``` ### JSON → DB 마이그레이션 ```bash docker exec -e EXPENSE_DB_URL="$EXPENSE_DB_URL" -it dbx-main \ python scripts/migrate_expense_json_to_db.py \ --json /data/expense.json --dry-run # 결과 확인 후 docker exec -e EXPENSE_DB_URL="$EXPENSE_DB_URL" -it dbx-main \ python scripts/migrate_expense_json_to_db.py --json /data/expense.json ``` > 멱등 INSERT(`ON CONFLICT DO NOTHING`). 원본 JSON 은 건드리지 않는다. --- ## cupang_db 스키마 / 초기화 DDL: `scripts/sql/cupang_db_init.sql` (멱등). DB·역할(`cupang_app`)·테이블·인덱스·트리거·센터 seed 를 한 번에 생성. **JSON 폴백 없음** — `CUPANG_DB_URL` 미설정 시 모듈이 "설정 필요" 안내만 표시. 테이블: | 테이블 | 용도 | | --- | --- | | `cupang_centers` | 입고센터. `active=false` 로 비활성화(사용 중이면 hard delete 금지) | | `cupang_box_rules` | 제품코드별 박스당 입수량(`units_per_box`). `product_code` UNIQUE | | `cupang_shipments` | 출고 묶음 헤더 (작성일/출고일/센터입고일/센터/출고방식/상태/작업자/메모) | | `cupang_shipment_lines` | 출고 라인. `shipment_id` FK ON DELETE CASCADE. `UNIQUE(shipment_id, line_no)` | | `cupang_box_calc_drafts` | 박스 계산 화면 임시 저장. `title` + `payload`(JSONB: 입력 품목·열어둔 센터·분배 내역). 같은 제목이면 덮어씀 | `status` 허용값: `작성중`, `출고준비`, `출고완료`, `센터입고완료`, `취소`. 삭제는 기본 soft delete(`status='취소'`). 박스 계산은 서버(`store.compute_boxes`)에서 재계산: `required_boxes = ceil(quantity / units_per_box)`. 클라이언트 계산은 미리보기용. 제품 카탈로그 `cupang_products`(제품코드 UNIQUE·제품명·쿠팡상품코드·활성) — **포장무게 `weight_g`**(INTEGER g, NULL = 미입력, 0~1,000,000 CHECK)는 마이그레이션 `scripts/sql/cupang_db_007_product_weight.sql`, 초기 값 시드 `scripts/sql/cupang_products_weight_seed.sql`(무게가 비어 있는 행만 채움, 실행 전 값은 `_cpg_weight_seed_backup` 에 남김). 007 미적용이면 화면은 무게 칸을 숨기고 그대로 동작. 출고 상세의 상자별 무게 합계는 저장하지 않고 화면·엑셀을 만들 때 지금 무게로 계산한다. 임시 저장(`cupang_box_calc_drafts`)은 화면 상태 스냅샷만 담는다. 불러올 때 박스 수는 저장값을 쓰지 않고 서버에서 다시 계산하고, 그 위에 분배 내역을 얹는다(사라진 항목은 제외). 마이그레이션: `scripts/sql/cupang_db_003_box_calc_drafts.sql`. 상품은 `cupang_db` 에 복제 저장하지 않는다. 라인에는 `product_code` + `product_name_snapshot` 만 보존(과거 명칭 보존). 상품 검색은 `itemcode_db` **읽기 전용**(`ITEMCODE_DB_URL`, 미설정 시 수동 입력). ### 운영 서버 초기화 (1회, 사용자 승인 후) ```bash read -s -p "cupang_app password: " APP_PWD; echo docker exec -i postgres-db psql -U postgres \ -v app_password="$APP_PWD" \ < scripts/sql/cupang_db_init.sql # main-app .env 에 추가: # CUPANG_DB_URL=postgresql://cupang_app:@postgres-db:5432/cupang_db cd /opt/www/main && docker compose up -d --build ``` > 멱등 스크립트. 기존 DB 가 있으면 DROP 하지 않음. itemcode_db 는 건드리지 않음. --- ## vacation_db 스키마 / 초기화 DDL: `scripts/sql/vacation_db_init.sql` (멱등). DB·역할(`vacation_app`)·테이블·인덱스·트리거·2026 공휴일 seed 를 한 번에 생성. **JSON 폴백 없음** — `VACATION_DB_URL` 미설정 시 모듈이 "설정 필요" 안내만 표시. 테이블: | 테이블 | 용도 | | --- | --- | | `vacation_requests` | 휴가 신청(헤더). 종류/기간/시작·종료 구분(full/am/pm)/일수/사유/상태/승인자/반려사유 | | `vacation_holidays` | 예전 공휴일 설정(2026 seed). **2026-10-27 부터 읽지 않음** — 공휴일 = 국경일·대체공휴일 표(`KR_HOLIDAYS`), 설정 화면 삭제 | | `vacation_balances` | 사용자별 연차(`UNIQUE(user_email, year)`). `total_days` 설정, 사용일수는 승인 휴가 합계로 자동 계산 | `status` 허용값: `작성중`, `제출`, `승인`, `반려`, `취소`. 워크플로: 작성중/반려 → 제출 → 승인|반려. 삭제는 기본 soft delete(`status='취소'`). 수정은 작성중/반려 상태에서 본인만. 휴가 일수는 서버(`store.compute_days`)에서 재계산: 주말 + 쉬는 날 제외, 오전/오후 반차 0.5일, 시작/종료 반차는 각 0.5 차감. 클라이언트 계산은 미리보기용(같은 공휴일 표). 쉬는 날(2026-10-27) = 국경일·대체공휴일(프로젝트 `KR_HOLIDAYS`, 2026~2030, 새 연도는 그 표에 추가) — `db.holiday_map`. `vacation_holidays` 는 읽지 않는다. 연차(2026-10-27) = **입사일 기준**(`store.leave_status`) — 연차마다 쓸 수 있는 기한이 따로(1년 미만 월 1일 = 입사일부터 1년, 근속 연차 = 생긴 날부터 1년), 12/31 소멸 없음. 쓴 연차 = 승인된 연차·오전반차·오후반차만, 먼저 소멸하는 연차부터 뺀다. `vacation_balances.year` = 직접 입력한 연차 기간이 시작한 해(+ 2026 줄 = 시스템 전 사용). 권한: `vacation`(접근) / `vacation_approver`(승인·반려 — 옵션에 승인자를 지정하면 그 사람들). admin 은 항상 통과. 옵션(승인자·통보자·잔여 연차) 수정 = admin + 승인자 + 통보자. **마이그레이션 001**(`scripts/sql/vacation_db_001_options_mail.sql`, 2026-10-27, 테이블만 추가·멱등): `vacation_options`(키 `approval` = 휴가 승인자·승인 통보자 JSONB — 승인자를 지정하면 그 사람들 + admin 만 승인·반려) · `vacation_mail_log`(제출·승인·반려 메일 기록 — 보낸 사람·gmail|smtp·받는 사람·성공·오류). 미적용이면 옵션 없음·기록 없음으로 동작. ```bash docker exec -i postgres-db psql -U postgres -d vacation_db -v ON_ERROR_STOP=1 < scripts/sql/vacation_db_001_options_mail.sql ``` **마이그레이션 002**(`scripts/sql/vacation_db_002_hire_prior.sql`, 2026-10-27, 멱등): `vacation_employees`(사람마다 입사일 → 근로기준법 제60조 연차, `store.leave_status`) · `vacation_balances.prior_used`(시스템 전에 쓴 연차, 2026 줄) · `vacation_balances.total_days` NULL 허용(NULL = 입사일 기준 법정 연차). ```bash docker exec -i postgres-db psql -U postgres -d vacation_db -v ON_ERROR_STOP=1 < scripts/sql/vacation_db_002_hire_prior.sql ``` ### 운영 서버 초기화 (1회, 사용자 승인 후) ```bash read -s -p "vacation_app password: " APP_PWD; echo docker exec -i postgres-db psql -U postgres \ -v app_password="$APP_PWD" \ < scripts/sql/vacation_db_init.sql # main-app .env 에 추가: # VACATION_DB_URL=postgresql://vacation_app:@postgres-db:5432/vacation_db cd /opt/www/main && docker compose up -d --build ``` > 멱등 스크립트. 기존 DB 가 있으면 DROP 하지 않음. 공휴일은 연도별로 다르므로 settings 화면에서 추가/수정. --- ## outreach_db 스키마 / 초기화 (안내문 발송, 2026-10-27) DDL: `scripts/sql/outreach_db_init.sql` (멱등). DB·역할(`outreach_app`)·테이블·인덱스·트리거. **JSON 폴백 없음** — `OUTREACH_DB_URL` 미설정 시 "설정 필요" 안내. 생성·연결 명령은 `docs/DEPLOYMENT.md` "안내문 발송 DB 생성". | 테이블 | 용도 | | --- | --- | | `outreach_settings` | 키 `template` = 메일 제목·본문({이름})·보내는 이름·끝 문구·(광고) 표시(JSONB) | | `outreach_images` | 메일 본문 아래 사진(가로 700px JPEG 로 줄여 BYTEA, 순서) — 최대 10장 | | `outreach_recipients` | 리스트 — `kind` email·instagram(주소를 보고 판별), `handle`(이메일 소문자·인스타 계정명), 이름·메모, 상태 대기→발송중→보냄/실패, `UNIQUE(kind, handle)` | | `outreach_logs` | 보낸 기록(메일·DM, 성공·오류) — 줄을 지워도 남음, 본문·토큰은 안 남김 | ## malaysia_stock_db 스키마 / 초기화 DDL: `scripts/sql/malaysia_stock_db_init.sql` (멱등). DB·역할(`malaysia_app`)·테이블·인덱스·트리거·창고/아이템 seed 를 한 번에 생성. **JSON 폴백 없음** — `MALAYSIA_STOCK_DB_URL` 미설정 시 모듈이 "설정 필요" 안내만 표시. 상품명은 `itemcode_db` 읽기 전용 재사용. 테이블: | 테이블 | 용도 | | --- | --- | | `warehouses` | 창고(`warehouse_code` UNIQUE). seed: `MY-WH-01 / Malaysia Warehouse` | | `malaysia_items` | 관리 대상 코드 스코프 + 종류(`individual`/`set`) + 이름 스냅샷. prefix CHECK. seed: 낱개 12 + 세트 5 | | `set_bom` | 세트 구성표. `set_code`(MY-)·`component_code`(MT/MX/MZ) prefix CHECK, `UNIQUE(set_code, component_code)` | | `stock_movement` | 입고/출고/조정/조사 이력. `item_code` 낱개만(CHECK), `movement_type` IN/OUT/ADJUST/STOCKTAKE. `ref_type`·`ref_no`(Shopee/Lazada 연동용) | | `daily_stocktake` | 재고조사 헤더. `status` draft/finalized/cancelled. 같은 날짜+창고 finalized 1건(부분 유니크 인덱스) | | `daily_stocktake_line` | 조사 라인. `sku_code` 낱개+세트 허용(MD- 금지), `qty>=0`, `UNIQUE(stocktake_id, sku_code)` | 현재고 = `SUM(IN) - SUM(OUT) + SUM(ADJUST) + SUM(STOCKTAKE)`. 재고조사 확정 시 시스템 재고와 조사 최종치의 **차이만** STOCKTAKE movement 로 기록. 세트는 movement 불가, 재고조사/BOM 계산 전용. MD- 뚜껑은 전 영역 제외. ### 운영 서버 초기화 (1회, 사용자 승인 후) ```bash read -s -p "malaysia_app password: " APP_PWD; echo docker exec -i postgres-db psql -U postgres \ -v app_password="$APP_PWD" \ < scripts/sql/malaysia_stock_db_init.sql # main-app .env 에 추가: # MALAYSIA_STOCK_DB_URL=postgresql://malaysia_app:@postgres-db:5432/malaysia_stock_db cd /opt/www/main && docker compose up -d --build ``` > 멱등 스크립트. 기존 DB 가 있으면 DROP 하지 않음. itemcode_db 는 건드리지 않음. --- ## cafe24_db 스키마 / 초기화 DDL: `scripts/sql/cafe24_db_init.sql` (멱등). DB·역할(`cafe24_app`)·테이블·인덱스·트리거를 한 번에 생성. **JSON 폴백 없음** — `CAFE24_DB_URL` 미설정 시 모듈이 "설정 필요" 안내만 표시. 테이블: | 테이블 | 용도 | | --- | --- | | `cafe24_oauth_tokens` | 쇼핑몰별 OAuth 토큰(`mall_id` UNIQUE). access/refresh 는 **Fernet 암호문**으로 저장. 상품관리 + 향후 주문관리가 공유 | | `cafe24_products` | 상품 캐시(`product_no` UNIQUE). 목록/검색 속도용이며 source of truth 는 언제나 카페24. `last_write_snapshot`(JSONB, 마이그레이션 004) 에 카페24 PUT 응답을 섹션별(`product`/`options`/`variants`)로 남겨 **읽기 지연**(PUT 뒤 GET 이 한동안 예전 값을 돌려줌) 동안 화면 기준으로 쓴다 | | `cafe24_product_revisions` | 상세페이지 HTML 버전(append-only). `revision_type` SYNC/DRAFT/**BACKUP**/MANUAL/SCHEDULED/ROLLBACK | | `cafe24_product_schedules` | 예약 작업. `status` PENDING/PROCESSING/SUCCESS/FAILED/CANCELLED, 재시도·자동종료·복원 대상 포함 | | `cafe24_audit_logs` | 누가 무엇을 바꿨나. worker 수행분은 `actor='SCHEDULER'` | | `cafe24_api_logs` | 카페24 API 호출 기록. **토큰/Authorization/client_secret 미기록** | 핵심 규칙: - 카페24에 쓰기 직전 **반드시 현재 HTML 을 다시 조회해 `BACKUP` revision 으로 저장**한다. 로컬 DB 의 마지막 값을 현재값으로 가정하지 않는다. - 예약의 `restore_revision_id` 는 **예약 실행 순간** 만든 BACKUP 을 가리킨다(예약 생성 시점 값이 아님). - 일괄 예약은 상품 1건당 1행 + 공통 `parent_job_id` — 한 상품 실패가 나머지를 막지 않는다. - 토큰 암호화 키는 `.env` 의 `CAFE24_TOKEN_SECRET`. **값을 바꾸면 기존 토큰을 복호화할 수 없어 카페24 재연결이 필요하다.** - 기존 운영 DB 에는 마이그레이션 002·003·004 를 순서대로 적용한다(전부 멱등): `docker exec -i postgres-db psql -U postgres -d cafe24_db < scripts/sql/cafe24_db_004_write_snapshot.sql` ### 운영 서버 초기화 (1회, 사용자 승인 후) ```bash read -s -p "cafe24_app password: " APP_PWD; echo docker exec -i postgres-db psql -U postgres \ -v app_password="$APP_PWD" \ < scripts/sql/cafe24_db_init.sql # main-app .env 에 추가: # CAFE24_DB_URL=postgresql://cafe24_app:@postgres-db:5432/cafe24_db # CAFE24_MALL_ID / CAFE24_CLIENT_ID / CAFE24_CLIENT_SECRET / CAFE24_REDIRECT_URI # CAFE24_TOKEN_SECRET=$(openssl rand -hex 32) cd /opt/www/main && docker compose up -d --build web ``` > 멱등 스크립트. 기존 DB 가 있으면 DROP 하지 않음. 상세는 `docs/CAFE24_MODULE.md`. --- ## performance_db 스키마 / 초기화 DDL: `scripts/sql/performance_db_init.sql` (멱등). DB·역할(`performance_app`)·테이블·인덱스·트리거·쇼핑몰 10곳 seed 를 한 번에 생성. **JSON 폴백 없음** — `PERFORMANCE_DB_URL` 미설정 시 모듈이 "설정 필요" 안내만 표시. 상세는 `docs/PERFORMANCE_MODULE.md`. | 테이블 | 용도 | | --- | --- | | `perf_marketplaces` | 쇼핑몰 코드·이름·사용 여부·매출 집계 여부·순서 | | `perf_commission_rates` | 수수료율 이력(`rate_percent NUMERIC(7,3)`, `effective_from`). 그날 유효한 요율로 과거 실적 계산 | | `perf_credentials` | API 인증정보. (쇼핑몰, 항목) 한 행 = **AES-256-GCM 암호문** + `key_version`. 토큰도 여기 | | `perf_connection_status` | 연결 상태·마지막 테스트/동기화·최근 오류(비밀값 가린 문구) | | `perf_sales_events` | 매출 사건(결제 +, 취소·반품 −, BIGINT 원). `UNIQUE(marketplace_code, event_type, external_event_id)`. `is_sample`=테스트 데이터 | | `perf_sync_runs` | 동기화 기록. `status='running'` 부분 유니크 인덱스로 같은 쇼핑몰 동시 실행 차단 | 핵심 규칙: - 인증정보는 **암호문만** 저장. 마스터 키 `APP_ENCRYPTION_KEY` 는 DB 가 아닌 `.env` 에만 있다 — DB 백업만으로는 복호화할 수 없고, **키를 잃으면 인증정보를 다시 입력해야 한다**(키는 별도 안전 보관). - 테스트 데이터 삭제는 `is_sample = TRUE` 조건 삭제만 한다(설정 화면 버튼). ### 운영 서버 초기화 (1회, 사용자 승인 후) ```bash read -s -p "performance_app password: " APP_PWD; echo docker exec -i postgres-db psql -U postgres \ -v app_password="$APP_PWD" \ < scripts/sql/performance_db_init.sql # main-app .env 에 추가: # PERFORMANCE_DB_URL=postgresql://performance_app:@postgres-db:5432/performance_db # APP_ENCRYPTION_KEY=$(openssl rand -hex 32) # 별도 안전한 곳에도 백업 # APP_ENCRYPTION_KEY_VERSION=1 cd /opt/www/main && docker compose up -d --build ``` > 멱등 스크립트. 기존 DB 가 있으면 DROP 하지 않음. --- ## 백업 / 복구 (안전 절차) ### 백업 ```bash # 단일 DB 덤프 (운영 권장) docker exec -t \ pg_dump -U -F c -d orderlist_db \ > /var/backups/postgres/orderlist_db_$(date +%F).dump ``` ### 복구 (덮어쓰기 위험 → 사용자 승인 필수) ```bash # 1) 신규 DB로 먼저 복구해 검증 docker exec -i \ pg_restore -U -d < backup.dump # 2) 검증 완료 후 운영 DB 교체 (필요 시) ``` > `pg_restore --clean`은 기존 객체를 삭제한다. **운영 대상 DB에서 절대 무단 실행 금지**. --- ## .env 관련 - DB 접속 정보(`*_HOST`, `*_PORT`, `*_USER`, `*_PASSWORD`, `*_NAME`)는 모두 `.env`로 관리한다. - `.env`는 **Git에 올리지 않는다**. `.env.example`만 커밋한다. - 비밀값 유출이 의심되면 즉시 회전(비밀번호/키 변경)을 진행한다.