# 원격 설정 (Remote Config) 스키마 문서

## 개요

이 문서는 `https://jwt.wrmc.cc/config`에서 호스팅되는 원격 설정 파일의 스키마와 운영 가이드를 설명합니다.

클라이언트 애플리케이션은 시작 시 이 설정을 가져와 Supabase 연결 정보, 기능 플래그, 점검 모드 등을 동적으로 적용합니다.

---

## JSON 스키마

```json
{
  "configVersion": "20251130.2",
  "lastUpdated": "2025-11-30T12:00:00Z",
  "environments": {
    "main": {
      "supabaseUrl": "https://kong.wrmc.cc",
      "anonKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "priority": 1,
      "enabled": true,
      "description": "기본 운영 서버"
    },
    "mirror": {
      "supabaseUrl": "https://mirror.wrmc.cc",
      "anonKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "priority": 2,
      "enabled": false,
      "description": "미러 서버 (장애 시 사용)"
    },
    "development": {
      "supabaseUrl": "https://dev.wrmc.cc",
      "anonKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "priority": 3,
      "enabled": false,
      "description": "개발 서버"
    }
  },
  "defaultEnvironment": "main",
  "features": {
    "debugMode": false
  },
  "maintenance": {
    "enabled": false,
    "message": "서버 점검 중입니다. 잠시 후 다시 시도해주세요.",
    "estimatedEndTime": "2025-11-30T14:00:00Z"
  }
}
```

---

## 필드 설명

### 최상위 필드

| 필드 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `configVersion` | string | ✅ | 설정 버전 (형식: `YYYYMMDD.N`, 예: `20251130.2`) |
| `lastUpdated` | string | ✅ | 최종 업데이트 시간 (ISO 8601 형식) |
| `environments` | object | ✅ | 환경별 Supabase 연결 설정 |
| `defaultEnvironment` | string | ✅ | 기본 사용 환경 |
| `features` | object | ❌ | 기능 플래그 설정 |
| `maintenance` | object | ✅ | 점검 모드 설정 |

### environments (환경 설정)

각 환경은 다음 필드를 포함합니다:

| 필드 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `supabaseUrl` | string | ✅ | Supabase 서버 URL |
| `anonKey` | string | ✅ | Supabase Anonymous Key |
| `priority` | number | ✅ | 우선순위 (1이 가장 높음) |
| `enabled` | boolean | ✅ | 환경 활성화 여부 |
| `description` | string | ❌ | 환경 설명 (로깅용) |

**환경 예시**:
- `main`: 기본 운영 서버
- `mirror`: 미러 서버 (운영 서버 장애 시 사용)
- `development`: 개발 서버

### features (기능 플래그)

| 필드 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `debugMode` | boolean | `false` | 디버그 모드 활성화 |

> 💡 필요에 따라 새로운 기능 플래그를 추가할 수 있습니다.

### maintenance (점검 모드)

| 필드 | 타입 | 설명 |
|------|------|------|
| `enabled` | boolean | 점검 모드 활성화 여부 |
| `message` | string | 사용자에게 표시할 점검 메시지 |
| `estimatedEndTime` | string \| null | 점검 종료 예정 시간 (ISO 8601) |

---

## 운영 가이드

### 1. 서버 점검 시

서버 점검 시 `maintenance` 섹션을 수정합니다:

```json
{
  "maintenance": {
    "enabled": true,
    "message": "서버 점검 중입니다. 오후 2시에 재개 예정입니다.",
    "estimatedEndTime": "2025-11-30T14:00:00Z"
  }
}
```

**클라이언트 동작**:
- 앱 시작 시 점검 모드 메시지가 표시되고 앱이 종료됩니다.

**점검 완료 후**:
```json
{
  "maintenance": {
    "enabled": false,
    "message": "",
    "estimatedEndTime": null
  }
}
```

---

### 2. 운영 서버 장애 시 (미러 서버 전환)

