본문으로 건너뛰기

endpoints

관련 문서​

Mobile API 엔드포인트

목차​

관련 문서​

1. 엔드포인트 접근 권한 매트릭스​

엔드포인트App TokenUser Access Token서비스 계정비고
GET /v1/mobile/app-settings✓✘✓앱 초기화 시 사용
GET /v1/mobile/version-compatibility✓✘✓앱 버전 호환성 확인
GET /v1/mobile/agreements/{agreementId}✓✓✓약관 상세 내용 조회
GET /v1/mobile/questionnaires/{questionnaireId}✓✓✓설문지 구조 조회
GET /v1/mobile/announcements/{announcementId}✓✓✓공지사항 상세 조회
POST /v1/mobile/app-tokens✘✘✓앱 토큰 발급 (내부/서비스)
POST /v1/mobile/app-tokens/refresh✓✘✓앱 토큰 갱신
GET /v1/mobile/users/{userId}/settings✘✓✓사용자 모바일 설정 조회
PATCH /v1/mobile/users/{userId}/settings✘✓✓사용자 모바일 설정 수정
POST /v1/mobile/users/{userId}/settings/reset✘✘✓사용자 모바일 설정 초기화
GET /v1/mobile/app-settings/{settingsId}/history✘✘✓AppSettings 변경 이력 조회 (관리자 권한)
GET /v1/mobile/app-settings/{settingsId}/history/{version}✘✘✓특정 버전 AppSettings 이력 조회 (관리자 권한)
POST /v1/mobile/admin/app-settings✘✓✓AppSettings 새 버전 생성 (관리자 권한)
POST /v1/mobile/app-settings/new-version✘✘✓AppSettings 새 버전 생성 (관리자 권한)
POST /v1/mobile/app-settings/{settingsId}/rollback✘✘✓AppSettings 롤백 (관리자 권한)
GET /v1/mobile/app-settings/audit-report✘✘✓AppSettings 감사 리포트 생성 (감사 권한)

참고:

  • ✓: 접근 가능
  • ✘: 접근 불가
  • App Token: 모바일 앱 인증 토큰 (사용자 인증과 무관)
  • User Access Token: 사용자 인증 후 발급된 접근 토큰

2. 앱 초기화 및 설정 정보 API​

  • 경로: /v1/mobile/app-settings/version

2.1 앱 설정 정보 조회​

  • HTTP 메서드: GET
  • 경로: /v1/mobile/app-settings
  • Headers:
    • Authorization: Bearer {appToken}
  • Query Parameters:
    • platform: 모바일 플랫폼 (android/ios) (필수)
    • appVersion: 앱 버전 (필수)
    • deviceId: 기기 식별자 (필수)
    • language: 언어 태그 (선택, 기본값: de-DE)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "hashcode",
  "version": 15,
  "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": 17463168000000,
      "isRequired": true
    },
    {
      "versionsId": "privacy-policy",
      "type": "PRIVACY_POLICY",
      "validFrom": 1744675200000,
      "isRequired": true
    }
  ],
  "questionnaireBundle": {
    "id": "283572-skdjfho5h25-asdkfja23576f-sdfkj-uuid",
    "validFrom": 1742428800000
  },
  "announcementSummaries": [
    {
      "id": "announce-123",
      "title": "새로운 기능이 추가되었습니다",
      "createdAt": 1747126800000,
      "isNew": true,
      "importance": "high"
    }
  ],
  "learning": {
    "contentBundle": {
      "id": "383572-skdjfho5h25-asdkfja23576f-sdfkj-uuid",
      "validFrom": 1742428800000
    },
    "quizBundle": {
      "id": "483572-skdjfho5h25-asdkfja23576f-sdfkj-uuid",
      "validFrom": 1742428800000
    }
  },
  "relaxation": {
    "bundle": {
      "id": "583572-skdjfho5h25-asdkfja23576f-sdfkj-uuid",
      "validFrom": 1742428800000
    }
  },
  "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
}

🔍 자동 추적 기능: 이 API 호출 시 인증된 사용자의 UserMobileSettings에 다음 정보가 자동으로 업데이트됩니다:

  • currentAppSettingsId: 현재 조회한 AppSettings ID (id 필드 값)
  • currentAppSettingsVersion: 현재 조회한 AppSettings 버전 (version 필드 값)
  • appSettingsLastCheckedAt: 조회 시점 타임스탬프

