앱 설정 정보 조회 API

앱 설정 정보 조회 API는 모바일 앱 초기화 시 필요한 통합 시스템 설정 정보를 조회합니다.

참고

이 API는 모바일 앱이 시작될 때 필요한 기본 설정 정보들을 제공합니다. 언어별 설정, 시스템 구성 정보 등을 포함합니다.

1. 앱 설정 정보 조회

모바일 앱 초기화 시 필요한 통합 시스템 설정 정보를 조회합니다.

• HTTP Method: GET
• Path: /v1/mobile/app-settings
• 인증: App Token 필요 (Authorization: Bearer {appToken})

Headers

Header	Type	Description	Required
Authorization	string	Bearer <app-token>	Yes
Accept-Language	string	언어 태그 (Language Codes 참조, 기본값: de-DE)	Yes

Query Parameters

이 API는 Query Parameter를 사용하지 않습니다.

노트

2025-05-27 기준으로는 Query Parameter를 사용하지 않으며, 향후 필요에 따라 추가 파라미터 지원 여부를 논의할 예정입니다.

Request Body

이 API는 Request Body를 사용하지 않습니다.

Responses

HTTP Status Code	설명	Error Code(s)
200 OK	조회 성공	-
401 Unauthorized	앱 토큰 인증 실패	2051
404 Not Found	앱 설정 없음	8010
500 Internal Server Error	서버 내부 오류	8000

200 OK - 앱 설정 정보 조회 성공

{
  "id": "hashcode",
  "systemSettings": {
    "globalConfig": {
      "sessionTimeoutMinutes": 30,
      "maxUploadSizeMB": 10
    }
  },
  "featureFlags": [
    {
      "name": "enableNewSleepTracking",
      "isEnabled": true,
      "description": "New sleep tracking functionality"
    },
    {
      "name": "enableQuestionnaireSurvey",
      "isEnabled": false,
      "description": "In-app questionnaire survey feature"
    }
  ],
  "agreements": [
    {
      "versionsId": "terms-of-service",
      "type": "TERMS",
      "validFrom": 1746316800000,
      "isRequired": true
    },
    {
      "versionsId": "privacy-policy",
      "type": "PRIVACY_POLICY",
      "validFrom": 1744675200000,
      "isRequired": true
    }
  ],
  "announcementSummaries": [
    {
      "id": "announce-123",
      "title": "새로운 기능이 추가되었습니다",
      "createdAt": 1747126800000,
      "isNew": true,
      "importance": "high"
    }
  ],
  "mobile": {
    "android": {
      "latest": {
        "code": "12",
        "name": "1.2.15"
      },
      "min": {
        "code": "11",
        "name": "1.2.14"
      }
    },
    "iOS": {
      "latest": {
        "build": 57,
        "name": "1.2.15"
      },
      "min": {
        "build": 57,
        "name": "1.2.15"
      }
    }
  },
  "authenticationMethods": [
    {
      "type": "email",
      "isEnabled": true,
      "displayName": "이메일"
    },
    {
      "type": "google",
      "isEnabled": true,
      "displayName": "Google"
    },
    {
      "type": "apple",
      "isEnabled": true,
      "displayName": "Apple"
    }
  ],
  "device": {
    "minFreeSpaceMB": 500
  },
  "lastUpdatedAt": 1747557000,
  "cacheExpiresAt": 1747600200
}

