From 3117a5e3fffac18baa6b03954ea1a5604da422e0 Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Tue, 29 Jul 2025 21:08:10 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20auth-server=20=EB=8D=B0=EC=9D=B4?=
 =?UTF-8?q?=ED=84=B0=EB=B2=A0=EC=9D=B4=EC=8A=A4=20=EC=8A=A4=ED=82=A4?=
 =?UTF-8?q?=EB=A7=88=20=EB=AC=B8=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

- PostgreSQL auth_db 스키마 구조 상세 분석
- companies, slack_workspaces 테이블 구조 및 관계
- 멀티테넌트 B2B SaaS 아키텍처 특징 설명
- 현재 데이터 현황 및 로빙 프로젝트와의 연관성
---
 .../auth-server-database-schema.md            | 127 ++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 docs/architecture/auth-server-database-schema.md

diff --git a/docs/architecture/auth-server-database-schema.md b/docs/architecture/auth-server-database-schema.md
new file mode 100644
index 0000000..55e51c1
--- /dev/null
+++ b/docs/architecture/auth-server-database-schema.md
@@ -0,0 +1,127 @@
+# auth-server 데이터베이스 스키마
+
+**날짜**: 2025-07-29  
+**데이터베이스**: auth_db (PostgreSQL)  
+**목적**: 멀티테넌트 B2B Slack 봇 인증 관리 시스템
+
+## 개요
+
+auth-server는 개별 사용자 인증보다는 **회사별 Slack 봇 인증 및 관리**에 특화된 시스템입니다. 각 회사마다 고유한 서브도메인을 제공하고, Slack 워크스페이스와 연동하여 로빙 AI 서비스를 제공하는 B2B SaaS 구조입니다.
+
+## 테이블 구조
+
+### 1. companies (회사/조직 관리)
+
+```sql
+CREATE TABLE companies (
+    id             uuid PRIMARY KEY,
+    name           varchar(255) NOT NULL,
+    subdomain      varchar(100) NOT NULL UNIQUE,
+    container_port integer UNIQUE,
+    status         varchar(50),
+    created_at     timestamp without time zone,
+    updated_at     timestamp without time zone
+);
+```
+
+**필드 설명**:
+- `id`: 회사 고유 식별자 (UUID)
+- `name`: 회사명
+- `subdomain`: 고유 서브도메인 (예: test-company-oauth)
+- `container_port`: 할당된 컨테이너 포트 (향후 회사별 전용 인스턴스 지원)  
+- `status`: 회사 상태 (active, inactive 등)
+- `created_at`, `updated_at`: 생성/수정 시간
+
+**인덱스**:
+- Primary Key: `id`
+- Unique: `subdomain`, `container_port`
+
+### 2. slack_workspaces (Slack 워크스페이스 연동)
+
+```sql
+CREATE TABLE slack_workspaces (
+    id                    uuid PRIMARY KEY,
+    company_id            uuid NOT NULL REFERENCES companies(id),
+    team_id               varchar(100) NOT NULL UNIQUE,
+    team_name             varchar(255),
+    bot_token             text,
+    bot_user_id           varchar(100),
+    app_id                varchar(100),
+    scopes                json,
+    is_enterprise_install boolean,
+    is_active             boolean,
+    installed_at          timestamp without time zone,
+    updated_at            timestamp without time zone
+);
+```
+
+**필드 설명**:
+- `id`: 워크스페이스 고유 식별자 (UUID)
+- `company_id`: 소속 회사 참조 (FK)
+- `team_id`: Slack 팀 고유 ID
+- `team_name`: Slack 팀명
+- `bot_token`: Slack 봇 액세스 토큰
+- `bot_user_id`: 봇 사용자 ID
+- `app_id`: Slack 앱 ID
+- `scopes`: OAuth 스코프 정보 (JSON)
+- `is_enterprise_install`: 엔터프라이즈 설치 여부
+- `is_active`: 워크스페이스 활성화 상태
+- `installed_at`, `updated_at`: 설치/수정 시간
+
+**인덱스**:
+- Primary Key: `id`
+- Unique: `team_id`
+- Foreign Key: `company_id` → `companies(id)`
+
+## 현재 데이터 현황
+
+### Companies (2건)
+```
+     name     |      subdomain      | container_port | status 
+--------------+---------------------+----------------+--------
+ 테스트 회사  | test-company-oauth  |                | active
+ 테스트 회사2 | test-company-oauth2 |                | active
+```
+
+### Slack Workspaces (2건)
+```
+   team_name   | bot_user_id | is_active |        installed_at        
+---------------+-------------+-----------+----------------------------
+ GoodGang Labs | U0988K1BLQY | t         | 2025-07-26 07:05:39.019511
+ test          | U097FFP4QQ3 | t         | 2025-07-26 07:11:36.388755
+```
+
+## 아키텍처 특징
+
+### 멀티테넌트 B2B SaaS 구조
+- **회사별 격리**: 각 회사마다 고유한 서브도메인 제공
+- **전용 리소스**: `container_port` 필드로 회사별 전용 컨테이너 지원 준비
+- **Slack 중심**: 각 회사의 Slack 워크스페이스와 1:1 매핑
+
+### 인증 방식
+- **사용자 테이블 없음**: 개별 사용자 정보를 DB에 저장하지 않음
+- **JWT/세션 기반**: 사용자 인증 정보는 JWT 토큰이나 세션에서 관리
+- **OAuth 토큰**: Google/Slack OAuth 토큰은 파일 시스템(`/tokens/`)에 저장
+
+### 확장성 고려사항
+- **회사별 스케일링**: `container_port`를 통한 회사별 전용 인스턴스 지원
+- **워크스페이스 다중화**: 한 회사가 여러 Slack 워크스페이스 연동 가능 (1:N 관계)
+- **봇 토큰 관리**: 각 워크스페이스별로 독립적인 봇 토큰 관리
+
+## 로빙 프로젝트와의 연관성
+
+auth-server는 로빙 AI 에이전트 생태계에서 다음 역할을 수행합니다:
+
+1. **기업 고객 관리**: B2B 고객사별로 독립된 로빙 서비스 제공
+2. **Slack 통합**: 기업의 Slack 워크스페이스에서 로빙 봇 서비스 제공
+3. **중앙 인증**: 여러 로빙 서비스(rb8001, rb10508, skill_email 등)의 통합 인증
+4. **토큰 공유**: OAuth 토큰을 파일 시스템을 통해 다른 서비스와 공유
+
+## 보안 고려사항
+
+- **봇 토큰 보호**: `bot_token` 필드는 민감한 정보로 적절한 암호화 필요
+- **서브도메인 검증**: 악의적인 서브도메인 생성 방지 필요
+- **워크스페이스 무결성**: 비활성화된 워크스페이스에 대한 접근 제어 필요
+
+---
+**최종 업데이트**: 2025-07-29
\ No newline at end of file