클라이언트는 이후 UserMobileSettings 업데이트 시 이 정보를 함께 전달할 수 있습니다.

  • 오류 응답 (400 Bad Request)
{
  "code": 8001,
  "message": "INVALID_INPUT_DATA",
  "detail": "필수 파라미터가 누락되었습니다."
}
  • 오류 응답 (401 Unauthorized)
{
  "code": 2001, // Auth 에러 코드 재사용
  "message": "UNAUTHORIZED",
  "detail": "유효하지 않은 앱 토큰입니다."
}

2.2 앱 버전 호환성 검사​

  • HTTP 메서드: GET
  • 경로: /v1/mobile/version-compatibility
  • Headers:
    • Authorization: Bearer {appToken}
  • Query Parameters:
    • platform: 모바일 플랫폼 (android/ios) (필수)
    • appVersion: 앱 버전 (필수)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "isCompatible": true,
  "isForceUpdateRequired": false,
  "minimumRequiredVersion": "1.2.14",
  "recommendedVersion": "1.2.15",
  "updateUrl": "https://play.google.com/store/apps/details?id=com.example.app",
  "message": {
    "de": "Ihre App-Version wird unterstützt.",
    "en": "Your app version is supported.",
    "ko": "앱 버전이 지원됩니다."
  }
}
  • 성공 응답 (200 OK) - 업데이트 필요한 경우
{
  "isCompatible": false,
  "isForceUpdateRequired": true,
  "minimumRequiredVersion": "1.2.14",
  "recommendedVersion": "1.2.15",
  "updateUrl": "https://play.google.com/store/apps/details?id=com.example.app",
  "message": {
    "de": "Ihre App-Version wird nicht mehr unterstützt. Bitte aktualisieren Sie.",
    "en": "Your app version is no longer supported. Please update.",
    "ko": "앱 버전이 더 이상 지원되지 않습니다. 업데이트하세요."
  }
}
  • 오류 응답 (400 Bad Request)
{
  "code": 8001,
  "message": "INVALID_INPUT_DATA",
  "detail": "필수 파라미터가 누락되었습니다."
}

3. 콘텐츠 상세 조회 API​

3.1 약관 상세 내용 조회​

  • HTTP 메서드: GET
  • 경로: /v1/mobile/agreements/{agreementId}
  • Headers:
    • Authorization: Bearer {appToken} 또는 Bearer {accessToken}
  • Query Parameters:
    • version: 약관 버전 (필수)
    • language: 언어 코드 (선택, 기본값: de)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "terms-of-service",
  "type": "TERMS",
  "version": "1.2.0",
  "validFrom": 1746316800,
  "isRequired": true,
  "content": "약관 전체 내용...",
  "detailsUrl": "https://example.com/terms/v1.2",
  "language": "ko"
}
  • 오류 응답 (404 Not Found)
{
  "code": 8021,
  "message": "AGREEMENT_NOT_FOUND",
  "detail": "요청한 약관을 찾을 수 없습니다."
}
  • 오류 응답 (400 Bad Request)
{
  "code": 8022,
  "message": "AGREEMENT_VERSION_NOT_FOUND",
  "detail": "요청한 버전의 약관을 찾을 수 없습니다."
}

3.2 설문지 구조 조회​

  • HTTP 메서드: GET
  • 경로: /v1/mobile/questionnaires/{questionnaireId}
  • Headers:
    • Authorization: Bearer {appToken} 또는 Bearer {accessToken}
  • Query Parameters:
    • version: 설문지 버전 (필수)
    • language: 언어 코드 (선택, 기본값: de)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "isi-questionnaire",
  "type": "ISI",
  "version": "2.0.0",
  "title": "불면증 심각도 지수",
  "description": "당신의 수면 문제의 심각도를 평가하는 설문입니다.",
  "questions": [
    {
      "id": "q1",
      "text": "지난 2주 동안, 잠들기 어려운 문제가 얼마나 심각했습니까?",
      "type": "LINEAR_SCALE",
      "isRequired": true,
      "options": [
        { "value": "0", "text": "전혀 없음", "score": 0 },
        { "value": "1", "text": "약간", "score": 1 },
        { "value": "2", "text": "중간", "score": 2 },
        { "value": "3", "text": "심각", "score": 3 },
        { "value": "4", "text": "매우 심각", "score": 4 }
      ]
    }
    // 추가 질문들...
  ],
  "scoreLevels": [
    {
      "minScore": 0,
      "maxScore": 7,
      "label": "정상 수면",
      "description": "수면 문제가 없거나 경미합니다.",
      "feedback": "현재 수면 습관을 유지하세요."
    }
    // 추가 점수 레벨...
  ],
  "language": "ko"
}
  • 오류 응답 (404 Not Found)
{
  "code": 8031,
  "message": "QUESTIONNAIRE_NOT_FOUND",
  "detail": "요청한 설문지를 찾을 수 없습니다."
}
  • 오류 응답 (400 Bad Request)
{
  "code": 8032,
  "message": "QUESTIONNAIRE_VERSION_NOT_FOUND",
  "detail": "요청한 버전의 설문지를 찾을 수 없습니다."
}