필드	타입	설명	필수
id	string	설정 ID (해시코드)	Yes
systemSettings	object	시스템 설정	No
systemSettings.globalConfig	object	글로벌 설정	No
systemSettings.globalConfig.sessionTimeoutMinutes	number	세션 타임아웃 (분, Kotlin: Int, Swift: Int)	No
systemSettings.globalConfig.maxUploadSizeMB	number	최대 업로드 크기 (MB, Kotlin: Int, Swift: Int)	No
featureFlags	array	기능 플래그 목록	No
featureFlags[].name	string	기능 플래그 이름	No
featureFlags[].isEnabled	boolean	기능 활성화 여부	No
featureFlags[].description	string	기능 설명	No
agreements	array	약관 버전 정보	No
agreements[].versionsId	string	약관 버전 ID	No
agreements[].type	string	약관 타입	No
agreements[].validFrom	number	유효 시작 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)	No
agreements[].isRequired	boolean	필수 동의 여부	No
announcementSummaries	array	공지사항 요약 목록	No
announcementSummaries[].id	string	공지사항 ID	No
announcementSummaries[].title	string	공지사항 제목	No
announcementSummaries[].createdAt	number	생성 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)	No
announcementSummaries[].isNew	boolean	새 공지사항 여부	No
announcementSummaries[].importance	string	중요도	No
mobile	object	모바일 앱 버전 정보	No
mobile.android	object	Android 버전 정보	No
mobile.android.latest	object	Android 최신 버전	No
mobile.android.latest.code	string	Android 최신 버전 코드	No
mobile.android.latest.name	string	Android 최신 버전 이름	No
mobile.android.min	object	Android 최소 지원 버전	No
mobile.android.min.code	string	Android 최소 버전 코드	No
mobile.android.min.name	string	Android 최소 버전 이름	No
mobile.iOS	object	iOS 버전 정보	No
mobile.iOS.latest	object	iOS 최신 버전	No
mobile.iOS.latest.build	number	iOS 최신 빌드 번호 (Kotlin: Int, Swift: Int)	No
mobile.iOS.latest.name	string	iOS 최신 버전 이름	No
mobile.iOS.min	object	iOS 최소 지원 버전	No
mobile.iOS.min.build	number	iOS 최소 빌드 번호 (Kotlin: Int, Swift: Int)	No
mobile.iOS.min.name	string	iOS 최소 버전 이름	No
authenticationMethods	array	지원 인증 방식 목록	No
authenticationMethods[].type	string	인증 방식 타입	No
authenticationMethods[].isEnabled	boolean	활성화 여부	No
authenticationMethods[].displayName	string	표시 이름	No
device	object	디바이스 요구사항	No
device.minFreeSpaceMB	number	최소 여유 공간 (MB, Kotlin: Int, Swift: Int)	No
lastUpdatedAt	number	마지막 업데이트 시간 (Unix timestamp in seconds, Kotlin: Long, Swift: Int64)	No
cacheExpiresAt	number	캐시 만료 시간 (Unix timestamp in seconds, Kotlin: Long, Swift: Int64)	No

401 Unauthorized - 앱 토큰 인증 실패

{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}

404 Not Found - 앱 설정 없음

{
  "code": 8010,
  "message": "APP_SETTINGS_NOT_FOUND",
  "detail": "앱 설정을 찾을 수 없습니다"
}

500 Internal Server Error - 서버 내부 오류

{
  "code": 8000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류가 발생했습니다"
}

설명

• mobile.service.ts의 getAppSettings 메서드에 해당하며, MobileController를 통해 노출됩니다.
• 주요 기능:
  1. 설정 ID (해시코드) 제공
  2. 시스템 전역 설정 제공 (세션 타임아웃, 업로드 제한 등)
  3. 기능 플래그를 통한 클라이언트 기능 제어
  4. 약관 버전 정보 제공
  5. 공지사항 요약 목록 제공
  6. 플랫폼별 최소 버전 요구사항
  7. 지원 인증 방식 목록
  8. 디바이스 요구사항 (저장공간 등)
  9. 캐시 관리를 위한 타임스탬프 정보
• 모바일 앱 시작 시 이 API를 호출하여 필요한 모든 기본 설정 정보를 한 번에 조회합니다.
• 클라이언트는 이 정보를 바탕으로 기능 활성화, 약관 동의, 버전 호환성 등을 관리할 수 있습니다.

Accept-Language 헤더 상세

값	설명	예시 응답 언어 설정
ko-KR	한국어	한국어 설정 반환
en-US	영어(미국)	영어 설정 반환
de-DE	독일어	독일어 설정 반환

참고: Accept-Language 헤더가 제공되지 않거나 지원하지 않는 언어인 경우 기본값으로 de-DE가 사용됩니다.

사용 예시

요청 예시:

curl -X GET "https://api.dta-wide.com/mobile/app-settings" \
  -H "Authorization: Bearer your-app-token" \
  -H "Accept-Language: ko-KR"

