Move CORM settings and histories to dedicated PostgreSQL database
This commit is contained in:
@@ -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 전환 후 변경이 있었다면 양쪽 자료의 차이를 검토해 복구해야 한다.
|
||||
@@ -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`에 지정한 뒤 같은 명령을 실행한다.
|
||||
통합 테스트는 매번 별도의 임시 스키마를 만들고 그 스키마만 제거한다. 테스트 계정에는 스키마 생성 권한이 필요하다.
|
||||
Reference in New Issue
Block a user