3.3 공지사항 상세 조회​

  • HTTP 메서드: GET
  • 경로: /v1/mobile/announcements/{announcementId}
  • Headers:
    • Authorization: Bearer {appToken} 또는 Bearer {accessToken}
  • Query Parameters:
    • language: 언어 코드 (선택, 기본값: de)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "announce-123",
  "title": "새로운 기능이 추가되었습니다",
  "content": "공지사항 전체 내용...",
  "createdAt": 1747126800,
  "publishedAt": 1747130400,
  "importance": "high",
  "imageUrl": "https://example.com/images/announcement-123.jpg",
  "detailsUrl": "https://example.com/announcements/123",
  "language": "ko"
}
  • 오류 응답 (404 Not Found)
{
  "code": 8041,
  "message": "ANNOUNCEMENT_NOT_FOUND",
  "detail": "요청한 공지사항을 찾을 수 없습니다."
}

4. 앱 토큰 관리 API​

4.1 앱 토큰 발급​

  • HTTP 메서드: POST
  • 경로: /v1/mobile/app-tokens
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {serviceAccountToken}
  • 비고: 주로 서비스 계정이나 내부 시스템에서 호출됨. 모바일 앱에서 직접 호출하지 않음.

요청 (Request)​

{
  "appId": "com.example.app",
  "deviceId": "device-unique-identifier",
  "platform": "android",
  "validityDays": 30
}

응답 (Response)​

  • 성공 응답 (201 Created)
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": 1750053600,
  "appId": "com.example.app",
  "deviceId": "device-unique-identifier"
}
  • 오류 응답 (400 Bad Request)
{
  "code": 8001,
  "message": "INVALID_INPUT_DATA",
  "detail": "필수 파라미터가 누락되었습니다."
}
  • 오류 응답 (403 Forbidden)
{
  "code": 2060,
  "message": "PERMISSION_DENIED",
  "detail": "앱 토큰을 발급할 권한이 없습니다."
}

4.2 앱 토큰 갱신​

  • HTTP 메서드: POST
  • 경로: /v1/mobile/app-tokens/refresh
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {appToken}

요청 (Request)​

{
  "appId": "com.example.app",
  "deviceId": "device-unique-identifier"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": 1750053600,
  "appId": "com.example.app",
  "deviceId": "device-unique-identifier"
}
  • 오류 응답 (401 Unauthorized)
{
  "code": 2001,
  "message": "UNAUTHORIZED",
  "detail": "유효하지 않은 앱 토큰입니다."
}
  • 오류 응답 (403 Forbidden)
{
  "code": 2052,
  "message": "TOKEN_REFRESH_FORBIDDEN",
  "detail": "요청한 토큰을 갱신할 권한이 없습니다."
}

5. 사용자 모바일 설정 API​

