NerdNavis_AiDev
/
BurningTimesAi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
BurningTimesAi/공유/소통/완료/2026-04-17_서버_작업_참고자료.md

9.1 KiB
Raw Blame History

from to date type status version audience tags
개발팀장 PM (DOCX 변환 → 외부 서버 작업자) 2026-04-17 참고자료 완료 v1.2 외부 서버 작업자
서버참고자료
수상한잡화점
서버경계
데이터SOT

서버 작업 참고 자료 — 수상한잡화점

본 문서의 성격: 수상한잡화점 프로젝트 서버 파트 작업자에게 전달하는 참고 자료입니다. 공식 업무 지시서가 아니라, 현 프로젝트의 서버 현황·데이터 카테고리·클라-서버 경계 원칙·참고용 API 샘플을 정리한 배경 문서입니다. 세부 구현 방향과 서버 스택 선택은 작업자가 판단·제안할 수 있는 열린 영역으로 남겨져 있습니다. 권장 완독 시간: 5~7분

0. 1페이지 개요

  • 프로젝트: 수상한잡화점 (로그라이크 RPG, Unity 2022+, 모바일)
  • 현 서버 스택: PlayFab 사용 중 (Title API·CloudScript·Leaderboard·Profiles·Mail). 유지·전환·하이브리드 여부는 열린 결정 사항
  • 서버 담당 영역 (현 프로젝트 범위): ① 재화 SOT 서버 검증·지급 ② 랭킹 저장·조회 ③ 우편·IAP 영수증 검증 ④ 서버 시간 기준 리셋
  • 어뷰징 판정 책임: 클라이언트 주도. 서버는 판정 결과(플래그) 수신 시 지급 거부 처리만 수행 (섹션 5 참조)
  • 현 상태: 서버 Critical 보안 3건 보류 중, 서버 작업자 합류 시점 재개 예정

프로젝트 기본 원칙 4종 (확정, 변경 불가)

  1. 모든 보상은 재화 형태로 지급. 비재화 보상(칭호·스킨·장비·PC 등) 없음 → 모든 보상은 서버 검증·지급 대상
  2. 재화 사용·획득은 항상 서버 응답 필수. 클라 단독 처리 금지
  3. 미션 클리어 판단은 클라 재량. 서버는 보상 지급 시점에만 개입
  4. 랭킹 등록은 클라 정보를 서버가 그대로 저장

1. 현 서버 스택 현황 (PlayFab 사용 중)

구성 요소 현 상태 비고
PlayFab 인증·UserData·TitleData 사용 중 -
CloudScript 사용 중 (Get_UserInfo·Get_MailList·Get_MailReward 등) 함수 dump 후 버전 관리 편입 필요
Leaderboard (Progression API) 읽기 경로 존재 (GetLeaderboard·GetLeaderboardAroundEntity) 등록 경로 미확인 → 재설계 필요
Mail Get_AllMail CloudScript 존재 재화 보상 우편 처리
Save_StageResult (스테이지 완료 처리) 비활성 상태 (주석 처리) 복원·신규 설계 필요
InappInfo.cs (IAP 영수증) 비활성 상태 재활성화 + ValidateGooglePlayPurchase 연결
Server_Live_ID·Server_Dev_ID 코드 주석 처리 상태 인수인계 시 복구

스택 선택은 열린 사안: 본 섹션은 "현재 이렇게 구현되어 있다"는 현황 기술입니다. PlayFab 유지, 하이브리드 구성, 별도 스택으로의 전환 등 서버 아키텍처 방향은 작업자 판단·제안 가능 영역입니다.

2. 서버 관리 데이터 카테고리 (8개 도메인)

# 도메인 주요 필드 SOT 방향
1 재화 인벤토리 dic_Item[itemid] = amount (Gold·Soul 등) 서버 SOT 필수
2 PC(캐릭터) 보유 dic_PC[pcid] — 레벨·경험치·각성 서버 SOT
3 장비·카드 Equipment·dic_Card[cardid] 서버 SOT
4 스테이지 진행 StageData.dic_stagedata[diff][chapter][stageid].Star 서버 SOT (보상 지급 연결)
5 미션·출석 Mission.dic_Mission[type]·RewardAttandanceDay 서버 SOT (재화 보상)
6 랭킹 Leaderboard (현 PlayFab) 서버 저장
7 우편 CloudScript 기반 (현 PlayFab) 서버 SOT
8 시즌·패스 신규 정의 필요 기획 SOT 정의 후 구체화

3. 클라/서버 경계 — 핵심 원칙 3

  1. 재화 사용·획득 → 서버 응답 필수

    • 클라: 사용·획득 요청 전송 / 서버: 잔고 검증·차감·응답 (또는 지급·응답)
    • 서버 거부 시 클라 롤백

  2. 미션 클리어 → 클라 판단, 재화 보상은 서버 지급

    • 클라: 조건 체크·카운트 누적·달성 판정 / 서버: 보상 수령 요청 수신 시 지급

  3. 랭킹 등록 → 클라가 계산한 값을 서버가 그대로 저장

    • 클라: 점수·메타정보 계산·전송 / 서버: Leaderboard 저장

