ecc76ae4d8
- Fee = 시간 x RM25, 커미션 = 판매금액 x 10% (저장 안 함, 이미지에서 매출을 읽으면 다시 계산) - 광고비·호스트 비용(수기) = 방송마다 저장 (마이그레이션 live_db_006_broadcast_fees.sql) - 달력 날짜 광고비 = 그날 방송 광고비 합, 호스트 비용 = host_fee 합 (날짜별 광고비 입력 버튼·/live/ad-spend 없앰) - 방송 장소는 창·표에서 뺌 (예전 값은 DB 에 그대로) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
464 lines
25 KiB
Markdown
464 lines
25 KiB
Markdown
# 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 <postgres_volume>` | 운영 데이터 영구 손실 |
|
|
| `docker compose down -v` | 볼륨까지 제거. 운영에서 금지 |
|
|
|
|
실행 전 반드시:
|
|
|
|
1. 백업 확인 (`pg_dump`, 컨테이너 외부 마운트)
|
|
2. 영향 범위 설명
|
|
3. 사용자 명시 승인
|
|
|
|
---
|
|
|
|
## 자주 쓰는 점검 명령
|
|
|
|
```bash
|
|
# 컨테이너/네트워크
|
|
docker ps
|
|
docker network ls
|
|
docker inspect <postgres_container_name>
|
|
|
|
# DB 목록 / 접속
|
|
sudo -u postgres psql -l
|
|
docker exec -it <postgres_container_name> psql -U postgres -l
|
|
|
|
# 특정 DB 접속
|
|
docker exec -it <postgres_container_name> psql -U <user> -d itemcode_db
|
|
|
|
# 테이블/권한 확인
|
|
\dt
|
|
\dn+
|
|
\du
|
|
\z <table_name>
|
|
```
|
|
|
|
---
|
|
|
|
## 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:<APP_PWD>@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:<APP_PWD>@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
|
|
# 003(2026-11-02, 멱등) — vacation_consults(협의자 결재: 협의 내용·상태), vacation_mail_log.event 에 consult_request·consulted 추가. 미적용이면 협의자 칸 잠김.
|
|
docker exec -i postgres-db psql -U postgres -d vacation_db -v ON_ERROR_STOP=1 < scripts/sql/vacation_db_003_consults.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:<APP_PWD>@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, 성공·오류) — 줄을 지워도 남음, 본문·토큰은 안 남김 |
|
|
| `outreach_dm_bodies` | DM 수동 보내기 탭의 저장한 본문({이름} 이 든 글, 최대 1000자, 제목 = 첫 줄) — 마이그레이션 `outreach_db_002_dm_bodies.sql`(2026-10-30) |
|
|
|
|
## live_db 스키마 / 초기화 (라이브 커머스, 2026-11-04)
|
|
|
|
DDL: `scripts/sql/live_db_init.sql` (멱등). DB·역할(`live_app`)·테이블·인덱스·트리거. **JSON 폴백 없음** — `LIVE_DB_URL` 미설정 시 "설정 필요" 안내.
|
|
생성·연결 명령은 `docs/DEPLOYMENT.md` "라이브 커머스 DB 생성". 호스트 계좌·주소 등 개인정보 포함(평문 저장, 화면은 ERP 관리자만).
|
|
|
|
| 테이블 | 용도 |
|
|
| --- | --- |
|
|
| `live_hosts` | 호스트 — `platform`(쇼핑몰 `tiktok`·`shopee`, `''` = 예전 호스트, 마이그레이션 `live_db_005_host_platform.sql`)·`display_name`(간단한 이름, 마이그레이션 `live_db_004_host_display_name.sql`)·Full Name (as per IC)·Phone Number·Email·Address·Bank Name·Bank Account Number, `is_active`. `tiktok_handle` 열은 값만 남아 있고 쓰지 않음(003) |
|
|
| `live_broadcasts` | 방송 스케줄 — `host_id`(FK RESTRICT)·`broadcast_date`·`start_time`·`end_time`(말레이시아 시간 그대로)·`venue`(2026-11-06 부터 입력 안 받음, 예전 값만)·`tiktok_handle`(그 방송의 계정, @ 없이, 마이그레이션 `live_db_003_broadcast_account.sql`)·`sales_amount`(RM, NULL = 미입력)·`ad_spend`(방송별 광고비)·`host_fee`(호스트 비용, 수기 입력) — 둘 다 RM·NULL = 미입력, 마이그레이션 `live_db_006_broadcast_fees.sql` |
|
|
| `live_broadcast_images` | 방송 결과 이미지(메타데이터 제거 후 BYTEA, 방송을 지우면 CASCADE) — 방송당 최대 10장(앱에서 확인) |
|
|
| `live_daily_ad_spend` | 날짜별 광고비(RM) — 마이그레이션 `live_db_002_ad_spend.sql`(init 에도 포함). **006 부터 안 씀**(달력 AD SPEND = 그날 방송 `ad_spend` 합), 값만 남김 |
|
|
|
|
## 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:<APP_PWD>@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:<APP_PWD>@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'` 부분 유니크 인덱스로 같은 쇼핑몰 동시 실행 차단 |
|
|
| `perf_settings` | (마이그레이션 011) 설정 값 — 키 하나 = JSONB. `auto_sync` = 매출·광고비 자동 업데이트 일정(간격·요일·시작/끝) |
|
|
|
|
핵심 규칙:
|
|
|
|
- 인증정보는 **암호문만** 저장. 마스터 키 `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:<APP_PWD>@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 <postgres_container_name> \
|
|
pg_dump -U <user> -F c -d orderlist_db \
|
|
> /var/backups/postgres/orderlist_db_$(date +%F).dump
|
|
```
|
|
|
|
### 복구 (덮어쓰기 위험 → 사용자 승인 필수)
|
|
|
|
```bash
|
|
# 1) 신규 DB로 먼저 복구해 검증
|
|
docker exec -i <postgres_container_name> \
|
|
pg_restore -U <user> -d <new_db_name> < backup.dump
|
|
|
|
# 2) 검증 완료 후 운영 DB 교체 (필요 시)
|
|
```
|
|
|
|
> `pg_restore --clean`은 기존 객체를 삭제한다. **운영 대상 DB에서 절대 무단 실행 금지**.
|
|
|
|
---
|
|
|
|
## .env 관련
|
|
|
|
- DB 접속 정보(`*_HOST`, `*_PORT`, `*_USER`, `*_PASSWORD`, `*_NAME`)는 모두 `.env`로 관리한다.
|
|
- `.env`는 **Git에 올리지 않는다**. `.env.example`만 커밋한다.
|
|
- 비밀값 유출이 의심되면 즉시 회전(비밀번호/키 변경)을 진행한다.
|