5.1 모바일 설정 조회​

  • HTTP 메서드: GET
  • 경로: /v1/mobile/users/{userId}/settings
  • Headers:
    • Authorization: Bearer {accessToken}
  • Path Parameters:
    • userId: 사용자 ID (필수)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "settings-123-uuid",
  "userId": "user-123-uuid",
  "questionnaireBundleId": "bundle-456-uuid",
  "screenshotAllowed": false,
  "appNotificationEnabled": true,
  "systemNotificationEnabled": true,
  "analyticsConfiguration": {
    "enabled": true,
    "level": "basic",
    "dataTypes": ["usage", "performance"]
  },
  "healthKitPermissionGranted": true,
  "healthConnectPermissionGranted": false,
  "locationPermissionGranted": true,
  "videoRecordingAllowed": false,
  "cameraPermissionGranted": true,
  "photoLibraryPermissionGranted": true,
  "fcmToken": "fGHI789012JKLM...",
  "createdAt": 1747500000000,
  "updatedAt": 1747557000000,
  "lastResetAt": 1747500000000
}
  • 오류 응답 (404 Not Found)
{
  "code": 8061,
  "message": "USER_MOBILE_SETTINGS_NOT_FOUND",
  "detail": "사용자 모바일 설정을 찾을 수 없습니다."
}

5.2 모바일 설정 수정​

  • HTTP 메서드: PATCH
  • 경로: /v1/mobile/users/{userId}/settings
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}
  • Path Parameters:
    • userId: 사용자 ID (필수)

요청 (Request)​

{
  "screenshotAllowed": true,
  "appNotificationEnabled": false,
  "systemNotificationEnabled": true,
  "analyticsConfiguration": {
    "enabled": false,
    "level": "none",
    "dataTypes": []
  },
  "healthKitPermissionGranted": false,
  "healthConnectPermissionGranted": true,
  "locationPermissionGranted": false,
  "videoRecordingAllowed": true,
  "cameraPermissionGranted": false,
  "photoLibraryPermissionGranted": false,
  "fcmToken": "fXYZ789012ABCD...",
  "currentAppSettingsId": "app-settings-uuid-456",
  "currentAppSettingsVersion": 12
}

🔍 AppSettings 추적: 클라이언트에서 currentAppSettingsId와 currentAppSettingsVersion을 함께 전달하면, 사용자가 실제로 사용하는 AppSettings 버전을 정확히 추적할 수 있습니다. 이 필드들은 선택사항이며, 전달하지 않아도 정상 동작합니다.

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "settings-123-uuid",
  "userId": "user-123-uuid",
  "questionnaireBundleId": "bundle-456-uuid",
  "screenshotAllowed": true,
  "appNotificationEnabled": false,
  "systemNotificationEnabled": true,
  "analyticsConfiguration": {
    "enabled": false,
    "level": "none",
    "dataTypes": []
  },
  "healthKitPermissionGranted": false,
  "healthConnectPermissionGranted": true,
  "locationPermissionGranted": false,
  "videoRecordingAllowed": true,
  "cameraPermissionGranted": false,
  "photoLibraryPermissionGranted": false,
  "fcmToken": "fXYZ789012ABCD...",
  "createdAt": 1747500000000,
  "updatedAt": 1747560000000,
  "lastResetAt": 1747500000000
}
  • 오류 응답 (400 Bad Request)
{
  "code": 8062,
  "message": "INVALID_MOBILE_SETTINGS",
  "detail": "유효하지 않은 모바일 설정 값입니다."
}

5.3 모바일 설정 초기화​

  • HTTP 메서드: POST
  • 경로: /v1/mobile/users/{userId}/settings/reset
  • Headers:
    • Authorization: Bearer {accessToken}
  • Path Parameters:
    • userId: 사용자 ID (필수)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "settings-123-uuid",
  "userId": "user-123-uuid",
  "questionnaireBundleId": "bundle-456-uuid",
  "screenshotAllowed": false,
  "appNotificationEnabled": false,
  "systemNotificationEnabled": false,
  "analyticsConfiguration": {
    "enabled": true,
    "level": "basic",
    "dataTypes": ["usage"]
  },
  "healthKitPermissionGranted": false,
  "healthConnectPermissionGranted": false,
  "locationPermissionGranted": false,
  "videoRecordingAllowed": false,
  "cameraPermissionGranted": false,
  "photoLibraryPermissionGranted": false,
  "createdAt": 1747500000000,
  "updatedAt": 1747570000000,
  "lastResetAt": 1747570000000
}

6. 현재 사용자 기반 모바일 설정 API (/me)​

JWT 토큰에서 사용자 ID를 추출하여 자신의 모바일 설정을 관리하는 간편한 API입니다.

6.1 현재 사용자의 모바일 설정 조회​

  • HTTP 메서드: GET
  • 경로: /v1/mobile/me/settings
  • Headers:
    • Authorization: Bearer {accessToken}