보상 통일: 모든 보상은 재화 단위. 비재화 보상(칭호·스킨·장비·PC 등) 없음.

4. 핵심 API 참고 예시

아래는 현 구현 참고용 샘플입니다. 서버 스택·구현 방식이 변경될 경우 인터페이스는 재설계 대상입니다. "반드시 이 방식을 유지해야 한다"는 의미가 아닙니다.

4-1. Save_StageResult (복원 필요 — 현 PlayFab CloudScript 기준 샘플)

유형: CloudScript 함수 / 호출 권한: Client (LoginSession 유효) 역할: 스테이지 클리어 결과를 저장하고 재화를 지급

요청 파라미터 (예시):

{
  "difficulty": 2,
  "chapter": 3,
  "stageId": 47,
  "starCount": 3,
  "clearTimeMs": 125000,
  "droppedItems": [{"itemId": 101, "amount": 500}],
  "is_abuse_flag": false
}

응답 (성공):

{
  "status": "ok",
  "grantedRewards": [{"itemId": 101, "amount": 500}],
  "newStar": 3,
  "stageProgress": {"maxStageId": 47}
}

응답 (실패):

에러 코드 조건 클라 처리
AbuseFlagged is_abuse_flag: true 수신 지급 거부, 기록 저장 (섹션 5)
SessionInvalid 세션 없음·만료 재로그인 유도
StageLocked 해당 스테이지 미해금 경로 이탈 처리

4-2. Grant_MissionReward

  • 미션 보상 재화 지급. 클라가 미션 완료 판정 후 수령 요청 시 서버가 지급·응답
  • is_abuse_flag 동일 수용 (클라가 자체 판정 시 true 동봉 가능)

4-3. 랭킹 등록 경로 (신규 설계 필요)

  • 현 코드에서 등록 호출처 미확인 → 재구축 필요. 엔드포인트명 예: Submit_RankingEntry
  • 클라 전송 점수·메타정보 그대로 Leaderboard 저장. 세부는 설계 단계에서 확정

5. 참고: 어뷰징 방지 체계 (클라 주도, 서버 최소 역할)

프로젝트 정책: 어뷰징 판정은 클라이언트 책임. 서버는 판정 결과(플래그)만 받아 처리합니다.

판정 책임: 클라이언트 (경계값 보관·수치 검증 전부 클라에서 수행)

서버 역할 (최소):

  • 재화 지급 요청 페이로드에 is_abuse_flag: true 가 포함된 경우, 해당 지급을 거부하고 기록 저장
  • 플래그 저장 위치: 현 스택 기준 Profile 필드 또는 별도 모니터링 엔드포인트 (구현 단계에서 결정)
  • 관리자 알림 채널(Slack Webhook·이메일 등) 연계는 구현 단계에서 결정

서버가 하지 않는 것 (프로젝트 정책):

  • 경계값 테이블 보관 (Title Data 등에 적재 불필요)
  • 경계값과 클라 전송 수치 비교 검증
  • 어뷰징 판정 로직 자체

협의 범위: 클라이언트팀 구현 시 필요하면 서버 작업자와 플래그 인터페이스 스펙만 협의합니다 (판정 로직 자체는 협의 대상 아님).

6. 환경 셋업 체크리스트

  • 현 서버 스택(PlayFab) 접근 권한 수령 (Title ID 인수·Game Manager 대시보드·CloudScript revision 접근) — 현 스택 유지 시
  • 현 배포 CloudScript 전문 dump → 버전 관리 편입 (경로 후보: 코어코드/수상한잡화점_서버/)
  • Unity 프로젝트 clone + git fetch origin && git pull
  • Unity 에디터 설치 (프로젝트 버전 기준)
  • 현 PlayFab SDK 연동 확인 (빌드·실행 1회 성공)
  • IDE (VS Code 또는 JetBrains Rider) + Node.js (CloudScript 로컬 테스트용)

7. 용어집

용어 뜻
PlayFab Microsoft BaaS. 본 프로젝트가 현재 사용 중인 서버 스택
CloudScript PlayFab 서버 사이드 JavaScript 실행 환경
Title Data PlayFab Title 단위 공용 설정 저장소
UserData PlayFab 유저별 서버 저장소
Leaderboard PlayFab 순위표 서비스 (Progression API)
ObscuredType CodeStage.AntiCheat 로컬 변조 방어 타입. 서버 검증 대체재는 아님
ServerData 수상한잡화점 프로젝트 클래스(ServerClass.cs). 유저 데이터 SOT 로컬 표현
SOT Source of Truth. 데이터의 단일 진실 근원
AntiCheat 어뷰징·치트 방지 체계. 본 프로젝트는 클라 판정 + 서버는 플래그 수신 시 지급 거부

8. 변경 이력

일시 버전 요지
2026-04-17 v1.2 외부 서버 작업자용 참고 자료로 중립화 — PlayFab 전제 제거(현 사용 중 상태로만 기술), 조직 내부 프로세스 표현 제거, "지시서" → "참고 자료"로 성격 재정의

용도: 서버 작업자 합류 시 본 자료를 출발점으로 사용. 세부 서버 스택 선택, 아키텍처 방향, API 스펙 확정은 배정 후 설계 단계에서 진행.