Files
dbx-corm/docs/settings-postgres.md
T

132 lines
8.4 KiB
Markdown

# 구글 시트 설정을 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`에 지정한 뒤 같은 명령을 실행한다.
통합 테스트는 매번 별도의 임시 스키마를 만들고 그 스키마만 제거한다. 테스트 계정에는 스키마 생성 권한이 필요하다.