응답 (Response)​

  • 성공 응답 (200 OK) - 5.1과 동일한 응답 구조
  • 오류 응답 (401 Unauthorized)
{
  "code": 2001,
  "message": "UNAUTHORIZED",
  "detail": "유효하지 않은 액세스 토큰입니다."
}
  • 오류 응답 (404 Not Found) - 5.1과 동일한 오류 구조

6.2 현재 사용자의 모바일 설정 수정​

  • HTTP 메서드: PATCH
  • 경로: /v1/mobile/me/settings
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken}

요청 (Request)​

{
  "appNotificationEnabled": true,
  "fcmToken": "new-fcm-token-123",
  "currentAppSettingsId": "app-settings-uuid-456",
  "currentAppSettingsVersion": 12
}

🔍 AppSettings 추적: 클라이언트에서 currentAppSettingsId와 currentAppSettingsVersion을 함께 전달하면, 사용자가 실제로 사용하는 AppSettings 버전을 정확히 추적할 수 있습니다. 이 필드들은 선택사항이며, 전달하지 않아도 정상 동작합니다.

응답 (Response)​

  • 성공 응답 (200 OK) - 5.1과 동일한 응답 구조
  • 오류 응답 (400 Bad Request) - 5.2와 동일한 오류 구조
  • 오류 응답 (401 Unauthorized) - 6.1과 동일한 오류 구조
  • 오류 응답 (404 Not Found) - 5.1과 동일한 오류 구조

6.3 현재 사용자의 모바일 설정 초기화​

  • HTTP 메서드: POST
  • 경로: /v1/mobile/me/settings/reset
  • Headers:
    • Authorization: Bearer {accessToken}

응답 (Response)​

  • 성공 응답 (200 OK) - 5.1과 동일한 응답 구조
  • 오류 응답 (401 Unauthorized) - 6.1과 동일한 오류 구조
  • 오류 응답 (404 Not Found) - 5.1과 동일한 오류 구조

7. 관리자 AppSettings 관리 API​

7.1 AppSettings 새 버전 생성​

  • HTTP 메서드: POST
  • 경로: /v1/mobile/admin/app-settings
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken} (관리자 권한 필요)

요청 (Request)​

{
  "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으로 업데이트"
}

응답 (Response)​

  • 성공 응답 (201 Created)
{
  "id": "new-settings-uuid-789",
  "version": 16,
  "systemSettings": {
    "globalConfig": {
      "sessionTimeoutMinutes": 30,
      "maxUploadSizeMB": 10
    }
  },
  "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": "이메일"
    }
  ],
  "lastUpdatedAt": 1747570000
}
  • 오류 응답 (401 Unauthorized)
{
  "code": 2001,
  "message": "UNAUTHORIZED",
  "detail": "관리자 권한이 필요합니다."
}
  • 오류 응답 (400 Bad Request)
{
  "code": 8001,
  "message": "INVALID_APP_SETTINGS",
  "detail": "유효하지 않은 AppSettings 데이터입니다."
}

8. AppSettings 변경 이력 관리 API​

8.1 AppSettings 변경 이력 조회​

  • HTTP 메서드: GET
  • 경로: /v1/mobile/app-settings/{settingsId}/history
  • Headers:
    • Authorization: Bearer {accessToken} (관리자 권한 필요)
  • Query Parameters:
    • page: 페이지 번호 (선택, 기본값: 1)
    • limit: 페이지당 항목 수 (선택, 기본값: 20, 최대: 100)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "data": [
    {
      "id": "history-uuid-123",
      "appSettingsId": "settings-uuid-456",
      "version": 3,
      "operationType": "UPDATE",
      "changedAt": 1747557000000,
      "changedBy": "admin@weltcorp.com",
      "changeReason": "모바일 버전 정보 업데이트",
      "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" }
        }
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 89,
    "itemsPerPage": 20
  }
}

8.2 특정 버전 AppSettings 이력 조회​

  • HTTP 메서드: GET
  • 경로: /v1/mobile/app-settings/{settingsId}/history/{version}
  • Headers:
    • Authorization: Bearer {accessToken} (관리자 권한 필요)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "history-uuid-123",
  "appSettingsId": "settings-uuid-456",
  "version": 2,
  "operationType": "UPDATE",
  "systemSettings": { /* 변경 시점의 시스템 설정 */ },
  "featureFlags": [ /* 변경 시점의 기능 플래그 */ ],
  "mobile": { /* 변경 시점의 모바일 버전 정보 */ },
  "changedAt": 1747500000000,
  "changedBy": "system",
  "changeReason": "자동 업데이트",
  "originalCreatedAt": 1747400000000,
  "originalUpdatedAt": 1747500000000
}