응답 예시:

{
  "id": "hashcode",
  "systemSettings": {
    "globalConfig": {
      "sessionTimeoutMinutes": 30,
      "maxUploadSizeMB": 10
    }
  },
  "featureFlags": [
    {
      "name": "enableNewSleepTracking",
      "isEnabled": true,
      "description": "New sleep tracking functionality"
    }
  ],
  "agreements": [
    {
      "versionsId": "terms-of-service",
      "type": "TERMS",
      "validFrom": 1746316800000,
      "isRequired": true
    }
  ],
  "announcementSummaries": [
    {
      "id": "announce-123",
      "title": "새로운 기능이 추가되었습니다",
      "createdAt": 1747126800000,
      "isNew": true,
      "importance": "high"
    }
  ],
  "mobile": {
    "android": {
      "latest": {
        "code": "12",
        "name": "1.2.15"
      },
      "min": {
        "code": "11",
        "name": "1.2.14"
      }
    },
    "iOS": {
      "latest": {
        "build": 57,
        "name": "1.2.15"
      },
      "min": {
        "build": 57,
        "name": "1.2.15"
      }
    }
  },
  "authenticationMethods": [
    {
      "type": "email",
      "isEnabled": true,
      "displayName": "이메일"
    }
  ],
  "device": {
    "minFreeSpaceMB": 500
  },
  "lastUpdatedAt": 1747557000,
  "cacheExpiresAt": 1747600200
}

주요 필드 상세

SystemSettings

시스템 전역 설정을 포함합니다.

• globalConfig.sessionTimeoutMinutes: 앱 세션 타임아웃 시간 (분)
• globalConfig.maxUploadSizeMB: 파일 업로드 최대 크기 제한 (MB)

FeatureFlags

클라이언트 기능 제어를 위한 플래그 목록입니다.

• name: 기능 식별자
• isEnabled: 해당 기능 활성화 여부
• description: 기능에 대한 설명

Agreements

약관 정보 목록입니다.

• versionsId: 약관 버전 식별자
• type: 약관 타입 (TERMS, PRIVACY_POLICY 등)
• validFrom: 해당 약관이 유효해지는 시점 (Unix timestamp)
• isRequired: 필수 동의 약관 여부

Mobile Version Information

모바일 앱 버전 정보입니다.

• mobile.android.latest: Android 최신 버전 정보
  • code: 버전 코드 (앱 스토어에서 사용하는 내부 버전 번호)
  • name: 사용자에게 표시되는 버전 이름
• mobile.android.min: Android 최소 지원 버전 정보
• mobile.iOS.latest: iOS 최신 버전 정보
  • build: 빌드 번호 (App Store에서 사용하는 내부 빌드 번호)
  • name: 사용자에게 표시되는 버전 이름
• mobile.iOS.min: iOS 최소 지원 버전 정보

Authentication Methods

지원하는 인증 방식 목록입니다.

• type: 인증 방식 (email, google, apple 등)
• isEnabled: 해당 인증 방식 활성화 여부
• displayName: 클라이언트에서 표시할 이름

2. AppSettings 새 버전 생성

관리자가 새로운 버전의 AppSettings를 생성합니다. 기존 설정은 history로 이관되고 새 버전이 활성화됩니다.

• HTTP Method: POST
• Path: /v1/mobile/admin/app-settings
• 인증: Access Token 필요 (관리자 권한 필요)

Headers

Header	Type	Description	Required
Authorization	string	Bearer <access-token> (관리자 권한 필요)	Yes
Content-Type	string	application/json	Yes

Request Body

{
  "systemSettings": {
    "globalConfig": {
      "sessionTimeoutMinutes": 30,
      "maxUploadSizeMB": 10
    }
  },
  "agreementVersions": [],
  "announcementSummaries": [],
  "featureFlags": [
    {
      "name": "enableNewSleepTracking",
      "isEnabled": true,
      "description": "New sleep tracking functionality"
    }
  ],
  "mobile": {
    "android": {
      "latest": { "code": "12", "name": "1.2.15" },
      "min": { "code": "11", "name": "1.2.14" }
    },
    "iOS": {
      "latest": { "build": 37, "name": "0.1.6" },
      "min": { "build": 37, "name": "0.1.6" }
    }
  },
  "authenticationMethods": [
    {
      "type": "email",
      "isEnabled": true,
      "displayName": "이메일"
    }
  ],
  "reason": "iOS 버전을 build 37, name 0.1.6으로 업데이트"
}

