Move CORM settings and histories to dedicated PostgreSQL database

This commit is contained in:
2026-10-22 17:48:50 +09:00
parent 92986eb1cc
commit 399e91518c
20 changed files with 2058 additions and 84 deletions
+100
View File
@@ -0,0 +1,100 @@
# 문자내역·수동발주내역을 corm_db로 이전
설정은 `corm_settings`, 문자내역은 `corm_sms_history`, 수동발주내역은 `corm_manual_history`에 저장한다.
서버와 계정은 기존 `POSTGRES_*`, DB 이름은 `SETTINGS_DB=corm_db`를 공통 사용한다.
기존 `itemcode_db`의 코드표와 CS 기록은 그대로 유지한다.
## 동작
- `HISTORY_BACKEND=postgres`이면 두 내역의 조회·저장과 문자내역 삭제는 DB만 사용한다. 기존 `.dat`와 내역 시트에는 추가로 쓰지 않는다.
- 문자 내역의 고객 정보·상품 목록·할인/배송 옵션·문자 전문을 JSONB에 보존한다. 기록마다 고유 ID를 부여해 목록 순서가 바뀌어도 같은 내역을 선택·삭제한다.
- 수동발주내역은 기존처럼 한국 시간의 오늘 내역을 표시한다. DB에는 과거 내역도 모두 보관하며 날짜가 바뀌어도 삭제하지 않는다.
- 실제 발주 입력/엑셀 다운로드에 사용하는 별도 **수동 발주** 시트는 계속 사용한다.
- 기존 수동발주 삭제는 발주 시트의 주문 행도 지우는 기능이다. DB 모드에서도 해당 주문 행 삭제를 확인한 뒤 내역을 삭제한다. 구글 장애 시 DB 내역을 보존하고 오류를 표시한다.
- 같은 일시의 내역이 여러 건이면 주문을 잘못 취소하지 않도록 자동 삭제를 중단한다. 발주 시트에서 대상 주문을 먼저 확인해야 한다.
- 구글 발주 시트 삭제와 DB 삭제는 서로 다른 서비스라 하나의 트랜잭션으로 묶이지 않는다. 시트 삭제 후 DB 오류가 발생하면 시트의 주문 상태를 확인하고 재시도한다. 없는 시트 행은 재삭제하지 않는다.
- DB 장애를 저장 성공으로 표시하거나 예전 시트/파일로 자동 우회하지 않는다.
## 원본 준비
구글 시트에는 상품·문자 텍스트 위주로 저장되고, `.dat` 파일에 상세 상품 목록과 옵션이 더 남아 있을 수 있다.
따라서 **실제 운영 중인 컨테이너의 로컬 내역 파일도 함께 가져와야 한다.** 새 일회용 컨테이너에는 이 파일이 자동 복사되지 않는다.
아래는 Linux 서버 프로젝트 폴더에서 실행하는 명령이다. 먼저 [설정 DB 이전 문서](settings-postgres.md)에 따라
`corm_db`를 준비하고 새 코드를 빌드한다. `.env`에는 `SETTINGS_DB=corm_db`를 지정하고, 내역 모드는 아직 `HISTORY_BACKEND=google`로 유지한다.
1. 직원 및 다른 구버전 앱의 문자 생성·발주·내역 저장·삭제와 시트 직접 편집을 잠시 중단하고, 앱을 정지한다.
```bash
mkdir -p .settings-backups
docker compose stop corm-app
```
2. 기존 컨테이너에서 원본 파일을 호스트로 복사한다. 아래는 기본 경로 예시다.
`SMS_HISTORY_FILE`·`MANUAL_HISTORY_FILE`을 따로 지정했다면 해당 경로를 사용한다.
정지된 컨테이너에서도 `docker cp`가 가능하다. 파일이 없다는 오류가 나면 실제 운영 경로부터 확인한다.
```bash
docker cp dbx-corm:/app/sms_history.dat .settings-backups/legacy-sms.dat
docker cp dbx-corm:/app/manual_history.dat .settings-backups/legacy-manual.dat
```
원래 해당 로컬 파일이 존재하지 않았다면 그 파일의 복사와 다음 명령의 해당 `--*-local-file` 인자를 생략한다.
파일이 없으면 시트에 남은 정보만 이전할 수 있다. 브라우저에만 남아 있는 고객 캐시는 자동 이전하지 않는다.
3. 구글의 **문자내역·수동발주내역 전체**와 로컬 파일을 읽어 원본 백업을 생성한다. DB에는 접속하지 않는다.
```bash
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python history_migrate.py snapshot --sms-local-file /backups/legacy-sms.dat --manual-local-file /backups/legacy-manual.dat --output /backups/history-source.json
```
출력된 두 내역 건수와 로컬 파일 유무를 확인한다. 개인 정보나 문자 내용은 콘솔에 출력하지 않는다.
같은 일시의 시트·로컬 기록은 다른 필드도 비교해 한 건씩 병합하고, 매칭되지 않은 기록과 로컬에만 저장된 기록도 보존한다.
같은 일시라는 이유만으로 여러 기록을 한 건으로 합치지 않는다. 형식이 깨진 로컬 JSON은 조용히 누락시키지 않고 이전을 중단한다.
백업에는 원본 전체 행·셀과 로컬 기록도 포함된다. 백업 경로는 덮어쓰지 않으므로 재실행 시 새 파일명을 사용한다.
4. 백업에서 DB로 이전하고 원본과 전체 내역을 검증한다.
```bash
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python history_migrate.py import --input-file /backups/history-source.json --apply --backup /backups/before-history-db.json
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python history_migrate.py verify --input-file /backups/history-source.json
```
두 테이블의 생성·저장·전체 검증은 하나의 DB 트랜잭션으로 처리한다. 이미 내역이 있으면 덮어쓰거나 중복으로 추가하지 않는다.
빈 원본도 이전 완료 상태로 기록한다. 이전 완료 후 내역을 지웠더라도 재가져오기로 삭제한 내역이 되살아나지 않는다.
5. `.env`를 변경하고 앱을 기동한다. 설정도 함께 전환했다면 다음 세 값을 사용한다.
```dotenv
SETTINGS_DB=corm_db
SETTINGS_BACKEND=postgres
HISTORY_BACKEND=postgres
```
```bash
docker compose up -d --no-deps corm-app
docker compose logs --tail=100 corm-app
```
두 내역 테이블과 이전 완료 표시가 없으면 기동이 실패한다. 기존 브라우저 탭은 새로고침해 새 ID 기반 동작을 사용한다.
직원 계정으로 과거 문자 불러오기, 고객 정보·문자 옵션 복원, 새 문자내역 저장 및 오늘의 수동발주 내역 표시를 확인한다.
실제 주문 취소를 수반하는 수동발주 삭제 검증에는 테스트 주문을 사용한다.
운영 DB에는 자동 테스트를 실행하지 않는다.
설정을 이미 DB로 이전했다면 설정 이전을 반복할 필요는 없다. 이번에는 위 내역 이전과 `HISTORY_BACKEND` 전환만 진행한다.
## 백업과 복귀
정기 백업은 `corm_db` 전체를 포함한다. 내역을 JSON으로 별도 보관하려면 다음을 실행한다.
```bash
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python history_migrate.py export --output /backups/current-histories.json
```
항상 새 파일명을 사용하고 고객 정보가 포함된 백업의 접근 권한을 제한한다. `.settings-backups/`는 Git과 이미지 빌드에서 제외된다.
이 JSON도 `import --input-file`로 **아직 내역이 없는 DB**에 복구할 수 있다. 기존 DB 덮어쓰기는 지원하지 않는다.
전환 직후 복귀가 필요하면 `HISTORY_BACKEND=google`로 바꾸고 컨테이너를 재생성한다.
DB 전환 후의 추가·삭제는 기존 시트/파일에 복제되지 않으므로 복귀 전 DB 내역을 내보내 보관한다.
이전 때 복사한 `.dat`는 백업이며, Google 모드에서 로컬 상세 복원을 계속 사용하려면 원래 경로에 마운트하거나 복원해야 한다.
DB 전환 후 변경이 있었다면 양쪽 자료의 차이를 검토해 복구해야 한다.
+131
View File
@@ -0,0 +1,131 @@
# 구글 시트 설정을 PostgreSQL로 이전
## 이전 범위와 저장 구조
- 대상: `CS 통합 프로그램 설정` 스프레드시트의 **설정** 탭 전체.
- 상품 그룹·상품 코드/이름/가격·정렬·구분선·소그룹 이름·사은품 규칙·문자 문구·배송비·폰트·송장 접두어를 보존한다.
- 같은 PostgreSQL 서버의 별도 DB `corm_db` 안에 `corm_settings` 테이블로 저장한다. DB 이름은 `SETTINGS_DB`로 지정하며 기본값은 `corm_db`이다. 기존 `ITEMCODE_DB`와 코드표/CS 기록 테이블은 수정하지 않는다.
- 설정 전체를 JSONB 배열로 저장하므로 행과 셀 순서를 보존한다. DB 버전을 함께 비교해 동시 저장의 조용한 덮어쓰기를 차단한다.
- DB 모드는 요청마다 작은 설정 문서 1건을 읽는다. 프로세스별 캐시 차이 없이 최신 커밋 값을 사용하며, 구글 요청/구글 작업 풀/구글 설정 캐시는 사용하지 않는다.
- DB 장애 시에는 503을 반환한다. 구글의 오래된 설정으로 자동 전환하지 않는다.
- DB 접속 정보와 API 비밀키는 계속 `.env`/환경변수에 둔다. `.env`를 DB로 복사하는 처리는 없다.
- 이 도구는 `설정` 탭을 이전한다. `문자내역`, `수동발주내역`은 [내역 DB 이전 절차](history-postgres.md)에 따라 같은 `corm_db`로 별도 이전한다. `아이템코드` 탭은 사용하지 않는다.
- 실제 수동발주 시트와 밀크런 등 다른 구글 연동에는 계속 구글 인증이 필요하다.
구글 시트의 탭과 DB 테이블을 반드시 1:1로 맞출 필요는 없다. 현재 업무 설정은 **설정** 탭 안에서
`APP_SETTINGS`, `GROUP_NAMES`, `ORDER_*`, `SMS_GIFT_RULES` 등의 분류로 구분되어 있다.
이 분류와 상품 순서를 그대로 저장하므로 하나의 `corm_settings` 테이블을 사용해도 설정이 서로 섞이지 않는다.
`문자내역`과 `수동발주내역`은 설정이 아닌 이력 데이터이므로 같은 DB 안의 `corm_sms_history`, `corm_manual_history` 테이블로 구분한다.
## 운영 서버 전환 순서
아래 명령은 Linux 운영 서버의 프로젝트 폴더(`/opt/dbx-corm`)에서 실행한다.
이 문서의 명령을 실행하기 전까지 현재 동작은 바뀌지 않는다. 기본값은 `SETTINGS_BACKEND=google`이다.
기존 `.env`를 예제 파일로 덮어쓰지 말고 필요한 항목만 추가한다.
먼저 PostgreSQL 관리 계정으로 **같은 서버에** `corm_db`를 생성한다. 기존 DB는 이동하거나 변경하지 않는다.
아래는 앱 DB 계정이 `king`일 때의 SQL 예시다. 실제 `POSTGRES_USER`가 다르면 소유자를 맞춘다.
이미 DB가 있다면 생성 명령을 다시 실행하지 말고 소유자와 접근 권한을 확인한다.
```sql
CREATE DATABASE corm_db OWNER king;
```
앱 계정에 DB 생성 권한을 추가할 필요는 없다. 관리자가 DB를 생성하고 앱 계정에는 해당 DB 접근 및 테이블 생성/읽기/쓰기 권한을 부여한다.
앱과 이전 도구는 DB를 자동 생성하지 않는다.
이전 명령을 실행하기 **전에** 서버 `.env`에 아래 값을 추가한다. 이 단계에서는 저장소 모드는 `google`로 유지한다.
```dotenv
ITEMCODE_DB=itemcode_db
SETTINGS_DB=corm_db
SETTINGS_BACKEND=google
```
1. 코드를 서버에 반영하고 새 이미지를 빌드한다. 기존 앱은 아직 구글 모드로 실행된다.
```bash
docker compose build corm-app
```
2. 원본 읽기 및 형식 점검을 실행한다. 이 명령은 DB에 접속하거나 데이터를 쓰지 않는다.
```bash
docker compose run --rm --no-deps corm-app python settings_migrate.py import
```
3. 직원에게 설정 편집을 잠시 멈추도록 알리고, 직접 시트 편집과 다른 구버전 앱의 설정 저장도 중단한다.
이전 완료 후 DB 모드로 기동할 때까지 이 상태를 유지한다.
현재 앱을 정지하고 원본 JSON을 서버 호스트에 백업한 뒤 DB에 저장한다.
```bash
mkdir -p .settings-backups
docker compose stop corm-app
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python settings_migrate.py import --apply --backup /backups/before-postgres.json
docker compose run --rm --no-deps corm-app python settings_migrate.py verify
```
`verify`가 **원본과 DB 전체 행·셀·순서 일치**를 출력해야 한다.
`--apply`는 백업을 먼저 생성하고, 테이블 생성·최초 저장·전체 데이터 검증을 하나의 DB 트랜잭션으로 처리한다.
이미 DB 설정이 있거나 백업 경로가 존재하면 덮어쓰지 않고 중단한다.
실패하면 원인을 확인한다. DB가 비어 있는 경우에는 새 백업 경로로 다시 실행할 수 있다.
4. 이전·검증 완료 후 운영 서버 `.env`의 저장소 모드를 변경한다. DB 계정은 `corm_db`에 테이블을 생성하고 읽고 쓸 수 있어야 한다.
```dotenv
SETTINGS_DB=corm_db
SETTINGS_BACKEND=postgres
```
기존 `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `ITEMCODE_DB`와
`NAVER_*`, `CAFE24_*`, 구글 인증 설정은 그대로 유지한다.
5. 앱을 기동하고 상태 및 실제 사용자 화면을 확인한다.
```bash
docker compose up -d --no-deps corm-app
docker compose ps
docker compose logs --tail=100 corm-app
```
초기화되지 않은 DB에서는 시작이 실패한다. 먼저 이전이 완료되었는지 확인한다.
권한이 있는 직원으로 로그인해 상품 순서·가격·배송비·문자 문구를 확인하고,
설정 저장 후 새로고침으로 반영 여부를 확인한다. 저장 충돌이나 DB 장애 안내가 보이면 저장을 재시도하기 전에 새로고침한다.
브라우저 개발자 도구의 `/api/config` 응답 헤더 `X-Settings-Backend: postgres`로 저장소를 확인할 수 있다.
`/health/db` 확인만으로 사용자 설정 조회·저장 검증을 대신하지 않는다.
이후 설정은 프로그램 화면에서 수정한다. 구글 시트 설정 탭의 변경은 DB에 자동 반영되지 않는다.
## 백업과 복구
정기 PostgreSQL 백업에 **`corm_db`**와 그 안의 `corm_settings` 테이블을 포함한다.
기존 `itemcode_db`만 백업하면 CORM 설정은 보관되지 않는다. 최신 설정을 JSON으로 내보낼 수도 있다.
```bash
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python settings_migrate.py export --output /backups/current-settings.json
```
이 명령도 기존 파일은 덮어쓰지 않는다. 매번 새 파일명을 사용한다.
백업에는 업무 설정과 문자 문구가 있으므로 접근을 제한한다. `.settings-backups/`는 Git과 Docker 빌드에서 제외되어 있다.
파일을 호스트에 보관하려면 위와 같이 반드시 백업 디렉터리를 마운트한다.
빈 DB에 JSON 백업을 복구할 때는 다음 명령을 사용한다. 기존 DB 설정은 덮어쓰지 않는다.
```bash
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python settings_migrate.py import --input-file /backups/current-settings.json --apply --backup /backups/before-restore.json
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python settings_migrate.py verify --input-file /backups/current-settings.json
```
전환 직후 문제가 생기면 `.env`를 `SETTINGS_BACKEND=google`로 되돌리고 컨테이너를 재생성할 수 있다.
구글 시트 원본은 그대로 남아 있다. **DB 전환 후 새로 저장한 내용은 구글에 복제되지 않으므로**,
변경이 있었다면 우선 위 `export`로 최신 DB 설정을 보관한다. 단순 모드 복귀 시에는 구글에 남은 이전 값이 표시된다.
구글 모드에서 다시 수정한 내용을 기존 DB로 재이전하려면 별도로 차이를 검토해야 한다. 자동 덮어쓰기는 지원하지 않는다.
## 로컬 검증
```bash
python -m unittest discover -s tests -v
```
외부 연결 없이 설정 API·순서 보존·구글 작업 풀 분리·오류·충돌·백업/이전 절차를 검증한다.
실제 PostgreSQL 검증은 운영 DB가 아닌 폐기 가능한 테스트 DB의 DSN을 `SETTINGS_TEST_DSN`에 지정한 뒤 같은 명령을 실행한다.
통합 테스트는 매번 별도의 임시 스키마를 만들고 그 스키마만 제거한다. 테스트 계정에는 스키마 생성 권한이 필요하다.