기본 운영 서버에 문제가 생겼을 때 미러 서버로 전환:

```json
{
  "environments": {
    "main": {
      "enabled": false,
      ...
    },
    "mirror": {
      "enabled": true,
      ...
    }
  }
}
```

**클라이언트 동작**:
- `main`이 비활성화되면 자동으로 `priority`가 가장 높은 활성화된 환경(mirror)을 선택합니다.

**복구 후**:
```json
{
  "environments": {
    "main": {
      "enabled": true,
      ...
    },
    "mirror": {
      "enabled": false,
      ...
    }
  }
}
```

---

### 3. 개발 환경 사용

개발자가 개발 서버를 사용하려면 코드에서 환경을 지정합니다:

```python
# 특정 환경 지정
supabase_manager = SupabaseManager(logger, environment="development")
```

또는 서버 설정에서 `defaultEnvironment`를 변경:

```json
{
  "defaultEnvironment": "development"
}
```

---

### 4. 기능 플래그 활용

특정 기능을 서버에서 제어하려면:

```json
{
  "features": {
    "debugMode": true,
    "newFeatureX": false
  }
}
```

클라이언트 코드에서:
```python
if supabase_manager.is_feature_enabled("debugMode"):
    # 디버그 모드 동작
    pass
```

---

### 5. 설정 버전 관리

설정을 변경할 때마다 `configVersion`과 `lastUpdated`를 업데이트합니다:

```json
{
  "configVersion": "20251130.3",
  "lastUpdated": "2025-11-30T15:30:00Z",
  ...
}
```

**버전 형식**: `YYYYMMDD.N`
- `YYYYMMDD`: 날짜 (예: 20251130)
- `N`: 해당 날짜의 리비전 번호 (1, 2, 3, ...)

---

## 클라이언트 API

### SupabaseManager 메서드

| 메서드 | 반환 타입 | 설명 |
|--------|----------|------|
| `is_feature_enabled(name, default=False)` | `bool` | 기능 활성화 여부 |
| `is_maintenance_mode()` | `bool` | 점검 모드 여부 |
| `get_maintenance_message()` | `str` | 점검 메시지 |
| `get_maintenance_end_time()` | `str \| None` | 점검 종료 예정 시간 |
| `get_config_info()` | `dict` | 전체 설정 정보 |

### 속성

| 속성 | 타입 | 설명 |
|------|------|------|
| `config_version` | `str` | 설정 버전 |
| `last_updated` | `str` | 최종 업데이트 시간 |
| `current_environment` | `str` | 현재 환경 이름 |
| `features` | `dict` | 기능 플래그 |
| `maintenance` | `dict` | 점검 모드 설정 |

---

## 폴백 동작

원격 설정 서버에 접속할 수 없는 경우, 클라이언트는 하드코딩된 기본값을 사용합니다:

```python
DEFAULT_URL = "https://kong.wrmc.cc"
DEFAULT_KEY = "eyJhbGciOiJIUzI1NiIs..."
DEFAULT_ENVIRONMENT = "production"
```

---

## 운영 시나리오 요약

| 시나리오 | 변경 내용 |
|---------|----------|
| 서버 점검 | `maintenance.enabled = true` |
| 점검 완료 | `maintenance.enabled = false` |
| 기본 서버 장애 | `main.enabled = false`, `mirror.enabled = true` |
| 기본 서버 복구 | `main.enabled = true`, `mirror.enabled = false` |
| 개발 모드 전환 | `defaultEnvironment = "development"` |
| 디버그 모드 | `features.debugMode = true` |

---

## 보안 고려사항

1. **HTTPS 필수**: 설정 파일은 반드시 HTTPS로 제공해야 합니다.
2. **anon key만 노출**: 서비스 키는 절대 노출하지 마세요.
3. **CDN 캐싱**: 설정 변경 시 CDN 캐시 무효화를 확인하세요.