Responses

HTTP Status Code	설명	Error Code(s)
201 Created	AppSettings 생성 성공	-
400 Bad Request	유효하지 않은 요청 데이터	8001
401 Unauthorized	인증 실패	2001
403 Forbidden	관리자 권한 없음	2060
500 Internal Server Error	서버 내부 오류	8000

201 Created - AppSettings 생성 성공

{
  "id": "new-settings-uuid-789",
  "version": 16,
  "systemSettings": {
    "globalConfig": {
      "sessionTimeoutMinutes": 30,
      "maxUploadSizeMB": 10
    }
  },
  "featureFlags": [
    {
      "name": "enableNewSleepTracking",
      "isEnabled": true,
      "description": "New sleep tracking functionality"
    }
  ],
  "agreements": [],
  "announcementSummaries": [],
  "mobile": {
    "android": {
      "latest": { "code": "12", "name": "1.2.15" },
      "min": { "code": "11", "name": "1.2.14" }
    },
    "iOS": {
      "latest": { "build": 37, "name": "0.1.6" },
      "min": { "build": 37, "name": "0.1.6" }
    }
  },
  "authenticationMethods": [
    {
      "type": "email",
      "isEnabled": true,
      "displayName": "이메일"
    }
  ],
  "lastUpdatedAt": 1747570000
}

401 Unauthorized - 인증 실패

{
  "code": 2001,
  "message": "UNAUTHORIZED",
  "detail": "관리자 권한이 필요합니다."
}

400 Bad Request - 유효하지 않은 요청 데이터

{
  "code": 8001,
  "message": "INVALID_APP_SETTINGS",
  "detail": "유효하지 않은 AppSettings 데이터입니다."
}

설명

• 이 API는 immutable versioning 전략을 사용합니다.
• 새 버전 생성 시 기존 활성 AppSettings는 AppSettingsHistory 테이블로 자동 이관됩니다.
• 새로 생성된 설정이 즉시 활성화되어 GET /v1/mobile/app-settings API에서 반환됩니다.
• version 필드는 자동으로 증가합니다 (예: 15 → 16).
• reason 필드는 변경 이력 추적을 위한 선택적 필드입니다.

사용 예시

iOS 버전 정보 업데이트 요청:

curl -X POST "https://api.dta-wide.com/mobile/admin/app-settings" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "systemSettings": {
      "globalConfig": {
        "sessionTimeoutMinutes": 30,
        "maxUploadSizeMB": 10
      }
    },
    "agreementVersions": [],
    "announcementSummaries": [],
    "featureFlags": [],
    "mobile": {
      "android": {
        "latest": { "code": "12", "name": "1.2.15" },
        "min": { "code": "11", "name": "1.2.14" }
      },
      "iOS": {
        "latest": { "build": 37, "name": "0.1.6" },
        "min": { "build": 37, "name": "0.1.6" }
      }
    },
    "authenticationMethods": [],
    "reason": "iOS 버전을 build 37, name 0.1.6으로 업데이트"
  }'

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-05-27	elizabeth@weltcorp.com	최초 작성 - 앱 설정 정보 조회 API 문서화
0.2.0	2025-08-03	bok@weltcorp.com	구현체에 맞춰 응답 구조 업데이트 - systemSettings, featureFlags, agreements 등 추가
0.3.0	2025-08-03	bok@weltcorp.com	모바일 버전 정보 구조 개선 - androidMinVersion/iOSMinVersion을 mobile 객체로 대체, latest/min 버전 및 code/build 정보 추가
0.4.0	2025-08-03	bok@weltcorp.com	AppSettings 새 버전 생성 API 추가 - POST /v1/mobile/admin/app-settings로 관리자가 설정 관리 가능