8.3 AppSettings 새 버전 생성​

  • HTTP 메서드: POST
  • 경로: /v1/mobile/app-settings/new-version
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken} (관리자 권한 필요)

요청 (Request)​

{
  "systemSettings": {
    "globalConfig": {
      "sessionTimeoutMinutes": 30,
      "maxUploadSizeMB": 10
    }
  },
  "featureFlags": [
    {
      "name": "enableNewSleepTracking",
      "isEnabled": true,
      "description": "New sleep tracking functionality"
    }
  ],
  "mobile": {
    "android": {
      "latest": { "code": "13", "name": "1.2.16" },
      "min": { "code": "11", "name": "1.2.14" }
    },
    "iOS": {
      "latest": { "build": 58, "name": "1.2.16" },
      "min": { "build": 57, "name": "1.2.15" }
    }
  },
  "reason": "모바일 앱 최신 버전 업데이트"
}

응답 (Response)​

  • 성공 응답 (201 Created)
{
  "id": "settings-uuid-789",
  "version": 4,
  "systemSettings": { /* 새 버전의 시스템 설정 */ },
  "mobile": { /* 새 버전의 모바일 정보 */ },
  "createdAt": 1747570000000,
  "updatedAt": 1747570000000,
  "message": "새 버전의 AppSettings가 성공적으로 생성되었습니다. 이전 버전은 이력에 보관되었습니다."
}

8.4 AppSettings 롤백​

  • HTTP 메서드: POST
  • 경로: /v1/mobile/app-settings/{settingsId}/rollback
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer {accessToken} (관리자 권한 필요)

요청 (Request)​

{
  "targetVersion": 2,
  "reason": "이전 버전으로 롤백 필요"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "settings-uuid-456",
  "version": 4,
  "rollbackedFrom": 3,
  "rollbackedTo": 2,
  "mobile": { /* 롤백된 버전의 모바일 정보 */ },
  "changedAt": 1747560000000,
  "changedBy": "admin@weltcorp.com",
  "message": "버전 2로 성공적으로 롤백되었습니다."
}

8.5 AppSettings 감사 리포트 생성​

  • HTTP 메서드: GET
  • 경로: /v1/mobile/app-settings/audit-report
  • Headers:
    • Authorization: Bearer {accessToken} (감사 권한 필요)
  • Query Parameters:
    • startDate: 시작 날짜 (필수, ISO 8601 형식)
    • endDate: 종료 날짜 (필수, ISO 8601 형식)
    • format: 리포트 형식 (선택, 기본값: json, 옵션: json, csv)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "reportId": "audit-report-uuid-789",
  "period": {
    "startDate": "2025-01-01T00:00:00Z",
    "endDate": "2025-01-31T23:59:59Z"
  },
  "summary": {
    "totalChanges": 45,
    "creations": 2,
    "updates": 41,
    "deletions": 2,
    "rollbacks": 3
  },
  "changes": [
    {
      "settingsId": "settings-uuid-456",
      "version": 3,
      "operationType": "UPDATE",
      "changedAt": 1747557000000,
      "changedBy": "admin@weltcorp.com",
      "changeReason": "모바일 버전 정보 업데이트"
    }
  ],
  "generatedAt": 1747600000000,
  "generatedBy": "audit@weltcorp.com"
}

9. 오류 코드​

Mobile 도메인 API에서 사용하는 주요 오류 코드는 다음과 같습니다.

