---
from: 개발팀장
to: PM (DOCX 변환 → 인간 서버 개발자)
date: 2026-04-17
type: 지시서
status: 완료
version: v1.1
tags: [서버개발자지시서, 요약판, 서버역할, 클라서버경계, PlayFab, 수상한잡화점]
related: [C8, C11, C28, C29, C30, P13, P14, P18]
depends_on: [PD-#2, PD-#30, PD-#신규_어뷰징책임_재확정]
supersedes: v1.0 (2026-04-17 동일 경로, PD님 어뷰징 책임 재확정·요약판 재작성 지시로 대체)
---

# 인간 서버 개발자 업무 지시서 (요약판 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. 모든 보상은 **재화 형태로 지급**. 비재화 보상 없음 → 모든 보상은 서버 검증·지급 대상
2. 재화 사용·획득은 **항상 서버 응답 필수**. 클라 단독 처리 금지
3. 미션 클리어 판단은 **클라 재량**. 서버는 보상 지급 시점에만 개입
4. 랭킹 등록은 **클라 정보를 서버가 그대로 저장**

---

## 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

1. **재화 사용·획득 → 서버 응답 필수**
   - 클라: 사용·획득 요청 전송 / 서버: 잔고 검증·차감·응답 (또는 지급·응답)
   - 서버 거부 시 클라 롤백

2. **미션 클리어 → 클라 판단, 재화 보상은 서버 지급**
   - 클라: 조건 체크·카운트 누적·달성 판정 / 서버: 보상 수령 요청 수신 시 지급

3. **랭킹 등록 → 클라가 계산한 값을 서버가 그대로 저장**
   - 클라: 점수·메타정보 계산·전송 / 서버: Leaderboard 저장

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

---

## 4. 핵심 API 3종

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

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

**요청 파라미터** (예시):
```json
{
  "difficulty": 2,
  "chapter": 3,
  "stageId": 47,
  "starCount": 3,
  "clearTimeMs": 125000,
  "droppedItems": [{"itemId": 101, "amount": 500}],
  "is_abuse_flag": false
}
```

**응답 (성공)**:
```json
{
  "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 후속)

1. **PD-③ 서버 스택 유지 여부** — PlayFab 유지(A안, 본 지시서 전제) vs 하이브리드(B안) vs 자체 서버(C안). 인간 개발자 배정 후 기술 선호·경험 수렴하여 PM 경유 PD님 보고.
2. **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 결정·설계 엔트리 필수)

1. **"어뷰징 경계값 서버 보관·검증" 안 (v1.0 B-7 구조)** — PD님 재결정으로 기각. 서버가 경계값 테이블을 Title Data에 적재하고 수치 검증하는 구조는 폐기. 어뷰징은 **클라 주도 작업**이며 서버 개발자 작업 스펙 아님.
2. **"상세 설계 전부 포함한 장문 지시서" 안 (v1.0 446줄)** — 인간 개발자 파악 시간 낭비. 요약판 원칙으로 전환 (PD님 지시).
3. **"비재화 보상 유지" 안** — PD 확정(모든 보상=재화)으로 전제 소멸. 기각.
4. **"PlayFab 전면 폐기 + 자체 서버 전면 신규" 안** — 현 보류 항목 해소 전 범위 확대 리스크. PD-③ 옵션으로만 제시.
5. **"배정 전 세부 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 갱신 + #신규 "어뷰징 책임 재확정·요약판 재작성" 등록·완료