From c45626d0db229b7ffe5d233e7a41391eaabe8674 Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@gmail.com>
Date: Wed, 10 Sep 2025 21:14:02 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20PostgreSQL=20=ED=85=8C=EC=9D=B4?=
 =?UTF-8?q?=EB=B8=94=20=EB=B3=80=EA=B2=BD=20=EA=B3=84=ED=9A=8D=20=EB=AC=B8?=
 =?UTF-8?q?=EC=84=9C=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 12개 테이블 전체 사용 위치 조사
- 파일별 정확한 라인 번호 기록
- 수정 작업 체크리스트 작성
- 위험 요소 및 롤백 계획 포함
---
 ...ll80_PostgreSQL_테이블_변경_계획.md | 225 ++++++++++++++++++
 1 file changed, 225 insertions(+)
 create mode 100644 300_architecture/plans/250910_happybell80_PostgreSQL_테이블_변경_계획.md

diff --git a/300_architecture/plans/250910_happybell80_PostgreSQL_테이블_변경_계획.md b/300_architecture/plans/250910_happybell80_PostgreSQL_테이블_변경_계획.md
new file mode 100644
index 0000000..e58521d
--- /dev/null
+++ b/300_architecture/plans/250910_happybell80_PostgreSQL_테이블_변경_계획.md
@@ -0,0 +1,225 @@
+# PostgreSQL 데이터베이스 테이블 변경 계획
+
+## 작성 정보
+- **작성일**: 2025-09-10
+- **작성자**: happybell80
+- **목적**: PostgreSQL 테이블 구조 대대적 변경에 따른 영향 범위 파악 및 수정 계획
+
+## 1. 데이터베이스 연결 정보
+
+### 메인 데이터베이스
+- **main_db**: `postgresql://robeings:robeings@192.168.219.45:5432/main_db`
+- **robeing_metrics**: `postgresql://postgres:@172.17.0.1:5432/robeing_metrics`
+- **개별 로빙 DB**: `postgresql://postgres:postgres@localhost/{ROBEING_ID}_db`
+
+### 사용 라이브러리
+| 저장소 | 라이브러리 |
+|--------|------------|
+| auth-server | SQLAlchemy, asyncpg, psycopg2 |
+| rb8001 | SQLAlchemy |
+| rb10508_micro | asyncpg |
+| frontend-base | asyncpg |
+| robeing-gateway | SQLAlchemy, asyncpg |
+| robeing-monitor | SQLAlchemy, asyncpg |
+| skill-email | psycopg2 |
+
+## 2. 테이블별 사용 위치 상세
+
+### 2.1 users 테이블
+**컬럼**: id(UUID), username, email, name, avatar_url, oauth_provider, oauth_id, is_active, created_at, updated_at, last_login_at
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| auth-server/app/models/user.py | 21-35 | 테이블 모델 정의 |
+| auth-server/app/providers/gmail_passport.py | 178 | SELECT id FROM users WHERE username = $1 |
+| auth-server/app/providers/gmail_passport.py | 187 | SELECT username FROM users WHERE id = $1 |
+| robeing-gateway/app/database.py | 98-112 | JOIN 쿼리 (workspace_members, workspaces와 함께) |
+| robeing-gateway/app/database.py | 182-191 | SELECT * FROM users WHERE username = $1 |
+| robeing-gateway/app/database.py | 321-328 | SELECT * FROM users (전체 조회) |
+| robeing-gateway/app/models.py | 11-24 | 테이블 모델 정의 |
+
+### 2.2 workspaces 테이블
+**컬럼**: id(UUID), name, subdomain, robeing_id, robeing_port, robeing_url, max_members, workspace_type, status, created_at, updated_at
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| auth-server/app/models/workspace.py | 15-31 | 테이블 모델 정의 |
+| auth-server/scripts/run_migration.py | 54 | SELECT id, name, subdomain, robeing_id FROM workspaces |
+| auth-server/migrations/add_user_workspace_tables.sql | 25-28 | ALTER TABLE companies RENAME TO workspaces |
+| robeing-gateway/app/database.py | 98-112 | JOIN 쿼리 |
+| robeing-gateway/app/database.py | 216-230 | JOIN 쿼리 (workspace_members와 함께) |
+| robeing-gateway/app/models.py | 26-44 | 테이블 모델 정의 |
+
+### 2.3 workspace_members 테이블
+**컬럼**: id(UUID), workspace_id(FK), user_id(FK), role, robeing_id, robeing_url, is_active, joined_at, updated_at
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| auth-server/app/models/user.py | 46-60 | 테이블 모델 정의 |
+| auth-server/migrations/add_user_workspace_tables.sql | 41-52 | CREATE TABLE 정의 |
+| robeing-gateway/app/database.py | 98-112 | JOIN 쿼리 |
+| robeing-gateway/app/database.py | 263-266 | 중복 체크 쿼리 |
+| robeing-gateway/app/database.py | 274-282 | UPDATE 쿼리 |
+| robeing-gateway/app/database.py | 285-299 | INSERT 쿼리 (gen_random_uuid() 사용) |
+| robeing-gateway/app/models.py | 46-60 | 테이블 모델 정의 |
+
+### 2.4 slack_user_mapping 테이블
+**컬럼**: slack_user_id, user_id
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| auth-server/app/providers/slack.py | 266 | SELECT user_id FROM slack_user_mapping WHERE slack_user_id = :slack_user_id |
+| auth-server/app/providers/slack.py | 308-312 | INSERT INTO slack_user_mapping ... DO UPDATE SET |
+| rb8001/app/router/router.py | 92 | SELECT user_id FROM slack_user_mapping WHERE slack_user_id = :slack_id |
+| robeing-gateway/app/main.py | 479-486 | SELECT user_id FROM slack_user_mapping WHERE slack_user_id = $1 |
+
+### 2.5 slack_workspaces 테이블
+**컬럼**: id(UUID), company_id(UUID), team_id, team_name, bot_token, bot_user_id, app_id, scopes(JSON), is_enterprise_install, is_active, installed_at, updated_at
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| auth-server/app/models/workspace.py | 43-62 | 테이블 모델 정의 |
+| auth-server/migrations/add_user_workspace_tables.sql | 60-76 | ALTER TABLE 정의 |
+| robeing-gateway/app/main.py | 522-525 | SELECT bot_token FROM slack_workspaces WHERE team_id = $1 |
+| robeing-gateway/app/main.py | 567-570 | SELECT bot_token FROM slack_workspaces WHERE team_id = $1 |
+
+### 2.6 gmail_tokens 테이블
+**컬럼**: id, user_id, slack_user_id, robeing_id, access_token, refresh_token, oauth_config, scopes, expiry, is_equipped, equipped_to, created_at, updated_at
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| auth-server/app/providers/gmail_passport.py | 193-198 | INSERT INTO gmail_tokens ... DO UPDATE SET |
+| auth-server/app/providers/gmail_passport.py | 354 | SELECT token_data FROM gmail_tokens WHERE user_id = $1 |
+| auth-server/app/providers/gmail_passport.py | 370 | DELETE FROM gmail_tokens WHERE user_id = $1 |
+| skill-email/services/db_credentials_provider.py | 60-70 | SELECT 쿼리 (is_equipped 필터) |
+| skill-email/services/db_credentials_provider.py | 163-177 | UPDATE 쿼리 |
+| skill-email/services/db_credentials_provider.py | 231-235 | COUNT 쿼리 |
+| robeing-monitor/app/api/items.py | 97-111 | SELECT 쿼리 |
+| robeing-monitor/app/api/items.py | 185-190 | 소유권 확인 쿼리 |
+| robeing-monitor/app/api/items.py | 197-211 | UPDATE 쿼리 (장착/해제) |
+| robeing-monitor/app/api/items.py | 252-256 | UPDATE 쿼리 (해제) |
+| robeing-monitor/app/api/items.py | 307-319 | SELECT 쿼리 (장착된 토큰) |
+| robeing-monitor/app/api/items.py | 384-388 | DELETE 쿼리 |
+
+### 2.7 gmail_audit_logs 테이블
+**컬럼**: user_id, robeing_id, action, success, details
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| robeing-monitor/app/api/items.py | 214-223 | INSERT 쿼리 |
+| robeing-monitor/app/api/items.py | 263-270 | INSERT 쿼리 |
+| robeing-monitor/app/api/items.py | 395-401 | INSERT 쿼리 |
+
+### 2.8 robeing_stats 테이블
+**컬럼**: id, robeing_id, memory, compute, react, empathy, leadership, ethics, level, experience, stat_points, created_at, updated_at
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| rb8001/app/state/database.py | 24-38 | 테이블 모델 정의 |
+| rb10508_micro/app/api/endpoints.py | 155-161 | SELECT 쿼리 |
+| robeing-monitor/app/state/database.py | 19-33 | 테이블 모델 정의 |
+| robeing-monitor/app/state/state_service.py | 55 | SELECT 쿼리 |
+| robeing-monitor/app/state/state_service.py | 59-62 | INSERT 쿼리 |
+| robeing-monitor/app/state/state_service.py | 81 | SELECT 쿼리 |
+| robeing-monitor/app/state/state_service.py | 215 | SELECT 전체 조회 |
+| robeing-monitor/app/api/items.py | 169-173 | SELECT level 쿼리 |
+
+### 2.9 robeing_settings 테이블
+**컬럼**: id, robeing_id, company_name, workspace_id, preferences(JSON), created_at, updated_at
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| rb8001/app/state/database.py | 40-50 | 테이블 모델 정의 |
+| robeing-monitor/app/state/database.py | 35-45 | 테이블 모델 정의 |
+| robeing-monitor/app/state/state_service.py | 110 | SELECT 쿼리 |
+| robeing-monitor/app/state/state_service.py | 114-117 | INSERT 쿼리 |
+| robeing-monitor/app/state/state_service.py | 133 | SELECT 쿼리 |
+
+### 2.10 conversation_logs 테이블
+**컬럼**: id, robeing_id, user_id, slack_user_id, channel_id, message, response, intent, confidence, timestamp
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| rb8001/app/state/database.py | 52-65 | 테이블 모델 정의 |
+| rb8001/app/state/database.py | 86-92 | SELECT 쿼리 (최근 대화) |
+| rb8001/app/router/router.py | 464-496 | INSERT 쿼리 |
+| robeing-monitor/app/state/database.py | 47-59 | 테이블 모델 정의 |
+| robeing-monitor/app/state/state_service.py | 156-159 | INSERT 쿼리 |
+| robeing-monitor/app/state/state_service.py | 173-177 | SELECT 쿼리 (최근 로그) |
+| robeing-monitor/app/state/state_service.py | 194-203 | SELECT 쿼리 (7일간) |
+
+### 2.11 user_preferences 테이블
+**컬럼**: user_id, slack_user_id, news_keywords, email_filter, briefing_enabled, briefing_time
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| rb8001/app/skills/dm_skill.py | 466 | SELECT news_keywords WHERE user_id = :user_id |
+| rb8001/app/skills/dm_skill.py | 471 | SELECT news_keywords WHERE slack_user_id = :slack_user_id |
+| robeing-monitor/app/api/monitor.py | 148-165 | SELECT 쿼리 |
+| robeing-monitor/app/api/monitor.py | 276-292 | UPDATE 쿼리 (동적 쿼리 생성) |
+| robeing-monitor/app/api/monitor.py | 309-316 | INSERT 쿼리 |
+
+### 2.12 system_metrics 테이블
+**컬럼**: time, metric_type, value
+
+| 파일 경로 | 라인 번호 | 작업 내용 |
+|-----------|-----------|-----------|
+| frontend-base/backend/metrics_database.py | 58-60 | INSERT INTO system_metrics |
+| frontend-base/backend/metrics_database.py | 93-100 | SELECT (time_bucket 사용) |
+
+## 3. 수정 작업 체크리스트
+
+### 3.1 테이블 구조 변경 시
+- [ ] SQLAlchemy 모델 클래스 수정
+- [ ] Migration 스크립트 작성
+- [ ] 기존 데이터 마이그레이션 계획
+
+### 3.2 컬럼명 변경 시
+- [ ] 모든 SELECT 쿼리 수정
+- [ ] 모든 INSERT 쿼리 수정
+- [ ] 모든 UPDATE 쿼리 수정
+- [ ] 모든 DELETE 쿼리 수정
+- [ ] SQLAlchemy 모델 속성명 수정
+- [ ] API 응답 필드명 확인
+
+### 3.3 저장소별 작업
+- [ ] auth-server: SQLAlchemy 모델 + asyncpg 쿼리 수정
+- [ ] rb8001: SQLAlchemy 모델 + text() 쿼리 수정
+- [ ] rb10508_micro: asyncpg 직접 쿼리 수정
+- [ ] frontend-base: asyncpg 직접 쿼리 수정
+- [ ] robeing-gateway: SQLAlchemy 모델 + asyncpg 쿼리 수정
+- [ ] robeing-monitor: SQLAlchemy 모델 + asyncpg 쿼리 수정
+- [ ] skill-email: psycopg2 쿼리 수정
+
+### 3.4 테스트 계획
+- [ ] 각 저장소별 단위 테스트
+- [ ] 통합 테스트 (API 엔드포인트)
+- [ ] 데이터 마이그레이션 테스트
+- [ ] 롤백 계획 수립
+
+## 4. 위험 요소
+
+1. **다중 라이브러리 사용**: SQLAlchemy, asyncpg, psycopg2를 혼용하고 있어 일관성 있는 수정 필요
+2. **UUID 처리**: 일부는 문자열로, 일부는 UUID 타입으로 처리
+3. **JSON 컬럼**: preferences, scopes, oauth_config 등 JSON 타입 컬럼 처리 주의
+4. **외래키 관계**: workspace_members의 workspace_id, user_id FK 관계 유지
+5. **gen_random_uuid()**: PostgreSQL 함수 사용 부분 확인 필요
+
+## 5. 작업 우선순위
+
+1. **높음**: users, workspaces, workspace_members (핵심 인증/권한)
+2. **중간**: gmail_tokens, slack_user_mapping (통합 기능)
+3. **낮음**: robeing_stats, conversation_logs (부가 기능)
+
+## 6. 롤백 계획
+
+1. 변경 전 전체 데이터베이스 백업
+2. 각 테이블별 데이터 덤프
+3. 이전 버전 코드 태그 생성
+4. 단계별 배포 (테스트 환경 → 프로덕션)
+
+---
+**주의사항**: 
+- 모든 변경사항은 테스트 환경(rb10508_micro)에서 먼저 검증
+- 프로덕션(rb8001) 적용은 완전한 테스트 후 진행
+- 데이터 손실 방지를 위한 백업 필수
\ No newline at end of file