HTTP 상태 코드오류 코드 (Mobile: 8xxx)메시지설명
5008000SERVER_ERROR서버 내부 오류
4008001INVALID_INPUT_DATA요청 파라미터가 유효하지 않습니다
4008002INVALID_PLATFORM지원하지 않는 플랫폼입니다
4008003INVALID_APP_VERSION앱 버전 형식이 유효하지 않습니다
4008004UNSUPPORTED_OS_VERSION지원하지 않는 OS 버전입니다
401(Auth) 2001UNAUTHORIZED인증이 필요합니다
403(Auth) 2060PERMISSION_DENIED요청한 작업/리소스에 대한 권한이 없습니다
4048021AGREEMENT_NOT_FOUND요청한 약관을 찾을 수 없습니다
4008022AGREEMENT_VERSION_NOT_FOUND요청한 버전의 약관을 찾을 수 없습니다
4048031QUESTIONNAIRE_NOT_FOUND요청한 설문지를 찾을 수 없습니다
4008032QUESTIONNAIRE_VERSION_NOT_FOUND요청한 버전의 설문지를 찾을 수 없습니다
4048041ANNOUNCEMENT_NOT_FOUND요청한 공지사항을 찾을 수 없습니다
403(Auth) 2052TOKEN_REFRESH_FORBIDDEN토큰 갱신이 거부되었습니다
4048061USER_MOBILE_SETTINGS_NOT_FOUND사용자 모바일 설정을 찾을 수 없습니다
4008062INVALID_MOBILE_SETTINGS유효하지 않은 모바일 설정 값입니다
4048071APP_SETTINGS_HISTORY_NOT_FOUND요청한 AppSettings 변경 이력을 찾을 수 없습니다
4008072INVALID_HISTORY_VERSION유효하지 않은 이력 버전 번호입니다
4038073HISTORY_ACCESS_DENIEDAppSettings 변경 이력에 접근할 권한이 없습니다
4008074INVALID_ROLLBACK_VERSION롤백할 수 없는 버전입니다
4098075ROLLBACK_CONFLICT롤백 중 충돌이 발생했습니다
4008076INVALID_AUDIT_PERIOD유효하지 않은 감사 기간입니다
5008091APP_SETTINGS_ERROR앱 설정 정보 조회 중 오류가 발생했습니다
5008099UNKNOWN_MOBILE_ERROR알 수 없는 Mobile 도메인 오류가 발생했습니다

참고: 위 목록은 Mobile 도메인 고유 오류 중심으로 작성되었으며, Auth 도메인 오류 등 다른 공통 오류 코드도 함께 사용될 수 있습니다.

10. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-01-03bok@weltcorp.com최초 작성
0.2.02025-06-09bok@weltcorp.com앱 설정 응답에 learningContent 섹션 추가 - Learning 콘텐츠 버전 관리 지원
0.3.02025-07-11bok@weltcorp.com사용자 모바일 설정 API 추가 (조회/수정/초기화) - UserMobileSettings 관리
0.3.12025-07-11bok@weltcorp.com에러 코드 정리: Mobile 도메인 8xxx 범위 정리, TOKEN_REFRESH_FORBIDDEN을 Auth 도메인(2052)으로 이동
0.3.22025-07-11bok@weltcorp.comSERVER_ERROR (8000) 복원 - 각 도메인별 서버 에러 코드 필요
0.4.02025-07-11bok@weltcorp.com현재 사용자 기반 모바일 설정 API (/me) 추가 - JWT 토큰에서 userId 추출하여 자신의 설정 관리
0.5.02025-08-03bok@weltcorp.com모바일 버전 정보 구조 개선 - androidMinVersion/iOSMinVersion을 mobile 객체로 대체, latest/min 버전 및 code/build 정보 추가
0.6.02025-08-03bok@weltcorp.comAppSettings 변경 이력 조회 API 추가 - 이력 조회, 버전별 조회, 롤백, 감사 리포트 API
0.6.12025-08-03bok@weltcorp.comAppSettings 구조 개선 - Update API 제거, 새 버전 생성 방식으로 변경 (Immutable 버전 관리)
0.6.22025-08-03bok@weltcorp.com사용자 AppSettings 추적 기능 추가 - API 호출 시 UserMobileSettings에 자동 추적 정보 저장
0.6.32025-08-03bok@weltcorp.comUserMobileSettings 업데이트 API에 AppSettings 추적 필드 추가 - currentAppSettingsId, currentAppSettingsVersion 선택적 필드
0.6.42025-08-03bok@weltcorp.comAppSettings API 응답에 version 필드 추가 - 클라이언트가 버전 정보를 정확히 추적할 수 있도록 개선
0.7.02025-08-03bok@weltcorp.com관리자 AppSettings 관리 API 추가 - POST /v1/mobile/admin/app-settings로 새 버전 생성 기능