11 KiB

Raw Blame History

from

date

type

status

version

인간 서버 개발자 업무 지시서 (요약판 v1.1)

대상: 인간 서버 개발자 (수상한잡화점 서버 파트 합류 예정) 읽는 시간: 5~7분 완독 가능 수준으로 축약 v1.1 변경 요지: (1) 어뷰징 판정 클라 100% 책임으로 확정 (PD님 재결정). 서버는 클라가 보내준 판정 플래그만 수신하여 지급 거부. (2) v1.0 446줄을 요약판으로 전면 재작성. 세부 원문은 초안 공유/소통/완료/2026-04-17_RPT_서버역할_정리_초안.md 참조.

0. 1페이지 개요

프로젝트: 수상한잡화점 (로그라이크 RPG, Unity 2022+, 모바일)
서버 스택: PlayFab 기반 (Title API·CloudScript·Leaderboard·Profiles·Mail) — 본 지시서는 PlayFab 유지 전제
역할 범위: ① 재화 SOT 서버 검증·지급 ② 랭킹 저장·조회 ③ 우편·IAP 영수증 검증 ④ 서버 시간 기준 리셋
어뷰징 판정: 클라 100% 책임. 서버는 판정 결과(플래그) 수신 시 지급 거부만 수행 (섹션 5 참조)
현 상태: 서버 Critical 3건 보류 중(PD 지시 로그 #2), 인간 개발자 배정 후 재개

기본 원칙 4종 (PD 확정, 변경 불가)

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

1. 서버 스택 현황

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

2. 서버 관리 데이터 카테고리

#	도메인	주요 필드	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	랭킹	PlayFab Leaderboard	서버 저장
7	우편	CloudScript 기반	서버 SOT
8	시즌·패스	신규 정의 필요	기획팀 SOT 정의 후 구체화

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

재화 사용·획득 → 서버 응답 필수
- 클라: 사용·획득 요청 전송 / 서버: 잔고 검증·차감·응답 (또는 지급·응답)
- 서버 거부 시 클라 롤백
미션 클리어 → 클라 판단, 재화 보상은 서버 지급
- 클라: 조건 체크·카운트 누적·달성 판정 / 서버: 보상 수령 요청 수신 시 지급
랭킹 등록 → 클라가 계산한 값을 서버가 그대로 저장
- 클라: 점수·메타정보 계산·전송 / 서버: Leaderboard 저장

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

4. 핵심 API 3종

4-1. `Save_StageResult` (복원 필수 — 샘플)

유형: 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`	`Save_IngameStart` 세션 없음·만료	재로그인 유도
`StageLocked`	해당 스테이지 미해금	경로 이탈 처리

4-2. `Grant_MissionReward`

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

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

현 코드에서 등록 호출처 미확인 → 인간 개발자가 재구축. 엔드포인트명 예: Submit_RankingEntry.
클라 전송 점수·메타정보 그대로 Leaderboard 저장. 세부는 D-3 설계 문서에서 확정.

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

2026-04-17 PD님 직접 재확정: 어뷰징 판정은 클라이언트 100% 책임. 서버는 판정 결과(플래그)만 받아 처리.

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

서버 역할 (최소):

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

서버가 하지 않는 것:

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

세부 설계: 기획팀 공유/소통/기획팀→PM/2026-04-17_어뷰징판정_솔루션_기획서_v1.md 참조 (클라이언트팀 구현 시 필요 시 서버 개발자와 플래그 인터페이스만 협의).

6. 환경 셋업 체크리스트

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

7. 결정 대기 2건 (PD·PM 후속)

PD-③ 서버 스택 유지 여부 — PlayFab 유지(A안, 본 지시서 전제) vs 하이브리드(B안) vs 자체 서버(C안). 인간 개발자 배정 후 기술 선호·경험 수렴하여 PM 경유 PD님 보고.
PD-④ 세이브 SOT 전환 범위 — 현 "로컬 1차 + 클라우드 보조" 하이브리드 유지(A안) vs 서버 1차 SOT(B안). 개발팀 의견: 수상한잡화점 현 시점 A안, 차기 프로젝트 B안 (코어 프레임워크 반영).

PD-⑤ 일일/주간 리셋 시간 기준 — 서버 시간 기준 전환 확정 (개발팀 재량, [필수 작업]).

8. 용어집

용어	뜻
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	어뷰징·치트 방지 체계. 본 프로젝트는 클라 판정 + 서버는 플래그 수신 시 지급 거부

9. 기각안 (P24·P27 결정·설계 엔트리 필수)

"어뷰징 경계값 서버 보관·검증" 안 (v1.0 B-7 구조) — PD님 재결정으로 기각. 서버가 경계값 테이블을 Title Data에 적재하고 수치 검증하는 구조는 폐기. 어뷰징은 클라 주도 작업이며 서버 개발자 작업 스펙 아님.
"상세 설계 전부 포함한 장문 지시서" 안 (v1.0 446줄) — 인간 개발자 파악 시간 낭비. 요약판 원칙으로 전환 (PD님 지시).
"비재화 보상 유지" 안 — PD 확정(모든 보상=재화)으로 전제 소멸. 기각.
"PlayFab 전면 폐기 + 자체 서버 전면 신규" 안 — 현 보류 항목 해소 전 범위 확대 리스크. PD-③ 옵션으로만 제시.
"배정 전 세부 API 스펙 전량 확정" 안 — 배정된 개발자의 기술 선호 반영 없는 스펙은 재작업 리스크. 본 지시서는 원칙·경계·샘플 1건까지, 세부는 배정 후 설계 문서에서 확정.

10. 변경 이력

일시	버전	작성자	요지
2026-04-17	v1.0	개발팀장	최종본 초판 (B-7 어뷰징 방지 서버 연계 포함). PD님 어뷰징 책임 재확정으로 대체됨
2026-04-17	v1.1	개발팀장	요약판 재작성: (1) 어뷰징 판정 클라 100% 책임 확정 반영 — 서버는 플래그 수신만 (섹션 5). (2) 446줄 → 150줄 이내 축약. (3) 샘플 API 1건 유지, 템플릿·매트릭스 세부는 D-3 설계 문서로 이관

서명: 개발팀장 (인간 서버 개발자 배정 시 본 지시서를 출발점으로 사용) DOCX 변환: PM이 anthropic-skills:docx로 재생성 후속 트래킹: 개발팀 PD 지시 로그 #30 v1.1 갱신 + #신규 "어뷰징 책임 재확정·요약판 재작성" 등록·완료

11 KiB Raw Blame History