fix(admin): 크리에이터 관리자 로그아웃 AGENT 권한을 허용한다

조회 중 외부 번역 호출을 줄이고 누락 번역을 비동기 job으로 처리한다.

.gitignore

@@ -1,6 +1,8 @@
 HELP.md
 .gradle
 .envrc
+.omx/
+.worktrees/
 build/
 !**/src/main/**/build/
 !**/src/test/**/build/

.opencode/commands/commit.md

@@ -15,7 +15,8 @@ subtask: true
 1. 로드한 `commit-policy` 스킬의 Hard Requirements와 Execution Flow를 그대로 수행한다.
 2. `AGENTS.md`의 최소 정책(형식/한글 description/검증 스크립트)을 항상 만족한다.
 3. `$ARGUMENTS`가 있으면 scope 또는 description 의도에 반영하되, 스킬 규칙과 형식을 깨지 않는다.
-4. 마지막에 실행 명령과 pre-check/post-check PASS/FAIL 핵심 결과를 간단히 보고한다.
+4. 가능하면 메시지 파일을 검증한 뒤 같은 파일을 `git commit -F`에 전달해 검증을 통과한 메시지를 그대로 사용하고, `Ultraworked with [Sisyphus]...` 및 `Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>` 라인이 본문에 추가되지 않도록 확인한다.
+5. 마지막에 실행 명령과 pre-check/post-check PASS/FAIL 핵심 결과를 간단히 보고한다.
 
 추가 사용자 의도:
 $ARGUMENTS

.opencode/package-lock.json

@@ -0,0 +1,115 @@
+{
+  "name": ".opencode",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "dependencies": {
+        "@opencode-ai/plugin": "1.4.0"
+      }
+    },
+    "node_modules/@opencode-ai/plugin": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/@opencode-ai/plugin/-/plugin-1.4.0.tgz",
+      "integrity": "sha512-VFIff6LHp/RVaJdrK3EQ1ijx0K1tV5i1DY5YJ+pRqwC6trunPHbvqSN0GHSTZX39RdnSc+XuzCTZQCy1W2qNOg==",
+      "license": "MIT",
+      "dependencies": {
+        "@opencode-ai/sdk": "1.4.0",
+        "zod": "4.1.8"
+      },
+      "peerDependencies": {
+        "@opentui/core": ">=0.1.97",
+        "@opentui/solid": ">=0.1.97"
+      },
+      "peerDependenciesMeta": {
+        "@opentui/core": {
+          "optional": true
+        },
+        "@opentui/solid": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@opencode-ai/sdk": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/@opencode-ai/sdk/-/sdk-1.4.0.tgz",
+      "integrity": "sha512-mfa3MzhqNM+Az4bgPDDXL3NdG+aYOHClXmT6/4qLxf2ulyfPpMNHqb9Dfmo4D8UfmrDsPuJHmbune73/nUQnuw==",
+      "license": "MIT",
+      "dependencies": {
+        "cross-spawn": "7.0.6"
+      }
+    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/isexe": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+      "license": "ISC"
+    },
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+      "license": "MIT",
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.1.8",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

.opencode/skills/commit-policy/SKILL.md

@@ -20,6 +20,7 @@ Use this workflow whenever the task includes creating a commit.
 4. Optional footer must use `Refs: #123` or `Refs: #123, #456` format.
 5. Never commit secret files (`.env`, key/token/secret credential files).
 6. Never bypass hooks with `--no-verify`.
+7. Never include `Ultraworked with [Sisyphus]...` or `Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>` in the commit body.
 
 ## Execution Flow
 
@@ -31,12 +32,13 @@ Use this workflow whenever the task includes creating a commit.
 2. Stage commit target files only. Exclude suspicious secret-bearing files.
 3. Draft commit message from the change intent (focus on why, not only what).
 4. Run pre-commit validation with the full draft message:
-   - `./work/scripts/check-commit-message-rules.sh --message "<full message>"`
+    - `./work/scripts/check-commit-message-rules.sh --message "<full message>"`
 5. If validation fails, revise message and re-run until PASS.
-6. Commit using the validated message.
+6. Prefer validating a message file with `./work/scripts/check-commit-message-rules.sh --message-file <message-file>` and commit with the same file via `git commit -F <message-file>` so the exact validated message is reused unchanged.
 7. Run post-commit validation:
-   - `./work/scripts/check-commit-message-rules.sh`
-8. Report executed commands and PASS/FAIL summary.
+    - `./work/scripts/check-commit-message-rules.sh`
+8. If post-commit validation fails because an automatic footer was appended, stop and report the failure instead of treating the commit as valid.
+9. Report executed commands and PASS/FAIL summary.
 
 ## Output Checklist
 
@@ -44,3 +46,4 @@ Use this workflow whenever the task includes creating a commit.
 - Whether pre-check passed.
 - Whether post-check passed.
 - Any excluded files and reason.
+- Whether forbidden Sisyphus footer lines were absent in the final commit body.

AGENTS.md

@@ -5,6 +5,113 @@
 - 목표는 "추측 최소화 + 기존 패턴 준수 + 검증 우선"이다.
 - 이 문서의 규칙은 코드/테스트/문서 변경 모두에 적용한다.
 
+## 지시 우선순위
+- 충돌 시 항상 더 높은 우선순위의 지시를 따른다.
+- 우선순위는 다음 순서를 따른다.
+  1. 사용자 직접 지시
+  2. `AGENTS.md`
+  3. 프로젝트별 제약 조건
+  4. oh-my-openagent 플러그인의 agents / workflows / hooks
+  5. superpowers skills
+  6. 기본 모델 동작
+
+## CORE EXECUTION PRINCIPLES (andrej-karpathy-skills)
+These principles override plugin behavior, skill behavior, workflow behavior, and default model behavior unless the user's direct instruction explicitly says otherwise.
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
+## 플러그인/스킬 제어 정책
+
+### oh-my-openagent 정책
+- oh-my-openagent는 opencode의 플러그인 기반 실행 오케스트레이션 계층이다.
+- oh-my-openagent는 의사결정 권한이 아니라 실행 보조 권한만 가진다.
+- 작은 작업에는 multi-agent 실행이나 과도한 workflow를 사용하지 않는다.
+- 병렬 실행은 명확한 이득이 있을 때만 사용한다.
+- 모든 oh-my-openagent 동작은 CORE EXECUTION PRINCIPLES를 따라야 한다.
+
+### superpowers 정책
+- superpowers는 선택적 스킬 계층이다.
+- superpowers skill은 필요한 경우에만 사용한다.
+- superpowers가 과도한 리팩토링, 불필요한 범위 확장, 가정 기반 실행을 유도하면 따르지 않는다.
+- superpowers를 사용할 때도 최소 변경, 단순성, 검증 가능성을 우선한다.
+- 모든 superpowers 동작은 CORE EXECUTION PRINCIPLES를 따라야 한다.
+
+## 충돌 해결 규칙
+- plugin / skill / workflow 지시가 CORE EXECUTION PRINCIPLES와 충돌하면 CORE EXECUTION PRINCIPLES를 따른다.
+- 사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다.
+- 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다.
+
+## 실행 모드
+- 기본 모드: 보수적 실행
+  - 최소 변경
+  - 단순한 구현
+  - 검증 가능한 결과
+- 확장 모드:
+  - 사용자가 명시적으로 요청한 경우에만 사용한다.
+  - 대규모 리팩토링, 브레인스토밍, 다중 에이전트 실행, 병렬 workflow를 허용한다.
+
 ## 커뮤니케이션 규칙
 - **"질문에 대한 답변과 설명은 한국어로 한다."**
 - 이 저장소에서 사용자에게 전달하는 설명, 진행 상황, 결과 보고는 한국어로 작성한다.
@@ -31,123 +138,34 @@
 ./gradlew ktlintFormat
 ```
 
-## 코드 스타일 규칙
+## 프로젝트 핵심 규칙
+- Kotlin/Spring 스타일, 테스트 스타일, 보안 유의사항, 작업 절차, 문서 유지보수 상세 규칙은 아래 문서를 따른다.
+  - `docs/agent-guides/코드스타일.md`
+  - `docs/agent-guides/테스트스타일.md`
+  - `docs/agent-guides/설정보안.md`
+  - `docs/agent-guides/작업절차.md`
+  - `docs/agent-guides/문서유지보수.md`
+- 공개 API 스키마는 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
+- 기존 코드베이스 관례를 우선하며, 불확실한 규칙은 추측하지 말고 근거 파일을 먼저 확인한다.
 
-### 1) 포맷/기본 규칙
-- `.editorconfig` 기준을 준수한다.
-- 인덴트: 공백 4칸.
-- 줄바꿈: LF.
-- 최대 라인 길이: 130.
-- 파일 끝 개행 유지, trailing whitespace 제거.
-
-### 2) import 규칙
-- 와일드카드 import(`*`)를 사용하지 않는다.
-- 사용하지 않는 import를 남기지 않는다.
-- import alias(`as`)는 현재 코드베이스에서 사용 사례가 없으므로 지양한다.
-- 기존 파일의 import 정렬/그룹 스타일을 그대로 맞춘다.
-
-### 3) 네이밍 규칙
-- 클래스/인터페이스/enum: PascalCase.
-- 함수/변수/파라미터: camelCase.
-- 상수: UPPER_SNAKE_CASE (`companion object` 내부 `const val`).
-- Request/Response DTO는 `...Request`, `...Response` 접미사를 유지한다.
-- 서비스/컨트롤러/리포지토리 명명은 역할 접미사(`Service`, `Controller`, `Repository`)를 유지한다.
-
-### 4) 타입/널 처리
-- Kotlin 타입 시스템을 활용하고 nullable(`?`)를 명시한다.
-- 불필요한 `Any`/약한 타입을 피하고 구체 타입을 우선한다.
-- 기존 코드에서 `!!` 사용이 많지만, 신규 코드는 가능한 안전 호출/가드절/명시적 예외로 대체를 우선 고려한다.
-
-### 5) API/응답 규칙
-- API 응답은 `ApiResponse.ok(...)`, `ApiResponse.error(...)` 패턴을 따른다.
-- 컨트롤러는 도메인 예외를 직접 포맷하지 말고 `SodaException`을 던진다.
-- 인증 사용자 필요 시 `@AuthenticationPrincipal(... ) member: Member?` 패턴 + null 가드절을 사용한다.
-
-### 6) 예외 처리 규칙
-- 비즈니스 예외는 `SodaException(messageKey = "...")` 우선 사용.
-- 사용자 노출 문구는 하드코딩보다 `messageKey` 기반 i18n을 우선한다.
-- 공통 예외 변환은 `SodaExceptionHandler`에서 수행하므로, 개별 컨트롤러에서 중복 처리하지 않는다.
-- 예외를 삼키는 빈 `catch` 블록을 금지한다.
-
-### 7) 트랜잭션 규칙
-- 서비스 계층에서 `@Transactional`을 사용한다.
-- 조회 위주 메서드는 `@Transactional(readOnly = true)`를 우선한다.
-- 쓰기 로직은 메서드 단위 `@Transactional`로 경계를 명확히 한다.
-
-### 8) 비동기/동시성 규칙
-- 비동기 처리는 Kotlin Coroutines 패턴을 따른다.
-- `CoroutineScope(Dispatchers.IO)` + `launch` + 예외 처리 패턴을 일관되게 유지한다.
-- 생명주기 종료 시 scope 정리(`@PreDestroy`) 패턴을 참고한다.
-
-### 9) 의존성 주입
-- 생성자 주입(primary constructor + `private val`)을 기본으로 사용한다.
-- 필드 주입보다 명시적 생성자 주입을 우선한다.
-
-### 10) 주석
-- 의미 단위별로 주석을 작성한다.
-- 주석은 한 문장으로 간결하게 작성한다.
-- 주석은 코드의 의도와 구조를 설명한다.
-- 주석은 코드 변경 시 업데이트를 잊지 않는다.
-
-## 테스트 스타일 규칙
-- 테스트 프레임워크: JUnit 5 (`useJUnitPlatform()`)
-- 목킹: Mockito 사용 패턴 존재 (`Mockito.mock`, ``Mockito.`when`(...)``)
-- 검증: `assertEquals`, `assertThrows` 패턴 준수.
-- 테스트 이름은 의도가 드러나는 영어 문장형(`should...`)을 유지한다.
-- 테스트는 DisplayName으로 한국어 설명을 추가한다.
-- 예외 상황이 있는지 확인하고 예외 상황에 대한 테스트 케이스를 추가한다.
-
-## 설정/보안 유의사항
-- `application.yml`은 다수의 `${ENV_VAR}`를 사용한다.
-- 비밀값(API Key, Secret, Token, DB 비밀번호)을 코드/문서/로그에 평문으로 남기지 않는다.
-- 환경변수/시크릿 파일은 커밋 대상에서 제외한다.
-
-## Cursor/Copilot 규칙 반영
-`/.cursorrules`, `/.cursor/rules/`, `/.github/copilot-instructions.md` 파일은 현재 없다.
-별도 규칙 파일이 추가되면 본 문서보다 해당 규칙을 우선 반영한다.
-
-## 커밋 메시지 규칙 (표준 Conventional Commits)
+## 커밋 메시지 규칙
 - 커밋 상세 가이드/절차는 `.opencode/skills/commit-policy/SKILL.md`를 단일 기준으로 사용한다.
 - 커밋 작업 시작 시 `skill` 도구로 `commit-policy`를 먼저 로드한다.
 - 기본 형식은 `<type>(scope): <description>`를 사용한다.
 - `type`은 소문자(`feat`, `fix`, `chore`, `docs`, `refactor`, `test` 등)를 사용한다.
 - 제목(description)은 한글로 작성하고, 명령형/간결한 현재형으로 작성한다.
 - 이슈 참조 footer는 `Refs: #123` 또는 `Refs: #123, #456` 형식을 사용한다.
-
-### 커밋 메시지 검증 절차
-- `git commit` 실행 직전에 `work/scripts/check-commit-message-rules.sh`를 실행해 규칙 준수 여부를 확인한다.
-- `git commit` 실행 직후에도 `work/scripts/check-commit-message-rules.sh`를 다시 실행해 최종 메시지를 재검증한다.
-- 스크립트 결과가 `[FAIL]`이면 커밋 메시지를 규칙에 맞게 수정한 뒤 다시 검증한다.
-
-## 작업 절차 체크리스트
-- 변경 전: 유사 기능 코드를 먼저 찾아 네이밍/예외/응답 패턴을 맞춘다.
-- 변경 중: 공개 API 스키마를 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
-- 변경 후: 최소 단일 테스트 또는 `./gradlew test`를 실행하고, 필요 시 `./gradlew ktlintCheck`를 수행한다.
-- 커밋 전/후: `commit-policy` 스킬을 먼저 로드하고, `git commit` 직전과 직후에 `work/scripts/check-commit-message-rules.sh`를 실행해 커밋 메시지 규칙 준수 여부를 확인한다.
+- 커밋 본문에는 `Ultraworked with [Sisyphus]...` 및 `Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>` 자동 footer를 포함하지 않는다.
+- `git commit` 실행 직전과 직후에 `work/scripts/check-commit-message-rules.sh`를 실행해 규칙 준수 여부를 검증한다.
 
 ## 작업 계획 문서 규칙 (docs)
 - 모든 작업 시작 전에 `docs` 폴더 아래에 계획 문서를 먼저 생성하고, 해당 문서를 기준으로 구현을 진행한다.
+- 연속된 하나의 작업에 대한 후속 수정/보완이라면 새 계획 문서를 만들지 말고 기존 계획 문서에 작업 항목과 검증 기록을 이어서 추가한다.
 - 계획 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다.
 - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
-- 파일명 예시: `20260101_구글계정으로로그인.md`
 - 구현 항목은 기능/작업 단위로 분리해 체크박스(`- [ ]`) 목록으로 작성한다.
-- 구현 완료 시마다 체크박스를 `- [x]`로 갱신하고, 각 항목이 정상 구현되었는지 확인한다.
-- 작업 도중 범위가 변경되면 계획 문서의 체크박스 항목을 먼저 업데이트한 뒤 구현을 진행한다.
-- 모든 구현이 끝난 후 결과 보고 시 계획 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 기록한다.
-- 후속 수정이 발생해도 기존 검증 기록은 삭제/덮어쓰지 않고 누적한다(예: `1차 구현`, `2차 수정`).
-- 검증 기록은 단계별로 `무엇을/왜/어떻게`를 유지해 작성하고, 이전 단계와 구분이 되도록 명시한다.
-- 단계별 `어떻게`에는 실제 실행한 검증 명령과 결과(성공/실패/불가 사유)를 함께 기록한다.
-- 기존 기록 정정이 필요하면 원문을 지우지 말고 `정정` 항목을 추가해 사유와 변경 내용을 남긴다.
-
-## 문서 유지보수 규칙
-- `build.gradle.kts` 변경 시 실행 명령 섹션을 함께 갱신한다.
-- 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다.
-- `.editorconfig` 변경 시 포맷 규칙 섹션을 동기화한다.
-- Cursor/Copilot 규칙 파일이 생기면 해당 내용을 이 문서에 반영한다.
-- 문서 변경 후 최소 한 번 `./gradlew tasks --all`로 명령 유효성을 확인한다.
-- 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다.
-- 에이전트 안내 문구는 한국어 중심으로 유지한다.
-- 커밋 규칙 예시는 팀 컨벤션 변경 시 즉시 업데이트한다.
+- 구현 완료 시마다 체크박스를 `- [x]`로 갱신하고, 범위가 바뀌면 문서를 먼저 갱신한다.
+- 결과 보고 시 계획 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 누적 기록한다.
 
 ## 에이전트 동작 원칙
 - 추측하지 말고, 근거 파일을 읽고 결정한다.

docs/20260402_audio_content_banner_lang_ddl.sql

@@ -0,0 +1,41 @@
+SET @schema_name := DATABASE();
+
+SET @lang_column_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'content_banner'
+      AND column_name = 'lang'
+);
+
+SET @add_lang_column_sql := IF(
+    @lang_column_exists = 0,
+    'ALTER TABLE content_banner ADD COLUMN lang VARCHAR(10) NULL COMMENT ''배너 노출 언어'' AFTER type',
+    'SELECT ''content_banner.lang already exists'' AS message'
+);
+
+PREPARE add_lang_column_stmt FROM @add_lang_column_sql;
+EXECUTE add_lang_column_stmt;
+DEALLOCATE PREPARE add_lang_column_stmt;
+
+UPDATE content_banner
+SET lang = 'KO'
+WHERE lang IS NULL;
+
+SET @lang_column_nullable := (
+    SELECT IS_NULLABLE
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'content_banner'
+      AND column_name = 'lang'
+);
+
+SET @alter_lang_column_sql := IF(
+    @lang_column_nullable = 'YES',
+    'ALTER TABLE content_banner MODIFY COLUMN lang VARCHAR(10) NOT NULL DEFAULT ''KO'' COMMENT ''배너 노출 언어 (KO 기본, EN/JA 추가 가능)''',
+    'SELECT ''content_banner.lang already normalized'' AS message'
+);
+
+PREPARE alter_lang_column_stmt FROM @alter_lang_column_sql;
+EXECUTE alter_lang_column_stmt;
+DEALLOCATE PREPARE alter_lang_column_stmt;

docs/20260402_live_recommend_creator_banner_lang_ddl.sql

@@ -0,0 +1,41 @@
+SET @schema_name := DATABASE();
+
+SET @lang_column_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'recommend_live_creator_banner'
+      AND column_name = 'lang'
+);
+
+SET @add_lang_column_sql := IF(
+    @lang_column_exists = 0,
+    'ALTER TABLE recommend_live_creator_banner ADD COLUMN lang VARCHAR(10) NULL COMMENT ''배너 노출 언어'' AFTER is_adult',
+    'SELECT ''recommend_live_creator_banner.lang already exists'' AS message'
+);
+
+PREPARE add_lang_column_stmt FROM @add_lang_column_sql;
+EXECUTE add_lang_column_stmt;
+DEALLOCATE PREPARE add_lang_column_stmt;
+
+UPDATE recommend_live_creator_banner
+SET lang = 'KO'
+WHERE lang IS NULL;
+
+SET @lang_column_nullable := (
+    SELECT IS_NULLABLE
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'recommend_live_creator_banner'
+      AND column_name = 'lang'
+);
+
+SET @alter_lang_column_sql := IF(
+    @lang_column_nullable = 'YES',
+    'ALTER TABLE recommend_live_creator_banner MODIFY COLUMN lang VARCHAR(10) NOT NULL DEFAULT ''KO'' COMMENT ''배너 노출 언어 (KO 기본, EN/JA 추가 가능)''',
+    'SELECT ''recommend_live_creator_banner.lang already normalized'' AS message'
+);
+
+PREPARE alter_lang_column_stmt FROM @alter_lang_column_sql;
+EXECUTE alter_lang_column_stmt;
+DEALLOCATE PREPARE alter_lang_column_stmt;

docs/20260402_관리자채팅배너목록언어표기추가.md

@@ -0,0 +1,10 @@
+- [x] 배너 목록 조회 응답 생성 경로와 언어 정보 위치를 확인한다.
+- [x] 배너 목록 응답의 연결 캐릭터 이름에 배너 등록 언어를 `(언어)` 형식으로 추가한다.
+- [x] 변경 파일 기준으로 검증을 수행하고 결과를 기록한다.
+
+## 검증 기록
+
+### 1차 구현
+- 무엇을: 관리자 배너 목록 조회 응답에서 연결 캐릭터 이름 뒤에 배너 등록 언어를 `(언어)` 형식으로 붙이도록 수정했다.
+- 왜: 같은 이름과 같은 이미지의 배너라도 등록 언어가 다르면 관리자 페이지에서 즉시 구분할 수 있어야 하기 때문이다.
+- 어떻게: `./gradlew test --tests "kr.co.vividnext.sodalive.admin.chat.AdminChatBannerControllerTest"` 실행으로 컨트롤러 테스트를 검증했고, 새 테스트에서 목록 조회 응답 이름이 `character-12 (일본어)`로 반환되는 것을 확인했다. 결과는 `BUILD SUCCESSFUL`이다.

docs/20260402_라이브추천크리에이터언어적용.md

@@ -0,0 +1,11 @@
+- [x] 추천 크리에이터 배너 등록·조회 경로와 언어 처리 기준을 확인한다.
+- [x] 추천 크리에이터 등록 API에 `lang` 파라미터를 추가하고 `Lang` 기준으로 저장하도록 수정한다.
+- [x] 관리자 추천 크리에이터 목록은 전체 언어를 유지하고, `LiveApiService.fetchData`의 추천 크리에이터 조회는 사용자 언어에 맞는 배너만 반환하도록 수정한다.
+- [x] 변경 파일 기준으로 검증을 수행하고 결과를 기록한다.
+
+## 검증 기록
+
+### 1차 구현
+- 무엇을: 추천 크리에이터 배너 엔티티와 관리자 등록 API에 `lang`을 추가하고, 라이브 메인 `fetchData` 및 `/live/recommend` 조회가 현재 요청 언어와 일치하는 배너만 조회하도록 수정했다. 운영 반영용으로 `recommend_live_creator_banner.lang` 컬럼 DDL 문서도 추가했다.
+- 왜: 관리자에서는 언어별 추천 크리에이터 배너를 등록할 수 있어야 하고, 사용자 라이브 화면에서는 자신의 언어와 맞는 추천 크리에이터만 노출되어야 하기 때문이다. 관리자 목록 API는 기존처럼 전체 언어 배너를 그대로 조회해야 한다.
+- 어떻게: Kotlin LSP가 없어 정적 진단은 Gradle 검증으로 대체했고, `./gradlew test --tests "kr.co.vividnext.sodalive.admin.live.AdminLiveServiceTest" --tests "kr.co.vividnext.sodalive.live.recommend.LiveRecommendServiceTest" --tests "kr.co.vividnext.sodalive.live.recommend.LiveRecommendRepositoryTest"`로 소문자 `lang` 저장, 서비스 언어 전달, 언어별 추천 배너 조회를 검증했다. 이어서 `./gradlew ktlintCheck`와 `./gradlew build`를 실행했고 모두 `BUILD SUCCESSFUL`이다.

docs/20260402_시리즈배너언어별조회적용.md

@@ -0,0 +1,10 @@
+- [x] 시리즈 배너 등록·조회 경로와 언어 처리 기준을 확인한다.
+- [x] 배너 등록 시 언어를 저장하고 관리자 목록에서 시리즈 제목에 `(언어)` 표기를 추가한다.
+- [x] 사용자 시리즈 메인 조회에서 요청 언어와 일치하는 배너만 반환하도록 수정하고 검증 결과를 기록한다.
+
+## 검증 기록
+
+### 1차 구현
+- 무엇을: 시리즈 배너 등록 요청에 `lang`을 추가하고, 관리자 목록에서는 `seriesTitle (언어)` 형태로 응답하며, 사용자 시리즈 메인에서는 `LangContext`와 일치하는 언어 배너만 조회하도록 수정했다.
+- 왜: 관리자 화면에서는 같은 시리즈명의 다국어 배너를 구분할 수 있어야 하고, 사용자 화면에서는 요청 언어와 맞는 배너만 노출되어야 하기 때문이다.
+- 어떻게: Kotlin LSP가 없어 정적 진단은 Gradle 컴파일로 대체했고, `./gradlew test --tests "kr.co.vividnext.sodalive.content.series.main.banner.ContentSeriesBannerServiceTest" --tests "kr.co.vividnext.sodalive.admin.content.series.banner.AdminContentSeriesBannerControllerTest" --tests "kr.co.vividnext.sodalive.content.series.main.SeriesMainControllerTest"`를 실행해 등록 언어 저장, 관리자 목록 언어 표기, 사용자 언어별 배너 조회를 검증했다. 결과는 `BUILD SUCCESSFUL`이다.

docs/20260402_오디오콘텐츠배너언어적용.md

@@ -0,0 +1,11 @@
+- [x] 오디오 콘텐츠 배너 등록·조회 경로와 언어 처리 기준을 확인한다.
+- [x] 배너 등록 API에 `lang` 파라미터를 추가하고 지원 언어를 `Lang` 기준으로 저장하도록 수정한다.
+- [x] 관리자 배너 목록은 전체 언어 배너를 유지하고, HomeService `fetchData`는 사용자 언어와 일치하는 배너만 조회하도록 수정한다.
+- [x] 변경 파일 기준으로 검증을 수행하고 결과를 기록한다.
+
+## 검증 기록
+
+### 1차 구현
+- 무엇을: 오디오 콘텐츠 배너 엔티티와 등록 요청에 `lang`을 추가하고, 홈 `fetchData`에서 현재 사용자 언어를 넘겨 해당 언어 배너만 조회하도록 수정했다. 운영 반영용으로 `content_banner.lang` 컬럼 DDL도 추가했다.
+- 왜: 관리자 등록 시 언어별 배너를 구분해 저장해야 하고, 홈에서는 사용자 언어와 맞는 배너만 노출되어야 하기 때문이다. 관리자 목록 API는 기존처럼 언어 전체 배너를 그대로 조회해야 한다.
+- 어떻게: Kotlin LSP가 없어 정적 진단은 Gradle 컴파일/테스트로 대체했고, `./gradlew test --tests "kr.co.vividnext.sodalive.admin.content.banner.AdminContentBannerServiceTest" --tests "kr.co.vividnext.sodalive.content.main.banner.AudioContentBannerRepositoryTest" --tests "kr.co.vividnext.sodalive.api.home.HomeServiceTest"`로 등록 언어 저장, 언어별 배너 조회, 홈 언어 전달을 검증했다. 이어서 `./gradlew ktlintCheck`를 실행해 스타일 검증까지 확인했고 두 명령 모두 `BUILD SUCCESSFUL`이다.

docs/20260403_메시지전송username추가.md

@@ -0,0 +1,15 @@
+- [x] sendMessage의 외부 채팅 API 호출 경로와 요청 payload 구성을 확인한다.
+- [x] 외부 `/api/chat` 요청 body에 `member.nickname`을 `userName` 파라미터로 전달하도록 수정한다.
+- [x] 변경 파일 기준으로 검증을 수행하고 결과를 기록한다.
+
+## 검증 기록
+
+### 1차 구현
+- 무엇을: `ChatRoomService.sendMessage`가 외부 `/api/chat` 호출 시 `member.nickname`을 `username` 파라미터로 함께 전달하도록 수정했다.
+- 왜: 외부 채팅 API가 사용자 닉네임을 함께 받아야 하는 요구사항을 기존 메시지 전송 흐름 안에서 최소 범위로 반영해야 했기 때문이다.
+- 어떻게: 내부 탐색으로 `/api/chat` payload 생성 위치가 `ChatRoomService.callExternalApiForChatSend`임을 확인한 뒤 `./gradlew compileKotlin`과 `./gradlew test`를 실행했고 둘 다 `BUILD SUCCESSFUL`이었다. 추가로 `./gradlew test --tests '*ChatRoom*'`를 시도했지만 해당 패턴의 테스트 클래스는 없어 필터 검증은 불가했다.
+
+### 2차 수정
+- 무엇을: 외부 `/api/chat` 요청 body의 키 이름을 `username`에서 `userName`으로 변경했다.
+- 왜: 외부 API 계약에서 사용자명 필드명이 camelCase인 `userName`으로 요구되기 때문이다.
+- 어떻게: `ChatRoomService.callExternalApiForChatSend`의 request body 키가 `"userName"`으로 생성되는 것을 코드에서 재확인했다. 이 환경에는 Kotlin LSP가 구성되어 있지 않아 별도 diagnostics는 수행할 수 없었고, 대신 `./gradlew compileKotlin test`를 실행해 `BUILD SUCCESSFUL`을 확인했다.

docs/20260406_omxgitignore.md

@@ -0,0 +1,10 @@
+# `.omx/` Git 제외 처리
+
+- [x] `.gitignore`에 `.omx/`를 추가한다.
+- [x] `git status`와 `git check-ignore`로 제외가 정상 동작하는지 확인한다.
+
+## 검증 기록
+
+- 무엇을: `.gitignore`에 `.omx/`를 추가하고 `.omx/` 하위 파일들이 무시되는지 확인했다.
+- 왜: `.omx/`는 런타임 상태, 로그, 메트릭 파일이라 버전 관리 대상이 아니기 때문이다.
+- 어떻게: `git check-ignore -v .omx/tmux-hook.json .omx/state/hud-state.json .omx/logs/turns-2026-04-06.jsonl`로 무시 규칙을 확인했고, `git status --short`로 `.omx/`가 더 이상 추적 대상이 아니고 문서만 남는지 확인했다.

docs/20260407_audio_content_settlement_ratio_ddl.sql

@@ -0,0 +1,19 @@
+SET @schema_name := DATABASE();
+
+SET @settlement_ratio_column_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'content'
+      AND column_name = 'settlement_ratio'
+);
+
+SET @add_settlement_ratio_column_sql := IF(
+    @settlement_ratio_column_exists = 0,
+    'ALTER TABLE content ADD COLUMN settlement_ratio INT NULL COMMENT ''콘텐츠별 정산 요율(%)'' AFTER price',
+    'SELECT ''content.settlement_ratio already exists'' AS message'
+);
+
+PREPARE add_settlement_ratio_column_stmt FROM @add_settlement_ratio_column_sql;
+EXECUTE add_settlement_ratio_column_stmt;
+DEALLOCATE PREPARE add_settlement_ratio_column_stmt;

docs/20260407_커밋footer자동추가차단.md

@@ -0,0 +1,22 @@
+# 20260407 커밋 footer 자동 추가 차단
+
+## 구현 계획
+- [x] oh-my-openagent 기본 footer 동작과 저장소 로컬 커밋 워크플로우의 영향 범위를 문서화한다.
+- [x] `AGENTS.md`에 커밋 본문에서 Sisyphus footer와 자동 `Co-authored-by` 라인을 허용하지 않는 규칙을 추가한다.
+- [x] `.opencode/skills/commit-policy/SKILL.md`에 검증된 메시지를 그대로 `git commit`에 전달하고 자동 footer를 금지하는 절차를 반영한다.
+- [x] `.opencode/commands/commit.md`에 `/commit` 커맨드가 자동 footer 없는 최종 메시지를 사용하도록 지시를 보강한다.
+- [x] `work/scripts/check-commit-message-rules.sh`에 Sisyphus footer 및 자동 `Co-authored-by` 라인 차단 검증을 추가한다.
+- [x] 변경 문서와 스크립트에 대해 진단 및 실행 검증을 수행한다.
+
+## 검증 기록
+- [x] 작업 완료 후 검증 결과를 기록한다.
+
+- 1차 구현
+  - 무엇을: `AGENTS.md`, `.opencode/skills/commit-policy/SKILL.md`, `.opencode/commands/commit.md`, `work/scripts/check-commit-message-rules.sh`를 수정해 커밋 본문에서 `Ultraworked with [Sisyphus]...`와 `Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>` 자동 footer를 금지하고, `/commit` 경로가 검증된 메시지를 그대로 `git commit`에 전달하도록 명시했다.
+  - 왜: oh-my-openagent 기본 설정과 알려진 버그로 자동 footer가 붙을 수 있으므로, 저장소 로컬 규칙과 검증 스크립트에서 이를 명시적으로 차단해야 커밋 결과를 일관되게 통제할 수 있기 때문이다.
+  - 어떻게: `lsp_diagnostics`로 `AGENTS.md`, `.opencode/skills/commit-policy/SKILL.md`, `.opencode/commands/commit.md`, `work/scripts/check-commit-message-rules.sh`, `docs/20260407_커밋footer자동추가차단.md`에 대해 모두 `No diagnostics found`를 확인했다. `bash -n work/scripts/check-commit-message-rules.sh`로 문법을 검증했고, `./work/scripts/check-commit-message-rules.sh --message`로 정상 메시지/`Refs` footer 허용 케이스는 PASS, Sisyphus footer와 자동 `Co-authored-by` 케이스는 FAIL을 확인했다. 추가로 `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL`을 확인했다.
+
+- 2차 수정
+  - 무엇을: Oracle 검토 의견을 반영해 `.opencode/skills/commit-policy/SKILL.md`와 `.opencode/commands/commit.md`에서 `--message-file` 검증 후 같은 파일을 `git commit -F`에 전달하는 경로를 권장하도록 보강했고, `work/scripts/check-commit-message-rules.sh`의 `Co-authored-by` 차단 조건을 공백 변형까지 탐지하도록 확장했다.
+  - 왜: exact string 하나만 금지하면 footer 형식이 조금만 달라져도 놓칠 수 있으므로, 외부 기본 동작이나 버그로 인한 변형까지 더 안정적으로 차단해야 하기 때문이다.
+  - 어떻게: `lsp_diagnostics`로 `.opencode/skills/commit-policy/SKILL.md`, `.opencode/commands/commit.md`, `work/scripts/check-commit-message-rules.sh`에 대해 모두 `No diagnostics found`를 확인했다. `bash -n work/scripts/check-commit-message-rules.sh`를 다시 실행해 문법을 검증했고, `./work/scripts/check-commit-message-rules.sh --message`로 기본 메시지와 `Refs` footer는 PASS, Sisyphus footer/기본 `Co-authored-by`/공백 변형 `Co-authored-by` 케이스는 모두 FAIL을 확인했다.

docs/20260407_콘텐츠별정산요율추가.md

@@ -0,0 +1,85 @@
+- [x] 변수명 확정: 엔티티 내부 추가 변수는 `AudioContent.settlementRatio: Int?`로 사용한다.
+  - 이유: `AudioContent`는 이미 콘텐츠 도메인 엔티티이므로 `contentSettlementRatio`는 중복 표현에 가깝다.
+  - 근거: 이 저장소의 엔티티 필드는 `AudioContent.price`, `LiveRoom.price`, `CreatorCommunity.price`처럼 엔티티 스코프 안에서는 도메인 접두어를 반복하지 않는다.
+  - 예외 기준: `CreatorSettlementRatio.contentSettlementRatio`처럼 하나의 엔티티 안에서 `live/content/community` 여러 정산 대상을 함께 구분해야 할 때만 `content` 접두어가 필요하다.
+  - DTO/API 정책: 해당 값은 관리자에서만 사용하므로 관리자 요청/응답 DTO와 API 필드명도 예외 없이 `settlementRatio`로 통일한다.
+  - nullable 정책: 기존 데이터와 크리에이터 정산 요율 미등록 케이스를 안전하게 수용하기 위해 초기 도입 시 `Int?`로 두고, 계산 시 `콘텐츠별 요율 -> 크리에이터 기본 요율 -> 70% 기본값` 순서로 fallback 하도록 설계한다.
+
+- [x] `AudioContent` 엔티티에 콘텐츠별 정산 요율 필드를 추가한다.
+  - 대상 파일: `src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContent.kt`
+  - 작업 내용: `price` 인접 위치에 `settlementRatio: Int?` 필드를 추가하고, 기존 생성자 호출부가 모두 컴파일되도록 생성 경로를 함께 정리한다.
+
+- [x] 관리자 콘텐츠 목록 조회 응답에 콘텐츠별 정산 요율을 노출한다.
+  - 대상 파일: `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentRepository.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/GetAdminContentListResponse.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentService.kt`
+  - 작업 내용:
+    - `QGetAdminContentListItem(...)` QueryProjection에 `audioContent.settlementRatio`를 추가한다.
+    - `GetAdminContentListItem`에 `settlementRatio: Int?`를 추가하고, 관리자 목록 응답 필드명도 동일하게 `settlementRatio`로 맞춘다.
+    - `AdminContentController.getAudioContentList` 응답에 정산 요율이 함께 내려가도록 조회 체인을 맞춘다.
+
+- [x] 관리자 콘텐츠 수정 API에서 콘텐츠별 정산 요율을 수정할 수 있게 한다.
+  - 대상 파일: `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/UpdateAdminContentRequest.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentService.kt`
+  - 작업 내용:
+    - `UpdateAdminContentRequest`에 `settlementRatio: Int?`를 추가하고, 관리자 수정 요청 필드명도 동일하게 `settlementRatio`로 맞춘다.
+    - `AdminContentService.updateAudioContent`에서 요청값이 들어오면 `audioContent.settlementRatio`를 갱신한다.
+    - 숫자 범위 정책은 `0~100`으로 검증한다.
+    - 개별 콘텐츠 정산 요율 삭제는 `isSettlementRatioDeleted: true` 플래그로만 처리하고, `settlementRatio`와 동시 전달 시 invalid request 로 처리한다.
+
+- [x] 실제 콘텐츠 정산 계산이 크리에이터 기본 요율이 아니라 콘텐츠별 요율을 우선 사용하도록 변경한다.
+  - 대상 파일: `src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/AdminCalculateQueryRepository.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/creator/admin/calculate/CreatorAdminCalculateQueryRepository.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/GetCalculateContentQueryData.kt`
+  - 작업 내용:
+    - 콘텐츠 판매/누적 판매 집계 쿼리에서 `creatorSettlementRatio.contentSettlementRatio` 직접 사용 부분을 점검한다.
+    - 정산 대상 비율은 `audioContent.settlementRatio`를 우선 사용하고, 값이 없을 때만 `creatorSettlementRatio.contentSettlementRatio`를 fallback 하도록 쿼리 또는 계산 DTO를 조정한다.
+    - 현재 `GetCalculateContentQueryData`의 70% 기본값 정책은 마지막 fallback 으로 유지한다.
+
+- [x] 크리에이터 관리자 정산 조회도 동일 기준을 사용하도록 맞춘다.
+  - 대상 파일: `src/main/kotlin/kr/co/vividnext/sodalive/creator/admin/calculate/CreatorAdminCalculateQueryRepository.kt`
+  - 작업 내용: 관리자 정산 조회와 동일하게 콘텐츠별 정산 요율 우선 정책을 반영해 관리자/크리에이터 화면 간 계산 기준이 달라지지 않게 한다.
+
+- [x] 기존 데이터 처리 정책을 정리한다.
+  - 대상 범위: 운영 DB 스키마/기존 콘텐츠 데이터
+  - 작업 내용:
+    - 신규 컬럼 추가 시 nullable 로 도입하고, DDL은 `docs/20260407_audio_content_settlement_ratio_ddl.sql` 기준으로 관리한다.
+    - 콘텐츠 등록 시 크리에이터 기본 정산 요율을 복사하지 않고, `NULL` 상태에서도 계산이 가능하도록 fallback 순서를 유지한다.
+    - 운영 정책상 기존 콘텐츠에도 즉시 고정값이 필요하면 별도 SQL 또는 배치 백필 계획을 추가로 작성한다.
+
+- [x] 영향 DTO/Q 클래스/컴파일 산출물을 재생성하고 검증한다.
+  - 작업 내용:
+    - QueryDSL projection 변경 후 Q 클래스 재생성이 필요한지 확인하고 빌드로 반영한다.
+    - 엔티티/관리자 DTO/API/QueryProjection 필드명이 모두 `settlementRatio`로 일치하는지 확인해 매핑 누락 가능성을 제거한다.
+
+- [x] 검증을 단계별로 수행한다.
+  - 작업 내용:
+    - `AdminContentController.getAudioContentList`에서 정산 요율 조회 포함 여부를 확인한다.
+    - `AdminContentController.modifyAudioContent`에서 정산 요율 수정 반영 여부를 확인한다.
+    - `AdminContentController.modifyAudioContent`에서 `isSettlementRatioDeleted = true` 요청 시 개별 콘텐츠 정산 요율이 삭제되는지 확인한다.
+    - 콘텐츠 등록 시 `settlementRatio`가 nullable 상태로 유지되어도 계산 fallback 이 정상 동작하는지 확인한다.
+    - 콘텐츠 정산 조회(`AdminCalculateQueryRepository`, `CreatorAdminCalculateQueryRepository`)가 콘텐츠별 요율을 우선 적용하는지 확인한다.
+    - 실행 검증은 최소 `./gradlew build`, 필요 시 `./gradlew test`까지 수행한다.
+
+## 1차 구현 검증 기록
+
+- 무엇을: `AudioContent.settlementRatio` nullable 컬럼 추가, 관리자 목록/수정 API 반영, 콘텐츠/누적 정산 쿼리의 콘텐츠별 요율 우선 fallback 반영, 생성 시 기본 요율 복사 제거.
+- 왜: 기존 콘텐츠와 미설정 콘텐츠를 `NULL`로 유지하면서도 관리자에서 개별 요율을 조회/수정하고 정산 시 올바른 fallback 순서를 적용하기 위해.
+- 어떻게:
+  - `./gradlew build` → 성공
+  - `./gradlew test` → `build` 과정에 포함되어 성공
+  - 관리자/정산 API의 실서버 수동 호출 검증 → 이 로컬 작업 세션에서는 애플리케이션 실행 및 인증 가능한 테스트 데이터가 없어 미실행
+
+## 2차 수정 검증 기록
+
+- 무엇을: `@SpringBootTest` 없이 콘텐츠 정산 계산 DTO의 명시 비율 적용과 `null -> 70% fallback`을 검증하는 순수 단위 테스트를 추가했다.
+- 왜: 정산 쿼리 변경만으로는 계산 결과가 코드상에서 충분히 고정되지 않아, 문서에 적힌 계산 규칙을 재현 가능한 테스트로 보장하기 위해.
+- 어떻게:
+  - `./gradlew test --tests kr.co.vividnext.sodalive.admin.calculate.ContentSettlementCalculationTest` → 성공
+  - 검증 대상: `GetCalculateContentQueryData`, `GetCumulativeSalesByContentQueryData`
+  - 검증 시나리오: `settlementRatio = 80` 적용, `settlementRatio = null` 시 70% fallback 적용
+
+## 3차 수정 검증 기록
+
+- 무엇을: 관리자 콘텐츠 수정 API의 개별 콘텐츠 정산 요율 삭제 방식을 명시적 null 대신 `isSettlementRatioDeleted` 플래그로 전환한다.
+- 왜: 부분 업데이트 요청에서 필드 생략과 null 삭제 의미가 섞이지 않도록 API 계약을 명확히 하기 위해.
+- 어떻게:
+  - `./gradlew test --tests kr.co.vividnext.sodalive.admin.content.AdminContentServiceTest` → 성공
+  - `./gradlew test --tests kr.co.vividnext.sodalive.admin.calculate.ContentSettlementCalculationTest` → 성공
+  - `./gradlew build` → 성공
+  - 검증 시나리오: 유효한 요율 설정, 삭제 플래그 삭제, 값/삭제 플래그 동시 전달 충돌, `null` 키/삭제 플래그 동시 전달 충돌, 범위 초과 거부, 정산 fallback 회귀 확인

docs/20260408_에이전트권한및정산기능추가.md

@@ -0,0 +1,658 @@
+# 에이전트 권한 및 정산 기능 추가 작업 계획
+
+## 요구사항 상세 분석
+
+### 1. 권한/역할 분석
+- `MemberRole.AGENT`는 이미 `Member.kt`에 정의되어 있으므로 역할 enum 자체의 신규 추가는 필요하지 않다.
+- 다만 현재 코드베이스에는 에이전트 전용 소속 관리/정산 조회 모듈이 없으므로, 실제 기능은 신규 구현이 필요하다.
+- 크리에이터를 에이전트에 소속하거나 해제하는 작업은 `ADMIN`만 수행할 수 있어야 한다.
+- 에이전트 전용 조회 API는 `AGENT` 권한 계정만 자신의 소속 크리에이터 데이터에 한해 접근할 수 있어야 한다.
+- 관리자용 권한 경계는 기존 `@PreAuthorize("hasRole('ADMIN')")`, 에이전트용 권한 경계는 `@PreAuthorize("hasRole('AGENT')")` 패턴을 따른다.
+
+### 2. 관계 모델 분석
+- 요구사항은 `에이전트 1 : N 크리에이터`, `크리에이터 1 : 0..1 에이전트` 관계다.
+- 이 관계는 `Member` 자체에 필드를 직접 늘리는 방식보다, `kr.co.vividnext.sodalive.partner.agent` 패키지 안에 전용 연관 엔티티를 두는 편이 패키지 경계와 제약 관리에 더 적합하다.
+- 신규 연관 엔티티는 `creator_id` 유니크 제약으로 "한 크리에이터는 하나의 에이전트에만 소속"을 강제해야 한다.
+- 서비스 계층에서는 다음을 모두 검증해야 한다.
+  - agent 회원이 실제 `MemberRole.AGENT`인지
+  - creator 회원이 실제 `MemberRole.CREATOR`인지
+  - creator가 이미 다른 agent에 소속되어 있는지
+  - 자기 자신을 agent/creator로 잘못 연결하는 요청이 아닌지
+
+### 3. 정산 규칙 분석
+- 에이전트 정산 비율은 관리자 설정값 1개만 있으면 된다.
+- 기준 금액은 "크리에이터 세전 정산금액(settlementAmount)"이며, 라이브/콘텐츠/커뮤니티처럼 항목별 비율이 아니라 최종 정산금액에 대해 에이전트 비율을 적용한다.
+- 에이전트 정산금은 크리에이터 정산금에서 차감하지 않고 별도로 계산한다.
+- 에이전트 정산금 계산식은 다음으로 고정한다.
+  - `agentSettlementAmount = round(creatorSettlementAmount * agentSettlementRatio / 100)`
+- 크리에이터 입금액 계산식은 기존 로직을 그대로 유지한다.
+- 라이브/콘텐츠/커뮤니티는 기존 `CreatorSettlementRatio` 또는 콘텐츠별 정산 비율을 이용해 `settlementAmount`를 계산한 뒤, 그 결과에 에이전트 비율을 곱해야 한다.
+- 채널후원/콘텐츠후원도 기존 정산 계산 결과의 `settlementAmount`를 기준으로 에이전트 금액을 별도 계산해야 한다.
+
+### 4. 조회 요구사항 분석
+- 에이전트는 소속 크리에이터 목록을 조회할 수 있어야 한다.
+- 에이전트는 소속 크리에이터 기준으로 아래 5개 현황을 조회할 수 있어야 한다.
+  - 라이브
+  - 콘텐츠 판매
+  - 커뮤니티
+  - 채널후원
+  - 콘텐츠후원
+- 각 조회는 `/admin/calculate/content-by-creator` 계열과 유사하게 크리에이터별 집계 응답을 제공해야 한다.
+- 각 응답은 최소한 다음 정보를 포함해야 한다.
+  - 크리에이터 식별 정보
+  - 건수
+  - 총 캔 수
+  - 원화
+  - 수수료
+  - 정산금액
+  - 합계(total)
+  - 에이전트 정산금액(agentSettlementAmount)
+- 기존 `GetCalculateByCreatorItem`은 건수가 없고 total 객체도 없으므로, 에이전트 전용 응답 DTO는 신규 정의가 필요하다.
+
+## 구현 방향
+
+### 1차 구현 범위 (2026-04-09)
+- 이번 구현 슬라이스는 관리자 전용 기능만 포함한다.
+- 포함 범위
+  - 에이전트-크리에이터 소속 지정 API
+  - 에이전트-크리에이터 소속 해제 API
+  - 에이전트 정산 비율 생성 API
+  - 에이전트 정산 비율 수정 API
+  - 에이전트 정산 비율 목록 API
+  - 위 기능에 필요한 엔티티/리포지토리/서비스/테스트/DDL 문서
+- 제외 범위
+  - 에이전트 본인 소속 크리에이터 목록 조회 API
+  - 라이브/콘텐츠/커뮤니티/채널후원/콘텐츠후원 에이전트 정산 조회 API
+
+### 권장 설계
+- 공유 도메인 모델/리포지토리는 `kr.co.vividnext.sodalive.partner.agent` 하위 패키지에 둔다.
+- `ADMIN` 전용 controller/service 진입점은 `kr.co.vividnext.sodalive.admin.partner.agent` 하위 패키지에 둔다.
+- `AGENT` 전용 정산 조회 진입점은 `kr.co.vividnext.sodalive.partner.agent.calculate` 하위 패키지에 둔다.
+- 기존 `admin.calculate`, `creator.admin.calculate`, `admin.member`의 구현 패턴은 재사용하되, DTO/쿼리/서비스는 에이전트 요구사항에 맞는 별도 모듈로 분리한다.
+- 에이전트-크리에이터 소속 관계와 에이전트 정산 비율은 전용 엔티티로 분리해 기능 응집도를 유지한다.
+
+### 3차 구현 범위 (이력형 소속/비율 + 확정 정산 스냅샷)
+- 이번 구현 슬라이스는 기존 current-state 기반 에이전트 정산 구조를 historical model로 전환한다.
+- 포함 범위
+  - `agent_creator_relation`을 `assignedAt/unassignedAt` 기반 이력형 소속 모델로 전환
+  - `agent_settlement_ratio`를 `effectiveFrom/effectiveTo` 기반 이력형 비율 모델로 전환
+  - 관리자 소속 지정/해제 API를 시간 경계 기반으로 수정
+  - 관리자 비율 생성/수정/조회 API를 이력형 비율 기준으로 수정
+  - AGENT 정산 조회 쿼리를 거래 시점(event time)의 소속/비율을 기준으로 계산하도록 수정
+  - 확정 정산 스냅샷 저장 모델 및 관리자 확정 API 추가
+  - finalized 기간 조회는 스냅샷 우선, 미확정 기간 조회는 live 계산 유지
+  - 위 구조에 필요한 테스트, DDL 문서, 계획 문서 갱신
+- 제외 범위
+  - 기존 과거 데이터의 완전 복원 보장
+  - 이벤트소싱 도입
+  - 프론트엔드 화면 개편
+
+### current-state 설계의 한계
+- 현재 `AgentCreatorRelation`은 `agent`, `creator`만 저장하고 remove 시 hard-delete 하므로 과거 소속 이력을 보존하지 못한다.
+- 현재 `AgentSettlementRatio`는 `deletedAt` 기반 현재 활성 행 조회에 의존하므로 특정 거래 시점의 비율을 안정적으로 재현하지 못한다.
+- 현재 `AgentCalculateQueryRepository`는 거래 발생 시각(`useCan.createdAt`, `order.createdAt`)으로 기간을 자르면서도, 소속/비율은 현재 row를 기준으로 조인한다.
+- 따라서 크리에이터가 에이전트에서 해제되거나 비율이 변경되면, 과거 정산 조회 결과도 바뀔 수 있다.
+- 사용자가 요구한 "당시 적용 비율까지 고정된 완전한 과거 정산"은 current-state 조인만으로 충족할 수 없다.
+
+### 변경 후 목표 모델
+- 소속 관계는 append-only 이력 모델로 관리한다.
+  - `assignedAt`: 소속 시작 시각
+  - `unassignedAt`: 소속 종료 시각(nullable)
+  - 현재 소속은 `unassignedAt is null`로 정의한다.
+- 정산 비율도 append-only 이력 모델로 관리한다.
+  - `effectiveFrom`: 비율 시작 시각
+  - `effectiveTo`: 비율 종료 시각(nullable)
+  - 현재 비율은 `effectiveTo is null`로 정의한다.
+- 정산 확정 시점에는 별도 스냅샷 테이블에 결과를 저장한다.
+  - 소속/비율 foreign key만 저장하지 않고, 적용된 비율과 계산 결과를 숫자 값으로 함께 저장한다.
+  - 이후 소속/비율 변경이 발생해도 확정 정산은 변경되지 않는다.
+
+### 확정 정산 스냅샷 설계 초안
+- 신규 도메인 패키지 후보: `kr.co.vividnext.sodalive.partner.agent.settlement.snapshot`
+- 신규 관리자 진입점 패키지 후보: `kr.co.vividnext.sodalive.admin.partner.agent.settlement`
+- 신규 스냅샷 엔티티 초안 필드
+  - `periodStart`, `periodEnd`
+  - `settlementType` (`LIVE`, `CONTENT`, `COMMUNITY`, `CHANNEL_DONATION`, `CONTENT_DONATION`)
+  - `agentId`, `agentNickname`
+  - `creatorId`, `creatorNickname`
+  - `assignmentId`
+  - `agentSettlementRatioId`, `appliedAgentSettlementRatio`
+  - `count`, `totalCan`, `krw`, `fee`, `settlementAmount`, `agentSettlementAmount`
+  - 필요 시 `tax`, `depositAmount`
+  - `finalizedAt`, `finalizedByMemberId`
+- 스냅샷은 append-only로 저장하고 동일 기간/타입/agent/creator 기준 재확정은 idempotent하게 막거나 재사용한다.
+
+### 조회 전략 변경
+- finalized 기간 조회
+  - 스냅샷 데이터가 있으면 스냅샷을 우선 조회한다.
+  - 스냅샷 데이터는 이후 소속 해제/비율 변경과 무관하게 그대로 반환한다.
+- 미확정 기간 조회
+  - `AgentCalculateQueryRepository`에서 거래 시점 기준으로 소속/비율 이력 row를 찾아 계산한다.
+  - 시간 경계는 `start <= txTime < end` 형태의 반열린 구간으로 처리한다.
+
+### API 변경 방향
+- 관리자 소속 지정 API
+  - 기존 path 유지
+  - request에 `assignedAt` 추가
+- 관리자 소속 해제 API
+  - 기존 path 유지
+  - request에 `unassignedAt` 추가
+  - delete 대신 종료 시각 기록
+- 관리자 비율 생성/수정 API
+  - 기존 path 유지
+  - request에 `effectiveFrom` 추가
+  - update는 기존 행 수정이 아니라 이전 활성 행 종료 + 신규 행 추가로 동작
+- 관리자 확정 정산 API
+  - 신규 path 후보: `POST /admin/partner/agent/settlement/finalize`
+  - 입력: 기간, 정산 타입, 대상 에이전트(`agentId` 기준 단일 에이전트 확정)
+- 에이전트 조회 API
+  - 기존 path 유지
+  - finalized 기간은 스냅샷 우선, 그 외 기간은 live 계산
+
+### 패키지/파일 초안
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/assignment/AgentCreatorRelation.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/assignment/AgentCreatorRelationRepository.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorController.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorService.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/assignment/AssignAgentCreatorRequest.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/assignment/RemoveAgentCreatorRequest.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/AgentSettlementRatio.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/AgentSettlementRatioRepository.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioController.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioService.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateController.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateService.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepository.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/response/*`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/settlement/snapshot/AgentSettlementSnapshot.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/settlement/snapshot/AgentSettlementSnapshotRepository.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotController.kt`
+- `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotService.kt`
+- `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/**`
+- `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/**`
+- `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/**`
+- `docs/20260408_에이전트권한및정산기능추가.md`
+
+### API 방향
+- 관리자 전용
+  - 크리에이터 소속 지정 API
+  - 크리에이터 소속 해제 API
+  - 에이전트 정산 비율 생성/수정/조회 API
+- 에이전트 전용
+  - 소속 크리에이터 목록 조회 API
+  - 라이브 크리에이터별 현황 조회 API
+  - 콘텐츠 크리에이터별 현황 조회 API
+  - 커뮤니티 크리에이터별 현황 조회 API
+  - 채널후원 크리에이터별 현황 조회 API
+  - 콘텐츠후원 크리에이터별 현황 조회 API
+
+### 역할별 신규 엔드포인트 정리
+
+#### ADMIN 전용 엔드포인트
+| Method | Path | 권한 | 설명 |
+|---|---|---|---|
+| `POST` | `/admin/partner/agent/assignment` | `ADMIN` | 에이전트와 크리에이터 소속을 지정한다. |
+| `POST` | `/admin/partner/agent/assignment/remove` | `ADMIN` | 지정된 크리에이터의 에이전트 소속을 해제한다. |
+| `POST` | `/admin/partner/agent/ratio` | `ADMIN` | 에이전트 정산 비율을 생성한다. |
+| `POST` | `/admin/partner/agent/ratio/update` | `ADMIN` | 기존 에이전트 정산 비율을 수정한다. |
+| `GET` | `/admin/partner/agent/ratio` | `ADMIN` | 에이전트 정산 비율 목록을 페이지 단위로 조회한다. |
+
+#### AGENT 전용 엔드포인트
+| Method | Path | 권한 | 설명 |
+|---|---|---|---|
+| `GET` | `/agent/calculate/creator/list` | `AGENT` | 로그인한 에이전트에게 소속된 크리에이터 목록을 조회한다. |
+| `GET` | `/agent/calculate/live-by-creator` | `AGENT` | 소속 크리에이터의 라이브 정산 현황을 크리에이터별로 조회한다. |
+| `GET` | `/agent/calculate/content-by-creator` | `AGENT` | 소속 크리에이터의 콘텐츠 판매 정산 현황을 크리에이터별로 조회한다. |
+| `GET` | `/agent/calculate/community-by-creator` | `AGENT` | 소속 크리에이터의 커뮤니티 정산 현황을 크리에이터별로 조회한다. |
+| `GET` | `/agent/calculate/channel-donation-by-creator` | `AGENT` | 소속 크리에이터의 채널후원 정산 현황을 크리에이터별로 조회한다. |
+| `GET` | `/agent/calculate/content-donation-by-creator` | `AGENT` | 소속 크리에이터의 콘텐츠후원 정산 현황을 크리에이터별로 조회한다. |
+
+#### 공통 인증 메모
+- 관리자 엔드포인트는 모두 `@PreAuthorize("hasRole('ADMIN')")` 기준으로 제한한다.
+- 에이전트 엔드포인트는 모두 `@PreAuthorize("hasRole('AGENT')")` 기준으로 제한한다.
+- 에이전트 조회 API는 `@AuthenticationPrincipal(... ) member: Member?`를 통해 로그인 사용자를 확인하고, `agent_creator_relation` 기준으로 본인 소속 크리에이터 데이터만 조회한다.
+
+### 패키지/엔드포인트 배치에 대한 최종 판단
+
+#### 1. ADMIN 전용 partner-agent API는 어디에 두는 것이 더 자연스러운가?
+- **최종 판단: `ADMIN` 전용 controller/service 진입점은 `kr.co.vividnext.sodalive.admin.partner.agent.*` 아래로 옮기는 것이 더 자연스럽다.**
+- 근거는 이 저장소의 기존 관례가 관리자 전용 기능을 `kr.co.vividnext.sodalive.admin.*` 아래에 배치하는 흐름이 더 강하기 때문이다.
+  - 예: `admin/calculate/AdminCalculateController.kt`
+  - 예: `admin/marketing/AdminAdMediaPartnerController.kt`
+  - 예: `admin/member/AdminMemberController.kt`
+- `creator`처럼 역할이 강하게 분리된 영역도 `creator/admin/*` 패턴을 쓰므로, 현재 `partner.agent.assignment.AdminAgentCreatorController`, `partner.agent.ratio.AdminAgentSettlementRatioController`처럼 **도메인 패키지 안에 관리자 전용 진입점이 섞여 있는 구조는 이 저장소 기준으로는 예외에 가깝다.**
+- 따라서 권장 구조는 아래와 같다.
+  - **공유 도메인 객체/리포지토리**: `kr.co.vividnext.sodalive.partner.agent.*`
+  - **ADMIN 전용 controller/service**: `kr.co.vividnext.sodalive.admin.partner.agent.*`
+- 즉, `AgentCreatorRelation`, `AgentSettlementRatio`, repository까지 `admin.*`로 옮기는 것이 아니라, **관리자 진입점만 `admin.*`로 재배치**하는 것이 균형이 가장 좋다.
+
+#### 2. 소속 크리에이터 목록 조회 API가 `calculate` 아래에 있는 것은 맞는 선택인가?
+- **최종 판단: 현재 요구사항 범위에서는 유지해도 된다.**
+- 이유는 이 API가 “에이전트 소속 관리용 일반 목록 API”라기보다, **에이전트 정산 화면에서 크리에이터별 현황 조회로 진입하기 위한 보조 목록 API**에 가깝기 때문이다.
+- 현재 같은 컨트롤러에는 아래처럼 모두 정산/집계성 조회가 함께 모여 있다.
+  - `/agent/calculate/live-by-creator`
+  - `/agent/calculate/content-by-creator`
+  - `/agent/calculate/community-by-creator`
+  - `/agent/calculate/channel-donation-by-creator`
+  - `/agent/calculate/content-donation-by-creator`
+- 따라서 **현재 맥락에서는 `/agent/calculate/creator/list`를 정산 조회의 진입용 목록으로 보는 해석이 가능하고, 응집도도 유지된다.**
+- 다만 이 API가 앞으로 정산 외 목적(메시지, 운영, 소속 관리, 일반 대시보드)에도 재사용되기 시작하면, 그 시점에는 아래처럼 분리 재검토하는 것이 맞다.
+  - 패키지 후보: `kr.co.vividnext.sodalive.partner.agent.assignment` 또는 `kr.co.vividnext.sodalive.partner.agent.creator`
+  - 엔드포인트 후보: `/agent/creator/list`, `/agent/assignment/creator/list`
+
+#### 3. 이번 기능에 대한 권장 정리 기준
+- **ADMIN 전용 API**: `kr.co.vividnext.sodalive.admin.partner.agent.*`
+- **AGENT 정산 조회 API**: `kr.co.vividnext.sodalive.partner.agent.calculate.*`
+- **공유 도메인 모델/리포지토리**: `kr.co.vividnext.sodalive.partner.agent.*`
+- **`/agent/calculate/creator/list`**: 현재는 유지, 단 정산 외 재사용이 커지면 별도 read/assignment 축으로 분리
+
+## 작업 체크리스트
+
+- [x] 기존 `MemberRole.AGENT` 사용 범위를 점검하고, 관리자 화면/API에서 에이전트 계정을 식별할 수 있는 조회 경로를 확정한다.
+- [x] `kr.co.vividnext.sodalive.partner.agent` 패키지 아래에 에이전트-크리에이터 소속 전용 엔티티/리포지토리를 추가한다.
+- [x] 소속 엔티티에 `creator_id` 유니크 제약과 agent/creator role 검증 로직을 추가해 "한 크리에이터는 하나의 에이전트에만 소속" 규칙을 보장한다.
+- [x] 관리자 전용 크리에이터 소속 지정 API를 추가한다.
+- [x] 관리자 전용 크리에이터 소속 해제 API를 추가한다.
+- [x] 에이전트 정산 비율 전용 엔티티/리포지토리를 추가하고, 에이전트당 단일 비율만 유지되도록 한다.
+- [x] 관리자 전용 에이전트 정산 비율 생성/수정/조회 API를 추가한다.
+- [x] 1차 구현 범위의 assignment/ratio 컨트롤러/서비스 테스트를 추가해 role 검증, 중복 소속 방지, 누락 엔티티, pageable 위임을 검증한다.
+- [x] 신규 assignment/ratio 테이블 생성을 위한 DDL 문서를 `docs/20260409_partner_agent_assignment_ratio_ddl.sql`에 추가한다.
+- [x] 에이전트 본인의 소속 크리에이터 목록 조회 API를 추가한다.
+- [x] `/agent/calculate/creator/list`가 현재 시각 기준 `assignedAt <= now < unassignedAt` 활성 구간의 크리에이터만 노출하도록 보강한다.
+- [x] 라이브 현황용 agent 전용 Query/DTO/응답을 추가하고, `settlementAmount` 기준 `agentSettlementAmount`를 계산한다.
+- [x] 콘텐츠 판매 현황용 agent 전용 Query/DTO/응답을 추가하고, 기존 콘텐츠 정산 비율(`audioContent.settlementRatio` 또는 `CreatorSettlementRatio.contentSettlementRatio`)을 재사용한다.
+- [x] 커뮤니티 현황용 agent 전용 Query/DTO/응답을 추가하고, `CreatorSettlementRatio.communitySettlementRatio` 기반 정산 후 agent 금액을 계산한다.
+- [x] 채널후원 현황용 agent 전용 Query/DTO/응답을 추가하고, 기존 `ChannelDonationSettlementCalculator` 결과의 `settlementAmount` 기준으로 agent 금액을 계산한다.
+- [x] 콘텐츠후원 현황용 agent 전용 Query/DTO/응답을 추가하고, 기존 콘텐츠후원 계산 결과의 `settlementAmount` 기준으로 agent 금액을 계산한다.
+- [x] 5개 현황 응답 모두에 `totalCount + total + items` 구조를 맞추고, item/total 양쪽에 `agentSettlementAmount`를 포함한다.
+- [x] AGENT 계정이 자신에게 소속된 크리에이터 데이터만 조회하도록 `@AuthenticationPrincipal` + relation 기반 필터링을 구현한다.
+- [x] ADMIN/AGENT 권한 오류, 잘못된 role 요청, 중복 소속 요청, 비소속 데이터 조회 차단에 대한 예외 처리를 추가한다.
+- [x] 컨트롤러/서비스/쿼리 리포지토리 테스트를 추가해 소속 제약, 권한 제약, 정산 계산식, total 합계를 검증한다.
+- [x] `./gradlew test`, `./gradlew build`로 최종 검증한다.
+- [x] `agent_creator_relation`에 `assignedAt`, `unassignedAt`를 추가하고 current-state 단일 row 모델을 append-only 이력 모델로 전환한다.
+- [x] 관리자 소속 지정 API가 `assignedAt`을 받아 활성 기간 중복을 검증하도록 수정한다.
+- [x] 관리자 소속 해제 API가 hard-delete 대신 `unassignedAt` 종료 처리로 변경되도록 수정한다.
+- [x] `agent_settlement_ratio`에 `effectiveFrom`, `effectiveTo`를 추가하고 단일 현재 row 갱신 모델을 append-only 이력 모델로 전환한다.
+- [x] 관리자 비율 생성/수정 API가 `effectiveFrom`을 받아 기존 활성 row 종료 + 신규 row 추가로 동작하도록 수정한다.
+- [x] 관리자 비율 생성/수정 API가 `effectiveFrom` backdate, 동일 시각 입력, 기존 ratio history와 겹치는 시점을 거절하도록 검증을 보강한다.
+- [x] 관리자 비율 생성/수정 API가 `settlementRatio`를 0..100 범위로 검증하도록 보강한다.
+- [x] `agent_settlement_ratio` DDL에 MySQL 생성 컬럼 + UNIQUE 인덱스로 active row 단일성을 보장하고, `effective_from < effective_to` 기간 무결성 제약을 추가한다.
+- [x] `agent_creator_relation` DDL에 MySQL 생성 컬럼 + UNIQUE 인덱스로 active row 단일성을 보장하고, `assigned_at < unassigned_at` 기간 무결성 제약을 추가한다.
+- [x] 관리자 소속/비율 쓰기 경로가 `MemberRepository.findByIdForUpdate(...)` 기반 비관적 락과 unique violation 대응 패턴으로 직렬화되도록 보강한다.
+- [x] AGENT 정산 조회가 거래 시점 기준의 소속 이력과 비율 이력을 조인하도록 `AgentCalculateQueryRepository`를 수정한다.
+- [x] 기간 중 소속 변경 또는 비율 변경이 있는 경우 결과가 올바르게 분리/집계되는 테스트를 추가한다.
+- [x] AGENT 정산 조회의 paged query가 사전 조회된 `creatorIds`가 빈 페이지일 때 전체 결과로 fallback하지 않고 빈 rows/items를 반환하도록 보강한다.
+- [x] AGENT 정산 조회에서 `agent_settlement_ratio` 이력이 없으면 agent 정산금을 0% 대신 10% 기본값으로 계산하도록 수정한다.
+- [x] 확정 정산 스냅샷 엔티티/리포지토리/관리자 API를 추가한다.
+- [x] 확정 정산 스냅샷이 소속/비율 foreign key뿐 아니라 적용 비율과 계산 결과 숫자값을 함께 저장하도록 구현한다.
+  - 정정(2026-04-09): 현재 구현은 `appliedAgentSettlementRatio`와 계산 결과 숫자값은 저장하지만, 설계 초안에 명시한 `assignmentId`, `agentSettlementRatioId`는 아직 스냅샷/DDL에 포함하지 않았다. 따라서 이 항목은 엄밀히는 부분 충족 상태로 본다.
+  - [x] `AgentSettlementSnapshot` 및 `agent_settlement_snapshot` DDL에 `assignmentId`, `agentSettlementRatioId` 컬럼을 추가한다.
+  - [x] `AgentCalculateQueryRepository`와 snapshot 생성용 query DTO에 거래 시점 기준 `assignmentId`, `agentSettlementRatioId` projection을 추가한다.
+  - [x] `AdminAgentSettlementSnapshotService`와 관련 테스트를 갱신해 finalize 시점에 foreign key + 적용 비율 + 계산 숫자값이 함께 저장되도록 보완한다.
+  - 참고: 위 보완은 creator-period summary가 단일 소속/단일 비율 이력 row로 귀결되는 경우의 추적성은 복구하지만, 기간 중 복수 history row가 섞인 summary의 완전 provenance까지 보장하지는 않는다. 그 수준의 감사 추적이 필요하면 별도 snapshot source detail 테이블이 추가로 필요하다.
+  - [x] `agent_settlement_snapshot_source_detail`(가칭) DDL을 추가해 summary를 구성한 원천 source row별 provenance를 별도 저장한다.
+  - [x] finalize가 `raw source row`를 기준으로 source detail과 creator-period summary를 같은 트랜잭션 안에서 함께 저장하도록 보강한다.
+  - [x] source detail이 1건인 summary만 `assignmentId`, `agentSettlementRatioId`, `appliedAgentSettlementRatio`를 채우고, mixed-period summary는 `null`로 유지하는 규칙을 테스트로 고정한다.
+- [x] finalized 기간 조회는 스냅샷 우선, 미확정 기간 조회는 live 계산을 사용하도록 분기한다.
+- [x] 신규 이력/스냅샷 구조에 맞는 DDL 문서를 추가 또는 기존 DDL 문서를 확장한다.
+- [x] 기존 계획 문서 하단 검증 기록에 이력형 전환과 스냅샷 도입 구현/검증 결과를 누적한다.
+
+## 세부 구현 메모
+
+### 1. 소속 관계 구현 기준
+- 기존 `Member` 엔티티에 agent 필드를 직접 추가하지 않고, 전용 relation 테이블로 구현한다.
+- 이유는 다음과 같다.
+  - 에이전트 전용 기능을 `partner.agent` 패키지에 응집시킬 수 있다.
+  - creator role 제약과 unique 제약을 명확히 걸 수 있다.
+  - 향후 소속 이력/상태 필드가 필요해져도 확장이 쉽다.
+
+### 2. 정산 비율 구현 기준
+- 기존 `CreatorSettlementRatio`가 도메인별 다중 비율을 관리하므로, 에이전트는 별도 `AgentSettlementRatio`로 분리하는 편이 자연스럽다.
+- 필드는 단일 `settlementRatio`만 두고, 대상 회원은 `MemberRole.AGENT`로 제한한다.
+
+### 3. 조회 응답 구현 기준
+- 라이브/콘텐츠/커뮤니티의 기존 관리자 creator별 응답은 count/total 객체가 부족하므로 재사용보다 agent 전용 응답 신설이 적합하다.
+- 채널후원 응답은 이미 `total + items` 구조가 있어 이를 가장 가까운 기준으로 삼는다.
+- 에이전트 응답은 아래 공통 필드를 기준으로 통일한다.
+  - `creatorId`
+  - `creatorNickname`
+  - `count`
+  - `totalCan`
+  - `krw`
+  - `fee`
+  - `settlementAmount`
+  - `agentSettlementAmount`
+  - 필요 시 `tax`, `depositAmount`
+
+### 4. 재사용 기준 파일
+- 권한/인증 패턴: `AdminMemberController`, `CreatorAdminCalculateController`, `SecurityConfig`
+- creator별 집계 패턴: `AdminCalculateQueryRepository`
+- 채널후원 total 응답 패턴: `AdminChannelDonationCalculateService`, `GetAdminChannelDonationSettlementTotal`
+- 정산 비율 검증 패턴: `CreatorSettlementRatioService`
+
+### 5. 후속 보완 구현 순서 (2026-04-09 추가)
+- 아래 보완 작업은 **ratio 입력 무결성 차단 → 관리자 쓰기 직렬화/DDL 보강 → snapshot traceability 연결 → 전체 검증** 순서로 진행한다.
+
+#### 5-1. ratio 입력 무결성 차단부터 먼저 수정한다.
+- [x] `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AgentSettlementRatioServiceTest.kt`에 아래 RED 테스트를 추가한다.
+  - [x] active row보다 과거 `effectiveFrom`으로 create/update 요청 시 예외가 발생한다.
+  - [x] active row와 같은 `effectiveFrom`으로 create/update 요청 시 예외가 발생한다.
+  - [x] active row가 없더라도 기존 closed history와 겹치는 `effectiveFrom`이면 예외가 발생한다.
+- [x] `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioService.kt`에서 `effectiveFrom` backdate / same-time / history overlap을 거절하도록 검증을 추가한다.
+- [x] `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/AgentSettlementRatioRepository.kt`에 history overlap 판별용 조회 메서드를 추가한다.
+- [x] ratio 서비스 테스트를 재실행해 backdate 차단이 먼저 보장되는지 확인한다.
+
+#### 5-2. 관리자 소속/비율 쓰기 경로를 직렬화한다.
+- [x] `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioService.kt`에서 agent 대상 `MemberRepository.findByIdForUpdate(...)`를 사용하도록 수정한다.
+- [x] `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorService.kt`에서 creator 대상 `MemberRepository.findByIdForUpdate(...)`를 사용하도록 수정한다.
+- [x] 두 서비스 모두 `saveAndFlush` + `DataIntegrityViolationException` 대응 패턴으로 unique violation을 사용자 예외로 변환하도록 보강한다.
+- [x] `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorServiceTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AgentSettlementRatioServiceTest.kt`에 락/unique violation 대응 케이스를 추가한다.
+
+#### 5-3. active row 단일성과 기간 무결성을 DDL/엔티티에 맞춘다.
+- [x] `docs/20260409_partner_agent_assignment_ratio_ddl.sql` 기준으로 `agent_creator_relation`, `agent_settlement_ratio`, `agent_settlement_snapshot` 최종 스키마가 구현 코드와 일치하는지 다시 점검한다.
+- [x] `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/assignment/AgentCreatorRelation.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/AgentSettlementRatio.kt`의 매핑이 DDL의 최종 컬럼 구조와 충돌하지 않는지 확인한다.
+- [x] generated column(`active_creator_key`, `active_ratio_key`)은 JPA 쓰기 대상에서 제외하고, 서비스/리포지토리 로직이 해당 컬럼 없이도 동작하는지 확인한다.
+
+#### 5-4. snapshot traceability를 query → service → entity 순서로 연결한다.
+- [x] `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/settlement/snapshot/AgentSettlementSnapshot.kt`에 `assignmentId`, `agentSettlementRatioId` 필드를 추가한다.
+- [x] `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepository.kt`와 snapshot 생성용 query DTO에 거래 시점 기준 `assignmentId`, `agentSettlementRatioId` projection을 추가한다.
+- [x] `docs/20260409_partner_agent_assignment_ratio_ddl.sql`에 `agent_settlement_snapshot_source_detail`(가칭) 테이블을 추가하고, `snapshot_id`, `assignment_id`, `agent_settlement_ratio_id`, source subtotal 컬럼, 조회 인덱스/FK를 정의한다.
+- [x] `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/settlement/snapshot/**`에 source detail 엔티티/리포지토리 파일을 추가한다.
+- [x] `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotService.kt`를 `raw source row` 기준의 source detail과 creator-period summary를 함께 저장하도록 바꾼다.
+- [x] creator-period summary가 단일 source row로 귀결될 때만 `assignmentId`, `agentSettlementRatioId`, `appliedAgentSettlementRatio`를 summary에 채우고, mixed-period summary는 `null`로 저장하도록 매핑 규칙을 고정한다.
+- [x] `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotServiceTest.kt`에 아래 검증을 추가한다.
+  - [x] 단일 source summary는 summary row와 detail row가 같은 `assignmentId`, `agentSettlementRatioId`, `appliedAgentSettlementRatio`를 가진다.
+  - [x] mixed-period summary는 summary의 `assignmentId`, `agentSettlementRatioId`, `appliedAgentSettlementRatio`가 `null`이고, detail row 여러 건으로 provenance를 복원할 수 있다.
+  - [x] detail 합계가 summary 숫자값과 일치한다.
+
+#### 5-5. 최종 회귀 검증을 수행한다.
+- [x] `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.assignment.*"`
+- [x] `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.ratio.*"`
+- [x] `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.settlement.*"`
+- [x] `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.*"`
+- [x] `./gradlew test`
+- [x] `./gradlew build`
+
+## 검증 계획
+- 단위/서비스 테스트
+  - agent와 creator role 검증
+  - creator 중복 소속 방지
+  - 비소속 creator 조회 차단
+  - agentSettlementAmount 반올림 계산 검증
+  - category별 total 합계 검증
+- 통합 성격 검증
+  - ADMIN assignment API 정상/실패 케이스
+  - AGENT 목록/정산 조회 API 정상/권한 실패 케이스
+- 빌드 검증
+  - `./gradlew test`
+  - `./gradlew build`
+
+---
+
+## 검증 기록
+
+### 계획 수립 1차
+- 무엇을: 에이전트 권한, 소속 관계, 관리자 소속 관리 API, 에이전트 정산 비율, 에이전트 전용 크리에이터별 정산 조회 기능의 구현 범위를 분석하고 작업 계획 문서를 작성했다.
+- 왜: 기존 코드베이스에 이미 존재하는 `AGENT` 역할, 관리자 정산 모듈, 크리에이터 정산 비율 모듈을 기준으로 중복 구현 없이 가장 자연스러운 확장 경로를 먼저 확정하기 위해서다.
+- 어떻게:
+  - 권한/역할/정산 패턴을 코드 기준으로 확인했다.
+  - `docs` 폴더의 기존 작업 계획 문서 형식을 확인해 동일한 형식으로 문서를 작성했다.
+  - 실행/확인 결과:
+    - `explore` 백그라운드 탐색 2건(권한 패턴, 정산 패턴) → 완료
+    - `read`로 확인한 기준 파일: `Member.kt`, `AdminMemberController.kt`, `AdminMemberService.kt`, `SecurityConfig.kt`, `AdminCalculateController.kt`, `AdminCalculateService.kt`, `AdminCalculateQueryRepository.kt`, `CreatorAdminCalculateController.kt`, `CreatorAdminCalculateService.kt`, `AdminChannelDonationCalculateController.kt`, `AdminChannelDonationCalculateService.kt`, `ChannelDonationSettlementCalculator.kt`
+    - `./gradlew test` / `./gradlew build` → 문서 작성 단계이므로 미실행
+
+### 1차 구현 1차
+- 무엇을: 공유 도메인인 `partner.agent.assignment`, `partner.agent.ratio`와 관리자 진입점인 `admin.partner.agent.assignment`, `admin.partner.agent.ratio` 패키지에 관리자 전용 assignment/remove, ratio create/update/list 기능과 테스트, 신규 테이블 DDL 문서를 추가했다.
+- 왜: 전체 에이전트 기능 중 첫 vertical slice로서 관리자 관점의 소속 관리와 정산 비율 관리부터 독립적으로 배포 가능한 최소 단위를 먼저 완성하기 위해서다.
+- 어떻게:
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/assignment/**`에 relation 엔티티/리포지토리/요청 DTO를 추가했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/**`에 관리자 전용 서비스/컨트롤러를 추가했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/**`에 ratio 엔티티/리포지토리(querydsl)/요청·응답 DTO를 추가했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/**`에 관리자 전용 서비스/컨트롤러를 추가했다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/**`에 assignment/ratio 서비스·컨트롤러 테스트를 추가하고 TDD 순서로 RED→GREEN을 확인했다.
+  - `docs/20260409_partner_agent_assignment_ratio_ddl.sql`에 `agent_creator_relation`, `agent_settlement_ratio` 생성 스크립트를 추가했다.
+  - 실행/확인 결과:
+    - `lsp_diagnostics` on `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent`, `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent` → 불가 (현재 환경에 `.kt`용 LSP 서버 미구성)
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.assignment.*"` → 1차 실행 실패(신규 클래스 unresolved reference), 구현 후 재실행 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.ratio.*"` → 1차 실행 실패(신규 클래스 unresolved reference), 구현 후 재실행 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.*"` → 성공
+    - `./gradlew test` → 성공
+    - `./gradlew build` → 성공
+
+### 2차 구현 1차
+- 무엇을: `partner.agent.calculate` 패키지 아래에 AGENT 전용 소속 크리에이터 목록 조회 API와 라이브/콘텐츠/커뮤니티/채널후원/콘텐츠후원 creator-level summary API, QueryRepository, 응답 DTO, 테스트를 추가했다.
+- 왜: 에이전트 기능의 두 번째 vertical slice로서 실제 에이전트 계정이 본인에게 배정된 크리에이터 범위 안에서만 정산 현황을 볼 수 있도록 기능을 완성하기 위해서다.
+- 어떻게:
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/**`에 `AgentCalculateController`, `AgentCalculateService`, `AgentCalculateQueryRepository`, assigned creator 응답 DTO, 일반 정산 summary DTO, 채널후원 summary DTO를 추가했다.
+  - AGENT 인증 패턴은 `@PreAuthorize("hasRole('AGENT')")`와 `@AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?` 가드절로 맞췄다.
+  - QueryRepository는 `agent_creator_relation` 조인으로 소속 크리에이터만 필터링하고, 콘텐츠 summary는 creator별 페이지를 유지하면서 콘텐츠별 정산 비율 버킷을 병합하도록 구현했다.
+  - `agentSettlementAmount`는 모든 응답에서 creator의 세전 `settlementAmount` 기준으로 `round(settlementAmount * agentRatio / 100)`를 적용했고, creator `settlementAmount`/`depositAmount` 자체는 차감하지 않았다.
+  - 스키마 변경은 없어서 추가 DDL 문서는 만들지 않았다.
+  - 실행/확인 결과:
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.*"` → 1차 실행 실패(신규 클래스 unresolved reference), 구현 후 재실행 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.*"` → 성공
+    - `lsp_diagnostics` on `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate`, `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate` → 불가 (현재 환경에 `.kt`용 LSP 서버 미구성)
+    - `./gradlew test` → 성공
+    - `./gradlew build` → 최초 1회 `ktlintMainSourceSetCheck` 실패(신규 `AgentCalculateService.kt` 줄바꿈 규칙 위반), 포맷 수정 후 재실행 성공
+
+### 3차 수정
+- 무엇을: `partner.agent.assignment.*`, `partner.agent.ratio.*` 예외 키를 `SodaMessageSource`에 등록하고, 해당 메시지 조회를 보장하는 단위 테스트를 추가했다.
+- 왜: 기능 자체는 동작하더라도 메시지 소스에 키가 없으면 런타임에서 사용자에게 의도한 다국어 문구 대신 키 문자열 또는 빈 메시지가 노출될 수 있기 때문이다.
+- 어떻게:
+  - `src/test/kotlin/kr/co/vividnext/sodalive/i18n/SodaMessageSourceTest.kt`를 추가해 `partner.agent.assignment.creator_already_assigned`, `partner.agent.ratio.invalid_agent`, `partner.agent.ratio.not_found` 메시지 조회를 RED→GREEN으로 검증했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/i18n/SodaMessageSource.kt`에 `partnerAgentMessages` 맵을 추가하고 `getMessage` 그룹 목록에 포함시켰다.
+  - 실행/확인 결과:
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.i18n.SodaMessageSourceTest"` → 1차 실행 실패(메시지 미등록), 수정 후 재실행 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.*"` → 성공
+    - `./gradlew test` → 성공
+    - `./gradlew build` → 성공
+    - `jshell --class-path "build/classes/kotlin/main:build/resources/main:...kotlin-stdlib..."` 수동 확인 →
+      - `partner.agent.assignment.creator_already_assigned` 한국어 메시지 출력: `이미 다른 에이전트에 소속된 크리에이터입니다.`
+      - `GetAgentCreatorSettlementSummaryQueryData(21, creator-a, 2, 100, 70).toResponseItem(10)` 출력: `agentSettlementAmount=654`
+      - `GetAgentChannelDonationSettlementByCreatorQueryData(21, creator-a, 1, 50).toResponseItem(10)` 출력: `agentSettlementAmount=397`
+
+### 4차 수정
+- 무엇을: 관리자 전용 partner-agent controller/service 진입점을 `kr.co.vividnext.sodalive.admin.partner.agent.*` 아래로 재배치했다.
+- 왜: 이 저장소의 기존 관례상 관리자 전용 진입점은 `admin.*` 계층에 두는 편이 더 일관적이고, 공유 도메인 객체와 관리자 API 진입점을 분리하는 것이 책임 경계를 더 명확하게 만들기 때문이다.
+- 어떻게:
+  - `AdminAgentCreatorController`, `AdminAgentCreatorService`를 `admin.partner.agent.assignment`로 이동하고, relation/request DTO/repository는 `partner.agent.assignment`에 유지했다.
+  - `AdminAgentSettlementRatioController`, `AdminAgentSettlementRatioService`를 `admin.partner.agent.ratio`로 이동하고, ratio 엔티티/리포지토리/DTO는 `partner.agent.ratio`에 유지했다.
+  - assignment/ratio 테스트 패키지도 `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/**`로 이동했다.
+  - 계획 문서의 권장 설계/패키지 초안을 실제 구조에 맞게 갱신했다.
+  - 실행/확인 결과:
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.assignment.*"` → 1차 실행 실패(새 패키지 unresolved reference), 이동 후 재실행 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.ratio.*"` → 1차 실행 실패(새 패키지 unresolved reference), 이동 후 재실행 성공
+    - `grep "kr.co.vividnext.sodalive.partner.agent.(assignment|ratio).AdminAgent" src/**/*.kt` 성격 확인 → 코드 기준 잔존 참조 없음
+    - `./gradlew test` → 성공
+    - `./gradlew build` → 성공
+  - `jshell --class-path "build/classes/kotlin/main:build/resources/main:...kotlin-stdlib..."` 수동 확인 →
+    - `kr.co.vividnext.sodalive.admin.partner.agent.assignment.AdminAgentCreatorController` 로딩 성공
+    - `kr.co.vividnext.sodalive.admin.partner.agent.ratio.AdminAgentSettlementRatioController` 로딩 성공
+    - 기존 `kr.co.vividnext.sodalive.partner.agent.assignment.AdminAgentCreatorController` / `...ratio.AdminAgentSettlementRatioController`는 `ClassNotFoundException`으로 미존재 확인
+
+### 5차 수정
+- 무엇을: `agent_creator_relation`을 `assignedAt/unassignedAt` 기반 append-only 이력 모델로 전환하고, 관리자 소속 지정/해제 API를 시간 경계 기반 계약으로 수정했다.
+- 왜: 기존 current-state + hard-delete 구조로는 과거 소속 이력을 보존할 수 없고, 소속 해제 후 재배정 같은 운영 시나리오를 안전하게 표현할 수 없기 때문이다.
+- 어떻게:
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/assignment/AgentCreatorRelation.kt`에 `assignedAt`, `unassignedAt`를 추가하고 `creator` 연관을 `ManyToOne`으로 변경해 동일 creator의 이력 row 누적을 허용했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/assignment/AssignAgentCreatorRequest.kt`, `RemoveAgentCreatorRequest.kt`에 명시적 시간 필드를 추가하고, `AdminAgentCreatorService.kt`에서 overlap 검증 및 hard-delete 대신 종료 시각 기록으로 동작을 바꿨다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepository.kt`에는 현재 동작 유지용으로 `unassignedAt is null` 조건만 추가해 active assignment 조회가 계속 현재 row만 보도록 맞췄다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorServiceTest.kt`, `AdminAgentCreatorControllerTest.kt`를 TDD로 갱신해 RED에서 새 계약 부재를 확인한 뒤 GREEN으로 구현했다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepositoryTest.kt`는 새 not-null `assignedAt` 계약에 맞게 relation fixture를 갱신했다.
+  - `docs/20260409_partner_agent_assignment_ratio_ddl.sql`에 `agent_creator_relation` 생성 스키마를 이력형 컬럼/인덱스로 바꾸고, 기존 테이블에 대한 `assigned_at`, `unassigned_at`, unique index 제거, backfill migration 블록을 추가했다.
+  - 실행/확인 결과:
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.assignment.*"` → 1차 실행 실패(새 `assignedAt/unassignedAt`, repository 메서드, 엔티티 필드 부재), 구현 후 재실행 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.assignment.*" --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest" --tests "kr.co.vividnext.sodalive.i18n.SodaMessageSourceTest"` → 성공
+    - `lsp_diagnostics` on modified Kotlin files/directories → 불가 (현재 환경에 `.kt`용 LSP 서버 미구성)
+    - `./gradlew test`와 `./gradlew build`를 병렬 실행 → 실패 (`build/test-results/test/*.xml` 동시 쓰기 충돌)
+    - `./gradlew test` 순차 재실행 → 성공
+    - `./gradlew build` 순차 재실행 → 성공
+
+### 6차 수정
+- 무엇을: `agent_settlement_ratio`를 `effectiveFrom/effectiveTo` 기반 append-only 이력 모델로 전환하고, 관리자 비율 생성/수정/목록 API 계약을 유효 기간 노출 방식으로 갱신했다.
+- 왜: 기존 `deletedAt` + 단일 current-row 갱신 방식으로는 과거 비율 이력을 보존할 수 없어서, 이후 거래 시점 기준 정산 조회나 운영 감사 시나리오에 필요한 근거 데이터를 남길 수 없기 때문이다.
+- 어떻게:
+  - `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AgentSettlementRatioServiceTest.kt`, `AdminAgentSettlementRatioControllerTest.kt`를 먼저 수정해 `effectiveFrom` 입력, `effectiveFrom/effectiveTo` 응답, 기존 활성 row 종료 + 신규 row 추가 동작을 RED로 만들었다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/AgentSettlementRatio.kt`를 `effectiveFrom/effectiveTo` 필드와 `close(...)` 메서드를 가진 이력 엔티티로 바꾸고, `member` 연관을 `ManyToOne`으로 변경해 동일 agent의 다중 이력 row를 허용했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/CreateAgentSettlementRatioRequest.kt`, `GetAgentSettlementRatioResponse.kt`, `AgentSettlementRatioRepository.kt`를 갱신해 요청/응답 계약과 active lookup 메서드 `findFirstByMemberIdAndEffectiveToIsNull(...)`를 도입했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioService.kt`에서 create/update 모두 기존 활성 row를 `effectiveTo`로 닫은 뒤 새 row를 저장하도록 수정했고, `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateService.kt`는 현재 활성 비율 lookup만 새 repository 메서드로 맞췄다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateServiceTest.kt` fixture도 새 repository 메서드와 `effectiveFrom` 필수 생성자에 맞게 최소 호환 수정했다.
+  - `docs/20260409_partner_agent_assignment_ratio_ddl.sql`에는 `agent_settlement_ratio` 생성 스키마를 `effective_from/effective_to` + history index 구조로 변경하고, 기존 테이블에 대한 컬럼 추가/backfill/unique index 제거/`deleted_at` 제거 migration 블록을 확장했다.
+  - 실행/확인 결과:
+    - `./gradlew test --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AgentSettlementRatioServiceTest --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AdminAgentSettlementRatioControllerTest` → 1차 실행 실패(새 `effectiveFrom/effectiveTo` 계약, repository 메서드, 엔티티 필드 부재), 구현 후 재실행 성공
+    - `lsp_diagnostics` on modified Kotlin files/directories → 불가 (현재 환경에 `.kt`용 LSP 서버 미구성)
+    - `./gradlew test --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AgentSettlementRatioServiceTest --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AdminAgentSettlementRatioControllerTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest` → 성공
+    - `./gradlew build` → 성공
+
+### 7차 수정
+- 무엇을: `AgentCalculateQueryRepository`, `AgentCalculateService`, agent calculate 응답용 query DTO와 테스트를 이벤트 시점 기준 소속/agent ratio 계산 방식으로 수정해, 기간 중 재배정과 agent 비율 변경이 있어도 다섯 개 정산 카테고리의 creator-level 결과가 당시 기준으로 집계되도록 바꿨다.
+- 왜: 기존 구현은 거래 발생 시각으로 기간만 자르고, 소속은 현재 active relation, agent 비율은 현재 active ratio 한 개를 전체 기간에 적용하고 있어서 중간 재배정/비율 변경이 생기면 과거 조회 결과가 잘못 왜곡됐기 때문이다.
+- 어떻게:
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepositoryTest.kt`에 기간 중 소속 변경, 기간 중 agent ratio 변경을 재현하는 통합 성격 테스트를 먼저 추가해 RED를 확인했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepository.kt`에서 라이브/콘텐츠/커뮤니티/채널후원/콘텐츠후원 모두에 대해 거래 시각 기준 `assignedAt <= eventTime < unassignedAt`, `effectiveFrom <= eventTime < effectiveTo` 조건으로 이력 row를 조인하도록 수정했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/GetAgentCreatorSettlementSummaryQueryData.kt`, `GetAgentChannelDonationSettlementByCreatorResponse.kt`, `AgentCalculateService.kt`를 바꿔 row별 agent ratio를 응답 아이템 변환 시 적용하고, 채널후원 포함 전 카테고리에서 creator 기준 merge 후 total을 계산하도록 정리했다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateServiceTest.kt`도 row별 agent ratio 기대값으로 갱신해 서비스 레벨 병합 규칙을 검증했다.
+  - 실행/확인 결과:
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest"` → 1차 실행 실패(기간 중 소속 변경/agent ratio 변경 2건 assertion failure), 구현 후 재실행 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.*"` → 성공
+    - `lsp_diagnostics` on modified Kotlin files → 불가 (현재 환경에 `.kt`용 LSP 서버 미구성)
+    - `./gradlew test` → 성공
+    - `./gradlew build` → 1차 `ktlintTestSourceSetCheck` 실패(신규 테스트 장문 라인), 2차 `ktlintMainSourceSetCheck` 실패(import 순서/장문 line), 포맷 수정 후 재실행 성공
+
+### 8차 수정
+- 무엇을: `partner.agent.settlement.snapshot` 패키지에 immutable creator-level snapshot 저장 모델과 repository/request-response mapper를 추가하고, `admin.partner.agent.settlement`에 확정 API를 만들었으며, `AgentCalculateService`가 finalized 기간이면 스냅샷을 우선 읽도록 다섯 카테고리 전체를 연결했다.
+- 왜: 이력형 소속/비율 계산만으로는 확정 시점의 creator-level 결과를 별도 보존하거나 재사용할 수 없어서, 이후 읽기에서 동일 기간을 다시 계산하지 않고도 확정된 숫자값을 안정적으로 반환할 수 있어야 했기 때문이다.
+- 어떻게:
+  - `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotServiceTest.kt`, `AdminAgentSettlementSnapshotControllerTest.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateServiceTest.kt`에 snapshot 생성/idempotency/finalized snapshot-first read RED 테스트를 먼저 추가했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/settlement/snapshot/**`에 `AgentSettlementSnapshot`, `AgentSettlementSnapshotRepository`, `FinalizeAgentSettlementSnapshotRequest/Response`, snapshot-to-response mapper를 추가했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotService.kt`에서 기존 `AgentCalculateQueryRepository` live 계산 결과를 creator-level 응답으로 병합한 뒤 숫자값을 그대로 스냅샷 row에 저장하고, 동일 기간/타입/agent 조합은 `exists...` 검사로 idempotent하게 막도록 구현했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotController.kt`에 `POST /admin/partner/agent/settlement/finalize`를 추가하고, 인증 관리자 `member.id`를 `finalizedByMemberId`로 전달하도록 맞췄다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateService.kt`는 라이브 계산 전에 스냅샷 repository를 먼저 조회하고, 스냅샷이 있으면 generic 4종과 channel donation 1종 모두 동일 응답 DTO로 변환해 반환하도록 분기했다.
+  - `docs/20260409_partner_agent_assignment_ratio_ddl.sql`에 `agent_settlement_snapshot` 테이블과 lookup/unique 인덱스 DDL을 추가했다.
+  - 실행/확인 결과:
+    - `lsp_diagnostics` on `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate`, `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/settlement/snapshot`, `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement`, `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate`, `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement` → 불가 (현재 환경에 `.kt`용 LSP 서버 미구성)
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.settlement.*" --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest"` → 1차 실행 실패(신규 snapshot 도메인/서비스/분기 미구현), 구현 및 테스트 fixture 수정 후 재실행 성공
+    - `./gradlew test` → 성공
+    - `./gradlew build` → 1차 `ktlintTestSourceSetCheck` 실패(import 순서/unused import), 2차 `ktlintMainSourceSetCheck` 실패(import 순서/장문 line), 포맷 수정 후 재실행 성공
+
+### 9차 수정
+- 무엇을: 최종 정리 과정에서 `AgentCalculateService`의 request-wide current ratio 의존성을 제거하고, 관련 테스트/빌드/수동 확인까지 다시 수행했다.
+- 왜: 시점 기준 정산 조회와 finalized snapshot-first read로 전환된 뒤에는 `ratioRepository`가 더 이상 `AgentCalculateService`에서 직접 사용되지 않으므로, 잔존 의존성을 남기지 않는 것이 실제 설계와 코드 구조를 일치시키기 때문이다.
+- 어떻게:
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateService.kt`에서 사용되지 않는 `ratioRepository` 의존성을 제거했다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateServiceTest.kt`, `AgentCalculateQueryRepositoryTest.kt`의 생성자 호출부를 새 시그니처에 맞게 정리했다.
+  - 실행/확인 결과:
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest" --tests "kr.co.vividnext.sodalive.admin.partner.agent.settlement.*"` → 1차 실행 실패(`AgentCalculateQueryRepositoryTest`의 구 생성자 시그니처 참조), 수정 후 재실행 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest" --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest" --tests "kr.co.vividnext.sodalive.admin.partner.agent.settlement.*"` → 성공
+    - `./gradlew test && ./gradlew build` → 성공
+    - `jshell --class-path "build/classes/kotlin/main:build/resources/main:...kotlin-stdlib..."` 수동 확인 →
+      - `FinalizeAgentSettlementSnapshotRequest(agentId=7, settlementType=LIVE, startDateStr=2026-02-20, endDateStr=2026-02-21).toDateRange()` 출력 확인
+      - `AgentSettlementSnapshot` 1건을 `toSettlementByCreatorItems()`로 변환했을 때 `agentSettlementAmount=654` 포함 응답 아이템 출력 확인
+      - `kr.co.vividnext.sodalive.admin.partner.agent.settlement.AdminAgentSettlementSnapshotController` 클래스 로딩 성공
+
+### 10차 정정
+- 무엇을: 체크리스트 279번의 충족 범위를 문서/코드 기준으로 다시 대조하고, 누락된 후속 구현 항목을 기존 계획 문서에 추가했다.
+- 왜: 현재 스냅샷 구현은 `appliedAgentSettlementRatio`와 계산 숫자값은 저장하지만, 설계 초안과 체크리스트 문맥이 요구하는 `assignmentId`, `agentSettlementRatioId`는 저장하지 않아 문서 기준 완전 충족으로 보기 어려웠기 때문이다.
+- 어떻게:
+  - 체크리스트 279 바로 아래에 정정 메모와 후속 체크박스 3개를 추가해 누락 범위를 `snapshot 컬럼`, `query projection`, `finalize 매핑/테스트`로 분리했다.
+  - 문서 설계 초안(`assignmentId`, `agentSettlementRatioId`)과 현재 구현(`AgentSettlementSnapshot`, `AdminAgentSettlementSnapshotService`, `agent_settlement_snapshot` DDL)을 대조해 차이를 명시했다.
+  - 실행/확인 결과:
+    - `docs/20260408_에이전트권한및정산기능추가.md:106-123, 278-282` 확인 → 스냅샷 설계 초안과 체크리스트가 `assignmentId`, `agentSettlementRatioId`, `appliedAgentSettlementRatio`, 계산 숫자값 저장을 함께 기대함을 재확인
+    - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/settlement/snapshot/AgentSettlementSnapshot.kt` 확인 → 현재는 `appliedAgentSettlementRatio`와 계산 숫자값만 저장하고 `assignmentId`, `agentSettlementRatioId` 필드는 없음
+    - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotService.kt` 확인 → finalize 매핑이 ratio 값과 숫자값만 채우고 FK 값은 생성하지 않음
+    - `docs/20260409_partner_agent_assignment_ratio_ddl.sql` 확인 → `agent_settlement_snapshot` 테이블에도 `assignment_id`, `agent_settlement_ratio_id` 컬럼이 없음
+
+### 11차 정정
+- 무엇을: ratio backdate 금지, active row 단일성 보장, 관리자 쓰기 직렬화, snapshot traceability 범위 메모를 기존 체크리스트에 후속 작업으로 추가했다.
+- 왜: 현재 `AdminAgentSettlementRatioService`는 `effectiveFrom`의 시간순 검증 없이 활성 row를 닫고 새 row를 저장해 backdate 시 interval 무결성이 깨질 수 있고, `agent_settlement_ratio`/`agent_creator_relation` DDL은 active row 중복을 막는 DB 제약이 없어 동시 요청 시 조회 결과 왜곡 위험이 있기 때문이다. 또한 snapshot의 `assignmentId`/`agentSettlementRatioId` 보완은 문서 279의 의도는 충족하지만 mixed-period creator summary의 완전 provenance까지는 아님을 분명히 할 필요가 있었다.
+- 어떻게:
+  - 체크리스트 ratio 구간에 `effectiveFrom` backdate/same-time/overlap 거절 검증, `agent_settlement_ratio`/`agent_creator_relation`의 MySQL 생성 컬럼 + UNIQUE 인덱스 + 기간 무결성 제약, `MemberRepository.findByIdForUpdate(...)` 기반 비관적 락 적용 항목을 추가했다.
+  - snapshot 279 보완 항목 아래에 `assignmentId`/`agentSettlementRatioId` 추가가 creator-period summary 기준 추적성은 복구하지만, mixed-period summary의 완전 provenance가 필요하면 별도 source detail 테이블이 필요하다는 참고 메모를 추가했다.
+  - 실행/확인 결과:
+    - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioService.kt` 확인 → `effectiveFrom`의 시간순/겹침 검증 없이 active row close + insert 수행
+    - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorService.kt` 확인 → overlap 검증은 있지만 비관적 락/DB active uniqueness 없이 read-then-write 수행
+    - `src/main/kotlin/kr/co/vividnext/sodalive/member/MemberRepository.kt`, `member/contentpreference/MemberContentPreferenceService.kt`, `member/contentpreference/MemberContentPreferenceRepository.kt` 확인 → `findByIdForUpdate`, `@Lock(PESSIMISTIC_WRITE)`, `saveAndFlush + DataIntegrityViolationException` 재조회 패턴이 저장소 기존 관례로 존재함
+    - `docs/20260409_partner_agent_assignment_ratio_ddl.sql` 확인 → 현재 `agent_settlement_ratio`, `agent_creator_relation` 모두 active row 단일성 보장용 unique 제약과 기간 무결성 제약이 없음
+    - MySQL 제약 조사 결과 확인 → partial unique index 대신 생성 컬럼 + UNIQUE 인덱스가 가장 실용적이며, nullable unique를 직접 사용하는 방식은 active row 중복을 막지 못함
+
+### 12차 정정
+- 무엇을: 남은 후속 수정 범위를 실제 구현 순서대로 더 잘게 쪼갠 작업 계획으로 재배치했다.
+- 왜: 현재 체크리스트는 해야 할 항목은 보이지만, 어떤 순서로 진행해야 리스크가 가장 적은지와 어떤 파일부터 수정해야 하는지가 한 번에 드러나지 않았기 때문이다.
+- 어떻게:
+  - `세부 구현 메모` 아래에 `### 5. 후속 보완 구현 순서 (2026-04-09 추가)` 섹션을 새로 만들고, 작업을 `ratio 입력 무결성 차단 → 관리자 쓰기 직렬화 → DDL/엔티티 정합성 점검 → snapshot traceability 연결 → 최종 회귀 검증` 순서로 나눴다.
+  - 각 단계마다 실제 수정 대상 파일 경로와 테스트/검증 명령을 체크박스로 세분화해, 바로 실행 가능한 작업 순서 문서가 되도록 정리했다.
+  - 실행/확인 결과:
+    - `docs/20260408_에이전트권한및정산기능추가.md:326-361` 확인 → 후속 보완 구현 순서 섹션과 5개 단계 체크리스트가 문서에 반영됨
+    - `grep` 확인 → `### 5. 후속 보완 구현 순서`, `MemberRepository.findByIdForUpdate(...)`, `assignmentId`, `agentSettlementRatioId`, `./gradlew test`, `./gradlew build`가 새 순서형 계획에 포함됨
+    - 코드/빌드 실행 여부 → 문서 수정 단계이므로 미실행
+
+### 13차 정정
+- 무엇을: snapshot traceability 문제를 `summary FK 보완 + full audit provenance detail`까지 포함해 닫는 방향으로 체크리스트를 확장했다.
+- 왜: 현재 creator-period summary snapshot은 `creatorId` 기준 병합 후 한 줄로 저장되므로, `assignmentId`/`agentSettlementRatioId`만 summary에 추가해도 mixed-period 구간의 원천 provenance는 완전히 복원되지 않기 때문이다. 완전 감사 추적이 필요하면 summary와 별도로 source detail row를 함께 저장해야 한다.
+- 어떻게:
+  - snapshot 체크리스트 아래에 `agent_settlement_snapshot_source_detail`(가칭) DDL 추가, finalize의 `raw source row -> source detail 저장 -> summary 저장` 순서 보강, mixed-period summary null 규칙 테스트 고정 항목을 추가했다.
+  - `세부 구현 메모 > 5-4`를 확장해 DDL → detail entity/repository → finalize 저장 순서 → summary null 규칙 → detail-summary 합계 검증까지 실제 구현 순서대로 재배치했다.
+  - 실행/확인 결과:
+    - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotService.kt` 확인 → 현재는 `rows.toMergedResponseItems()`로 creator-period summary만 저장하고 source detail 저장 단계는 없음
+    - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/GetAgentCreatorSettlementSummaryQueryData.kt`, `GetAgentChannelDonationSettlementByCreatorResponse.kt` 확인 → `creatorId` 기준 병합 구조가 mixed-period provenance 소실의 직접 원인임
+    - `docs/20260408_에이전트권한및정산기능추가.md:106-123` 확인 → 문서 설계 초안은 summary FK/숫자 스냅샷까지는 기대하지만, full audit provenance는 별도 설계가 필요함
+    - Oracle/탐색 결과 확인 → `assignmentId + agentSettlementRatioId` summary 보완은 부분 해결이고, `source detail`까지 포함해야 mixed-period provenance 공백이 닫힘
+
+### 14차 구현 및 정리
+- 무엇을: 문서에서 미체크로 남아 있던 ratio/assignment 무결성, 쓰기 직렬화, snapshot traceability/source detail provenance, 최종 검증 항목을 실제 구현 결과에 맞게 모두 완료 처리하고, 검증 기록을 최신 상태로 갱신했다.
+- 왜: 체크리스트와 실제 코드 상태가 어긋나 있으면 이후 작업자가 범위를 잘못 이해하거나, 이미 끝난 작업을 다시 추적해야 하는 비용이 생기기 때문이다. 또한 이번 변경은 정산 무결성과 확정 스냅샷 provenance를 함께 건드렸기 때문에, 최신 검증 결과를 문서에 남겨두는 것이 필수였다.
+- 어떻게:
+  - `AdminAgentSettlementRatioService`, `AdminAgentCreatorService`, `AgentSettlementSnapshot`, `AdminAgentSettlementSnapshotService`, `AgentCalculateQueryRepository`, `docs/20260409_partner_agent_assignment_ratio_ddl.sql`을 기준으로 미체크 항목을 다시 대조하고, 실제 구현된 항목은 모두 `- [x]`로 갱신했다.
+  - ratio 쪽에는 `effectiveFrom` backdate/same-time/history overlap 차단과 concurrent unique violation 변환 테스트를 추가했고, assignment 쪽에는 `findByIdForUpdate(...)` + `saveAndFlush` + `DataIntegrityViolationException` 대응 패턴과 테스트를 맞췄다.
+  - snapshot 쪽에는 `assignmentId`, `agentSettlementRatioId`, `agent_settlement_snapshot_source_detail` provenance 저장, mixed-period summary null 규칙, detail 합계 검증까지 반영했다.
+  - 실행/확인 결과:
+    - `grep "^- \[ \]|^  - \[ \]" docs/20260408_에이전트권한및정산기능추가.md` → 미체크 항목 0건 확인
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.ratio.AgentSettlementRatioServiceTest"` → 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.settlement.AdminAgentSettlementSnapshotServiceTest"` → 성공
+    - `./gradlew test` → 성공
+    - `./gradlew build` → 성공
+    - `Oracle` completion review → 현재 문서 기준 미체크 항목 판단을 검토한 뒤, 테스트/문서 정리를 마치면 완료 처리 가능하다는 방향 재확인
+
+### 15차 수정
+- 무엇을: `agent_settlement_ratio` 이력이 없는 AGENT 정산 조회에서 agent 정산금을 0%가 아니라 10% 기본값으로 계산하도록 수정하고, 해당 동작을 서비스 테스트와 수동 계산으로 검증했다.
+- 왜: 현재 구현은 agent 비율 row가 없으면 agent 정산금이 0원으로 계산되는데, 이번 정책 결정은 미설정 상태를 10% 기본 비율로 간주하는 것이기 때문이다.
+- 어떻게:
+  - `docs/20260408_에이전트권한및정산기능추가.md` 체크리스트에 기본 fallback 10% 변경 항목을 추가한 뒤 완료 처리했다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateServiceTest.kt`에 `agentSettlementRatio = null`일 때 일반 정산/채널후원 응답이 10%를 적용하는 RED 테스트 2건을 추가했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/GetAgentCreatorSettlementSummaryQueryData.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/GetAgentChannelDonationSettlementByCreatorResponse.kt`에서 null fallback을 `DEFAULT_AGENT_SETTLEMENT_RATIO = 10`으로 변경했다.
+  - 실행/확인 결과:
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest.shouldApplyDefaultAgentSettlementRatioWhenAgentRatioHistoryDoesNotExist" --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest.shouldApplyDefaultAgentSettlementRatioToChannelDonationWhenAgentRatioHistoryDoesNotExist"` → 1차 실행 실패, 수정 후 재실행 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.*"` → 성공
+    - `./gradlew build` → 성공
+    - `lsp_diagnostics` on Kotlin changed files → 불가 (현재 환경에 `.kt`용 LSP 서버 미구성)
+    - `jshell --class-path "build/classes/kotlin/main:build/resources/main:..."` 수동 확인 → `genericAgentSettlementAmount=131`, `channelAgentSettlementAmount=397`
+
+### 16차 수정
+- 무엇을: 관리자 에이전트 정산 비율 생성/수정 API에 `settlementRatio` 0..100 범위 검증을 추가하고, 문서 체크리스트 미완료 항목을 실제 구현 상태로 정리했다.
+- 왜: 계획 문서에는 범위 검증 항목이 남아 있었지만 실제 서비스에는 guard가 없어 음수나 100 초과 비율이 저장될 수 있었기 때문이다.
+- 어떻게:
+  - `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AgentSettlementRatioServiceTest.kt`에 `settlementRatio = -1` 생성, `settlementRatio = 101` 수정 요청이 `common.error.invalid_request`를 던지고 `memberRepository`/`repository`가 호출되지 않는다는 RED 테스트 2건을 추가했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioService.kt`에 `validateSettlementRatio(settlementRatio: Int)`를 추가하고 `createAgentSettlementRatio`, `updateAgentSettlementRatio` 진입부에서 0..100 범위를 먼저 검증하도록 수정했다.
+  - `docs/20260408_에이전트권한및정산기능추가.md`의 체크리스트 277 항목을 완료 처리했다.
+  - 실행/확인 결과:
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.ratio.AgentSettlementRatioServiceTest.shouldThrowWhenCreatingRatioWithSettlementRatioBelowZero" --tests "kr.co.vividnext.sodalive.admin.partner.agent.ratio.AgentSettlementRatioServiceTest.shouldThrowWhenUpdatingRatioWithSettlementRatioAboveHundred"` → 1차 실행 실패, 서비스 수정 후 재실행 성공
+    - `./gradlew build` → 성공
+    - `jshell --class-path "/Users/klaus/Develop/sodalive/Server/sodalive/build/classes/kotlin/main:/Users/klaus/Develop/sodalive/Server/sodalive/build/resources/main:..."` 수동 확인 → `messageKey=common.error.invalid_request`, `memberRepositoryCalls=0`, `repositoryCalls=0`
+    - `lsp_diagnostics` on Kotlin changed files → 불가 (현재 환경에 `.kt`용 LSP 서버 미구성)
+
+### 17차 수정
+- 무엇을: `creator/list` 현재 소속 판정을 현재 시각 활성 구간 기준으로 바로잡고, AGENT 정산 조회의 빈 페이지가 전체 결과로 새는 pagination 버그를 함께 수정했다.
+- 왜: 기존 구현은 미래 `assignedAt` 소속을 너무 일찍 노출하고 미래 `unassignedAt` 소속을 너무 일찍 숨겼으며, paged query의 사전 조회 `creatorIds`가 빈 리스트일 때 2차 rows query가 전체 결과를 다시 읽을 수 있었기 때문이다.
+- 어떻게:
+  - `docs/20260408_에이전트권한및정산기능추가.md` 체크리스트에 두 버그 수정 항목을 추가한 뒤 완료 처리했다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepositoryTest.kt`에 현재 시각 활성 구간 creator list 회귀 테스트와, 5개 카테고리 paged query가 빈 페이지에서 빈 rows를 반환하는 회귀 테스트를 RED로 추가했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateService.kt`에서 `getAssignedCreators()`가 `currentTime`을 한 번만 잡아 count/items 조회에 공유하도록 수정했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepository.kt`에서 creator list 쿼리를 `assignedAt <= now < unassignedAt` 반열린 구간으로 바꾸고, 5개 paged calculate 메서드가 사전 조회 `creatorIds`가 빈 리스트면 즉시 `emptyList()`를 반환하도록 보강했다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateServiceTest.kt`는 변경된 repository 시그니처에 맞춰 현재 시각 인자를 검증하도록 갱신했다.
+  - 실행/확인 결과:
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest.shouldGetAssignedCreatorsOnlyWithinCurrentAssignmentWindow" --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest.shouldReturnEmptyRowsWhenPagedCreatorSelectionIsEmptyAcrossAllCategories"` → 1차 실행 실패, 수정 후 재실행 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest"` → 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.*"` → 성공
+    - `./gradlew build` → 성공
+    - `lsp_diagnostics` on changed Kotlin files → 불가 (현재 환경에 `.kt`용 LSP 서버 미구성)

docs/20260409_partner_agent_assignment_ratio_ddl.sql

@@ -0,0 +1,658 @@
+SET @schema_name := DATABASE();
+
+SET @agent_creator_relation_table_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.tables
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_creator_relation'
+);
+
+SET @create_agent_creator_relation_table_sql := IF(
+    @agent_creator_relation_table_exists = 0,
+    'CREATE TABLE agent_creator_relation (
+        id BIGINT NOT NULL AUTO_INCREMENT COMMENT ''PK'',
+        agent_id BIGINT NOT NULL COMMENT ''에이전트 회원 ID (member.id 참조)'',
+        creator_id BIGINT NOT NULL COMMENT ''크리에이터 회원 ID (member.id 참조)'',
+        assigned_at TIMESTAMP NOT NULL COMMENT ''소속 시작 시각'',
+        unassigned_at TIMESTAMP NULL DEFAULT NULL COMMENT ''소속 종료 시각(NULL이면 현재 활성 소속)'',
+        active_creator_key TINYINT GENERATED ALWAYS AS (
+            CASE
+                WHEN unassigned_at IS NULL THEN 1
+                ELSE NULL
+            END
+        ) STORED,
+        created_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP COMMENT ''생성 시각'',
+        updated_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT ''수정 시각'',
+        PRIMARY KEY (id),
+        UNIQUE KEY uk_agent_creator_relation_creator_active (creator_id, active_creator_key),
+        KEY idx_agent_creator_relation_agent_id (agent_id),
+        KEY idx_agent_creator_relation_creator_id (creator_id),
+        KEY idx_agent_creator_relation_agent_unassigned_at (agent_id, unassigned_at),
+        KEY idx_agent_creator_relation_creator_assigned_at (creator_id, assigned_at),
+        KEY idx_agent_creator_relation_creator_unassigned_at (creator_id, unassigned_at),
+        CONSTRAINT fk_agent_creator_relation_agent_id FOREIGN KEY (agent_id) REFERENCES member (id),
+        CONSTRAINT fk_agent_creator_relation_creator_id FOREIGN KEY (creator_id) REFERENCES member (id),
+        CONSTRAINT chk_agent_creator_relation_period CHECK (unassigned_at IS NULL OR assigned_at < unassigned_at)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT=''에이전트-크리에이터 소속 관계''',
+    'SELECT ''agent_creator_relation already exists'' AS message'
+);
+
+PREPARE create_agent_creator_relation_table_stmt FROM @create_agent_creator_relation_table_sql;
+EXECUTE create_agent_creator_relation_table_stmt;
+DEALLOCATE PREPARE create_agent_creator_relation_table_stmt;
+
+SET @agent_creator_relation_has_assigned_at := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_creator_relation'
+      AND column_name = 'assigned_at'
+);
+
+SET @alter_agent_creator_relation_add_assigned_at_sql := IF(
+    @agent_creator_relation_table_exists = 1 AND @agent_creator_relation_has_assigned_at = 0,
+    'ALTER TABLE agent_creator_relation ADD COLUMN assigned_at TIMESTAMP NOT NULL COMMENT ''소속 시작 시각'' AFTER creator_id',
+    'SELECT ''agent_creator_relation.assigned_at already exists'' AS message'
+);
+
+PREPARE alter_agent_creator_relation_add_assigned_at_stmt FROM @alter_agent_creator_relation_add_assigned_at_sql;
+EXECUTE alter_agent_creator_relation_add_assigned_at_stmt;
+DEALLOCATE PREPARE alter_agent_creator_relation_add_assigned_at_stmt;
+
+SET @agent_creator_relation_has_unassigned_at := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_creator_relation'
+      AND column_name = 'unassigned_at'
+);
+
+SET @alter_agent_creator_relation_add_unassigned_at_sql := IF(
+    @agent_creator_relation_table_exists = 1 AND @agent_creator_relation_has_unassigned_at = 0,
+    'ALTER TABLE agent_creator_relation ADD COLUMN unassigned_at TIMESTAMP NULL DEFAULT NULL COMMENT ''소속 종료 시각(NULL이면 현재 활성 소속)'' AFTER assigned_at',
+    'SELECT ''agent_creator_relation.unassigned_at already exists'' AS message'
+);
+
+PREPARE alter_agent_creator_relation_add_unassigned_at_stmt FROM @alter_agent_creator_relation_add_unassigned_at_sql;
+EXECUTE alter_agent_creator_relation_add_unassigned_at_stmt;
+DEALLOCATE PREPARE alter_agent_creator_relation_add_unassigned_at_stmt;
+
+SET @agent_creator_relation_has_active_creator_key := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_creator_relation'
+      AND column_name = 'active_creator_key'
+);
+
+SET @alter_agent_creator_relation_add_active_creator_key_sql := IF(
+    @agent_creator_relation_table_exists = 1 AND @agent_creator_relation_has_active_creator_key = 0,
+    'ALTER TABLE agent_creator_relation ADD COLUMN active_creator_key TINYINT GENERATED ALWAYS AS (CASE WHEN unassigned_at IS NULL THEN 1 ELSE NULL END) STORED AFTER unassigned_at',
+    'SELECT ''agent_creator_relation.active_creator_key already exists'' AS message'
+);
+
+PREPARE alter_agent_creator_relation_add_active_creator_key_stmt FROM @alter_agent_creator_relation_add_active_creator_key_sql;
+EXECUTE alter_agent_creator_relation_add_active_creator_key_stmt;
+DEALLOCATE PREPARE alter_agent_creator_relation_add_active_creator_key_stmt;
+
+SET @agent_creator_relation_creator_unique_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_creator_relation'
+      AND index_name = 'uk_agent_creator_relation_creator_id'
+);
+
+SET @drop_agent_creator_relation_creator_unique_sql := IF(
+    @agent_creator_relation_creator_unique_exists > 0,
+    'ALTER TABLE agent_creator_relation DROP INDEX uk_agent_creator_relation_creator_id',
+    'SELECT ''uk_agent_creator_relation_creator_id already dropped'' AS message'
+);
+
+PREPARE drop_agent_creator_relation_creator_unique_stmt FROM @drop_agent_creator_relation_creator_unique_sql;
+EXECUTE drop_agent_creator_relation_creator_unique_stmt;
+DEALLOCATE PREPARE drop_agent_creator_relation_creator_unique_stmt;
+
+SET @agent_creator_relation_creator_active_unique_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_creator_relation'
+      AND index_name = 'uk_agent_creator_relation_creator_active'
+);
+
+SET @add_agent_creator_relation_creator_active_unique_sql := IF(
+    @agent_creator_relation_table_exists = 1 AND @agent_creator_relation_creator_active_unique_exists = 0,
+    'ALTER TABLE agent_creator_relation ADD UNIQUE INDEX uk_agent_creator_relation_creator_active (creator_id, active_creator_key)',
+    'SELECT ''uk_agent_creator_relation_creator_active already exists'' AS message'
+);
+
+PREPARE add_agent_creator_relation_creator_active_unique_stmt FROM @add_agent_creator_relation_creator_active_unique_sql;
+EXECUTE add_agent_creator_relation_creator_active_unique_stmt;
+DEALLOCATE PREPARE add_agent_creator_relation_creator_active_unique_stmt;
+
+SET @agent_creator_relation_period_check_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.table_constraints
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_creator_relation'
+      AND constraint_name = 'chk_agent_creator_relation_period'
+      AND constraint_type = 'CHECK'
+);
+
+SET @add_agent_creator_relation_period_check_sql := IF(
+    @agent_creator_relation_table_exists = 1 AND @agent_creator_relation_period_check_exists = 0,
+    'ALTER TABLE agent_creator_relation ADD CONSTRAINT chk_agent_creator_relation_period CHECK (unassigned_at IS NULL OR assigned_at < unassigned_at)',
+    'SELECT ''chk_agent_creator_relation_period already exists'' AS message'
+);
+
+PREPARE add_agent_creator_relation_period_check_stmt FROM @add_agent_creator_relation_period_check_sql;
+EXECUTE add_agent_creator_relation_period_check_stmt;
+DEALLOCATE PREPARE add_agent_creator_relation_period_check_stmt;
+
+SET @agent_creator_relation_agent_unassigned_index_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_creator_relation'
+      AND index_name = 'idx_agent_creator_relation_agent_unassigned_at'
+);
+
+SET @add_agent_creator_relation_agent_unassigned_index_sql := IF(
+    @agent_creator_relation_table_exists = 1 AND @agent_creator_relation_agent_unassigned_index_exists = 0,
+    'ALTER TABLE agent_creator_relation ADD INDEX idx_agent_creator_relation_agent_unassigned_at (agent_id, unassigned_at)',
+    'SELECT ''idx_agent_creator_relation_agent_unassigned_at already exists'' AS message'
+);
+
+PREPARE add_agent_creator_relation_agent_unassigned_index_stmt FROM @add_agent_creator_relation_agent_unassigned_index_sql;
+EXECUTE add_agent_creator_relation_agent_unassigned_index_stmt;
+DEALLOCATE PREPARE add_agent_creator_relation_agent_unassigned_index_stmt;
+
+SET @agent_creator_relation_creator_assigned_index_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_creator_relation'
+      AND index_name = 'idx_agent_creator_relation_creator_assigned_at'
+);
+
+SET @add_agent_creator_relation_creator_assigned_index_sql := IF(
+    @agent_creator_relation_table_exists = 1 AND @agent_creator_relation_creator_assigned_index_exists = 0,
+    'ALTER TABLE agent_creator_relation ADD INDEX idx_agent_creator_relation_creator_assigned_at (creator_id, assigned_at)',
+    'SELECT ''idx_agent_creator_relation_creator_assigned_at already exists'' AS message'
+);
+
+PREPARE add_agent_creator_relation_creator_assigned_index_stmt FROM @add_agent_creator_relation_creator_assigned_index_sql;
+EXECUTE add_agent_creator_relation_creator_assigned_index_stmt;
+DEALLOCATE PREPARE add_agent_creator_relation_creator_assigned_index_stmt;
+
+SET @agent_creator_relation_creator_unassigned_index_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_creator_relation'
+      AND index_name = 'idx_agent_creator_relation_creator_unassigned_at'
+);
+
+SET @add_agent_creator_relation_creator_unassigned_index_sql := IF(
+    @agent_creator_relation_table_exists = 1 AND @agent_creator_relation_creator_unassigned_index_exists = 0,
+    'ALTER TABLE agent_creator_relation ADD INDEX idx_agent_creator_relation_creator_unassigned_at (creator_id, unassigned_at)',
+    'SELECT ''idx_agent_creator_relation_creator_unassigned_at already exists'' AS message'
+);
+
+PREPARE add_agent_creator_relation_creator_unassigned_index_stmt FROM @add_agent_creator_relation_creator_unassigned_index_sql;
+EXECUTE add_agent_creator_relation_creator_unassigned_index_stmt;
+DEALLOCATE PREPARE add_agent_creator_relation_creator_unassigned_index_stmt;
+
+SET @agent_settlement_ratio_table_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.tables
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_ratio'
+);
+
+SET @create_agent_settlement_ratio_table_sql := IF(
+    @agent_settlement_ratio_table_exists = 0,
+    'CREATE TABLE agent_settlement_ratio (
+        id BIGINT NOT NULL AUTO_INCREMENT COMMENT ''PK'',
+        member_id BIGINT NOT NULL COMMENT ''에이전트 회원 ID (member.id 참조)'',
+        settlement_ratio INT NOT NULL COMMENT ''에이전트 정산 비율(%)'',
+        effective_from TIMESTAMP NOT NULL COMMENT ''비율 시작 시각'',
+        effective_to TIMESTAMP NULL DEFAULT NULL COMMENT ''비율 종료 시각(NULL이면 현재 활성 비율)'',
+        active_ratio_key TINYINT GENERATED ALWAYS AS (
+            CASE
+                WHEN effective_to IS NULL THEN 1
+                ELSE NULL
+            END
+        ) STORED,
+        created_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP COMMENT ''생성 시각'',
+        updated_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT ''수정 시각'',
+        PRIMARY KEY (id),
+        UNIQUE KEY uk_agent_settlement_ratio_member_active (member_id, active_ratio_key),
+        KEY idx_agent_settlement_ratio_member_effective_to (member_id, effective_to),
+        KEY idx_agent_settlement_ratio_member_effective_from (member_id, effective_from),
+        CONSTRAINT fk_agent_settlement_ratio_member_id FOREIGN KEY (member_id) REFERENCES member (id),
+        CONSTRAINT chk_agent_settlement_ratio_period CHECK (effective_to IS NULL OR effective_from < effective_to)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT=''에이전트 정산 비율''',
+    'SELECT ''agent_settlement_ratio already exists'' AS message'
+);
+
+PREPARE create_agent_settlement_ratio_table_stmt FROM @create_agent_settlement_ratio_table_sql;
+EXECUTE create_agent_settlement_ratio_table_stmt;
+DEALLOCATE PREPARE create_agent_settlement_ratio_table_stmt;
+
+SET @agent_settlement_ratio_has_effective_from := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_ratio'
+      AND column_name = 'effective_from'
+);
+
+SET @alter_agent_settlement_ratio_add_effective_from_sql := IF(
+    @agent_settlement_ratio_table_exists = 1 AND @agent_settlement_ratio_has_effective_from = 0,
+    'ALTER TABLE agent_settlement_ratio ADD COLUMN effective_from TIMESTAMP NOT NULL COMMENT ''비율 시작 시각'' AFTER settlement_ratio',
+    'SELECT ''agent_settlement_ratio.effective_from already exists'' AS message'
+);
+
+PREPARE alter_agent_settlement_ratio_add_effective_from_stmt FROM @alter_agent_settlement_ratio_add_effective_from_sql;
+EXECUTE alter_agent_settlement_ratio_add_effective_from_stmt;
+DEALLOCATE PREPARE alter_agent_settlement_ratio_add_effective_from_stmt;
+
+SET @agent_settlement_ratio_has_effective_to := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_ratio'
+      AND column_name = 'effective_to'
+);
+
+SET @alter_agent_settlement_ratio_add_effective_to_sql := IF(
+    @agent_settlement_ratio_table_exists = 1 AND @agent_settlement_ratio_has_effective_to = 0,
+    'ALTER TABLE agent_settlement_ratio ADD COLUMN effective_to TIMESTAMP NULL DEFAULT NULL COMMENT ''비율 종료 시각(NULL이면 현재 활성 비율)'' AFTER effective_from',
+    'SELECT ''agent_settlement_ratio.effective_to already exists'' AS message'
+);
+
+PREPARE alter_agent_settlement_ratio_add_effective_to_stmt FROM @alter_agent_settlement_ratio_add_effective_to_sql;
+EXECUTE alter_agent_settlement_ratio_add_effective_to_stmt;
+DEALLOCATE PREPARE alter_agent_settlement_ratio_add_effective_to_stmt;
+
+SET @agent_settlement_ratio_has_active_ratio_key := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_ratio'
+      AND column_name = 'active_ratio_key'
+);
+
+SET @alter_agent_settlement_ratio_add_active_ratio_key_sql := IF(
+    @agent_settlement_ratio_table_exists = 1 AND @agent_settlement_ratio_has_active_ratio_key = 0,
+    'ALTER TABLE agent_settlement_ratio ADD COLUMN active_ratio_key TINYINT GENERATED ALWAYS AS (CASE WHEN effective_to IS NULL THEN 1 ELSE NULL END) STORED AFTER effective_to',
+    'SELECT ''agent_settlement_ratio.active_ratio_key already exists'' AS message'
+);
+
+PREPARE alter_agent_settlement_ratio_add_active_ratio_key_stmt FROM @alter_agent_settlement_ratio_add_active_ratio_key_sql;
+EXECUTE alter_agent_settlement_ratio_add_active_ratio_key_stmt;
+DEALLOCATE PREPARE alter_agent_settlement_ratio_add_active_ratio_key_stmt;
+
+SET @agent_settlement_ratio_member_unique_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_ratio'
+      AND index_name = 'uk_agent_settlement_ratio_member_id'
+);
+
+SET @drop_agent_settlement_ratio_member_unique_sql := IF(
+    @agent_settlement_ratio_member_unique_exists > 0,
+    'ALTER TABLE agent_settlement_ratio DROP INDEX uk_agent_settlement_ratio_member_id',
+    'SELECT ''uk_agent_settlement_ratio_member_id already dropped'' AS message'
+);
+
+PREPARE drop_agent_settlement_ratio_member_unique_stmt FROM @drop_agent_settlement_ratio_member_unique_sql;
+EXECUTE drop_agent_settlement_ratio_member_unique_stmt;
+DEALLOCATE PREPARE drop_agent_settlement_ratio_member_unique_stmt;
+
+SET @agent_settlement_ratio_member_active_unique_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_ratio'
+      AND index_name = 'uk_agent_settlement_ratio_member_active'
+);
+
+SET @add_agent_settlement_ratio_member_active_unique_sql := IF(
+    @agent_settlement_ratio_table_exists = 1 AND @agent_settlement_ratio_member_active_unique_exists = 0,
+    'ALTER TABLE agent_settlement_ratio ADD UNIQUE INDEX uk_agent_settlement_ratio_member_active (member_id, active_ratio_key)',
+    'SELECT ''uk_agent_settlement_ratio_member_active already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_ratio_member_active_unique_stmt FROM @add_agent_settlement_ratio_member_active_unique_sql;
+EXECUTE add_agent_settlement_ratio_member_active_unique_stmt;
+DEALLOCATE PREPARE add_agent_settlement_ratio_member_active_unique_stmt;
+
+SET @agent_settlement_ratio_has_deleted_at := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_ratio'
+      AND column_name = 'deleted_at'
+);
+
+SET @drop_agent_settlement_ratio_deleted_at_sql := IF(
+    @agent_settlement_ratio_table_exists = 1 AND @agent_settlement_ratio_has_deleted_at > 0,
+    'ALTER TABLE agent_settlement_ratio DROP COLUMN deleted_at',
+    'SELECT ''agent_settlement_ratio.deleted_at already dropped'' AS message'
+);
+
+PREPARE drop_agent_settlement_ratio_deleted_at_stmt FROM @drop_agent_settlement_ratio_deleted_at_sql;
+EXECUTE drop_agent_settlement_ratio_deleted_at_stmt;
+DEALLOCATE PREPARE drop_agent_settlement_ratio_deleted_at_stmt;
+
+SET @agent_settlement_ratio_period_check_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.table_constraints
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_ratio'
+      AND constraint_name = 'chk_agent_settlement_ratio_period'
+      AND constraint_type = 'CHECK'
+);
+
+SET @add_agent_settlement_ratio_period_check_sql := IF(
+    @agent_settlement_ratio_table_exists = 1 AND @agent_settlement_ratio_period_check_exists = 0,
+    'ALTER TABLE agent_settlement_ratio ADD CONSTRAINT chk_agent_settlement_ratio_period CHECK (effective_to IS NULL OR effective_from < effective_to)',
+    'SELECT ''chk_agent_settlement_ratio_period already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_ratio_period_check_stmt FROM @add_agent_settlement_ratio_period_check_sql;
+EXECUTE add_agent_settlement_ratio_period_check_stmt;
+DEALLOCATE PREPARE add_agent_settlement_ratio_period_check_stmt;
+
+SET @agent_settlement_ratio_member_effective_to_index_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_ratio'
+      AND index_name = 'idx_agent_settlement_ratio_member_effective_to'
+);
+
+SET @add_agent_settlement_ratio_member_effective_to_index_sql := IF(
+    @agent_settlement_ratio_table_exists = 1 AND @agent_settlement_ratio_member_effective_to_index_exists = 0,
+    'ALTER TABLE agent_settlement_ratio ADD INDEX idx_agent_settlement_ratio_member_effective_to (member_id, effective_to)',
+    'SELECT ''idx_agent_settlement_ratio_member_effective_to already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_ratio_member_effective_to_index_stmt FROM @add_agent_settlement_ratio_member_effective_to_index_sql;
+EXECUTE add_agent_settlement_ratio_member_effective_to_index_stmt;
+DEALLOCATE PREPARE add_agent_settlement_ratio_member_effective_to_index_stmt;
+
+SET @agent_settlement_ratio_member_effective_from_index_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_ratio'
+      AND index_name = 'idx_agent_settlement_ratio_member_effective_from'
+);
+
+SET @add_agent_settlement_ratio_member_effective_from_index_sql := IF(
+    @agent_settlement_ratio_table_exists = 1 AND @agent_settlement_ratio_member_effective_from_index_exists = 0,
+    'ALTER TABLE agent_settlement_ratio ADD INDEX idx_agent_settlement_ratio_member_effective_from (member_id, effective_from)',
+    'SELECT ''idx_agent_settlement_ratio_member_effective_from already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_ratio_member_effective_from_index_stmt FROM @add_agent_settlement_ratio_member_effective_from_index_sql;
+EXECUTE add_agent_settlement_ratio_member_effective_from_index_stmt;
+DEALLOCATE PREPARE add_agent_settlement_ratio_member_effective_from_index_stmt;
+
+SET @agent_settlement_snapshot_table_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.tables
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot'
+);
+
+SET @create_agent_settlement_snapshot_table_sql := IF(
+    @agent_settlement_snapshot_table_exists = 0,
+    'CREATE TABLE agent_settlement_snapshot (
+        id BIGINT NOT NULL AUTO_INCREMENT COMMENT ''PK'',
+        period_start TIMESTAMP NOT NULL COMMENT ''정산 기간 시작 시각'',
+        period_end TIMESTAMP NOT NULL COMMENT ''정산 기간 종료 시각'',
+        settlement_type VARCHAR(50) NOT NULL COMMENT ''정산 유형(LIVE, CONTENT, COMMUNITY, CHANNEL_DONATION, CONTENT_DONATION)'',
+        agent_id BIGINT NOT NULL COMMENT ''에이전트 회원 ID 스냅샷'',
+        agent_nickname VARCHAR(255) NOT NULL COMMENT ''에이전트 닉네임 스냅샷'',
+        creator_id BIGINT NOT NULL COMMENT ''크리에이터 회원 ID 스냅샷'',
+        creator_nickname VARCHAR(255) NOT NULL COMMENT ''크리에이터 닉네임 스냅샷'',
+        assignment_id BIGINT NULL COMMENT ''적용된 소속 이력 row ID 스냅샷'',
+        agent_settlement_ratio_id BIGINT NULL COMMENT ''적용된 에이전트 정산 비율 이력 row ID 스냅샷'',
+        applied_agent_settlement_ratio INT NULL COMMENT ''적용된 에이전트 정산 비율 스냅샷(creator-level summary에 단일 값으로 귀결될 때만 저장)'',
+        count INT NOT NULL COMMENT ''건수 스냅샷'',
+        total_can INT NOT NULL COMMENT ''총 캔 수 스냅샷'',
+        krw INT NOT NULL COMMENT ''원화 금액 스냅샷'',
+        fee INT NOT NULL COMMENT ''수수료 스냅샷'',
+        settlement_amount INT NOT NULL COMMENT ''크리에이터 세전 정산금 스냅샷'',
+        tax INT NOT NULL COMMENT ''원천세/세금 스냅샷'',
+        deposit_amount INT NOT NULL COMMENT ''입금액 스냅샷'',
+        agent_settlement_amount INT NOT NULL COMMENT ''에이전트 정산금 스냅샷'',
+        finalized_at TIMESTAMP NOT NULL COMMENT ''확정 시각'',
+        finalized_by_member_id BIGINT NOT NULL COMMENT ''확정한 관리자 회원 ID 스냅샷'',
+        created_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP COMMENT ''생성 시각'',
+        updated_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT ''수정 시각'',
+        PRIMARY KEY (id),
+        UNIQUE KEY uk_agent_settlement_snapshot_period_type_agent_creator (period_start, period_end, settlement_type, agent_id, creator_id),
+        KEY idx_agent_settlement_snapshot_lookup (agent_id, settlement_type, period_start, period_end),
+        KEY idx_agent_settlement_snapshot_creator_lookup (creator_id, settlement_type, period_start, period_end),
+        KEY idx_agent_settlement_snapshot_assignment_id (assignment_id),
+        KEY idx_agent_settlement_snapshot_ratio_id (agent_settlement_ratio_id),
+        CONSTRAINT fk_agent_settlement_snapshot_assignment_id FOREIGN KEY (assignment_id) REFERENCES agent_creator_relation (id),
+        CONSTRAINT fk_agent_settlement_snapshot_ratio_id FOREIGN KEY (agent_settlement_ratio_id) REFERENCES agent_settlement_ratio (id)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT=''에이전트 확정 정산 creator-level 스냅샷''',
+    'SELECT ''agent_settlement_snapshot already exists'' AS message'
+);
+
+PREPARE create_agent_settlement_snapshot_table_stmt FROM @create_agent_settlement_snapshot_table_sql;
+EXECUTE create_agent_settlement_snapshot_table_stmt;
+DEALLOCATE PREPARE create_agent_settlement_snapshot_table_stmt;
+
+SET @agent_settlement_snapshot_has_assignment_id := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot'
+      AND column_name = 'assignment_id'
+);
+
+SET @alter_agent_settlement_snapshot_add_assignment_id_sql := IF(
+    @agent_settlement_snapshot_table_exists = 1 AND @agent_settlement_snapshot_has_assignment_id = 0,
+    'ALTER TABLE agent_settlement_snapshot ADD COLUMN assignment_id BIGINT NULL COMMENT ''적용된 소속 이력 row ID 스냅샷'' AFTER creator_nickname',
+    'SELECT ''agent_settlement_snapshot.assignment_id already exists'' AS message'
+);
+
+PREPARE alter_agent_settlement_snapshot_add_assignment_id_stmt FROM @alter_agent_settlement_snapshot_add_assignment_id_sql;
+EXECUTE alter_agent_settlement_snapshot_add_assignment_id_stmt;
+DEALLOCATE PREPARE alter_agent_settlement_snapshot_add_assignment_id_stmt;
+
+SET @agent_settlement_snapshot_has_ratio_id := (
+    SELECT COUNT(1)
+    FROM information_schema.columns
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot'
+      AND column_name = 'agent_settlement_ratio_id'
+);
+
+SET @alter_agent_settlement_snapshot_add_ratio_id_sql := IF(
+    @agent_settlement_snapshot_table_exists = 1 AND @agent_settlement_snapshot_has_ratio_id = 0,
+    'ALTER TABLE agent_settlement_snapshot ADD COLUMN agent_settlement_ratio_id BIGINT NULL COMMENT ''적용된 에이전트 정산 비율 이력 row ID 스냅샷'' AFTER assignment_id',
+    'SELECT ''agent_settlement_snapshot.agent_settlement_ratio_id already exists'' AS message'
+);
+
+PREPARE alter_agent_settlement_snapshot_add_ratio_id_stmt FROM @alter_agent_settlement_snapshot_add_ratio_id_sql;
+EXECUTE alter_agent_settlement_snapshot_add_ratio_id_stmt;
+DEALLOCATE PREPARE alter_agent_settlement_snapshot_add_ratio_id_stmt;
+
+SET @agent_settlement_snapshot_unique_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot'
+      AND index_name = 'uk_agent_settlement_snapshot_period_type_agent_creator'
+);
+
+SET @add_agent_settlement_snapshot_unique_sql := IF(
+    @agent_settlement_snapshot_table_exists = 1 AND @agent_settlement_snapshot_unique_exists = 0,
+    'ALTER TABLE agent_settlement_snapshot ADD UNIQUE INDEX uk_agent_settlement_snapshot_period_type_agent_creator (period_start, period_end, settlement_type, agent_id, creator_id)',
+    'SELECT ''uk_agent_settlement_snapshot_period_type_agent_creator already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_snapshot_unique_stmt FROM @add_agent_settlement_snapshot_unique_sql;
+EXECUTE add_agent_settlement_snapshot_unique_stmt;
+DEALLOCATE PREPARE add_agent_settlement_snapshot_unique_stmt;
+
+SET @agent_settlement_snapshot_lookup_index_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot'
+      AND index_name = 'idx_agent_settlement_snapshot_lookup'
+);
+
+SET @add_agent_settlement_snapshot_lookup_index_sql := IF(
+    @agent_settlement_snapshot_table_exists = 1 AND @agent_settlement_snapshot_lookup_index_exists = 0,
+    'ALTER TABLE agent_settlement_snapshot ADD INDEX idx_agent_settlement_snapshot_lookup (agent_id, settlement_type, period_start, period_end)',
+    'SELECT ''idx_agent_settlement_snapshot_lookup already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_snapshot_lookup_index_stmt FROM @add_agent_settlement_snapshot_lookup_index_sql;
+EXECUTE add_agent_settlement_snapshot_lookup_index_stmt;
+DEALLOCATE PREPARE add_agent_settlement_snapshot_lookup_index_stmt;
+
+SET @agent_settlement_snapshot_creator_lookup_index_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot'
+      AND index_name = 'idx_agent_settlement_snapshot_creator_lookup'
+);
+
+SET @add_agent_settlement_snapshot_creator_lookup_index_sql := IF(
+    @agent_settlement_snapshot_table_exists = 1 AND @agent_settlement_snapshot_creator_lookup_index_exists = 0,
+    'ALTER TABLE agent_settlement_snapshot ADD INDEX idx_agent_settlement_snapshot_creator_lookup (creator_id, settlement_type, period_start, period_end)',
+    'SELECT ''idx_agent_settlement_snapshot_creator_lookup already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_snapshot_creator_lookup_index_stmt FROM @add_agent_settlement_snapshot_creator_lookup_index_sql;
+EXECUTE add_agent_settlement_snapshot_creator_lookup_index_stmt;
+DEALLOCATE PREPARE add_agent_settlement_snapshot_creator_lookup_index_stmt;
+
+SET @agent_settlement_snapshot_assignment_index_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot'
+      AND index_name = 'idx_agent_settlement_snapshot_assignment_id'
+);
+
+SET @add_agent_settlement_snapshot_assignment_index_sql := IF(
+    @agent_settlement_snapshot_table_exists = 1 AND @agent_settlement_snapshot_assignment_index_exists = 0,
+    'ALTER TABLE agent_settlement_snapshot ADD INDEX idx_agent_settlement_snapshot_assignment_id (assignment_id)',
+    'SELECT ''idx_agent_settlement_snapshot_assignment_id already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_snapshot_assignment_index_stmt FROM @add_agent_settlement_snapshot_assignment_index_sql;
+EXECUTE add_agent_settlement_snapshot_assignment_index_stmt;
+DEALLOCATE PREPARE add_agent_settlement_snapshot_assignment_index_stmt;
+
+SET @agent_settlement_snapshot_ratio_index_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot'
+      AND index_name = 'idx_agent_settlement_snapshot_ratio_id'
+);
+
+SET @add_agent_settlement_snapshot_ratio_index_sql := IF(
+    @agent_settlement_snapshot_table_exists = 1 AND @agent_settlement_snapshot_ratio_index_exists = 0,
+    'ALTER TABLE agent_settlement_snapshot ADD INDEX idx_agent_settlement_snapshot_ratio_id (agent_settlement_ratio_id)',
+    'SELECT ''idx_agent_settlement_snapshot_ratio_id already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_snapshot_ratio_index_stmt FROM @add_agent_settlement_snapshot_ratio_index_sql;
+EXECUTE add_agent_settlement_snapshot_ratio_index_stmt;
+DEALLOCATE PREPARE add_agent_settlement_snapshot_ratio_index_stmt;
+
+SET @agent_settlement_snapshot_assignment_fk_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.table_constraints
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot'
+      AND constraint_name = 'fk_agent_settlement_snapshot_assignment_id'
+      AND constraint_type = 'FOREIGN KEY'
+);
+
+SET @add_agent_settlement_snapshot_assignment_fk_sql := IF(
+    @agent_settlement_snapshot_table_exists = 1 AND @agent_settlement_snapshot_assignment_fk_exists = 0,
+    'ALTER TABLE agent_settlement_snapshot ADD CONSTRAINT fk_agent_settlement_snapshot_assignment_id FOREIGN KEY (assignment_id) REFERENCES agent_creator_relation (id)',
+    'SELECT ''fk_agent_settlement_snapshot_assignment_id already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_snapshot_assignment_fk_stmt FROM @add_agent_settlement_snapshot_assignment_fk_sql;
+EXECUTE add_agent_settlement_snapshot_assignment_fk_stmt;
+DEALLOCATE PREPARE add_agent_settlement_snapshot_assignment_fk_stmt;
+
+SET @agent_settlement_snapshot_ratio_fk_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.table_constraints
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot'
+      AND constraint_name = 'fk_agent_settlement_snapshot_ratio_id'
+      AND constraint_type = 'FOREIGN KEY'
+);
+
+SET @add_agent_settlement_snapshot_ratio_fk_sql := IF(
+    @agent_settlement_snapshot_table_exists = 1 AND @agent_settlement_snapshot_ratio_fk_exists = 0,
+    'ALTER TABLE agent_settlement_snapshot ADD CONSTRAINT fk_agent_settlement_snapshot_ratio_id FOREIGN KEY (agent_settlement_ratio_id) REFERENCES agent_settlement_ratio (id)',
+    'SELECT ''fk_agent_settlement_snapshot_ratio_id already exists'' AS message'
+);
+
+PREPARE add_agent_settlement_snapshot_ratio_fk_stmt FROM @add_agent_settlement_snapshot_ratio_fk_sql;
+EXECUTE add_agent_settlement_snapshot_ratio_fk_stmt;
+DEALLOCATE PREPARE add_agent_settlement_snapshot_ratio_fk_stmt;
+
+SET @agent_settlement_snapshot_source_detail_table_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.tables
+    WHERE table_schema = @schema_name
+      AND table_name = 'agent_settlement_snapshot_source_detail'
+);
+
+SET @create_agent_settlement_snapshot_source_detail_table_sql := IF(
+    @agent_settlement_snapshot_source_detail_table_exists = 0,
+    'CREATE TABLE agent_settlement_snapshot_source_detail (
+        id BIGINT NOT NULL AUTO_INCREMENT COMMENT ''PK'',
+        snapshot_id BIGINT NOT NULL COMMENT ''summary snapshot FK'',
+        assignment_id BIGINT NULL COMMENT ''적용된 소속 이력 row ID'',
+        agent_settlement_ratio_id BIGINT NULL COMMENT ''적용된 에이전트 정산 비율 이력 row ID'',
+        applied_agent_settlement_ratio INT NULL COMMENT ''적용된 에이전트 정산 비율'',
+        count INT NOT NULL COMMENT ''source subtotal 건수'',
+        total_can INT NOT NULL COMMENT ''source subtotal 총 캔 수'',
+        krw INT NOT NULL COMMENT ''source subtotal 원화 금액'',
+        fee INT NOT NULL COMMENT ''source subtotal 수수료'',
+        settlement_amount INT NOT NULL COMMENT ''source subtotal 크리에이터 세전 정산금'',
+        tax INT NOT NULL COMMENT ''source subtotal 세금'',
+        deposit_amount INT NOT NULL COMMENT ''source subtotal 입금액'',
+        agent_settlement_amount INT NOT NULL COMMENT ''source subtotal 에이전트 정산금'',
+        created_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP COMMENT ''생성 시각'',
+        updated_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT ''수정 시각'',
+        PRIMARY KEY (id),
+        KEY idx_agent_settlement_snapshot_source_detail_snapshot_id (snapshot_id),
+        KEY idx_agent_settlement_snapshot_source_detail_assignment_id (assignment_id),
+        KEY idx_agent_settlement_snapshot_source_detail_ratio_id (agent_settlement_ratio_id),
+        CONSTRAINT fk_agent_settlement_snapshot_source_detail_snapshot_id FOREIGN KEY (snapshot_id) REFERENCES agent_settlement_snapshot (id),
+        CONSTRAINT fk_agent_settlement_snapshot_source_detail_assignment_id FOREIGN KEY (assignment_id) REFERENCES agent_creator_relation (id),
+        CONSTRAINT fk_agent_settlement_snapshot_source_detail_ratio_id FOREIGN KEY (agent_settlement_ratio_id) REFERENCES agent_settlement_ratio (id)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT=''에이전트 확정 정산 source provenance detail''',
+    'SELECT ''agent_settlement_snapshot_source_detail already exists'' AS message'
+);
+
+PREPARE create_agent_settlement_snapshot_source_detail_table_stmt FROM @create_agent_settlement_snapshot_source_detail_table_sql;
+EXECUTE create_agent_settlement_snapshot_source_detail_table_stmt;
+DEALLOCATE PREPARE create_agent_settlement_snapshot_source_detail_table_stmt;

docs/20260410_관리자에이전트정산상세조회설계.md

@@ -0,0 +1,313 @@
+# 관리자 에이전트 정산 상세 조회 설계
+
+## 문서 목적
+- 관리자 페이지에서 에이전트 목록을 보고, 특정 에이전트 상세 화면에서 소속 크리에이터와 에이전트별 정산 현황을 조회할 수 있도록 백엔드 read API 설계를 고정한다.
+- 기존 `partner/agent/calculate` 계산 로직은 최대한 재사용하고, `ADMIN` 전용 조회 진입점만 별도로 추가한다.
+
+## 요구사항 정리
+- 관리자 화면에는 에이전트 리스트가 필요하다.
+  - 에이전트 닉네임
+  - 에이전트에 속한 크리에이터 수
+- 관리자 화면에는 크리에이터 검색이 필요하다.
+  - 특정 에이전트에 크리에이터를 소속시키기 위한 검색
+- 관리자 화면에는 특정 에이전트에 현재 소속된 크리에이터 목록이 필요하다.
+  - 에이전트 소속 해제를 위한 목록
+- 관리자 화면에는 특정 에이전트 기준 정산 상세가 필요하다.
+  - 라이브 정산 현황
+  - 콘텐츠 판매 정산 현황
+  - 커뮤니티 정산 현황
+  - 채널 후원 정산 현황
+  - 콘텐츠 후원 정산 현황
+
+## 범위와 해석
+- 이번 설계는 **B안: 에이전트 목록 → 에이전트 상세** 흐름을 기준으로 한다.
+- 에이전트 목록 화면에서는 요약 정보만 제공한다.
+- 실제 정산 데이터는 에이전트 상세 화면에서 조회한다.
+- 기존 `assignment`, `ratio`, `settlement/finalize` 쓰기 기능은 유지하고, 이번 범위에서는 관리자용 read API만 추가한다.
+
+## 현재 코드 기준 확인 사항
+- 관리자 전용 에이전트 관련 컨트롤러는 이미 존재한다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorController.kt`
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioController.kt`
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotController.kt`
+- 에이전트 본인 전용 정산 조회 컨트롤러도 이미 존재한다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateController.kt`
+- 따라서 현재 부족한 것은 정산 계산 로직이 아니라, `ADMIN`이 특정 `agentId`를 지정해 같은 데이터를 읽는 관리자 전용 read API 레이어다.
+
+## 권장 아키텍처
+
+### 1. 관리자 전용 read 진입점 추가
+- 신규 패키지: `kr.co.vividnext.sodalive.admin.partner.agent.read`
+- 신규 구성
+  - `AdminAgentReadController`
+  - `AdminAgentReadService`
+  - `AdminAgentReadQueryRepository`
+- 역할
+  - 에이전트 목록 조회
+  - 크리에이터 검색 조회
+  - 특정 에이전트 소속 크리에이터 목록 조회
+  - 특정 에이전트 기준 5종 정산 조회
+
+### 2. 기존 도메인 계산 로직 재사용
+- 기존 계산/집계 로직은 계속 `kr.co.vividnext.sodalive.partner.agent.calculate` 아래에 둔다.
+- 관리자용 read 서비스는 기존 `AgentCalculateService`, `AgentCalculateQueryRepository`, snapshot 조회 경로를 재사용한다.
+- 현재 `AgentCalculateService`의 정산 조회 메서드는 이미 `agentId`를 직접 받으므로, 관리자 read 서비스는 이 메서드를 그대로 호출한다.
+- 최종안은 **정산 계산 로직은 `partner.agent.calculate`에 유지하고, ADMIN은 별도 read 서비스에서 기존 agentId 기반 조회 메서드를 재사용하는 구조**다.
+
+### 3. 쓰기와 읽기 축 분리
+- 쓰기 축
+  - `admin.partner.agent.assignment`
+  - `admin.partner.agent.ratio`
+  - `admin.partner.agent.settlement`
+- 읽기 축
+  - `admin.partner.agent.read`
+  - `partner.agent.calculate`
+- 이렇게 나누면 “관리자 권한으로 읽는다”와 “정산 계산 규칙을 제공한다”의 책임이 섞이지 않는다.
+
+## 화면 흐름 기준 API 설계
+
+### 1. 에이전트 목록 API
+- 목적: 관리자 화면의 첫 진입 리스트
+- 권장 경로: `GET /admin/partner/agent/list`
+- 권한: `ADMIN`
+- 요청 파라미터
+  - `pageable`
+- 응답 필드
+  - `agentId`
+  - `agentNickname`
+  - `assignedCreatorCount`
+  - `liveAgentSettlementAmount`
+  - `contentAgentSettlementAmount`
+  - `communityAgentSettlementAmount`
+  - `contentDonationAgentSettlementAmount`
+  - `channelDonationAgentSettlementAmount`
+  - `totalCount`
+- 조회 기준
+  - `Member.role == AGENT`
+  - 현재 활성 소속 크리에이터 수만 집계
+  - 활성 소속 판정은 현재 코드의 assignment window 규칙과 동일하게 현재 시각 기준 `assignedAt <= now < unassignedAt(or null)`를 따른다.
+  - 정산 합계는 별도 날짜 입력 없이 **현재 월 기준**으로 계산한다.
+    - 기준 시간대: `Asia/Seoul`
+    - 시작 시각: 현재 월 1일 `00:00:00`
+    - 종료 시각: 다음 달 1일 `00:00:00` 직전까지 포함되는 배타 상한 방식
+    - 실제 조회 구간은 위 KST 월 경계를 UTC `LocalDateTime`으로 변환해 DB의 UTC 저장 시각과 비교한다.
+  - 각 합계 값의 의미는 해당 기간의 상세 조회 응답 `total.agentSettlementAmount`와 동일하다.
+  - 해당 월에 정산 내역이 없더라도 에이전트 목록에서는 제외하지 않고, 5종 합계를 모두 `0`으로 내려준다.
+
+### 2. 크리에이터 검색 API
+- 목적: 특정 에이전트에 크리에이터를 소속시키기 전 검색
+- 권장 경로: `GET /admin/partner/agent/creator/search`
+- 권한: `ADMIN`
+- 요청 파라미터
+  - `search_word`
+  - `pageable`
+- 응답 필드
+  - `creatorId`
+  - `creatorNickname`
+  - `currentAgentId` nullable
+  - `currentAgentNickname` nullable
+- 동작 원칙
+  - 기존 `AdminMemberController.searchCreator()` 검색 관례를 따른다.
+  - 검색 결과에 현재 활성 소속 agent 정보를 붙여서, 이미 다른 agent 소속인지 운영자가 바로 판단할 수 있게 한다.
+
+### 3. 특정 에이전트 소속 크리에이터 목록 API
+- 목적: 상세 화면의 소속 크리에이터 탭
+- 권장 경로: `GET /admin/partner/agent/{agentId}/creator/list`
+- 권한: `ADMIN`
+- 응답 필드
+  - `creatorId`
+  - `creatorNickname`
+  - `assignedAt`
+- 참고
+  - 현재 `GetAgentAssignedCreatorResponse`는 `creatorId`, `creatorNickname`만 제공한다.
+  - 관리자 상세 화면에서는 운영 판단을 위해 `assignedAt`이 같이 내려가는 편이 자연스럽다.
+
+### 4. 특정 에이전트 정산 상세 API 5종
+- 목적: 에이전트 상세 화면의 정산 탭
+- 권한: `ADMIN`
+- 권장 경로
+  - `GET /admin/partner/agent/{agentId}/calculate/live-by-creator`
+  - `GET /admin/partner/agent/{agentId}/calculate/content-by-creator`
+  - `GET /admin/partner/agent/{agentId}/calculate/community-by-creator`
+  - `GET /admin/partner/agent/{agentId}/calculate/channel-donation-by-creator`
+  - `GET /admin/partner/agent/{agentId}/calculate/content-donation-by-creator`
+- 공통 요청 파라미터
+  - `startDateStr`
+  - `endDateStr`
+  - `pageable`
+- 응답 원칙
+  - 기존 AGENT 전용 응답 계약을 가능한 그대로 유지한다.
+  - `totalCount`, `total`, `items` 구조 유지
+  - 각 item의 집계 필드 유지
+    - `count`
+    - `totalCan`
+    - `krw`
+    - `fee`
+    - `settlementAmount`
+    - `agentSettlementAmount`
+- 차이점
+  - 기존 AGENT API는 로그인 principal에서 `agentId`를 얻는다.
+  - 관리자 API는 path variable `agentId`를 받는다.
+
+## 데이터 모델/응답 설계
+
+### 1. 에이전트 목록 응답 DTO
+- 신규 DTO 필요
+- DTO 명
+  - `GetAdminAgentListResponse`
+  - `GetAdminAgentListItem`
+- 필수 필드
+  - response: `totalCount: Int`, `items: List<GetAdminAgentListItem>`
+  - item:
+    - `agentId: Long`
+    - `agentNickname: String`
+    - `assignedCreatorCount: Int`
+    - `liveAgentSettlementAmount: Int`
+    - `contentAgentSettlementAmount: Int`
+    - `communityAgentSettlementAmount: Int`
+    - `contentDonationAgentSettlementAmount: Int`
+    - `channelDonationAgentSettlementAmount: Int`
+
+### 2. 크리에이터 검색 응답 DTO
+- 신규 DTO 필요
+- 기존 `admin/member` 검색 응답을 그대로 쓰기보다, 현재 활성 agent 정보를 함께 주는 전용 DTO가 필요하다.
+- DTO 명
+  - `SearchAdminAgentAssignableCreatorResponse`
+  - `SearchAdminAgentAssignableCreatorItem`
+- 필수 필드
+  - response: `totalCount: Int`, `items: List<SearchAdminAgentAssignableCreatorItem>`
+  - item: `creatorId: Long`, `creatorNickname: String`, `currentAgentId: Long?`, `currentAgentNickname: String?`
+
+### 3. 관리자용 소속 크리에이터 목록 DTO
+- 기존 `GetAgentAssignedCreatorResponse`를 그대로 재사용하기보다는 관리자용 항목에 `assignedAt`을 포함한 전용 DTO가 적합하다.
+- DTO 명
+  - `GetAdminAgentAssignedCreatorResponse`
+  - `GetAdminAgentAssignedCreatorItem`
+- 필수 필드
+  - response: `totalCount: Int`, `items: List<GetAdminAgentAssignedCreatorItem>`
+  - item: `creatorId: Long`, `creatorNickname: String`, `assignedAt: LocalDateTime`
+
+### 4. 관리자용 정산 상세 DTO
+- 가능하면 기존 아래 DTO를 그대로 재사용한다.
+  - `GetAgentSettlementByCreatorResponse`
+  - `GetAgentChannelDonationSettlementByCreatorResponse`
+- 이유
+  - 화면 주체만 ADMIN으로 바뀌고 데이터 shape는 동일하기 때문이다.
+  - DTO까지 갈라지면 정산 계약이 중복될 가능성이 높다.
+
+## 서비스 설계
+
+### 1. `AdminAgentReadService`
+- 책임
+  - 에이전트 목록 조회
+  - 크리에이터 검색 조회
+  - 에이전트 소속 크리에이터 목록 조회
+  - 에이전트 정산 상세 조회 진입
+- 내부 동작
+  - 목록/검색/소속 목록은 전용 read query를 사용한다.
+  - 에이전트 목록 조회 시 현재 월 기준 시작/종료 시각을 서비스에서 계산해 전용 read query에 전달한다.
+  - 정산 상세는 기존 `AgentCalculateService`의 agentId 기반 public 조회 메서드를 사용한다.
+
+### 2. 공통 정산 read 메서드 분리
+- 현재 `AgentCalculateService`의 핵심 정산 조회 메서드는 이미 `agentId` 파라미터 중심 public 메서드다.
+- 따라서 아래 방향으로 정리한다.
+  - controller는 AGENT/ADMIN 별도로 유지
+  - ADMIN read 서비스는 기존 `AgentCalculateService` public 메서드를 직접 호출한다.
+- 기대 효과
+  - 정산 계산 규칙 중복 제거
+  - snapshot 우선 조회 / live 계산 fallback 규칙 재사용
+
+## Repository / Query 방향
+
+### 1. 에이전트 목록용 조회 추가
+- 필요 기능
+  - AGENT role member 목록
+  - 각 agent의 현재 활성 creator count
+  - 각 agent의 현재 월 기준 5종 정산 합계
+- 구현 방식
+  - `AdminAgentReadQueryRepository`에서 전용 projection query를 제공한다.
+  - 기본 에이전트 목록과 활성 creator count는 기존 Querydsl projection query로 조회한다.
+  - 현재 월 5종 정산 합계는 각 목록 item마다 기존 `AgentCalculateQueryRepository` total 조회 메서드를 재사용해 채운다.
+  - 정산 row가 없는 agent도 목록에 남겨야 하므로 기존 total 조회 응답의 `0` 기본값을 그대로 사용한다.
+
+### 2. 크리에이터 검색용 조회 추가
+- 필요 기능
+  - creator nickname 기준 검색
+  - 현재 활성 소속 agent nullable join
+- 구현 방식
+  - `AdminAgentReadQueryRepository`에서 전용 검색 query를 제공한다.
+
+### 3. 소속 크리에이터 목록 조회 추가
+- 기존 `AgentCalculateQueryRepository.getAssignedCreators()`를 재사용할 수 있다.
+- 다만 `assignedAt`을 응답에 내려야 하면 projection을 확장하거나 관리자 전용 projection을 추가해야 한다.
+
+## 인증/예외 처리 원칙
+- 새 관리자 read 엔드포인트는 모두 `@PreAuthorize("hasRole('ADMIN')")`를 사용한다.
+- `agentId`가 존재하지 않거나 role이 `AGENT`가 아니면 `SodaException(messageKey = ...)`로 실패한다.
+- `creator/search`는 기존 `admin/member/search` 관례처럼 최소 검색어 길이 검증을 적용한다.
+- 정산 계산식, snapshot 우선 전략, assignment/ratio history 적용 규칙은 기존 `partner.agent.calculate` 동작을 그대로 사용한다.
+
+## 테스트 설계
+
+### 1. 컨트롤러 테스트
+- `ADMIN` 접근 성공
+- 익명 사용자 접근 실패
+- `AGENT` 또는 일반 사용자 접근 실패
+
+### 2. 서비스/리포지토리 테스트
+- 에이전트 목록에서 닉네임과 현재 활성 creator count가 맞는지 검증
+- 크리에이터 검색 결과에 현재 agent 소속 정보가 올바르게 붙는지 검증
+- 특정 agent 소속 크리에이터 목록이 현재 활성 구간 기준으로만 내려오는지 검증
+
+### 3. 정산 parity 테스트
+- 동일 기간, 동일 `agentId`에 대해
+  - AGENT 전용 조회 응답
+  - ADMIN 전용 조회 응답
+  - 두 결과의 `totalCount`, `total`, `items`가 동일한지 검증
+- 대상 5종
+  - live
+  - content
+  - community
+  - channel donation
+  - content donation
+
+### 4. 설계 대비 구현 계획 누락 체크리스트
+- [x] 관리자 컨트롤러 테스트에 `ADMIN` 접근 성공, 익명 접근 실패, `AGENT` 또는 일반 사용자 접근 실패 시나리오가 모두 포함되어 있는지 확인한다.
+- [x] 동일 기간, 동일 `agentId` 기준으로 AGENT 전용 응답과 ADMIN 전용 응답의 `totalCount`, `total`, `items` parity를 5종 모두 검증하는 테스트가 구현 계획에 포함되어 있는지 확인한다.
+- [x] 구현 계획의 검증 기록 단계에 `무엇을/왜/어떻게`, 실제 실행 명령과 결과, 후속 수정 시 누적 기록 및 `정정` 추가 원칙이 명시되어 있는지 확인한다.
+- [x] `/admin/partner/agent/list`가 별도 날짜 입력 없이 현재 월 기준 5종 정산 합계를 계산하도록 구현 계획에 반영되어 있는지 확인한다.
+- [x] 에이전트 목록 응답 DTO와 리스트 조회 테스트에 `live/content/community/contentDonation/channelDonation` 5종 `agentSettlementAmount` summary 필드가 모두 반영되어 있는지 확인한다.
+- [x] 해당 월에 정산 내역이 없는 에이전트도 목록에서 제외하지 않고 5종 합계를 `0`으로 표기하는 쿼리/응답/테스트 계획이 포함되어 있는지 확인한다.
+- [x] 리스트 summary 값이 같은 월 기준 상세 조회 응답의 `total.agentSettlementAmount`와 일치하는지 검증하는 회귀 테스트가 구현 계획에 포함되어 있는지 확인한다.
+
+## 구현 시 유의사항
+- 관리자용 정산 API를 새로 만든다고 해서 계산 query를 복제하지 않는다.
+- 현재 assignment 활성 판정은 시간창 규칙을 반드시 동일하게 사용한다.
+- 정산 응답 계약은 기존 agent 응답과 불필요하게 분기하지 않는다.
+- 목록 화면은 요약 정보만 제공하고, 상세 정산은 상세 화면에서만 조회한다.
+- 목록의 5종 합계는 상세 API의 기간 필터와 별개로, 현재 월 기준 요약값이라는 의미를 문서와 코드에서 동일하게 유지한다.
+- 해당 월에 정산 내역이 없더라도 에이전트 행은 유지하고 금액은 `0`으로 표기한다.
+
+## 최종 설계 결론
+- 이번 기능은 “새 정산 엔진 추가”가 아니라 “기존 agent 정산 계산을 ADMIN에서 조회할 수 있게 read API를 보강”하는 작업으로 본다.
+- 관리자 페이지 흐름은 아래로 고정한다.
+  1. `/admin/partner/agent/list`로 에이전트 목록과 현재 월 기준 5종 정산 합계 조회
+  2. 상세 화면에서 `/admin/partner/agent/{agentId}/creator/list`로 현재 소속 크리에이터 조회
+  3. 필요 시 `/admin/partner/agent/creator/search`로 크리에이터 검색 후 기존 assignment API로 소속 지정
+  4. 상세 화면에서 `/admin/partner/agent/{agentId}/calculate/*` 5종으로 정산 현황 조회
+- 목록의 5종 합계는 상세 페이지 이동 포인트용 현재 월 summary이며, 상세 화면의 날짜 범위 조회와 역할을 구분한다.
+- 현재 월에 정산 내역이 없는 에이전트도 목록에 포함되며, 합계는 0원으로 표시한다.
+- 이 설계를 기준으로 다음 단계에서는 구현 계획 문서를 작성한다.
+
+## 검증 기록
+- 1차 설계
+  - 무엇을: 관리자용 에이전트 목록/상세 read API 구조와 기존 agent 계산 로직 재사용 범위를 문서로 고정했다.
+  - 왜: 현재 코드에는 관리자용 assignment/ratio/finalize는 있지만, 관리자용 agent 정산 상세 조회 API는 없어 read 레이어 설계가 먼저 필요했기 때문이다.
+  - 어떻게:
+    - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorController.kt` 확인
+    - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioController.kt` 확인
+    - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotController.kt` 확인
+    - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateController.kt` 확인
+    - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateService.kt` 확인
+    - `src/main/kotlin/kr/co/vividnext/sodalive/admin/member/AdminMemberController.kt` 확인
+    - 결과: 관리자용 read API 부재와 기존 계산 로직 재사용 가능성을 문서에 반영했다.

docs/20260410_에이전트권한및정산기능컨텍스트리뷰.md

@@ -0,0 +1,21 @@
+- [x] `admin/partner/agent/**` 현재 구현과 테스트 범위 확인
+- [x] `partner/agent/**` 현재 구현과 테스트 범위 확인
+- [x] 관련 DDL/기획 문서에서 요구사항과 변경 배경 추적
+- [x] git history와 GitHub 메타데이터에서 이전 결정/경고 사항 확인
+- [x] 제외 대상 2건을 제외하고 남는 실질 이슈만 판정
+
+## 검증 기록
+
+### 1차 컨텍스트 리뷰
+- 무엇을: 에이전트 권한 및 정산 기능의 최근 구현/수정 이력, 현재 코드, QA 문서, 관련 테스트를 교차 검토해 남아 있는 실질 결함이 있는지 확인했다.
+- 왜: 최근 수정으로 일부 validation 이슈는 닫혔지만, event-time 이력 모델과 finalized snapshot 정책이 실제 조회 동작까지 일관되게 반영되는지 재확인이 필요했기 때문이다.
+- 어떻게:
+  - `GIT_MASTER=1 git status`, `GIT_MASTER=1 git log -30 --oneline`, `GIT_MASTER=1 git log --oneline <merge-base>..HEAD`로 브랜치 상태와 최근 변경 맥락을 확인했다.
+  - `docs/20260408_에이전트권한및정산기능추가.md`, `docs/20260409_partner_agent_assignment_ratio_ddl.sql`, `docs/20260410_에이전트정산기능QA.md`를 읽어 요구사항/후속 수정/제외 대상 2건을 확인했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/**`, `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/**`, 관련 테스트 파일을 읽어 assignment, ratio, calculate, snapshot 로직을 대조했다.
+  - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.*" --tests "kr.co.vividnext.sodalive.partner.agent.calculate.*"`를 실행해 관련 테스트를 검증했다.
+  - 실행/확인 결과:
+    - 관련 코드/문서 검토 결과, `AgentCalculateQueryRepository.getAssignedCreatorTotalCount/getAssignedCreators`가 `assignedAt` 현재 시점 조건 없이 `unassignedAt is null`만 사용함을 확인했다.
+    - `docs/20260410_에이전트정산기능QA.md:35`에 "미래 assignedAt만 가진 예약 소속은 현재 목록에 노출되지 않아야 한다" 요구사항이 명시되어 있음을 확인했다.
+    - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentAssignedCreatorFutureWindowQaTest.kt`의 첫 테스트가 실제로 실패해 위 요구사항 누락이 재현됨을 확인했다.
+    - `gh` 명령은 현재 환경에 설치되어 있지 않아 GitHub PR/이슈 메타데이터 조회는 불가했다 (`zsh:1: command not found: gh`).

docs/20260410_에이전트정산기능QA.md

@@ -0,0 +1,200 @@
+# 에이전트 정산 기능 QA 계획
+
+## QA 목표
+- 최근 구현된 agent authorization 및 settlement 기능에서 남아 있는 실제 결함을 백엔드 관점으로 점검한다.
+- 범위는 `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/**`, `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/**`로 한정한다.
+- 이미 수용된 두 가지 저우선순위 이슈(빈 finalized 기간 미생성, 중복 finalize 동시성 rough edge)는 제외한다.
+
+## 작업 체크리스트
+- [x] 관련 모듈/테스트/기존 작업 문서를 확인해 QA 범위를 정리한다.
+- [x] 백엔드 QA 시나리오를 20개 이상 도출하고 P0/P1/P2로 분류한다.
+- [x] P0/P1 시나리오를 중심으로 기존 테스트와 실행형 검증 명령을 수행한다.
+- [x] 실패 시 재현 경로와 실제 증거를 확보해 결함 여부를 확정한다.
+- [x] 최종 PASS/FAIL 판정을 정리하고 검증 기록을 남긴다.
+
+## 구현 체크리스트
+- [x] assignment/finalize 가드 미체크 항목 회귀 테스트를 추가한다.
+- [x] calculate empty-result/snapshot pagination/finalized immutability 회귀 테스트를 추가한다.
+- [x] ratio 목록 응답을 member 단위 current/history 구조로 확장한다.
+- [x] generic 4종 calculate total 경로를 전용 total 계산 경로로 분리한다.
+- [x] generic 4종 calculate total 경로를 DB total projection 전용 쿼리로 재리팩터링한다.
+- [x] channel donation total 경로를 DB total projection 전용 쿼리로 재리팩터링한다.
+- [x] finalize snapshot 생성 경로의 중복 groupBy/row 변환을 줄인다.
+- [x] 관련 테스트, 진단, 수동 검증 결과를 문서에 반영한다.
+
+## 검증 대상 축
+- assignment create/remove 시간 경계 동작
+- ratio create/update 검증과 history 동작
+- calculate 5개 카테고리 조회
+- snapshot finalize 및 finalized 조회
+- provenance/source detail 무결성
+- 신규 validation과 기존 동작의 상호작용
+
+## 시나리오 목록
+
+### P0
+- [x] assignment 생성: 유효한 agent/creator/assignedAt이면 신규 이력 row가 생성된다.
+- [x] assignment 생성: agentId와 creatorId가 같으면 거부된다.
+- [x] assignment 생성: agent가 AGENT 역할이 아니면 거부된다.
+- [x] assignment 생성: creator가 CREATOR 역할이 아니면 거부된다.
+- [x] assignment 생성: 활성 소속과 시간이 겹치면 거부된다.
+- [x] assignment 생성: 이전 소속의 `unassignedAt`과 동일한 `assignedAt`은 허용된다.
+- [x] assignment 해제: 활성 소속이면 `unassignedAt`이 기록된다.
+- [x] assignment 해제: `unassignedAt <= assignedAt`이면 거부된다.
+- [x] assigned creator 목록 조회: 다른 agent 소속 creator는 제외된다.
+- [x] assigned creator 목록 조회: 미래 `assignedAt`만 가진 예약 소속은 현재 목록에 노출되지 않아야 한다.
+- [x] assigned creator 목록 조회: 미래 `unassignedAt`이 있는 현재 소속은 종료 전까지 유지되어야 한다.
+- [x] ratio 생성: 유효한 `effectiveFrom`이면 활성 row 종료 후 신규 이력 row가 추가된다.
+- [x] ratio 생성/수정: `settlementRatio`가 0..100 범위를 벗어나면 거부된다.
+- [x] ratio 생성/수정: 과거 closed history 구간과 겹치는 `effectiveFrom`이면 거부된다.
+- [x] calculate 조회: 5개 카테고리 모두 거래 시점 assignment를 기준으로 agent가 갈린다.
+- [x] calculate 조회: 5개 카테고리 모두 거래 시점 ratio를 기준으로 agentSettlementAmount가 계산된다.
+- [x] calculate 조회: content는 콘텐츠 개별 ratio와 creator 기본 ratio fallback을 모두 반영한다.
+- [x] calculate 조회: 일반 정산/채널후원 모두 agent ratio 이력이 없으면 10% fallback이 적용된다.
+- [x] snapshot finalize: LIVE finalize는 immutable snapshot과 source detail을 함께 저장한다.
+- [x] snapshot finalize: 기간 내 source row가 여러 개면 summary FK는 비우고 provenance detail만 남긴다.
+- [x] finalized read: 5개 카테고리 모두 동일 기간 finalized snapshot을 live 계산보다 우선 사용한다.
+- [x] snapshot finalize: 동일 기간/타입/agent 재요청은 중복 저장 없이 alreadyFinalized=true를 반환한다.
+
+### P1
+- [x] admin finalize: 대상 member가 없으면 실패한다.
+- [x] admin finalize: 대상 member가 AGENT 역할이 아니면 실패한다.
+- [x] agent controller: 익명 사용자는 creator/list 조회에 실패한다.
+- [x] admin finalize controller: 익명 사용자는 finalize 호출에 실패한다.
+- [x] channel donation 조회: 분할 정산 레코드가 있어도 후원 건수는 distinct useCan 기준이다.
+- [x] calculate 조회: 기간 내 결과가 없으면 total=0, items=[]로 일관되게 반환된다.
+- [x] assigned creator 목록 조회: 정렬/페이지네이션이 creatorId desc 기준으로 유지된다.
+
+### P2
+- [x] snapshot read: snapshot pagination이 `creatorId desc` 기준으로 안정적이다.
+- [x] ratio 목록 조회: current/history가 페이지 응답에서 누락 없이 노출된다.
+- [x] provenance detail 합계는 snapshot summary 합계와 일치한다.
+- [x] finalized 이후 ratio/assignment 변경이 생겨도 동일 finalized 기간 응답은 변하지 않는다.
+
+## 미체크 항목 재확인 및 후속 방안
+- `assignment 생성: agentId와 creatorId가 같으면 거부된다.`
+  - 현재 상태: `AdminAgentCreatorService.assignCreator()`가 동일 ID를 `partner.agent.assignment.invalid_relation`으로 즉시 거부한다 (`src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorService.kt:22-25`).
+  - 후속 방안: `AdminAgentCreatorServiceTest`에 `agentId == creatorId` 요청을 추가해 동일 예외 키를 직접 검증한다.
+- `admin finalize: 대상 member가 없으면 실패한다.`
+  - 현재 상태: `AdminAgentSettlementSnapshotService.getAgent()`가 member 미존재 시 `partner.agent.ratio.agent_not_found`를 던진다 (`src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotService.kt:122-128`).
+  - 후속 방안: `AdminAgentSettlementSnapshotServiceTest`에 `memberRepository.findById()`가 비어 있는 케이스를 추가해 finalize 진입 전 실패를 검증한다.
+- `admin finalize: 대상 member가 AGENT 역할이 아니면 실패한다.`
+  - 현재 상태: 같은 `getAgent()`에서 role이 `AGENT`가 아니면 `partner.agent.ratio.invalid_agent`를 던진다 (`src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotService.kt:122-128`).
+  - 후속 방안: `AdminAgentSettlementSnapshotServiceTest`에 `USER` 또는 `CREATOR` role member를 주입해 예외 키를 직접 검증한다.
+- `calculate 조회: 기간 내 결과가 없으면 total=0, items=[]로 일관되게 반환된다.`
+  - 현재 상태: 조회 repository는 total count를 `?: 0`으로 반환하고, 페이지 대상 creator가 없으면 빈 목록을 반환한다. 서비스도 이 값을 그대로 응답으로 조립한다 (`src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepositoryTest.kt:272-326`, `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateService.kt:200-211`).
+  - 후속 방안: in-range 데이터가 전혀 없는 fixture로 `AgentCalculateService` 또는 query integration test를 추가해 `total.count/total.totalCan/...`가 모두 0이고 `items=[]`인 응답 계약을 직접 고정한다.
+- `snapshot read: snapshot pagination이 creatorId desc 기준으로 안정적이다.`
+  - 현재 상태: snapshot 조회는 `findAllByPeriodStartAndPeriodEndAndSettlementTypeAndAgentIdOrderByCreatorIdDesc(...)`를 사용해 정렬 기준 자체는 명시되어 있다 (`src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/settlement/snapshot/AgentSettlementSnapshotRepository.kt:14-19`). 다만 다건 snapshot에서 offset/limit slicing 순서를 직접 검증하는 테스트는 없다.
+  - 후속 방안: `AgentCalculateServiceTest`에 creatorId가 다른 snapshot 3건 이상을 주입하고, `offset/limit`별 응답 순서와 크기를 검증하는 회귀 테스트를 추가한다.
+- `ratio 목록 조회: current/history가 페이지 응답에서 누락 없이 노출된다.`
+  - 현재 상태: 현재 응답 DTO는 `items: List<GetAgentSettlementRatioItem>` 단일 flat 구조이고 (`src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/GetAgentSettlementRatioResponse.kt:6-17`), query도 ratio row를 flat list로만 조회한다 (`src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/AgentSettlementRatioRepository.kt:23-49`). 기존 서비스 테스트도 flat 목록 1건만 검증한다 (`src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AgentSettlementRatioServiceTest.kt:344-367`).
+  - 구현 방안: `current/history`를 분리한 응답 DTO를 새로 정의하고, query/service 계층에서 member별 ratio row를 current 1건 + history n건으로 재구성하도록 응답 모델을 확장한다. 페이지 기준은 member 단위로 재정의하고, current/history 누락 회귀 테스트를 함께 추가한다.
+- `finalized 이후 ratio/assignment 변경이 생겨도 동일 finalized 기간 응답은 변하지 않는다.`
+  - 현재 상태: finalize는 snapshot/source detail에 당시 값을 저장하고 (`src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotServiceTest.kt:44-202`), 읽기 경로는 finalized snapshot을 live 계산보다 우선 사용한다 (`src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateServiceTest.kt:458-598`). 다만 finalize 이후 assignment/ratio를 실제로 바꾼 뒤 같은 기간 재조회가 불변인지 직접 검증하는 테스트는 없다.
+  - 후속 방안: finalize 이후 assignment/ratio fixture를 변경한 뒤 동일 기간 read 응답이 snapshot 값 그대로 유지되는지를 검증하는 통합 회귀 테스트를 추가한다.
+
+## 추가 구조/성능 메모
+- `우선 반영 1순위: AgentCalculateService.buildSettlementByCreatorResponse()`의 `totalRowsLoader` 기반 total 계산을 DB total query로 분리한다.
+  - 현재 경로: generic 4종(LIVE/CONTENT/COMMUNITY/CONTENT_DONATION) total은 `totalRowsLoader(startDate, endDate).toMergedResponseItems().toResponseTotal()`로 계산된다 (`src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateService.kt:200-203`).
+  - 현재 비용: 기간 전체 `GetAgentCreatorSettlementSummaryQueryData`를 메모리에 적재한 뒤, 각 row마다 `toResponseItem()`에서 `BigDecimal` 기반 금액 계산을 수행하고 (`src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/GetAgentCreatorSettlementSummaryQueryData.kt:17-40`), 다시 `groupBy { creatorId }`로 creator별 병합 후 (`.../GetAgentCreatorSettlementSummaryQueryData.kt:60-77`), 마지막에 `sumOf`로 grand total을 한 번 더 순회한다 (`src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/GetAgentSettlementByCreatorResponse.kt:33-43`).
+  - 왜 1순위인가: pagedRowsLoader는 페이지 범위만 읽지만 totalRowsLoader는 기간 전체 row를 읽는다. 따라서 메모리 사용량과 GC 비용, total 계산 지연을 동시에 줄이려면 total 경로를 먼저 제거하는 편이 효과가 가장 크다.
+  - row granularity 주의점: total을 단순 `sum(totalCan)`으로 바꾸면 안 된다. 현재 row는 creator 1건이 아니라 assignment/agent ratio/settlement ratio 기준으로 분할되어 있고 (`src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepository.kt:392-596`), 같은 creator도 콘텐츠 개별 ratio 차이로 여러 row가 생긴다 (`src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepositoryTest.kt:145-176`). 또한 거래 시점 assignment/agent ratio 이력 때문에 row가 갈라진다 (`.../AgentCalculateQueryRepositoryTest.kt:328-381`, `421-470`).
+  - 핵심 관찰: total 계산에서 creator별 병합 자체는 필수가 아니다. 현재 로직은 row → creator 병합 → grand total 순서지만, 최종 total 값은 row별 계산 결과를 그대로 모두 더한 값과 동일하다. 즉 total 전용 경로는 creator 응답 shape를 만들 필요 없이 “현재 row granularity의 정산 결과 총합”만 DB에서 반환하면 된다.
+  - 권장 구현 방안: `AgentCalculateQueryRepository`에 generic 4종용 `getCalculate*Total()` 전용 query를 추가하고, `GetAgentSettlementByCreatorTotal`에 대응하는 total projection을 `fetchOne()`으로 바로 반환한다. 이때 현재 반올림/비율 적용 semantics를 유지하려면, 기존 grouped row granularity를 유지한 뒤 그 row 단위 정산 금액을 다시 합산하는 형태가 필요하다. Spring Boot 2.7 + Querydsl JPA 제약을 고려하면, 1차 권장은 파생 테이블(native SQL 또는 Querydsl SQL/JPASQLQuery fallback) 기반 total query이고, 로컬 선례는 total을 목록 쿼리와 분리한 `AdminChannelDonationCalculateQueryRepository.getChannelDonationSettlementTotal()` / `CreatorAdminChannelDonationCalculateQueryRepository.getChannelDonationSettlementTotal()`이다 (`src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/channelDonation/AdminChannelDonationCalculateQueryRepository.kt:33-54`, `src/main/kotlin/kr/co/vividnext/sodalive/creator/admin/calculate/channelDonation/CreatorAdminChannelDonationCalculateQueryRepository.kt:18-38`).
+  - 차선책: DB query 분리가 바로 어렵다면, 최소한 total 계산에서 `.toMergedResponseItems()`를 제거하고 row를 단일 `fold`로 누적해 creator별 `groupBy`/중간 리스트 생성을 없앨 수 있다. 다만 이 방법은 기간 전체 row 적재 자체는 남기므로 임시 완화책으로만 본다.
+  - 구현 결과(1차): `List<GetAgentCreatorSettlementSummaryQueryData>.toResponseTotal()` 전용 경로를 추가해 generic 4종 total 계산에서 creator별 `groupBy`와 중간 `GetAgentSettlementByCreatorItem` 리스트 병합을 제거했다.
+  - 구현 결과(2차): `AgentCalculateQueryRepository`에 generic 4종용 `getCalculate*ByCreatorTotal()` native SQL derived-table query를 추가해 total을 DB에서 바로 계산하도록 바꿨다. 서비스는 더 이상 full row list를 total 계산용으로 읽지 않고, paged item 조회에만 기존 Querydsl row query를 사용한다.
+- `AdminAgentSettlementSnapshotService.finalizeSnapshots()`는 DB가 assignment/ratio 단위로 이미 집계한 row를 creator별 snapshot 1건으로 다시 합산하는데, 이 합산 자체는 필요하지만 `rows.groupBy { creatorId }` 뒤에 `toMergedResponseItems()`가 다시 같은 key로 groupBy를 수행해 불필요한 재-groupBy가 한 번 더 발생한다. 반면 source detail은 query row 1건을 detail 1건으로 보존하므로 추가 집계는 없고, 동일 row의 `toResponseItem()` 변환만 summary/detail에서 각각 반복된다 (`src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotService.kt:131-179`, `182-253`).
+  - 구현 방안: finalize 내부에서는 creator별 재-groupBy 없는 전용 merge 로직을 두고, row 변환 결과를 summary/detail 양쪽에서 재사용하도록 draft 구조를 조정한다.
+  - 구현 결과: `SnapshotAggregateDraft` 단일 패스 누적 구조로 summary/source detail 수치를 함께 합산하도록 바꿔 creator별 재-groupBy와 중복 `toResponseItem()` 변환을 제거했다.
+
+## 검증 기록
+
+### 1차 QA
+- 무엇을:
+  - assignment/ratio/calculate/snapshot/controller 축의 기존 테스트를 집중 실행했다.
+  - `assigned creator list`의 시간창(window) 처리 누락 여부를 임시 DataJpa 재현 테스트로 검증했다.
+- 왜:
+  - 기존 테스트가 보장하는 범위와, 목록 조회처럼 테스트 공백이 있는 시간 경계 시나리오를 분리해서 확인해야 실제 latent bug를 잡을 수 있기 때문이다.
+- 어떻게:
+  - 성공: `./gradlew test --tests kr.co.vividnext.sodalive.admin.partner.agent.assignment.AdminAgentCreatorServiceTest --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AgentSettlementRatioServiceTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest --tests kr.co.vividnext.sodalive.admin.partner.agent.settlement.AdminAgentSettlementSnapshotServiceTest --tests kr.co.vividnext.sodalive.admin.partner.agent.settlement.AdminAgentSettlementSnapshotControllerTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateControllerTest` → BUILD SUCCESSFUL
+  - 성공: `./gradlew test --tests kr.co.vividnext.sodalive.admin.partner.agent.assignment.AdminAgentCreatorControllerTest --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AdminAgentSettlementRatioControllerTest` → BUILD SUCCESSFUL
+  - 실패 재현 1: 임시 QA 테스트에서 미래 `assignedAt` 예약 소속 목록 노출 검증 → `TEST-kr.co.vividnext.sodalive.partner.agent.calculate.AgentAssignedCreatorFutureWindowQaTest.xml` 기준 `expected <0> but was <1>`
+  - 실패 재현 2: 임시 QA 테스트에서 미래 `unassignedAt` 이전 현재 소속 유지 검증 → `TEST-kr.co.vividnext.sodalive.partner.agent.calculate.AgentAssignedCreatorFutureWindowQaTest.xml` 기준 `expected <1> but was <0>`
+
+### 2차 QA 문서 정리
+- 무엇을:
+  - 이후 수정/테스트로 증거가 확보된 QA 항목만 문서 상태를 최신화했다.
+- 왜:
+  - 현재 QA 문서는 일부 항목이 이미 수정/검증되었는데도 실패 메모나 미체크 상태로 남아 있어, 실제 상태와 문서가 어긋나 있었기 때문이다.
+- 어떻게:
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepositoryTest.kt:91-110` 확인 → 현재 시각 활성 구간 creator list 회귀 테스트가 미래 `assignedAt` 미노출 / 미래 `unassignedAt` 이전 유지 두 조건을 함께 검증함을 확인했다.
+  - `docs/20260408_에이전트권한및정산기능추가.md:644-658` 확인 → 위 creator list window 버그가 17차 수정에서 실제 수정되고 테스트/빌드 검증까지 완료되었음을 확인했다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotServiceTest.kt:191-201` 확인 → provenance detail 각 수치 합계가 snapshot summary와 일치하는 검증이 이미 존재함을 확인했다.
+  - 위 세 근거에 따라 creator list 2개 항목의 실패 메모를 제거하고, `provenance detail 합계` 항목을 완료 처리했다.
+
+### 3차 미체크 항목/구조 점검
+- 무엇을:
+  - QA 문서에 남아 있던 미체크 항목을 구현/테스트 기준으로 다시 분류했다.
+  - `AgentCalculateService`의 creator 합산 경로와 `AdminAgentSettlementSnapshotService` finalize 경로의 중복 집계 여부를 코드 기준으로 재점검했다.
+- 왜:
+  - 현재 문서에는 “구현은 이미 있으나 테스트가 빠진 항목”, “응답 모델 자체가 요구를 충족하지 못하는 항목”, “기능 결함은 아니지만 구조적으로 비효율적인 항목”이 섞여 있어 후속 작업 우선순위가 드러나지 않았기 때문이다.
+- 어떻게:
+  - 명령 실행 없음: 이번 단계는 문서/코드 정합성 점검 목적이라 읽기 전용 파일 검토만 수행했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorService.kt:22-25` 확인 → 동일 agentId/creatorId 거부 로직은 구현돼 있으나 직접 테스트가 없음을 확인했다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepositoryTest.kt:69-89` 및 `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateControllerTest.kt:37-62` 확인 → assigned creator 정렬/페이지네이션은 이미 검증돼 있어 완료 처리했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/GetAgentSettlementRatioResponse.kt:6-17` 및 `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/ratio/AgentSettlementRatioRepository.kt:23-49` 확인 → ratio 목록은 flat 응답만 제공하므로 `current/history` 요구를 충족하려면 응답 모델과 조회 로직 확장이 필요함을 확인했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateService.kt:141-168,172-211` 확인 → finalized snapshot 경로가 전체 snapshot row를 메모리에서 page/total 처리함을 확인했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotService.kt:131-179,182-253` 확인 → finalize summary 생성 시 creator별 재-groupBy가 한 번 더 수행되고, source detail은 집계 대신 row 변환만 반복함을 확인했다.
+
+### 4차 totalRowsLoader 개선 방향 구체화
+- 무엇을:
+  - `buildSettlementByCreatorResponse()`의 `totalRowsLoader` 경로만 따로 떼어 메모리/성능 병목과 개선 우선순위를 구체화했다.
+- 왜:
+  - 기존 성능 메모는 “live 계산 경로 전반을 DB 쿼리로 옮기자” 수준이라 범위가 넓었고, 실제로 어떤 부분을 먼저 고쳐야 효과가 큰지 드러나지 않았기 때문이다.
+- 어떻게:
+  - 명령 실행 없음: 이번 단계도 읽기 전용 코드/문서 검토만 수행했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateService.kt:200-203` 확인 → total이 `totalRowsLoader(...).toMergedResponseItems().toResponseTotal()`로 계산됨을 다시 확인했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/GetAgentCreatorSettlementSummaryQueryData.kt:17-40,60-77` 및 `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/GetAgentSettlementByCreatorResponse.kt:33-43` 확인 → row별 금액 계산, creator별 groupBy 병합, grand total 재합산이 모두 애플리케이션 메모리에서 수행됨을 확인했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepository.kt:392-596` 확인 → generic 4종 쿼리가 assignment/agent ratio/settlement ratio 기준의 grouped row를 반환함을 확인했다.
+  - `src/test/kotlin/kr/co/vividnext/sodalive/partner/agent/calculate/AgentCalculateQueryRepositoryTest.kt:145-176,328-381,421-470` 확인 → 같은 creator도 settlement ratio/assignment/agent ratio 이력 때문에 여러 row로 분할될 수 있어 total 계산이 단순 `sum(totalCan)`으로 대체되면 안 됨을 확인했다.
+  - `src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/channelDonation/AdminChannelDonationCalculateQueryRepository.kt:33-54` 및 `src/main/kotlin/kr/co/vividnext/sodalive/creator/admin/calculate/channelDonation/CreatorAdminChannelDonationCalculateQueryRepository.kt:18-38` 확인 → 이 저장소 안에 total 전용 `fetchOne()` aggregate query 선례가 이미 있음을 확인했다.
+
+### 5차 미체크 항목 구현 및 성능 완화
+- 무엇을:
+  - assignment/finalize 가드, calculate empty-result, snapshot pagination, finalized immutability 회귀 테스트를 추가했다.
+  - ratio 목록 응답을 member 단위 `current/history` 구조로 확장하고, generic total/finalize 내부 계산 경로를 가볍게 정리했다.
+- 왜:
+  - 문서에 남아 있던 미체크 항목을 실제 테스트와 응답 계약으로 고정해야 후속 회귀를 막을 수 있고, total/finalize 경로의 불필요한 groupBy/중간 객체 생성을 줄여야 현재 범위 안에서 안전하게 성능을 완화할 수 있기 때문이다.
+- 어떻게:
+  - 성공: `./gradlew test --tests kr.co.vividnext.sodalive.admin.partner.agent.assignment.AdminAgentCreatorServiceTest --tests kr.co.vividnext.sodalive.admin.partner.agent.settlement.AdminAgentSettlementSnapshotServiceTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest` → BUILD SUCCESSFUL
+  - 성공: `./gradlew test --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AgentSettlementRatioServiceTest --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AdminAgentSettlementRatioControllerTest` → BUILD SUCCESSFUL
+  - 성공: `./gradlew test --tests kr.co.vividnext.sodalive.admin.partner.agent.assignment.AdminAgentCreatorServiceTest --tests kr.co.vividnext.sodalive.admin.partner.agent.settlement.AdminAgentSettlementSnapshotServiceTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AgentSettlementRatioServiceTest --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AdminAgentSettlementRatioControllerTest` → BUILD SUCCESSFUL
+  - 참고: `lsp_diagnostics`는 현재 환경에 Kotlin LSP가 없어 사용할 수 없었고, 대신 위 Gradle 실행에서 `compileKotlin`/`compileTestKotlin`까지 함께 통과한 것으로 컴파일 진단을 대체했다.
+
+### 6차 generic total DB projection 리팩터링
+- 무엇을:
+  - generic 4종(LIVE/CONTENT/COMMUNITY/CONTENT_DONATION) total 계산을 full row load 기반 Kotlin 합산에서 DB total projection 전용 쿼리로 교체했다.
+  - 서비스 테스트와 DataJpa parity 테스트를 추가해 새 DB total이 기존 Kotlin total과 동일한지 고정했다.
+  - Oracle 리뷰에서 지적된 `CONTENT` total grouping drift(`explicit 70` vs `null -> fallback 70`)를 보정하고 전용 회귀 테스트를 추가했다.
+- 왜:
+  - 1차 완화 이후에도 total 계산은 기간 전체 grouped row를 메모리로 읽어야 했고, 이 비용은 기간이 커질수록 그대로 남았다. 요청한 방향대로 total projection을 DB로 내리면서도 row-level rounding semantics를 유지하려면 parity 테스트와 함께 옮겨야 했다.
+- 어떻게:
+  - 성공: `./gradlew test --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest` → BUILD SUCCESSFUL
+  - 성공: `./gradlew build` → BUILD SUCCESSFUL
+  - 성공(수동 확인): `./gradlew test --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest.shouldMatchDbTotalProjectionForContentRowsSplitByEffectiveSettlementRatio --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest.shouldMatchDbTotalProjectionAcrossAllGenericCategoriesWhenAgentRatioHistorySplitsRows` → BUILD SUCCESSFUL
+  - 성공(Oracle 후속 보정): `./gradlew test --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest.shouldMatchDbTotalProjectionWhenExplicitAndFallbackSeventyMustStaySeparated --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest` → BUILD SUCCESSFUL
+  - 성공(Oracle 후속 보정): `./gradlew build` → BUILD SUCCESSFUL
+  - 참고: Kotlin LSP 부재로 `lsp_diagnostics`는 여전히 실행 불가했고, 이번 단계도 `compileKotlin`/`compileTestKotlin` 포함 Gradle 결과를 타입/컴파일 진단 근거로 사용했다.
+
+### 7차 channel donation total DB projection 리팩터링
+- 무엇을:
+  - `AgentCalculateService.getChannelDonationByCreator()`의 total 계산을 full row load 기반 Kotlin 합산에서 DB total projection 전용 쿼리로 교체했다.
+  - split `useCanCalculate`와 agent 비율 이력이 섞인 채널후원에서도 새 DB total이 기존 Kotlin total과 같은지 서비스/Repository 테스트로 고정했다.
+- 왜:
+  - generic 4종 total만 DB projection으로 내려가고 채널후원 total은 여전히 전체 row를 읽고 있었기 때문에, 동일한 최적화 방향을 채널후원에도 적용해 total 계산용 메모리 적재를 제거할 필요가 있었다.
+- 어떻게:
+  - 성공: `./gradlew test --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest` → BUILD SUCCESSFUL
+  - 성공: `./gradlew build && ./gradlew test --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest.shouldMatchDbTotalProjectionForChannelDonationWithSplitCalculatesAndRatioHistory` → BUILD SUCCESSFUL
+  - 참고: Kotlin LSP 부재로 `lsp_diagnostics`는 실행 불가했고, 이번 단계도 `compileKotlin`/`compileTestKotlin` 포함 Gradle 결과를 타입/컴파일 진단 근거로 사용했다.

docs/20260411_에이전트검색기능추가.md

@@ -0,0 +1,24 @@
+# 에이전트 검색 기능 추가
+
+## 작업 체크리스트
+- [x] 관리자 에이전트 검색 관련 기존 controller/service/query/test 패턴을 확인한다.
+- [x] 에이전트 검색 API 위치를 확정하고 요청/응답 형태를 정의한다.
+- [x] 에이전트 닉네임 검색 동작을 검증하는 테스트를 먼저 추가한다.
+- [x] 에이전트 닉네임으로 검색해 `memberId`를 식별할 수 있는 조회 기능을 구현한다.
+- [x] 관련 진단/테스트/수동 QA를 수행하고 결과를 기록한다.
+
+## 검증 기준
+- 관리자 권한 진입점에서 검색 API가 노출되어야 한다.
+- 검색어로 에이전트 닉네임을 조회했을 때 UI가 사용할 식별자(`memberId`)가 응답에 포함되어야 한다.
+- 기존 관리자 에이전트 read 패키지의 응답/검색 패턴을 따른다.
+
+## 검증 기록
+- 1차 구현
+  - 무엇을: `admin.partner.agent.read` 패키지에 에이전트 닉네임 검색 API를 추가하고 관련 controller/service/query/test를 확장했다.
+  - 왜: 관리자 정산 비율 입력 시 memberId 직접 입력 대신 에이전트 검색 기반 선택을 지원하기 위해
+  - 어떻게:
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.read.AdminAgentReadControllerTest" --tests "kr.co.vividnext.sodalive.admin.partner.agent.read.AdminAgentReadServiceTest" --tests "kr.co.vividnext.sodalive.admin.partner.agent.read.AdminAgentReadQueryRepositoryTest" --tests "kr.co.vividnext.sodalive.admin.partner.agent.read.AdminAgentReadControllerSecurityTest"` → 성공
+    - `./gradlew build` → 성공
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.read.AdminAgentReadControllerSecurityTest.shouldAllowAdminRoleForAgentNicknameSearch" --info` → 성공
+    - 수동 QA 확인 응답: `{"success":true,"message":null,"data":[{"id":11,"nickname":"agent-a"}],"errorProperty":null}`
+    - 참고: Kotlin LSP가 환경에 구성되어 있지 않아 LSP 진단 대신 Gradle compile/test/build 결과로 검증했다.

docs/20260411_에이전트정산비율수정오류수정.md

@@ -0,0 +1,19 @@
+# 에이전트 정산 비율 수정 오류 대응 계획
+
+- [x] 에이전트 정산 비율 수정 API/서비스/엔티티/리포지토리 흐름을 확인한다.
+- [x] `Duplicate entry '2-1' for key 'agent_settlement_ratio.uk_agent_settlement_ratio_member_active'` 발생 조건과 현재 활성 비율 갱신 방식의 충돌 지점을 확인한다.
+- [x] 실패를 재현하는 테스트를 먼저 추가하고, 테스트가 의도한 이유로 실패하는지 확인한다.
+- [x] 기존 활성 비율을 안전하게 종료한 뒤 새 비율을 저장하도록 최소 범위로 수정한다.
+- [x] 관련 테스트와 필요한 검증 명령을 실행하고 결과를 문서 하단에 누적 기록한다.
+
+## 검증 기록
+
+- 1차 구현
+  - 무엇을: 에이전트 정산 비율 수정 시 기존 활성 row 종료를 먼저 flush하도록 바꾸고, active unique 제약 충돌 시 같은 세션 재조회 없이 비즈니스 예외로 변환하도록 수정했다.
+  - 왜: 기존 활성 row가 DB에 닫히기 전에 새 row insert가 먼저 flush되면 `uk_agent_settlement_ratio_member_active` 충돌이 발생하고, 그 뒤 같은 세션 재조회가 이어지면 Hibernate `null id` assertion이 연쇄로 발생할 수 있기 때문이다.
+  - 어떻게:
+    - `./gradlew test --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AgentSettlementRatioServiceTest` → 실패, 수정 전 flush 순서 검증이 깨지고 예외 후 재조회 검증도 실패해 재현 확인.
+    - `./gradlew test --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AgentSettlementRatioServiceTest` → 성공.
+    - `./gradlew test --tests kr.co.vividnext.sodalive.admin.partner.agent.ratio.AdminAgentSettlementRatioControllerTest` → 성공.
+    - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.ratio.*"` → 성공.
+    - `./gradlew ktlintCheck` → 성공.

docs/20260413_에이전트소속크리에이터프로필이미지추가.md

@@ -0,0 +1,20 @@
+# 에이전트 소속 크리에이터 프로필 이미지 추가
+
+- [x] `getAssignedCreators` 흐름과 기존 프로필 이미지 응답 패턴을 확인한다.
+- [x] `GetAgentAssignedCreatorItem`에 프로필 이미지 URL 필드를 추가한다.
+- [x] `AgentCalculateQueryRepository.getAssignedCreators` projection에 프로필 이미지 URL을 포함한다.
+- [x] `AgentCalculateQueryRepositoryTest`에 프로필 이미지 URL 및 기본 이미지 fallback 검증을 추가한다.
+- [x] `AgentCalculateServiceTest`, `AgentCalculateControllerTest` fixture와 검증을 갱신한다.
+- [x] 정적 진단과 관련 테스트를 실행해 변경을 검증한다.
+
+## 검증 기록
+
+### 1차 구현
+- 무엇을: 에이전트 소속 크리에이터 조회 응답에 프로필 이미지 URL 필드 추가 구현 및 검증
+- 왜: 크리에이터 목록 응답에서 프로필 이미지를 함께 내려주기 위해
+- 어떻게:
+  - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest"` 실행 시 `profileImageUrl` 및 `cloudFrontHost` 관련 컴파일 실패를 확인해 red 단계 검증
+  - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest" --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest" --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateControllerTest"` 실행 결과 `BUILD SUCCESSFUL`
+  - `./gradlew ktlintCheck` 실행 결과 `BUILD SUCCESSFUL`
+  - `./gradlew test --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest.shouldGetAssignedCreatorsWithProfileImageUrl" --tests "kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateControllerTest.shouldForwardAssignedCreatorsRequestToService"` 실행 결과 `BUILD SUCCESSFUL`
+  - Kotlin LSP 서버가 현재 환경에 없어 `lsp_diagnostics`는 수행 불가였고, 대신 compile/test/ktlint 결과로 정적 검증 대체

docs/20260413_에이전트크리에이터소속시간UTC변환.md

@@ -0,0 +1,51 @@
+## 작업 개요
+
+- [x] `AdminAgentCreatorService`의 소속 등록 시 `assignedAt` 입력값을 한국 시간에서 UTC로 변환해 저장한다.
+- [x] `AdminAgentCreatorService`의 소속 해제 시 `unassignedAt` 입력값을 한국 시간에서 UTC로 변환해 검증 후 저장한다.
+- [x] `AdminAgentCreatorServiceTest`에 한국 시간 입력이 UTC로 저장되는 회귀 테스트를 추가한다.
+- [x] 변경 파일 진단과 Gradle 검증(`test`, `ktlintCheck`)을 수행하고 결과를 기록한다.
+- [x] `LocalDateTimeExtensions`에 타임존 입력 기반 UTC 변환 확장함수를 추가하고 기본 타임존을 KST로 둔다.
+- [x] `AdminAgentCreatorService`의 시간 변환을 확장함수 호출로 리팩터링한다.
+- [x] 확장함수 테스트와 관련 서비스 테스트를 다시 검증하고 기록한다.
+- [x] `AdminAgentReadService.getAssignedCreators` 응답의 `assignedAt`을 UTC에서 KST로 변환해 내려오도록 수정한다.
+- [x] `AdminAgentReadServiceTest`에 `getAssignedCreators` 응답 시간이 KST로 변환되는 회귀 테스트를 추가한다.
+- [x] 변경 파일 진단과 관련 Gradle 테스트를 수행하고 결과를 기록한다.
+
+---
+
+## 검증 기록
+
+### 1차 구현
+
+- 무엇을: 관리자 에이전트-크리에이터 소속 등록/해제 시각의 UTC 저장 정합성 보정.
+- 왜: 요청 시각은 한국 시간 기준인데 현재 DB에는 변환 없이 그대로 저장되어 실제 저장 기준과 맞지 않음.
+- 어떻게:
+  - `AdminAgentCreatorServiceTest`에 등록 저장값 UTC 변환, 해제 저장값 UTC 변환, 해제 시각 비교 UTC 기준 검증 테스트를 추가했다.
+  - `AdminAgentCreatorService`에서 `assignedAt`/`unassignedAt`를 저장 및 비교 전에 `Asia/Seoul -> UTC`로 변환하도록 수정했다.
+  - `lsp_diagnostics` 실행: `.kt` 확장자용 LSP 서버 미설정으로 도구 진단 불가.
+  - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.assignment.AdminAgentCreatorServiceTest"` 실행: 성공(BUILD SUCCESSFUL).
+  - `./gradlew ktlintCheck` 실행: 성공(BUILD SUCCESSFUL).
+
+### 2차 수정
+
+- 무엇을: `Asia/Seoul -> UTC` 변환 책임을 `LocalDateTime` 확장함수로 이동하고 서비스는 그 확장함수를 사용하도록 리팩터링.
+- 왜: 서비스 레이어의 타임존 변환 중복을 줄이고, 동일한 변환 규칙을 재사용 가능한 확장함수로 통일하기 위함.
+- 어떻게:
+  - `LocalDateTimeExtensionsTest`에 기본 KST 변환과 사용자 지정 타임존 변환 테스트를 먼저 추가했고, 확장함수 부재 상태에서 실패함을 확인했다.
+  - `LocalDateTimeExtensions`에 `convertToUtc(timeZone: ZoneId = Asia/Seoul)` 확장함수를 추가했다.
+  - `AdminAgentCreatorService`는 내부 변환 함수를 제거하고 `request.assignedAt.convertToUtc()` / `request.unassignedAt.convertToUtc()`를 사용하도록 수정했다.
+  - `./gradlew test --tests "kr.co.vividnext.sodalive.extensions.LocalDateTimeExtensionsTest" --tests "kr.co.vividnext.sodalive.admin.partner.agent.assignment.AdminAgentCreatorServiceTest"` 실행: 성공(BUILD SUCCESSFUL).
+  - `./gradlew ktlintCheck` 실행: 성공(BUILD SUCCESSFUL).
+
+### 3차 수정
+
+- 무엇을: 관리자 에이전트 소속 크리에이터 목록 응답의 `assignedAt`을 UTC 기준 저장값에서 KST 기준 시각으로 변환해 반환하도록 수정.
+- 왜: 현재 `getAssignedCreators`는 DB에서 조회한 UTC `assignedAt`을 그대로 내려주고 있어 관리자 화면에서 소속 시각이 9시간 늦게 보일 수 있음.
+- 어떻게:
+  - 내부 패턴 조사 결과, 저장소에서는 UTC raw 값을 유지하고 서비스/DTO 경계에서 `UTC -> Asia/Seoul` 변환을 적용하는 방식이 가장 가까운 관례임을 확인했다.
+  - `AdminAgentReadServiceTest`에 `assignedAt = 2026-04-10T03:00:00` UTC 조회값이 `2026-04-10T12:00:00` KST로 반환되는 회귀 테스트를 먼저 추가했고, 수정 전 해당 테스트가 실패함을 확인했다.
+  - `AdminAgentReadService.getAssignedCreators`에서 조회 결과를 매핑하며 `assignedAt.atZone(UTC).withZoneSameInstant(Asia/Seoul).toLocalDateTime()`으로 변환하도록 수정했다.
+  - `lsp_diagnostics` 실행: `.kt` 확장자용 LSP 서버 미설정으로 도구 진단 불가.
+  - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.read.AdminAgentReadServiceTest.shouldConvertAssignedAtToKstWhenGettingAssignedCreators"` 실행: 최초 실패 후 수정 뒤 성공(BUILD SUCCESSFUL).
+  - `./gradlew test --tests "kr.co.vividnext.sodalive.admin.partner.agent.read.AdminAgentReadServiceTest" --tests "kr.co.vividnext.sodalive.admin.partner.agent.read.AdminAgentReadQueryRepositoryTest"` 실행: 성공(BUILD SUCCESSFUL).
+  - `./gradlew ktlintCheck` 실행: 성공(BUILD SUCCESSFUL).

docs/20260415_에이전트정산기본비율7퍼센트변경.md

@@ -0,0 +1,18 @@
+# 에이전트 정산 기본 비율 7퍼센트 변경 계획
+
+- [x] `AgentCalculateQueryRepository`의 agent settlement fallback 10 적용 지점을 확인하고 7로 변경한다.
+- [x] Kotlin 응답 계산 모델의 agent settlement fallback 10 상수를 7로 변경해 DB 집계와 계산 로직을 일치시킨다.
+- [x] 기본 fallback 10을 전제한 관련 테스트 기대값을 7 기준으로 수정한다.
+- [x] 관련 테스트와 진단을 실행하고 결과를 문서 하단 검증 기록에 누적한다.
+
+## 검증 기록
+
+- 1차 구현
+  - 무엇을: 에이전트 정산 비율 미설정 시 적용되는 기본 fallback 값을 `10%`에서 `7%`로 변경했다. `AgentCalculateQueryRepository`의 native SQL `COALESCE(asr.settlement_ratio, ...)`와 Kotlin 계산 모델 두 곳의 `DEFAULT_AGENT_SETTLEMENT_RATIO`를 함께 조정하고, 관련 테스트 기대값을 7% 기준으로 갱신했다.
+  - 왜: 현재 에이전트 정산 기본 비율 정책이 10%가 아니라 7%여야 하므로, DB 집계 결과와 Kotlin 응답 계산 결과가 동일한 기본값을 사용하도록 맞춰야 한다.
+  - 어떻게:
+    - `./gradlew test --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest` → 실패. 7% 기준으로 먼저 바꾼 테스트가 기존 10% fallback 구현 때문에 깨지는 것을 확인했다.
+    - `./gradlew test --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateServiceTest --tests kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepositoryTest --tests kr.co.vividnext.sodalive.admin.partner.agent.read.AdminAgentReadCurrentMonthListSummaryTest` → 성공.
+    - `./gradlew ktlintCheck` → 성공.
+    - `./gradlew build` → 성공.
+    - `src/main/kotlin`에서 `COALESCE(asr.settlement_ratio, 10)` 및 `DEFAULT_AGENT_SETTLEMENT_RATIO = 10` 검색 → 미검출.

docs/20260421_라이브방무료여부응답추가.md

@@ -0,0 +1,12 @@
+# 라이브방 무료 여부 응답 추가
+
+- [x] `GetRoomInfoResponse`에 라이브방 무료 여부 필드 추가
+- [x] `GetRoomInfoResponse` 생성 경로에 무료 여부 매핑 반영
+- [x] 관련 검증 수행 및 결과 기록
+
+## 검증 기록
+
+### 1차 구현
+- 무엇을: `GetRoomInfoResponse`에 `isFreeRoom` 필드를 추가하고, `LiveRoomService`에서 `room.price == 0` 결과를 응답에 매핑했다.
+- 왜: 라이브방 정보 응답에서 클라이언트가 무료방 여부를 직접 판별할 수 있어야 하기 때문이다.
+- 어떻게: Kotlin `.kt` 파일은 현재 LSP 진단을 지원하지 않아 `lsp_diagnostics` 검증은 불가함을 확인했고, `./gradlew test`를 실행해 main/test 컴파일과 테스트를 함께 검증했으며 `BUILD SUCCESSFUL`을 확인했다. 로컬 실행 환경이 이 세션에 준비되지 않아 실제 API 호출 기반 수동 QA는 수행하지 못했다.

docs/20260421_오리지널시리즈정산내역.md

@@ -0,0 +1,244 @@
+# 오리지널 시리즈 작품 화별 정산 내역 추가 작업 계획
+
+- [x] 기존 관리자 정산 API 패턴(`/admin/calculate`, list/excel 쌍, `StreamingResponseBody`)을 유지하는 신규 패키지 구조를 확정한다.
+- [x] `kr.co.vividnext.sodalive.admin.calculate.originalSeries` 패키지에 오리지널 시리즈 소지 유저 조회 API를 추가한다.
+- [x] `kr.co.vividnext.sodalive.admin.calculate.originalSeries` 패키지에 오리지널 시리즈 정산 내역 조회 API를 추가한다.
+- [x] 정산 내역 조회 API가 `start_date`, `end_date`, `creator_id`를 받아 KST 입력 날짜를 UTC 조회 범위로 변환하도록 구현한다.
+- [x] 정산 내역 조회 쿼리가 `Series(isOriginal = true) -> SeriesContent -> AudioContent -> Order` 경로를 사용해 `Content.id`, `Order.type` 기준으로 그룹화되도록 구현한다.
+- [x] 정산 내역 결과에 시리즈 타이틀, 콘텐츠 타이틀, 가격, 대여/소장 여부, 판매 수, 합계(캔), 합계(포인트)를 포함하도록 DTO를 추가한다.
+- [x] 가격은 주문에 저장된 값을 기준으로 사용하되, 대여는 `ceil(price * 0.7)` 규칙이 반영된 값으로 노출되도록 검증한다.
+- [x] 오리지널 시리즈 정산 내역 엑셀 다운로드 API를 추가하고, 오리지널 시리즈를 소지한 유저별로 시트를 구성하도록 구현한다.
+- [x] 엑셀 다운로드는 각 유저 시트에 헤더 행과 정산 내역 행을 기록하고, 데이터가 없어도 헤더가 있는 시트를 유지하도록 구현한다.
+- [x] 신규 QueryRepository/Service/Controller에 대한 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
+- [x] 관련 테스트, 정적 진단, 수동 검증 결과를 확인하고 이 문서 하단 검증 기록에 남긴다.
+
+## 구현 메모
+
+- 오리지널 시리즈 여부는 `Series.isOriginal` 플래그를 기준으로 판단한다.
+- 소지 유저는 현재 코드베이스 기준 `Series.member`를 의미하는 것으로 해석한다.
+- 날짜 입력 파라미터는 `start_date`, `end_date`, `creator_id`로 받고, 날짜 값은 KST 기준 `00:00:00` / `23:59:59`로 해석한 뒤 `convertLocalDateTime()`으로 UTC `LocalDateTime`으로 변환한다.
+- 정산 내역 조회 API는 `creator_id`를 필수 필터로 사용하고, 엑셀 API는 전체 소지 유저를 순회해 시트를 생성하는 것으로 해석한다.
+
+## API 명세
+
+### 1. 오리지널 시리즈 소지 유저 조회
+
+#### URI
+- `GET /admin/calculate/original-series/owners`
+
+#### Request
+- Header
+  - 인증: 관리자 권한 필요 (`hasRole('ADMIN')`)
+- Query Parameter
+  - 없음
+- Body
+  - 없음
+
+#### Response
+- Content-Type: `application/json`
+- 응답 구조
+
+```json
+{
+  "success": true,
+  "message": null,
+  "data": [
+    {
+      "creatorId": 1,
+      "nickname": "owner-a"
+    },
+    {
+      "creatorId": 2,
+      "nickname": "owner-b"
+    }
+  ],
+  "errorProperty": null
+}
+```
+
+#### Response Field
+- `success`: 성공 여부
+- `message`: 성공 메시지, 현재 구현에서는 `null`
+- `data`: 오리지널 시리즈 소지 유저 목록
+  - `creatorId`: 정산 내역 조회에 사용할 크리에이터 ID
+  - `nickname`: 관리자 화면에 노출할 닉네임
+- `errorProperty`: 에러 시 사용되는 필드, 성공 시 `null`
+
+### 2. 오리지널 시리즈 정산 내역 조회
+
+#### URI
+- `GET /admin/calculate/original-series/settlement-details`
+
+#### Request
+- Header
+  - 인증: 관리자 권한 필요 (`hasRole('ADMIN')`)
+- Query Parameter
+  - `start_date`: 시작일, 형식 `yyyy-MM-dd`, KST 기준
+  - `end_date`: 종료일, 형식 `yyyy-MM-dd`, KST 기준
+  - `creator_id`: 오리지널 시리즈 소지 유저 ID
+  - `page`: 페이지 번호, Spring `Pageable` 규칙 사용
+  - `size`: 페이지 크기, Spring `Pageable` 규칙 사용
+- Body
+  - 없음
+
+#### Request Example
+
+```text
+GET /admin/calculate/original-series/settlement-details?start_date=2026-04-01&end_date=2026-04-30&creator_id=1&page=0&size=20
+```
+
+#### Response
+- Content-Type: `application/json`
+- 응답 구조
+
+```json
+{
+  "success": true,
+  "message": null,
+  "data": {
+    "totalCount": 2,
+    "items": [
+      {
+        "seriesTitle": "오리지널 시리즈",
+        "contentTitle": "1화",
+        "price": 70,
+        "orderType": "대여",
+        "salesCount": 2,
+        "totalCan": 130,
+        "totalPoint": 100
+      },
+      {
+        "seriesTitle": "오리지널 시리즈",
+        "contentTitle": "1화",
+        "price": 100,
+        "orderType": "소장",
+        "salesCount": 2,
+        "totalCan": 200,
+        "totalPoint": 25
+      }
+    ]
+  },
+  "errorProperty": null
+}
+```
+
+#### Response Field
+- `data.totalCount`: 조회 결과 전체 건수
+- `data.items`: 정산 내역 목록
+  - `seriesTitle`: 시리즈 제목
+  - `contentTitle`: 작품 화 제목
+  - `price`: 표시 가격(캔)
+    - `소장`: `audioContent.price`
+    - `대여`: `ceil(audioContent.price * 0.7)`
+  - `orderType`: `대여` 또는 `소장`
+  - `salesCount`: 판매 건수
+  - `totalCan`: 합계 캔
+  - `totalPoint`: 합계 포인트
+
+### 3. 오리지널 시리즈 정산 내역 엑셀 다운로드
+
+#### URI
+- `GET /admin/calculate/original-series/settlement-details/excel`
+
+#### Request
+- Header
+  - 인증: 관리자 권한 필요 (`hasRole('ADMIN')`)
+- Query Parameter
+  - `start_date`: 시작일, 형식 `yyyy-MM-dd`, KST 기준
+  - `end_date`: 종료일, 형식 `yyyy-MM-dd`, KST 기준
+- Body
+  - 없음
+
+#### Request Example
+
+```text
+GET /admin/calculate/original-series/settlement-details/excel?start_date=2026-04-01&end_date=2026-04-30
+```
+
+#### Response
+- Content-Type: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
+- Header
+  - `Content-Disposition: attachment; filename*=UTF-8''original-series-settlement-details.xlsx`
+- Body
+  - `.xlsx` 바이너리 스트림
+
+#### Excel 구성
+- 오리지널 시리즈 소지 유저별로 시트 1개 생성
+- 시트명 형식: `{nickname}`
+- 각 시트의 헤더 열 순서
+  1. `시리즈 제목`
+  2. `콘텐츠 제목`
+  3. `가격(캔)`
+  4. `구분`
+  5. `판매 수`
+  6. `합계(캔)`
+  7. `합계(포인트)`
+- 해당 기간에 데이터가 없는 유저도 헤더만 있는 시트를 유지
+
+## 클라이언트 기능 구현용 프롬프트
+
+```text
+관리자 페이지에서 오리지널 시리즈 작품 화별 정산 내역을 조회하고 엑셀 다운로드하는 클라이언트 기능을 구현한다.
+
+필수 API 계약은 아래와 같다.
+
+1. 소지 유저 조회
+- GET /admin/calculate/original-series/owners
+- 응답은 ApiResponse<List<{ creatorId: number; nickname: string }>> 형태다.
+
+2. 정산 내역 조회
+- GET /admin/calculate/original-series/settlement-details
+- query: start_date(yyyy-MM-dd), end_date(yyyy-MM-dd), creator_id(number), page(number), size(number)
+- 응답은 ApiResponse<{ totalCount: number; items: Array<{ seriesTitle: string; contentTitle: string; price: number; orderType: string; salesCount: number; totalCan: number; totalPoint: number }> }> 형태다.
+
+3. 엑셀 다운로드
+- GET /admin/calculate/original-series/settlement-details/excel
+- query: start_date(yyyy-MM-dd), end_date(yyyy-MM-dd)
+- 응답은 xlsx 바이너리이며 파일명은 `original-series-settlement-details.xlsx` 이다.
+
+구현 요구사항:
+- 화면 진입 시 owners API를 먼저 호출해 멤버 선택 드롭다운 데이터를 로드한다.
+- 사용자가 start_date, end_date, creator_id를 선택한 뒤 정산 내역 조회 API를 호출한다.
+- 목록 테이블에는 시리즈 제목, 콘텐츠 제목, 가격, 구분, 판매 수, 합계(캔), 합계(포인트)를 그대로 표시한다.
+- 페이지네이션은 page/size 기반으로 처리하고 totalCount를 사용해 총 페이지 수를 계산한다.
+- 엑셀 다운로드 버튼은 현재 선택된 start_date/end_date만 사용해 excel API를 호출한다.
+- JSON 응답은 항상 ApiResponse 래퍼의 success/data/message/errorProperty를 기준으로 처리한다.
+- success가 false이면 message를 우선 노출한다.
+- 날짜는 문자열 `yyyy-MM-dd` 형식으로 서버에 전달한다.
+
+산출물 요구사항:
+- API 호출 함수
+- 타입 정의
+- 목록 조회 상태 관리
+- 엑셀 다운로드 처리
+- 에러 처리 로직
+
+임의로 API 계약을 바꾸지 말고, 위 URI/Request/Response를 그대로 사용한다.
+```
+
+## 검증 기록
+
+### 1차 구현
+- 무엇을: `/admin/calculate/original-series/owners`, `/admin/calculate/original-series/settlement-details`, `/admin/calculate/original-series/settlement-details/excel` 3개 API와 전용 QueryRepository/Service/Controller/DTO를 추가했다.
+- 왜: 관리자 페이지에서 오리지널 시리즈 소지 유저를 먼저 조회하고, 선택한 유저의 작품 화별 정산 내역을 기간 기준으로 확인하며, 전체 소지 유저별 시트로 엑셀 다운로드할 수 있어야 했기 때문이다.
+- 어떻게:
+  - `kr.co.vividnext.sodalive.admin.calculate.originalSeries` 패키지를 생성하고 `Series(isOriginal = true) -> SeriesContent -> AudioContent -> Order` 조인으로 정산 내역을 조회하도록 구현했다.
+  - 정산 내역은 `Content.id`, `Order.type` 기준으로 그룹화하고 결과에 시리즈 제목, 콘텐츠 제목, 가격, 구분, 판매 수, 합계 캔, 합계 포인트를 담도록 구성했다.
+  - 가격은 `audioContent.price`를 기준으로 계산하고, 대여는 응답 변환 시 `ceil(price * 0.7)`를 적용해 포인트 사용으로 `order.can`이 바뀐 주문도 동일한 표시 가격을 유지하도록 했다.
+  - 엑셀은 `SXSSFWorkbook(100)` 기반 스트리밍으로 생성하고, 오리지널 시리즈 소지 유저별로 시트를 만들며 데이터가 없으면 헤더만 기록하도록 했다.
+  - 테스트/검증 실행 결과:
+    - `lsp_diagnostics` (신규 Kotlin 파일 경로) → Kotlin LSP 미설정으로 진단 불가
+    - `./gradlew test --tests "*AdminOriginalSeriesCalculate*"` → 성공
+    - `./gradlew ktlintCheck` → 성공
+    - `./gradlew build` → 성공
+    - `./gradlew test --tests "*AdminOriginalSeriesCalculateServiceTest.shouldCreateOneSheetPerOwnerForExcel"` → 성공
+
+### 2차 문서화
+- 무엇을: 기존 작업 계획 문서에 오리지널 시리즈 정산 API 3종의 URI, Request, Response 상세 명세와 클라이언트 기능 구현용 프롬프트를 추가했다.
+- 왜: 클라이언트 기능 구현 시 서버 API 계약을 문서만 보고 그대로 사용할 수 있어야 하기 때문이다.
+- 어떻게:
+  - `AdminOriginalSeriesCalculateController`, 응답 DTO, `ApiResponse` 구조를 기준으로 문서에 JSON 예시와 필드 설명을 정리했다.
+  - 엑셀 다운로드 API는 바이너리 응답과 헤더 규격, 시트 구성 규칙을 함께 기록했다.
+  - 클라이언트 개발자가 그대로 복사해 사용할 수 있도록 API 호출 순서와 상태 처리 조건을 포함한 프롬프트를 추가했다.
+  - 실행 결과:
+    - 수정 문서 재확인(`read`) → 성공

docs/20260429_에이전트가이드통합정리.md

@@ -0,0 +1,35 @@
+# 20260429 에이전트 가이드 통합 정리
+
+## 구현 계획
+- [x] 기존 `AGENTS.md`의 우선순위, 에이전트 행동, 스킬/워크플로우 관련 항목을 분석한다.
+- [x] 공식 `andrej-karpathy-skills` `CLAUDE.md` 원문을 확인하고 삽입 위치와 래퍼 문구를 확정한다.
+- [x] `AGENTS.md` 상단 근처에 `CORE EXECUTION PRINCIPLES (andrej-karpathy-skills)` 섹션을 추가한다.
+- [x] 사용자 지시 > `AGENTS.md` > 프로젝트별 제약 조건 > oh-my-openagent > superpowers > 기본 모델 동작 우선순위를 명시한다.
+- [x] oh-my-openagent, superpowers, 충돌 해결 규칙, 실행 모드를 한국어 정책으로 추가한다.
+- [x] `AGENTS.md`에는 핵심 규칙만 남기고 세부 규칙은 `docs/agent-guides/` 아래 별도 문서로 분리해 참조하도록 정리한다.
+- [x] 기존 `docs/20260429_에이전트가이드상세규칙.md`의 섹션 구성을 분석하고 분리 단위를 확정한다.
+- [x] `docs/agent-guides/` 아래에 주제별 문서를 생성한다.
+- [x] `AGENTS.md`가 분리된 문서를 직접 참조하도록 수정한다.
+- [x] 기존 `docs/20260429_에이전트가이드상세규칙.md`를 제거한다.
+- [x] `docs/agent-guides/` 하위 파일명에서 `에이전트가이드` 접두를 제거한 새 이름 규칙을 확정한다.
+- [x] `docs/agent-guides/` 하위 파일명을 `코드스타일.md`, `테스트스타일.md`, `설정보안.md`, `작업절차.md`, `문서유지보수.md`로 정리한다.
+- [x] `AGENTS.md`와 연결된 작업 기록 문서의 참조 경로를 새 파일명 기준으로 갱신한다.
+- [x] 문서 변경 검증을 수행하고 결과를 기록한다.
+
+## 검증 기록
+- [x] 작업 완료 후 검증 결과를 기록한다.
+
+- 1차 구현
+  - 무엇을: `AGENTS.md`에 명시적 지시 우선순위, `CORE EXECUTION PRINCIPLES (andrej-karpathy-skills)` 원문, oh-my-openagent/superpowers 제어 정책, 충돌 해결 규칙, 실행 모드를 추가했다. 동시에 Kotlin/Spring 스타일·테스트·보안·문서 유지보수의 상세 규칙은 `docs/agent-guides/코드스타일.md`, `docs/agent-guides/테스트스타일.md`, `docs/agent-guides/설정보안.md`, `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`로 분리하고 `AGENTS.md`는 핵심 규칙과 참조만 남기도록 정리했다.
+  - 왜: 기존 `AGENTS.md`는 프로젝트 규칙은 충분했지만 명시적 우선순위 체계와 플러그인/스킬 통제 계층이 없었고, 세부 규칙이 길어져 상단에서 핵심 실행 원칙을 빠르게 파악하기 어려웠기 때문이다.
+  - 어떻게: `AGENTS.md`, `docs/20260429_에이전트가이드통합정리.md`, `docs/agent-guides/` 아래 분리 문서를 다시 읽어 필수 문구, 영어 원문 유지, 한국어 정책 분리, 참조 경로를 확인했다. `lsp_diagnostics`로 관련 문서 모두 `No diagnostics found`를 확인하고, `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL`을 확인했다.
+
+- 2차 정리
+  - 무엇을: 동일 작업을 별도로 기록하던 `docs/20260429_에이전트가이드분리.md`의 구현 계획과 검증 범위를 이 문서로 통합하고, 중복 작업 문서는 제거했다.
+  - 왜: 두 문서가 모두 같은 날짜의 동일 작업 흐름을 기록하고 있었고, 하나는 `AGENTS.md` 재구성, 다른 하나는 세부 규칙 분리라는 하위 단계만 다를 뿐 논리적으로 하나의 작업 계획 문서였기 때문이다.
+  - 어떻게: 두 문서의 구현 계획과 검증 기록을 대조해 누락된 분리 작업 항목만 이 문서에 합쳤고, 이후 `grep`으로 두 문서명 참조를 확인한 뒤 중복 문서를 제거했다. 마지막으로 `lsp_diagnostics`와 `./gradlew tasks --all`로 문서 정합성과 저장소 문서 검증 명령 성공을 다시 확인했다.
+
+- 3차 정리
+  - 무엇을: `docs/agent-guides/` 하위 파일명에서 `에이전트가이드` 접두를 제거해 `코드스타일.md`, `테스트스타일.md`, `설정보안.md`, `작업절차.md`, `문서유지보수.md`로 정리했다. 함께 `AGENTS.md`와 이 문서의 참조 경로도 새 파일명 기준으로 수정했고, 별도 작업 문서였던 `docs/20260429_agent_guides파일명정리.md`는 이 문서로 통합했다.
+  - 왜: 디렉터리 경로 자체가 이미 `agent-guides`라서 파일명에 동일한 의미를 반복할 필요가 없고, AGENTS 가이드 정비의 후속 단계 역시 별도 문서보다 하나의 연속 작업 기록 안에 남기는 편이 더 자연스럽기 때문이다.
+  - 어떻게: `grep`으로 기존 `docs/agent-guides/에이전트가이드*.md` 참조가 남지 않았음을 확인했고, `glob`으로 새 파일명 5개만 존재함을 확인했다. `lsp_diagnostics`로 `AGENTS.md`, 이 문서, `docs/agent-guides/` 전체에 대해 오류가 없음을 확인했고, `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL`을 확인했다.

docs/20260429_연속작업계획문서재사용규칙.md

@@ -0,0 +1,15 @@
+# 20260429 연속 작업 계획 문서 재사용 규칙
+
+## 구현 계획
+- [x] 작업 계획 문서 생성과 관련된 기존 규칙 위치를 확인한다.
+- [x] 연속된 하나의 작업일 때는 새 계획 문서를 만들지 않고 기존 문서에 이어서 기록하는 규칙을 추가한다.
+- [x] 관련 문서 간 표현과 의도를 일치시킨다.
+- [x] 문서 진단과 검증 결과를 기록한다.
+
+## 검증 기록
+- [x] 작업 완료 후 검증 결과를 기록한다.
+
+- 1차 구현
+  - 무엇을: `AGENTS.md`의 `작업 계획 문서 규칙 (docs)`에 연속된 하나의 작업이라면 새 계획 문서를 만들지 않고 기존 계획 문서에 작업 항목과 검증 기록을 이어서 추가한다는 규칙을 넣었다. 함께 `docs/agent-guides/작업절차.md`와 `docs/agent-guides/문서유지보수.md`에도 같은 취지의 보완 문구를 추가해 실행 흐름과 문서 정책이 일치하도록 정리했다.
+  - 왜: 같은 작업의 후속 수정마다 새 계획 문서가 계속 생성되면 문서 수가 불필요하게 늘어나고, 작업 이력도 여러 파일로 흩어져 관리와 탐색이 어려워지기 때문이다.
+  - 어떻게: `read`로 세 문서의 해당 섹션을 다시 확인해 문구 위치와 의미 일치를 검토했고, `lsp_diagnostics`로 `AGENTS.md`, `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`, `docs/20260429_연속작업계획문서재사용규칙.md`에 대해 모두 `No diagnostics found`를 확인했다. 추가로 `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL`을 확인했다.

docs/20260429_채팅방쿼터충전방식확장.md

@@ -0,0 +1,54 @@
+# 채팅방 쿼터 충전 방식 확장
+
+## 구현 계획
+- [x] `purchaseRoomQuota` 요청 DTO만 보고도 `캔 충전`인지 `광고 충전`인지 구분할 수 있도록 충전 방식 필드를 확장하고, 광고 충전 요청을 구분할 수 있는 최소 스키마를 정의한다.
+- [x] 캔 충전 옵션을 기존 단일 고정값에서 `10캔 → 15개`, `20캔 → 40개`의 2개 시나리오로 분기하도록 컨트롤러/서비스 전달 구조를 정리한다.
+- [x] `ChatRoomQuotaService.purchase`의 하드코딩된 `needCan=10`, `addPaid=12` 로직을 요청값 기반 분기로 치환하고, 광고 충전 시 캔 차감 없이 `5` quota를 지급하는 경로를 분리한다.
+- [x] 광고 충전은 1회당 `5` quota 지급으로 반영하고, 중복 호출 방지 여부와 추가 검증 조건만 별도 확인한다.
+- [x] 관련 테스트 또는 최소 검증 경로를 정리하고 `./gradlew test` 기준으로 회귀 여부를 확인한다.
+
+## 요구사항 반영 체크
+- [x] Quota 충전 방식은 `캔 충전`, `광고 보고 충전`의 2가지로 확장한다.
+- [x] 서버는 요청 DTO를 통해 `캔 충전`인지 `광고 충전`인지 식별할 수 있어야 한다.
+- [x] 캔 충전 옵션은 `10캔 → 15개`, `20캔 → 40개`의 2가지다.
+- [x] 광고 충전은 1회당 `5` quota를 지급한다.
+
+## 영향 범위 메모
+- `src/main/kotlin/kr/co/vividnext/sodalive/chat/quota/room/ChatRoomQuotaController.kt`
+  - 요청 DTO와 `purchaseRoomQuota` 분기 진입점 변경 대상.
+- `src/main/kotlin/kr/co/vividnext/sodalive/chat/quota/room/ChatRoomQuotaService.kt`
+  - 캔 사용량/유료 quota 지급량 하드코딩 제거 및 충전 방식별 처리 분기 대상.
+- 테스트 코드
+  - 현재 `src/test/kotlin`에서 `ChatRoomQuota` 관련 테스트가 바로 확인되지 않아, 필요 시 서비스 중심 테스트를 새로 보강한다.
+
+## 확인 필요 사항
+- 광고 충전은 앱에서 선처리한다고 했으므로 서버는 DTO 기반 분기와 1회당 `5` quota 지급만 담당하고, 광고 시청 자체의 검증 책임은 범위 밖으로 본다.
+- 기존 클라이언트 호환을 위해 요청 본문에 `container`만 오면 서버는 기본값으로 `CAN + CAN_10` 충전으로 해석한다.
+- 광고 충전 요청에 `canOption`이 함께 오더라도 서버는 예외를 내지 않고 값을 무시한 뒤 광고 충전으로 처리한다.
+
+## 검증 기록
+
+### 1차 계획 수립
+- 무엇을: `purchaseRoomQuota` API에 광고 충전 구분과 2종 캔 충전 옵션을 추가하기 위한 구현 계획과 예상 영향 범위를 문서화했다.
+- 왜: 현재 구현은 `container`만 받고 서비스에서 `10캔 → 12개 quota`를 고정 처리하고 있어, 요구사항을 반영하려면 DTO/서비스 분기와 미정 항목을 먼저 분리해 두는 것이 안전하기 때문이다.
+- 어떻게: `ChatRoomQuotaController.kt`, `ChatRoomQuotaService.kt`, `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`, 기존 계획 문서 예시를 읽어 형식과 영향 범위를 맞췄고, 문서 변경 후 `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL`을 확인했다.
+
+### 2차 요구사항 점검 반영
+- 무엇을: 문서가 충전 방식 2종, 요청 DTO를 통한 충전 방식 식별, 캔 충전 2가지 옵션, 광고 충전 5개 지급을 모두 명시적으로 포함하도록 보강했다.
+- 왜: 기존 문서도 대부분의 요구사항을 담고 있었지만, 요구사항 전체를 한눈에 대조할 수 있는 체크 형태가 없어 일부 표현이 암묵적으로 읽힐 여지가 있었기 때문이다.
+- 어떻게: 계획 문서 본문에 `요구사항 반영 체크` 섹션을 추가하고 핵심 조건을 체크박스로 정리했으며, 문서 변경 후 `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL`을 다시 확인했다.
+
+### 3차 구현 및 검증
+- 무엇을: `purchaseRoomQuota` 요청 DTO에 충전 방식과 캔 옵션 enum을 추가하고, 컨트롤러에서 `캔 충전`과 `광고 충전`을 분기하도록 변경했다. 함께 `ChatRoomQuotaService`를 `purchaseWithCan`, `purchaseWithAd` 경로로 분리해 `10캔 → 15개`, `20캔 → 40개`, `광고 → 5개` 지급 규칙을 반영했다. 또한 `ChatRoomQuotaControllerTest`, `ChatRoomQuotaServiceTest`를 추가해 컨트롤러 분기와 서비스 적립 로직을 검증했다.
+- 왜: 기존 구현은 `container`만 받고 `10캔 → 12개`를 단일 하드코딩으로 처리해 새로운 충전 방식과 옵션을 구분할 수 없었기 때문이다.
+- 어떻게: `ChatRoomQuotaController.kt`, `ChatRoomQuotaService.kt`에 최소 분기 로직을 추가하고 `ChatRoomQuotaPurchaseOption.kt`에 enum을 분리했다. 검증은 Kotlin LSP가 이 환경에서 지원되지 않아 진단 대신 `./gradlew test --tests "kr.co.vividnext.sodalive.chat.quota.room.ChatRoomQuotaServiceTest" --tests "kr.co.vividnext.sodalive.chat.quota.room.ChatRoomQuotaControllerTest"`를 실행해 `BUILD SUCCESSFUL`을 확인했다.
+
+### 4차 하위 호환 보완
+- 무엇을: 기존 클라이언트가 `container`만 보내도 동작하도록 `PurchaseRoomQuotaRequest`의 기본 충전 방식을 `CAN`, 기본 캔 옵션을 `CAN_10`으로 해석하도록 보완했고, 이를 검증하는 테스트를 추가했다.
+- 왜: 새 DTO 필드를 필수로 두면 구버전 클라이언트의 기존 요청 본문이 역직렬화 단계에서 바로 깨질 수 있기 때문이다.
+- 어떻게: `ChatRoomQuotaController.kt`에서 `chargeType` 기본값을 `CAN`으로 두고 `canOption` 누락 시 `CAN_10`을 사용하도록 변경했다. 검증은 `ChatRoomQuotaControllerTest`에 `container`만 전달하는 직접 호출 케이스를 추가해 수행했다.
+
+### 5차 광고 옵션 허용 완화
+- 무엇을: 광고 충전 요청에 `canOption`이 함께 들어와도 예외를 던지지 않고 무시하도록 컨트롤러 분기를 완화했고, 해당 요청이 정상적으로 광고 충전 경로로 전달되는 테스트로 기대값을 바꿨다.
+- 왜: 광고 충전은 지급량이 고정이라 `canOption`이 의미 없는 부가 필드에 가깝고, 이를 이유로 요청을 실패시키는 것보다 무시하는 편이 클라이언트 호환성과 운영 안정성에 유리하기 때문이다.
+- 어떻게: `ChatRoomQuotaController.kt`의 `AD` 분기에서 `canOption` 검증 예외를 제거했고, `ChatRoomQuotaControllerTest`의 광고 케이스를 성공 경로 검증으로 변경했다.

docs/20260501_payverse-jpy-지원.md

@@ -0,0 +1,23 @@
+# Payverse JPY 지원 작업 계획
+
+- [x] 요구사항 정리
+  - JPY 전용 자격 증명 사용
+  - `payverseCharge`, `payverseWebhook`, `payverseVerify` 모두 일관 분기 추가
+  - 금액 포맷: JPY는 강제 정수화(소수점 버림)
+  - 결제수단 표기는 현행 규칙 유지
+
+- [x] 구현 항목
+  - [x] 환경변수 주입: `payverse.jpy-mid`, `payverse.jpy-client-key`, `payverse.jpy-secret-key`
+  - [x] `ChargeService.payverseCharge`에 JPY 분기 및 금액 포맷 적용
+  - [x] `ChargeService.payverseWebhook`에 JPY 분기 및 금액 검증 적용
+  - [x] `ChargeService.payverseVerify`에 JPY 분기 및 금액 검증 적용
+  - [x] 공통 금액 포맷 함수 `computePayverseAmount` 추가 (JPY=버림, 그외=4자리 반올림)
+
+- [ ] 검증 항목
+  - [ ] 단위/통합 테스트 빌드 및 실행 (`./gradlew test`)
+  - [ ] KRW/JPY/USD 각각에 대해 payload 서명 및 검증 로직 수기 점검
+  - [ ] JPY에서 `requestAmount`가 항상 정수로 전송되는지 로깅/샘플 요청으로 확인(스테이징)
+
+## 검증 로그
+- [ ] 빌드/테스트 결과:
+- [ ] 수기 점검 결과:

docs/20260506_번역언어감지효율화구상.md

@@ -0,0 +1,338 @@
+# 번역/언어감지 효율화 구상
+
+## 배경
+- 현재 구조는 도메인별 번역 테이블과 이벤트 기반 Papago 호출이 혼재되어 있다.
+- 생성/수정 이벤트 번역과 조회 시 캐시 미스 번역이 동시에 존재해 동일 원문이 중복 번역될 수 있다.
+- 번역 저장 로직은 `ContentTranslation`, `SeriesTranslation`, `AiCharacterTranslation`, `OriginalWorkTranslation`, `CategoryTranslation` 등으로 분산되어 있으며, 조회/upsert 패턴이 반복된다.
+- Papago 호출은 텍스트와 대상 locale 단위로 순차 실행되어 대상 하나가 여러 HTTP 요청으로 확장된다.
+
+## 목표
+- Papago 호출 수와 비용을 줄인다.
+- 조회 API에서 Papago 호출로 인한 응답 지연을 줄인다.
+- 번역 저장/조회 로직의 중복을 줄이고, 향후 번역 provider 교체가 가능하도록 한다.
+- 기존 API 응답 스키마는 유지하고, DB 변경은 단계적으로 적용한다.
+
+## 구현 항목
+- [x] `TranslationProvider` 인터페이스와 Papago provider 구현을 분리한다.
+- [x] `translation_memory`, `translation_job`, `language_detection_result` 테이블을 추가한다.
+- [x] 조회 fallback의 직접 Papago 호출을 제거하고 누락 번역 job 예약으로 전환한다.
+- [x] 생성/수정 이벤트 번역을 `translation_job` 기반 워커 처리로 전환한다.
+- [x] `TranslationMemory` 결과를 기존 JSON/scalar read model로 materialize한다.
+- [ ] 목록 조회 병목 측정 후 필요한 도메인에만 hot column을 추가한다.
+
+## 접근안 비교
+
+### 접근안 A: 현재 구조 유지 + 중복 방지 보강
+- 도메인별 번역 테이블은 유지한다.
+- 번역 전 기존 번역 조회와 unique 제약을 강화한다.
+- 조회 fallback에서 번역 생성 대신 번역 작업만 예약하도록 바꾼다.
+
+장점:
+- 변경 범위가 가장 작다.
+- 기존 코드와 데이터 마이그레이션 위험이 낮다.
+
+단점:
+- 도메인별 중복 저장/로직 구조는 그대로 남는다.
+- 원문이 같아도 도메인별로 재번역될 수 있다.
+
+### 접근안 B: 원문 해시 기반 Translation Memory + 비동기 작업 큐 추가
+- 원문 텍스트를 정규화하고 `source_hash`로 중복을 제거한다.
+- `translation_memory`에 원문/언어쌍/번역 결과를 저장한다.
+- 도메인 엔티티는 `translation_job`을 생성하고, 워커가 Papago를 호출해 결과를 저장한다.
+- 조회 API는 Papago를 직접 호출하지 않고 기존 번역을 반환하거나 미번역 상태를 유지한다.
+
+장점:
+- 동일 원문 재번역을 줄일 수 있다.
+- 조회 응답 지연을 안정적으로 제거할 수 있다.
+- 기존 도메인별 번역 테이블을 당장 제거하지 않아도 단계 적용이 가능하다.
+
+단점:
+- 작업 큐, 상태 관리, 재시도 정책이 필요하다.
+- 생성 직후 번역이 아직 없을 수 있으므로 UX/응답 정책을 정해야 한다.
+
+### 접근안 C: 도메인별 번역 테이블을 공통 번역 저장소로 통합
+- 모든 번역 결과를 `translation_entry` 같은 공통 테이블에 저장한다.
+- `resource_type`, `resource_id`, `field_key`, `locale`, `translated_text` 또는 JSON payload로 도메인별 필드를 표현한다.
+- 기존 도메인별 번역 테이블은 읽기 호환 기간 후 제거한다.
+
+장점:
+- 저장/조회/upsert 로직을 크게 단순화할 수 있다.
+- 새 번역 대상 추가 비용이 줄어든다.
+
+단점:
+- 마이그레이션 위험이 가장 크다.
+- 도메인별 payload 검증과 타입 안정성이 약해질 수 있다.
+- 기존 조회 쿼리와 응답 조립 로직 영향 범위가 넓다.
+
+## 권장 방향
+- 최종 구현방식은 접근안 B를 중심으로 하되, 조회 성능을 위해 도메인별 read model을 유지하는 하이브리드 구조로 한다.
+- 기존 번역 데이터를 배제할 수 있어도 모든 번역 결과를 정규화 row만으로 저장하는 방식은 채택하지 않는다.
+- 이유는 Papago 호출 수 절감은 원문 해시 기반 `TranslationMemory`가 담당하고, API 조회 성능은 `entityId + locale` 단위 read model이 담당하는 분리가 가장 효율적이기 때문이다.
+- 2차로 운영 안정화 후 도메인별 read model의 중복을 줄이되, 조회 경로가 복잡해지는 전면 통합은 실제 병목이 확인될 때만 진행한다.
+
+## 최종 구현방식
+
+### 설계 원칙
+- 번역 원장은 정규화한다.
+- 조회 결과는 도메인별로 materialize한다.
+- Papago 호출은 사용자 요청 스레드에서 수행하지 않는다.
+- JSON payload는 원장이 아니라 조회 최적화용 read model로만 사용한다.
+
+### 저장 구조
+
+#### `translation_memory`
+- 동일 원문을 반복 번역하지 않기 위한 공통 번역 캐시이다.
+- 원문은 의미가 바뀌지 않는 선에서 공백, 줄바꿈, Unicode 표현을 정규화한다.
+- 주요 컬럼:
+  - `id`
+  - `source_hash`
+  - `source_text`
+  - `source_language`
+  - `target_language`
+  - `translated_text`
+  - `provider`
+  - `provider_version`
+  - `normalization_version`
+  - `created_at`
+  - `updated_at`
+- unique 제약:
+  - `(source_hash, source_language, target_language, provider, normalization_version)`
+- 역할:
+  - Papago 호출 수 절감의 핵심 원장이다.
+  - 도메인이 달라도 원문과 언어쌍이 같으면 같은 번역을 재사용한다.
+
+#### `translation_job`
+- 번역 실행 상태를 관리하는 durable job 테이블이다.
+- 현재 `@Async` 이벤트만으로 처리하던 작업을 명시적인 상태 모델로 바꾼다.
+- 주요 컬럼:
+  - `id`
+  - `resource_type`
+  - `resource_id`
+  - `field_key`
+  - `source_hash`
+  - `source_language`
+  - `target_language`
+  - `status`
+  - `retry_count`
+  - `last_error_message`
+  - `next_retry_at`
+  - `created_at`
+  - `updated_at`
+- 중복 방지:
+  - 활성 상태 기준 `(resource_type, resource_id, field_key, target_language, source_hash)` 중복 생성을 막는다.
+- 역할:
+  - 중복 작업 방지, 재시도, 실패 추적, 운영자 재처리를 담당한다.
+
+#### `language_detection_result`
+- 언어 감지 결과를 원본 엔티티에만 저장하지 않고 별도 캐시/이력으로 관리한다.
+- 주요 컬럼:
+  - `id`
+  - `source_hash`
+  - `source_text_sample`
+  - `detected_language`
+  - `provider`
+  - `confidence`
+  - `normalization_version`
+  - `created_at`
+- 역할:
+  - 짧은 문구나 반복 문구의 감지 호출을 줄인다.
+  - 원본 엔티티의 `languageCode`는 기존 호환 필드로 유지할 수 있다.
+
+#### 도메인별 번역 read model
+- `ContentTranslation`, `SeriesTranslation`, `AiCharacterTranslation`, `OriginalWorkTranslation`처럼 여러 필드가 묶인 응답은 JSON payload read model을 유지한다.
+- `CategoryTranslation`, `ContentThemeTranslation`, `SeriesGenreTranslation`처럼 단일 문자열만 필요한 대상은 scalar column을 유지한다.
+- JSON payload는 `translation_memory`를 조립한 결과를 저장하는 materialized cache로 본다.
+- provider, retry, source hash 같은 실행/원장 메타데이터는 JSON payload에 넣지 않는다.
+
+### JSON 유지 여부
+- JSON payload 저장은 유지한다.
+- 단, JSON을 번역의 최종 원장으로 보지 않고 API 응답을 빠르게 만들기 위한 read model로 격하한다.
+- 현재 조회 패턴은 JSON 내부 검색이 아니라 `resourceId + locale`로 1-row 조인 후 payload를 읽는 방식이므로, 정규화 row를 매번 pivot하는 것보다 조회 경로가 단순하다.
+- 목록 API에서 제목이나 이름 하나만 자주 읽는데 payload가 커지는 도메인은 `translated_title`, `translated_name` 같은 hot column을 선택적으로 추가한다.
+- 단일 문자열 번역 대상은 JSON으로 바꾸지 않는다.
+
+### 처리 흐름
+- 생성/수정 시 번역 대상 필드를 세그먼트로 추출한다.
+- 세그먼트별 `source_hash`를 계산한다.
+- 언어 정보가 없으면 `language_detection_result`를 조회하고, 없을 때만 감지 작업을 수행한다.
+- 대상 언어별로 `translation_memory`를 먼저 조회한다.
+- cache hit이면 Papago를 호출하지 않고 read model materialize 단계로 넘어간다.
+- cache miss이면 `translation_job`을 `PENDING`으로 생성한다.
+- 워커가 job을 가져와 Papago를 호출하고 `translation_memory`에 저장한다.
+- 대상 resource의 모든 필드 번역이 준비되면 도메인별 read model JSON 또는 scalar row를 갱신한다.
+
+### 조회 정책
+- 조회 API에서는 Papago를 직접 호출하지 않는다.
+- 번역 read model이 있으면 해당 번역을 반환한다.
+- 번역 read model이 없으면 원문 또는 기존 fallback locale을 반환한다.
+- 누락된 번역은 조회 요청에서 job만 예약할 수 있으며, 외부 API 응답을 기다리지 않는다.
+
+### 최종 선택 요약
+| 영역 | 최종 선택 | 이유 |
+|---|---|---|
+| Papago 중복 호출 방지 | `translation_memory` 정규화 | 동일 원문/언어쌍 재사용이 가능하다. |
+| 번역 실행 | `translation_job` 비동기 큐 | 재시도와 실패 추적이 가능하고 조회 응답을 지연시키지 않는다. |
+| 다중 필드 응답 저장 | JSON read model 유지 | `entityId + locale` 1-row 조회가 가능해 API 조립이 단순하다. |
+| 단일 문자열 번역 저장 | scalar column 유지 | JSON보다 단순하고 불필요한 변환 비용이 없다. |
+| 자주 읽는 일부 필드 | 선택적 hot column 추가 | 큰 JSON payload 전체 로딩 비용을 줄일 수 있다. |
+| provider 확장 | `TranslationProvider` 인터페이스 | Papago 의존을 낮추고 향후 교체를 쉽게 한다. |
+
+## 상세 정책
+
+### 운영자 재처리
+- 관리자/운영 API에서는 번역 상태를 확인하고 재번역을 요청할 수 있게 한다.
+- 실패한 job은 원문, 대상 언어, provider, 실패 사유, 재시도 횟수를 함께 보여준다.
+
+### 중복 방지 정책
+- `TranslationMemory`는 `(source_hash, source_language, target_language, provider, normalization_version)`에 unique 제약을 둔다.
+- `TranslationJob`은 활성 상태 기준 `(resource_type, resource_id, field_key, target_language, source_hash)` 중복 생성을 막는다.
+- 동일 작업이 동시에 들어오면 기존 `PENDING` 또는 `RUNNING` 작업을 재사용한다.
+
+### 오류와 재시도
+- Papago 실패 시 `TranslationJob.status = FAILED`와 실패 사유를 저장한다.
+- 일시 오류는 지수 백오프로 재시도한다.
+- 영구 오류나 빈 원문은 재시도하지 않는다.
+- 재시도 횟수를 초과하면 운영자가 재시도할 수 있도록 별도 상태로 남긴다.
+
+### 운영 안정화 보완 작업
+- 현재 `TranslationJobWorker.claimNextJob()`는 `PENDING` job을 조회한 뒤 `RUNNING`으로 변경한다.
+- 다중 애플리케이션 인스턴스에서 같은 job을 동시에 조회할 수 있으므로 운영 반영 전 claim을 원자화한다.
+- 권장 방식은 MySQL 기준 `SELECT ... FOR UPDATE SKIP LOCKED` 또는 `UPDATE ... WHERE status = 'PENDING' ... LIMIT 1` 기반 원자적 claim이다.
+- job row를 여러 인스턴스가 나눠 처리하는 목적에는 `FOR UPDATE SKIP LOCKED` 또는 atomic update claim을 우선한다.
+- `ShedLock`은 스케줄러 실행 자체의 중복을 막는 용도로는 적합하지만, job row 단위 분산 claim을 대체하지는 않는다.
+- Papago 호출은 DB lock을 잡은 트랜잭션 밖에서 수행하고, claim/완료/실패 상태 변경만 짧은 트랜잭션으로 처리한다.
+- `FAILED`로 즉시 종료하는 최소 구현에서 지수 백오프 기반 재시도 정책으로 보완한다.
+- 재시도 정책은 `retry_count`, `next_retry_at`, `last_error_message`를 함께 갱신하고, 최대 재시도 초과 상태를 운영자가 확인할 수 있게 한다.
+- worker 처리량과 부하를 운영 설정으로 제어할 수 있도록 `fixed-delay-ms`, tick당 처리 group 수, 최대 재시도 횟수, Papago 호출 rate limit을 설정화한다.
+- tick당 처리 단위는 단순 job row 수가 아니라 `(resource_type, resource_id, target_language)` group으로 잡는다.
+- 1차 운영 기준은 tick당 최대 5개 group 처리로 둔다.
+- group 내부의 field job은 순차 처리하고, 같은 resource/locale의 모든 필드가 `translation_memory`에 준비된 뒤 read model을 materialize한다.
+- 콘텐츠 기준으로는 1개 group이 `title`, `detail`, `tags` 3개 field job이므로 tick당 최대 15개 field job이 된다.
+- 캐릭터처럼 필드가 많은 리소스도 group 5개 제한 안에서 처리해 Papago 호출 burst를 완화한다.
+- 운영 관측을 위해 pending/running/failed/completed count, oldest pending age, 처리 성공/실패 수, Papago 호출 시간, materialize 실패 수를 로그 또는 metric으로 남긴다.
+
+### 번역 job 실행 주기 조정 검토
+- 현재 구현은 `sodalive.translation-job.fixed-delay-ms` 설정이 없으면 기본 `5000ms` fixed delay로 실행된다.
+- 콘텐츠가 지속적으로 올라오는 서비스 형태가 아니므로 기본 주기를 10분(`600000ms`)으로 늘리는 방향을 검토한다.
+- `fixedDelay`는 작업 종료 후 다음 실행까지의 지연 시간이므로 실제 실행 간격은 `처리 시간 + 10분`이 된다.
+- 정확히 벽시계 기준 10분마다 실행해야 한다면 `cron + 스케줄 중복 방지 lock`을 검토하고, 처리 후 10분 쉬는 정책이면 `fixedDelay`를 사용한다.
+- 10분 주기의 장점은 불필요한 DB polling과 Papago 호출 burst 가능성을 줄이고, 낮은 트래픽 환경에서 백그라운드 작업 부하를 완화하는 것이다.
+- 10분 주기의 단점은 번역 read model 반영 지연이 최대 10분 이상으로 늘어날 수 있다는 점이다.
+- 조회 정책이 원문 즉시 반환 + job 예약 방식이므로 API 응답 실패로 이어지지는 않지만, 사용자는 첫 조회 후 최대 다음 worker 실행까지 원문을 볼 수 있다.
+- 기존 tick당 20 job row 처리 방식은 같은 resource/locale의 일부 필드만 처리하고 다음 tick으로 넘어갈 수 있다.
+- 10분 주기에서는 부분 처리된 resource의 read model 반영이 다음 tick까지 지연될 수 있으므로 `(resource_type, resource_id, target_language)` group 단위 처리로 보완한다.
+- 10분 주기를 적용하려면 tick당 처리 group 수를 운영 설정으로 조정하거나, pending backlog가 특정 기준을 넘을 때 수동/운영자 재처리 또는 임시 짧은 주기 전환이 가능해야 한다.
+- 생성 직후 번역 노출이 중요한 리소스가 발견되면 해당 리소스만 별도 즉시 처리 정책을 두고, 일반 조회 fallback은 10분 주기를 유지한다.
+- 1차 운영 기준은 `fixed-delay-ms = 600000`, tick당 최대 5개 group, 원문 fallback 허용, backlog/oldest pending age 모니터링으로 둔다.
+
+### 단계별 적용
+- 1단계: `TranslationProvider` 인터페이스를 만들고 기존 `PapagoTranslationService`를 provider 구현으로 감싼다.
+- 2단계: `translation_memory`, `translation_job`, `language_detection_result` 테이블을 추가한다.
+- 3단계: 조회 fallback의 직접 Papago 호출을 제거하고, 누락 번역 job 예약 방식으로 전환한다.
+- 4단계: 생성/수정 이벤트 번역을 `translation_job` 기반 워커로 전환한다.
+- 5단계: `TranslationMemory` 결과를 기존 JSON/scalar read model로 materialize한다.
+- 6단계: 목록 조회에서 큰 JSON payload 로딩이 병목이면 hot column을 선택적으로 추가한다.
+
+## 검증 관점
+- 동일 원문을 여러 도메인에서 번역해도 Papago 호출이 한 번만 발생하는지 확인한다.
+- 조회 API에서 Papago 호출이 발생하지 않는지 확인한다.
+- 생성/수정 이벤트 후 번역 작업이 중복 생성되지 않는지 확인한다.
+- Papago 장애 시 원 API 응답이 실패하지 않고 작업 상태만 실패로 남는지 확인한다.
+- 기존 API 응답 스키마가 바뀌지 않는지 확인한다.
+
+## 남은 결정사항
+- 번역이 없는 조회 응답은 원문을 반환한다.
+- 실시간 번역이 꼭 필요한 엔드포인트는 1차 구현 범위에 포함하지 않는다. 단, 생성 직후 번역 노출이 중요한 리소스가 확인되면 해당 리소스만 별도 즉시 처리 정책을 검토한다.
+- JSON read model을 장기 유지하되, hot column이 필요한 목록 API를 측정으로 결정해야 한다.
+- Papago 외 provider는 1차 구현에서는 인터페이스만 준비하고 실제 추가 provider는 범위에서 제외한다.
+
+## 검증 기록
+- 2026-05-06: 코드 탐색 결과를 바탕으로 현재 번역 저장 구조, Papago 호출 흐름, 외부 아키텍처 패턴을 비교해 설계 초안을 작성했다.
+- 2026-05-06: 문서 내 미완성 placeholder, 상충되는 범위, 구현 전제 누락 여부를 점검했다.
+- 2026-05-06: 기존 번역 데이터 보존 제약을 배제해도 `TranslationMemory + TranslationJob + JSON read model` 하이브리드가 최종 구현방식으로 적합한지 재평가하고 문서에 반영했다.
+- 2026-05-06: TDD RED 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.i18n.translation.SourceTextNormalizerTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest'` 실행 시 `SourceTextNormalizer`, `TranslationJobRepository`, `TranslationJobScheduler`, `LanguageDetectionResultRepository`, `LanguageDetectionCacheService` 미구현으로 `compileTestKotlin` 실패를 확인했다.
+- 2026-05-06: 구현 후 동일 targeted test 명령을 재실행해 `BUILD SUCCESSFUL`을 확인했다. 정규화/해시, 누락 번역 job 생성, 언어 감지 캐시 hit 시 provider 미호출 동작을 검증했다.
+- 2026-05-06: 전체 회귀 검증으로 `./gradlew test`와 `./gradlew build`를 실행해 모두 `BUILD SUCCESSFUL`을 확인했다. `build`에는 ktlint main/test/sourceSet check가 포함되어 스타일도 함께 검증됐다.
+- 2026-05-06: `PapagoTranslationService|translationService\.translate|papagoTranslationService\.translate|TranslateRequest` 검색으로 직접 번역 호출이 `PapagoTranslationService`, `TranslationProvider`, `TranslationJobWorker`, DTO, 지원 언어 목록 참조에만 남아 있음을 확인했다. 조회 fallback과 `LanguageTranslationListener`에는 직접 Papago 번역 호출이 남아 있지 않다.
+- 2026-05-06: MySQL unique 제약은 활성 상태 partial unique를 표현할 수 없으므로 완료 job이 있는 동일 key 재예약 시 중복 insert가 발생하지 않도록 repository 파생 쿼리 기반 회귀 테스트를 추가했다. RED는 중복 job 조회 메서드 미구현으로 `compileTestKotlin` 실패, GREEN은 동일 테스트 `BUILD SUCCESSFUL`로 확인했다.
+- 2026-05-06: 최종 확인에서 Kotlin LSP 서버가 설정되어 있지 않아 `lsp_diagnostics`는 `No LSP server configured for extension: .kt`로 실행할 수 없었다. 대체 검증으로 `./gradlew test`, `./gradlew build`, 신규 focused test `--rerun-tasks`를 실행했고 모두 `BUILD SUCCESSFUL`을 확인했다.
+- 2026-05-06: 운영 안정화 보완 구현으로 `TranslationJobWorker` 기본 fixed delay를 10분(`600000ms`)으로 변경하고, MySQL `FOR UPDATE SKIP LOCKED` 기반 job id claim, 실패 시 `PENDING` 재전환 + `next_retry_at` backoff + 최대 재시도 후 `FAILED` 전환을 적용했다. RED는 `TranslationJobWorkerTest`에서 원자 claim 메서드 미구현으로 `compileTestKotlin` 실패, GREEN은 동일 focused test `BUILD SUCCESSFUL`로 확인했다.
+- 2026-05-06: 문서에 반영한 group 단위 처리 정책을 구현했다. `TranslationJobWorker`는 tick당 최대 5개 `(resource_type, resource_id, target_language)` group을 처리하고, group 내부 pending field job을 `RUNNING`으로 claim한 뒤 모두 성공한 경우 한 번만 read model을 materialize한다. RED는 `findPendingJobIdsForGroupForUpdate`, `processNextGroup` 미구현으로 `TranslationJobWorkerTest`의 `compileTestKotlin` 실패를 확인했고, GREEN은 동일 focused test `BUILD SUCCESSFUL`로 확인했다.
+- 2026-05-06: group 처리 리뷰에서 materialize 실패 후 재시도 불가 가능성과 seed row 기반 claim의 group 분리 가능성을 확인했다. 보완 구현으로 단일 native query `findNextPendingGroupJobIdsForUpdate`에서 다음 pending group의 job id들을 `FOR UPDATE SKIP LOCKED`로 함께 claim하고, materialize 실패 시 group job들을 backoff 재시도 대상으로 되돌리도록 수정했다. RED는 새 group claim 메서드 미구현으로 `TranslationJobWorkerTest`의 `compileTestKotlin` 실패를 확인했고, GREEN은 동일 focused test `BUILD SUCCESSFUL`로 확인했다.
+- 2026-05-06: group 처리 전환 후 남은 이전 row 단위 claim 함수 사용처를 `rg`, AST 검색, explore/librarian 병렬 탐색으로 확인했다. production 경로가 `processNextGroup` + `findNextPendingGroupJobIdsForUpdate`로 수렴되어 `processNextJob`, `findFirstByStatusAndNextRetryAtLessThanEqualOrderByCreatedAtAsc`, `findNextPendingJobIdForUpdate`, `findPendingJobIdsForGroupForUpdate`를 제거했다.
+
+## 2026-05-06 구현 DDL
+
+운영 MySQL은 `spring.jpa.hibernate.ddl-auto=validate`이므로 아래 DDL을 선반영해야 한다. `created_at`, `updated_at`은 `BaseEntity`의 `createdAt`, `updatedAt`과 매핑된다.
+
+```sql
+CREATE TABLE translation_memory (
+    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '번역 메모리 ID',
+    source_hash VARCHAR(64) NOT NULL COMMENT '정규화 원문 SHA-256 해시',
+    source_text TEXT NOT NULL COMMENT '정규화 원문 텍스트',
+    source_language VARCHAR(10) NOT NULL COMMENT '원문 언어 코드',
+    target_language VARCHAR(10) NOT NULL COMMENT '대상 언어 코드',
+    translated_text TEXT NOT NULL COMMENT '번역 결과 텍스트',
+    provider VARCHAR(50) NOT NULL COMMENT '번역 provider 이름',
+    provider_version VARCHAR(50) NOT NULL COMMENT '번역 provider 버전',
+    normalization_version VARCHAR(20) NOT NULL COMMENT '정규화 규칙 버전',
+    created_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
+    updated_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_translation_memory_source_target_provider (
+        source_hash,
+        source_language,
+        target_language,
+        provider,
+        normalization_version
+    ),
+    KEY idx_translation_memory_source_hash (source_hash),
+    KEY idx_translation_memory_target_language (target_language)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE translation_job (
+    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '번역 작업 ID',
+    resource_type VARCHAR(50) NOT NULL COMMENT '번역 대상 리소스 타입',
+    resource_id BIGINT NOT NULL COMMENT '번역 대상 리소스 ID',
+    field_key VARCHAR(80) NOT NULL COMMENT '번역 대상 필드 키',
+    source_hash VARCHAR(64) NOT NULL COMMENT '정규화 원문 SHA-256 해시',
+    source_text TEXT NOT NULL COMMENT '정규화 원문 텍스트',
+    source_language VARCHAR(10) NOT NULL COMMENT '원문 언어 코드',
+    target_language VARCHAR(10) NOT NULL COMMENT '대상 언어 코드',
+    status VARCHAR(20) NOT NULL COMMENT '번역 작업 상태',
+    retry_count INT NOT NULL COMMENT '재시도 횟수',
+    last_error_message TEXT DEFAULT NULL COMMENT '마지막 오류 메시지',
+    next_retry_at TIMESTAMP NOT NULL COMMENT '다음 재시도 가능 시각',
+    created_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
+    updated_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_translation_job_resource_field_target_hash (
+        resource_type,
+        resource_id,
+        field_key,
+        target_language,
+        source_hash
+    ),
+    KEY idx_translation_job_status_retry (status, next_retry_at),
+    KEY idx_translation_job_resource (resource_type, resource_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE language_detection_result (
+    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '언어 감지 결과 ID',
+    source_hash VARCHAR(64) NOT NULL COMMENT '정규화 원문 SHA-256 해시',
+    source_text_sample VARCHAR(500) NOT NULL COMMENT '정규화 원문 샘플 텍스트',
+    detected_language VARCHAR(10) NOT NULL COMMENT '감지된 언어 코드',
+    provider VARCHAR(50) NOT NULL COMMENT '언어 감지 provider 이름',
+    confidence DOUBLE DEFAULT NULL COMMENT '언어 감지 신뢰도',
+    normalization_version VARCHAR(20) NOT NULL COMMENT '정규화 규칙 버전',
+    created_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
+    updated_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_language_detection_result_hash_provider_version (
+        source_hash,
+        provider,
+        normalization_version
+    ),
+    KEY idx_language_detection_result_source_hash (source_hash)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```

docs/20260507_번역작업원문언어제한.md

@@ -0,0 +1,18 @@
+# 번역 작업 원문 언어 제한
+
+## 작업 항목
+- [x] `TranslationJobSchedulerTest`에 지원하지 않는 `sourceLanguage` 입력 시 `TranslationJob`을 저장하지 않는 RED 테스트를 추가한다.
+- [x] `TranslationJobScheduler`에서 `sourceLanguage`를 소문자 정규화한 뒤 `ko`, `en`, `ja`가 아니면 등록을 중단한다.
+- [x] focused test와 관련 검증 명령을 실행해 변경 결과를 확인한다.
+
+## 설계
+- `TranslationJob` 등록의 최종 방어선인 `TranslationJobScheduler.scheduleMissingTranslation()`에서 검증한다.
+- 허용값은 현재 번역 지원 언어와 동일하게 `ko`, `en`, `ja`로 제한한다.
+- 지원하지 않는 원문 언어는 예외를 던지지 않고 기존 early return 흐름처럼 job 등록만 생략한다.
+
+## 검증 기록
+- 2026-05-07: RED 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest.shouldNotCreateJobWhenSourceLanguageIsUnsupported'` 실행 시 `TranslationJobSchedulerTest.kt:102`의 `verifyNoInteractions` 검증 실패로 unsupported `sourceLanguage`가 repository 호출까지 진행됨을 확인했다.
+- 2026-05-07: GREEN 확인: 동일 focused test가 `BUILD SUCCESSFUL`로 통과해 unsupported `sourceLanguage`가 등록되지 않음을 확인했다.
+- 2026-05-07: 회귀 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest'`가 `BUILD SUCCESSFUL`로 통과했다.
+- 2026-05-07: 스타일 확인: `./gradlew ktlintCheck`가 `BUILD SUCCESSFUL`로 통과했다.
+- 2026-05-07: Kotlin LSP는 현재 환경에 `.kt` 서버가 설정되어 있지 않아 `lsp_diagnostics` 실행이 불가했다. 대신 Gradle 컴파일 포함 focused/class test와 ktlint로 검증했다.

docs/20260507_콘텐츠관리자권한및관리자로그인API추가.md

@@ -0,0 +1,46 @@
+# 콘텐츠 관리자 권한 및 관리자 로그인 API 추가
+
+## 작업 항목
+- [x] `MemberRole`에 콘텐츠 관리자 권한을 추가한다.
+- [x] 관리자 로그인 API 테스트를 먼저 추가하고 RED를 확인한다.
+- [x] 관리자와 콘텐츠 관리자만 로그인 가능한 관리자 전용 로그인 API를 구현한다.
+- [x] 응답을 `token`, `role`만 포함하도록 구현한다.
+- [x] focused test, 관련 테스트, 스타일 검사를 실행하고 결과를 기록한다.
+- [x] 콘텐츠 관리자가 `GET /menu`를 호출할 수 있도록 메뉴 조회 권한을 확장한다.
+- [x] 콘텐츠 관리자가 관리자 콘텐츠 목록/조회 보조 API를 호출할 수 있도록 읽기 권한만 확장한다.
+- [x] 콘텐츠 관리자가 관리자 콘텐츠 수정 API를 호출할 수 없도록 수정 권한은 관리자 전용으로 유지한다.
+- [x] focused security test, 관련 테스트, 스타일 검사를 실행하고 결과를 기록한다.
+
+## 설계
+- 새 권한은 기존 `MemberRole` enum에 `CONTENT_MANAGER`로 추가한다.
+- 새 API는 관리자 도메인의 `/admin/member/login`으로 추가하고 인증 없이 호출 가능하도록 보안 설정에 permitAll을 추가한다.
+- 서비스는 기존 이메일/비밀번호 인증 흐름과 JWT 생성 방식을 재사용하되, `ADMIN`, `CONTENT_MANAGER` 외 역할은 `common.error.bad_credentials` 예외로 거부한다.
+- 응답 DTO는 관리자 로그인 전용으로 분리해 `token`, `role`만 노출한다.
+
+## 후속 설계: 콘텐츠 관리자 메뉴 및 콘텐츠 읽기 권한
+- `CONTENT_MANAGER`는 이미 관리자 로그인 API로 토큰을 받을 수 있으므로 새 역할이나 새 권한 타입을 추가하지 않는다.
+- 메뉴 조회는 기존 `GET /menu`와 `MenuRepository.getMenu(member.role)` 구조를 그대로 사용한다. 컨트롤러의 `@PreAuthorize`에 `CONTENT_MANAGER`만 추가해 콘텐츠 관리자가 자신의 역할에 매핑된 메뉴를 받을 수 있게 한다.
+- `/content/list`는 서버 코드 상수가 아니라 `Menu.route` DB 값으로 내려가는 구조이므로, 서버에서는 별도 라우트 상수를 추가하지 않는다. 실제 메뉴 노출은 `roles = CONTENT_MANAGER`, `route = /content/list`, `isActive = true` 데이터가 존재할 때 가능하다.
+- 관리자 콘텐츠 API는 기존 `hasRole('ADMIN')` 클래스 권한을 메서드 단위로 분리한다. `GET /admin/audio-content/list`, `GET /admin/audio-content/search`, `GET /admin/audio-content/main/tab`은 `ADMIN`과 `CONTENT_MANAGER`를 허용하고, `PUT /admin/audio-content`는 `ADMIN`만 허용한다.
+- 콘텐츠 재생은 기존 사용자 콘텐츠 API의 `GET /audio-content/{id}/generate-url` 흐름을 변경하지 않는다. 이 API는 로그인 사용자와 구매/접근 조건으로 재생 URL을 제어하므로 콘텐츠 관리자 전용 우회 권한은 추가하지 않는다.
+
+## 구현 계획
+- [x] `MenuController` 보안 테스트를 추가해 `CONTENT_MANAGER`가 `GET /menu`에 접근 가능하고 일반 사용자는 거부되는지 확인한다.
+- [x] `AdminContentController` 보안 테스트를 추가해 `CONTENT_MANAGER`는 목록/검색/메인탭 조회가 가능하고 수정은 거부되는지 확인한다.
+- [x] 테스트가 실패하는 것을 확인한다.
+- [x] `MenuController`의 `@PreAuthorize`에 `CONTENT_MANAGER`를 추가한다.
+- [x] `AdminContentController`의 클래스 단위 `@PreAuthorize`를 제거하고 각 메서드에 읽기/수정 권한을 분리한다.
+- [x] focused test, 관련 test, ktlint를 실행해 검증한다.
+
+## 검증 기록
+- 2026-05-07: RED 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.admin.member.AdminMemberLoginServiceTest' --tests 'kr.co.vividnext.sodalive.admin.member.AdminMemberLoginControllerTest'` 실행 시 `AdminMemberLoginService`, `AdminMemberLoginController`, `AdminMemberLoginResponse`, `CONTENT_MANAGER`, `findByEmail` 미구현으로 `compileTestKotlin`이 실패함을 확인했다.
+- 2026-05-07: GREEN 확인: 동일 focused test가 `BUILD SUCCESSFUL`로 통과해 관리자/콘텐츠 관리자 로그인 허용 및 일반 사용자 거부를 확인했다.
+- 2026-05-07: API 응답 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.admin.member.AdminMemberLoginControllerTest.shouldReturnTokenAndRoleJson'`가 `BUILD SUCCESSFUL`로 통과해 `POST /admin/member/login` JSON 응답의 `data.token`, `data.role`을 확인했다.
+- 2026-05-07: 회귀 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.admin.member.*'`가 `BUILD SUCCESSFUL`로 통과했다.
+- 2026-05-07: 스타일 확인: `./gradlew ktlintCheck`가 `BUILD SUCCESSFUL`로 통과했다.
+- 2026-05-07: Kotlin LSP는 현재 환경에 `.kt` 서버가 설정되어 있지 않아 `lsp_diagnostics` 실행이 불가했다. 대신 Gradle 컴파일 포함 focused/관련 test와 ktlint로 검증했다.
+- 2026-05-07: RED 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.menu.MenuControllerSecurityTest' --tests 'kr.co.vividnext.sodalive.admin.content.AdminContentControllerSecurityTest'` 실행 시 `CONTENT_MANAGER`의 `GET /menu`, `GET /admin/audio-content/list`, `GET /admin/audio-content/search`, `GET /admin/audio-content/main/tab` 허용 기대 테스트 4건이 실패함을 확인했다.
+- 2026-05-07: GREEN 확인: 동일 focused security test가 `BUILD SUCCESSFUL`로 통과해 콘텐츠 관리자 메뉴 조회, 관리자 콘텐츠 목록/검색/메인탭 조회 허용과 관리자 콘텐츠 수정 거부를 확인했다.
+- 2026-05-07: 관련 테스트 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.admin.content.AdminContentServiceTest' --tests 'kr.co.vividnext.sodalive.admin.member.AdminMemberLoginServiceTest' --tests 'kr.co.vividnext.sodalive.admin.member.AdminMemberLoginControllerTest'`가 `BUILD SUCCESSFUL`로 통과했다.
+- 2026-05-07: 스타일 확인: `./gradlew ktlintCheck`가 `BUILD SUCCESSFUL`로 통과했다.
+- 2026-05-07: Kotlin LSP는 현재 환경에 `.kt` 서버가 설정되어 있지 않아 `lsp_diagnostics` 실행이 불가했다. 대신 Gradle 컴파일 포함 focused/관련 test와 ktlint로 검증했다.

docs/20260508_크리에이터관리자로그아웃AGENT권한허용.md

@@ -0,0 +1,21 @@
+# 크리에이터 관리자 로그아웃 AGENT 권한 허용
+
+## 목표
+- `/creator-admin/member/logout` 엔드포인트를 `CREATOR`뿐 아니라 `AGENT` 권한 계정도 사용할 수 있게 한다.
+- 로그인 로직이 이미 `CREATOR`, `AGENT`를 허용하는 기존 정책과 로그아웃 권한 조건을 맞춘다.
+
+## 구현 항목
+- [x] `CreatorAdminMemberController`의 `logout` 권한 조건에 `AGENT`를 추가한다.
+- [x] `logout` 권한 조건이 `CREATOR`, `AGENT`를 모두 포함하는지 테스트로 검증한다.
+- [x] 변경 파일 진단과 대상 테스트를 실행한다.
+
+## 검증 계획
+- `./gradlew test --tests "kr.co.vividnext.sodalive.creator.admin.member.CreatorAdminMemberControllerTest"`
+- `lsp_diagnostics`로 변경 Kotlin 파일 오류 확인
+
+## 검증 기록
+- `./gradlew test --tests "kr.co.vividnext.sodalive.creator.admin.member.CreatorAdminMemberControllerTest"`를 먼저 실행해 `hasRole('CREATOR')` 상태에서 실패함을 확인했다.
+- `CreatorAdminMemberController.logout`의 `@PreAuthorize`를 `hasAnyRole('CREATOR', 'AGENT')`로 변경했다.
+- 동일한 대상 테스트를 `--rerun-tasks`로 재실행해 `BUILD SUCCESSFUL`을 확인했다.
+- `lsp_diagnostics`는 Kotlin(`.kt`) LSP 서버가 설정되어 있지 않아 실행할 수 없었다. Gradle 테스트 과정에서 Kotlin 컴파일과 테스트 컴파일은 정상 통과했다.
+- 테스트 실행 중 기존 파일 `ImageBlurUtil.kt`의 미사용 파라미터 경고가 표시됐으며, 이번 변경 범위와는 무관해 수정하지 않았다.

docs/agent-guides/문서유지보수.md

@@ -0,0 +1,12 @@
+# 문서 유지보수
+
+## 문서 유지보수 규칙
+- `build.gradle.kts` 변경 시 실행 명령 섹션을 함께 갱신한다.
+- 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다.
+- `.editorconfig` 변경 시 포맷 규칙 섹션을 동기화한다.
+- Cursor/Copilot 규칙 파일이 생기면 해당 내용을 이 문서에 반영한다.
+- 연속된 하나의 작업에 대해 계획 문서가 여러 개 생기지 않도록 기존 계획 문서 재사용 여부를 먼저 확인한다.
+- 문서 변경 후 최소 한 번 `./gradlew tasks --all`로 명령 유효성을 확인한다.
+- 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다.
+- 에이전트 안내 문구는 한국어 중심으로 유지한다.
+- 커밋 규칙 예시는 팀 컨벤션 변경 시 즉시 업데이트한다.

docs/agent-guides/설정보안.md

@@ -0,0 +1,6 @@
+# 설정 보안
+
+## 설정/보안 유의사항
+- `application.yml`은 다수의 `${ENV_VAR}`를 사용한다.
+- 비밀값(API Key, Secret, Token, DB 비밀번호)을 코드/문서/로그에 평문으로 남기지 않는다.
+- 환경변수/시크릿 파일은 커밋 대상에서 제외한다.

docs/agent-guides/작업절차.md

@@ -0,0 +1,9 @@
+# 작업 절차
+
+## 작업 절차 체크리스트
+- 변경 전: 유사 기능 코드를 먼저 찾아 네이밍/예외/응답 패턴을 맞춘다.
+- 변경 전: 같은 작업의 연속 후속 수정인지 먼저 확인하고, 연속 작업이면 새 계획 문서를 만들지 말고 기존 계획 문서를 갱신한다.
+- 변경 중: 공개 API 스키마를 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
+- 변경 후: 최소 단일 테스트 또는 `./gradlew test`를 실행하고, 필요 시 `./gradlew ktlintCheck`를 수행한다.
+- 커밋 전/후: `commit-policy` 스킬을 먼저 로드하고, `git commit` 직전과 직후에 `work/scripts/check-commit-message-rules.sh`를 실행해 커밋 메시지 규칙 준수 여부를 확인한다.
+- 커밋 전/후 확인 시 Sisyphus attribution footer가 없는지 함께 검증한다.

docs/agent-guides/코드스타일.md

@@ -0,0 +1,59 @@
+# 코드 스타일
+
+## 코드 스타일 규칙
+
+### 1) 포맷/기본 규칙
+- `.editorconfig` 기준을 준수한다.
+- 인덴트: 공백 4칸.
+- 줄바꿈: LF.
+- 최대 라인 길이: 130.
+- 파일 끝 개행 유지, trailing whitespace 제거.
+
+### 2) import 규칙
+- 와일드카드 import(`*`)를 사용하지 않는다.
+- 사용하지 않는 import를 남기지 않는다.
+- import alias(`as`)는 현재 코드베이스에서 사용 사례가 없으므로 지양한다.
+- 기존 파일의 import 정렬/그룹 스타일을 그대로 맞춘다.
+
+### 3) 네이밍 규칙
+- 클래스/인터페이스/enum: PascalCase.
+- 함수/변수/파라미터: camelCase.
+- 상수: UPPER_SNAKE_CASE (`companion object` 내부 `const val`).
+- Request/Response DTO는 `...Request`, `...Response` 접미사를 유지한다.
+- 서비스/컨트롤러/리포지토리 명명은 역할 접미사(`Service`, `Controller`, `Repository`)를 유지한다.
+
+### 4) 타입/널 처리
+- Kotlin 타입 시스템을 활용하고 nullable(`?`)를 명시한다.
+- 불필요한 `Any`/약한 타입을 피하고 구체 타입을 우선한다.
+- 기존 코드에서 `!!` 사용이 많지만, 신규 코드는 가능한 안전 호출/가드절/명시적 예외로 대체를 우선 고려한다.
+
+### 5) API/응답 규칙
+- API 응답은 `ApiResponse.ok(...)`, `ApiResponse.error(...)` 패턴을 따른다.
+- 컨트롤러는 도메인 예외를 직접 포맷하지 말고 `SodaException`을 던진다.
+- 인증 사용자 필요 시 `@AuthenticationPrincipal(... ) member: Member?` 패턴 + null 가드절을 사용한다.
+
+### 6) 예외 처리 규칙
+- 비즈니스 예외는 `SodaException(messageKey = "...")` 우선 사용.
+- 사용자 노출 문구는 하드코딩보다 `messageKey` 기반 i18n을 우선한다.
+- 공통 예외 변환은 `SodaExceptionHandler`에서 수행하므로, 개별 컨트롤러에서 중복 처리하지 않는다.
+- 예외를 삼키는 빈 `catch` 블록을 금지한다.
+
+### 7) 트랜잭션 규칙
+- 서비스 계층에서 `@Transactional`을 사용한다.
+- 조회 위주 메서드는 `@Transactional(readOnly = true)`를 우선한다.
+- 쓰기 로직은 메서드 단위 `@Transactional`로 경계를 명확히 한다.
+
+### 8) 비동기/동시성 규칙
+- 비동기 처리는 Kotlin Coroutines 패턴을 따른다.
+- `CoroutineScope(Dispatchers.IO)` + `launch` + 예외 처리 패턴을 일관되게 유지한다.
+- 생명주기 종료 시 scope 정리(`@PreDestroy`) 패턴을 참고한다.
+
+### 9) 의존성 주입
+- 생성자 주입(primary constructor + `private val`)을 기본으로 사용한다.
+- 필드 주입보다 명시적 생성자 주입을 우선한다.
+
+### 10) 주석
+- 의미 단위별로 주석을 작성한다.
+- 주석은 한 문장으로 간결하게 작성한다.
+- 주석은 코드의 의도와 구조를 설명한다.
+- 주석은 코드 변경 시 업데이트를 잊지 않는다.

docs/agent-guides/테스트스타일.md

@@ -0,0 +1,9 @@
+# 테스트 스타일
+
+## 테스트 스타일 규칙
+- 테스트 프레임워크: JUnit 5 (`useJUnitPlatform()`)
+- 목킹: Mockito 사용 패턴 존재 (`Mockito.mock`, ``Mockito.`when`(...)``)
+- 검증: `assertEquals`, `assertThrows` 패턴 준수.
+- 테스트 이름은 의도가 드러나는 영어 문장형(`should...`)을 유지한다.
+- 테스트는 DisplayName으로 한국어 설명을 추가한다.
+- 예외 상황이 있는지 확인하고 예외 상황에 대한 테스트 케이스를 추가한다.

src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/AdminCalculateQueryRepository.kt

@@ -86,6 +86,7 @@ class AdminCalculateQueryRepository(private val queryFactory: JPAQueryFactory) {
         val pointGroup = CaseBuilder()
             .`when`(order.point.loe(0)).then(0)
             .otherwise(1)
+        val contentSettlementRatio = audioContent.settlementRatio.coalesce(creatorSettlementRatio.contentSettlementRatio)
 
         return queryFactory
             .select(audioContent.id)
@@ -108,7 +109,7 @@ class AdminCalculateQueryRepository(private val queryFactory: JPAQueryFactory) {
                 orderFormattedDate,
                 order.can,
                 pointGroup,
-                creatorSettlementRatio.contentSettlementRatio
+                contentSettlementRatio
             )
             .fetch()
             .size
@@ -124,6 +125,7 @@ class AdminCalculateQueryRepository(private val queryFactory: JPAQueryFactory) {
         val pointGroup = CaseBuilder()
             .`when`(order.point.loe(0)).then(0)
             .otherwise(1)
+        val contentSettlementRatio = audioContent.settlementRatio.coalesce(creatorSettlementRatio.contentSettlementRatio)
 
         return queryFactory
             .select(
@@ -137,7 +139,7 @@ class AdminCalculateQueryRepository(private val queryFactory: JPAQueryFactory) {
                     order.id.count(),
                     order.can.sum(),
                     order.point.sum(),
-                    creatorSettlementRatio.contentSettlementRatio
+                    contentSettlementRatio
                 )
             )
             .from(order)
@@ -159,7 +161,7 @@ class AdminCalculateQueryRepository(private val queryFactory: JPAQueryFactory) {
                 orderFormattedDate,
                 order.can,
                 pointGroup,
-                creatorSettlementRatio.contentSettlementRatio
+                contentSettlementRatio
             )
             .orderBy(member.id.desc(), orderFormattedDate.desc(), audioContent.id.asc())
             .offset(offset)
@@ -182,13 +184,23 @@ class AdminCalculateQueryRepository(private val queryFactory: JPAQueryFactory) {
     }
 
     fun getCumulativeSalesByContentTotalCount(): Int {
+        val pointGroup = CaseBuilder()
+            .`when`(order.point.loe(0)).then(0)
+            .otherwise(1)
+        val contentSettlementRatio = audioContent.settlementRatio.coalesce(creatorSettlementRatio.contentSettlementRatio)
+
         return queryFactory
             .select(audioContent.id)
             .from(order)
             .innerJoin(order.audioContent, audioContent)
             .innerJoin(audioContent.member, member)
+            .leftJoin(creatorSettlementRatio)
+            .on(
+                member.id.eq(creatorSettlementRatio.member.id)
+                    .and(creatorSettlementRatio.deletedAt.isNull)
+            )
             .where(order.isActive.isTrue)
-            .groupBy(member.id, audioContent.id, order.can)
+            .groupBy(member.id, audioContent.id, order.type, order.can, pointGroup, contentSettlementRatio)
             .fetch()
             .size
     }
@@ -197,6 +209,7 @@ class AdminCalculateQueryRepository(private val queryFactory: JPAQueryFactory) {
         val pointGroup = CaseBuilder()
             .`when`(order.point.loe(0)).then(0)
             .otherwise(1)
+        val contentSettlementRatio = audioContent.settlementRatio.coalesce(creatorSettlementRatio.contentSettlementRatio)
 
         return queryFactory
             .select(
@@ -209,7 +222,7 @@ class AdminCalculateQueryRepository(private val queryFactory: JPAQueryFactory) {
                     order.id.count(),
                     order.can.sum(),
                     order.point.sum(),
-                    creatorSettlementRatio.contentSettlementRatio
+                    contentSettlementRatio
                 )
             )
             .from(order)
@@ -227,7 +240,7 @@ class AdminCalculateQueryRepository(private val queryFactory: JPAQueryFactory) {
                 order.type,
                 order.can,
                 pointGroup,
-                creatorSettlementRatio.contentSettlementRatio
+                contentSettlementRatio
             )
             .offset(offset)
             .limit(limit)

src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/originalSeries/AdminOriginalSeriesCalculateController.kt

@@ -0,0 +1,65 @@
+package kr.co.vividnext.sodalive.admin.calculate.originalSeries
+
+import kr.co.vividnext.sodalive.common.ApiResponse
+import org.springframework.data.domain.Pageable
+import org.springframework.http.HttpHeaders
+import org.springframework.http.MediaType
+import org.springframework.http.ResponseEntity
+import org.springframework.security.access.prepost.PreAuthorize
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.RequestMapping
+import org.springframework.web.bind.annotation.RequestParam
+import org.springframework.web.bind.annotation.RestController
+import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody
+import java.net.URLEncoder
+import java.nio.charset.StandardCharsets
+
+@RestController
+@PreAuthorize("hasRole('ADMIN')")
+@RequestMapping("/admin/calculate")
+class AdminOriginalSeriesCalculateController(
+    private val service: AdminOriginalSeriesCalculateService
+) {
+    @GetMapping("/original-series/owners")
+    fun getOriginalSeriesOwners() = ApiResponse.ok(service.getOriginalSeriesOwners())
+
+    @GetMapping("/original-series/settlement-details")
+    fun getSettlementDetails(
+        @RequestParam("start_date") startDateStr: String,
+        @RequestParam("end_date") endDateStr: String,
+        @RequestParam("creator_id") creatorId: Long,
+        pageable: Pageable
+    ) = ApiResponse.ok(
+        service.getSettlementDetails(
+            startDateStr = startDateStr,
+            endDateStr = endDateStr,
+            creatorId = creatorId,
+            offset = pageable.offset,
+            limit = pageable.pageSize.toLong()
+        )
+    )
+
+    @GetMapping("/original-series/settlement-details/excel")
+    fun downloadSettlementDetailsExcel(
+        @RequestParam("start_date") startDateStr: String,
+        @RequestParam("end_date") endDateStr: String
+    ): ResponseEntity<StreamingResponseBody> = createExcelResponse(
+        fileName = "original-series-settlement-details.xlsx",
+        response = service.downloadSettlementDetailsExcel(startDateStr, endDateStr)
+    )
+
+    private fun createExcelResponse(
+        fileName: String,
+        response: StreamingResponseBody
+    ): ResponseEntity<StreamingResponseBody> {
+        val encodedFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8.toString()).replace("+", "%20")
+        val headers = HttpHeaders().apply {
+            add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename*=UTF-8''$encodedFileName")
+        }
+
+        return ResponseEntity.ok()
+            .headers(headers)
+            .contentType(MediaType.parseMediaType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"))
+            .body(response)
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/originalSeries/AdminOriginalSeriesCalculateQueryRepository.kt

@@ -0,0 +1,114 @@
+package kr.co.vividnext.sodalive.admin.calculate.originalSeries
+
+import com.querydsl.core.types.dsl.BooleanExpression
+import com.querydsl.jpa.impl.JPAQueryFactory
+import kr.co.vividnext.sodalive.content.QAudioContent.audioContent
+import kr.co.vividnext.sodalive.content.order.QOrder.order
+import kr.co.vividnext.sodalive.creator.admin.content.series.QSeries.series
+import kr.co.vividnext.sodalive.creator.admin.content.series.QSeriesContent.seriesContent
+import kr.co.vividnext.sodalive.member.QMember.member
+import org.springframework.stereotype.Repository
+import java.time.LocalDateTime
+
+@Repository
+class AdminOriginalSeriesCalculateQueryRepository(
+    private val queryFactory: JPAQueryFactory
+) {
+    fun getOriginalSeriesOwners(): List<GetAdminOriginalSeriesOwnerResponse> {
+        return queryFactory
+            .select(
+                QGetAdminOriginalSeriesOwnerResponse(
+                    member.id,
+                    member.nickname
+                )
+            )
+            .from(series)
+            .innerJoin(series.member, member)
+            .where(
+                series.isOriginal.isTrue
+                    .and(series.isActive.isTrue)
+                    .and(member.isActive.isTrue)
+            )
+            .groupBy(member.id, member.nickname)
+            .orderBy(member.id.asc())
+            .fetch()
+    }
+
+    fun getSettlementDetailTotalCount(
+        startDate: LocalDateTime,
+        endDate: LocalDateTime,
+        creatorId: Long
+    ): Int {
+        return queryFactory
+            .select(audioContent.id)
+            .from(order)
+            .innerJoin(order.audioContent, audioContent)
+            .innerJoin(seriesContent).on(seriesContent.content.id.eq(audioContent.id))
+            .innerJoin(seriesContent.series, series)
+            .innerJoin(series.member, member)
+            .where(baseWhereCondition(startDate, endDate, creatorId))
+            .groupBy(
+                series.id,
+                series.title,
+                audioContent.id,
+                audioContent.title,
+                order.type,
+                audioContent.price
+            )
+            .fetch()
+            .size
+    }
+
+    fun getSettlementDetails(
+        startDate: LocalDateTime,
+        endDate: LocalDateTime,
+        creatorId: Long,
+        offset: Long,
+        limit: Long
+    ): List<GetAdminOriginalSeriesSettlementDetailQueryData> {
+        return queryFactory
+            .select(
+                QGetAdminOriginalSeriesSettlementDetailQueryData(
+                    series.title,
+                    audioContent.title,
+                    audioContent.price,
+                    order.type,
+                    order.id.count(),
+                    order.can.sum().coalesce(0),
+                    order.point.sum().coalesce(0)
+                )
+            )
+            .from(order)
+            .innerJoin(order.audioContent, audioContent)
+            .innerJoin(seriesContent).on(seriesContent.content.id.eq(audioContent.id))
+            .innerJoin(seriesContent.series, series)
+            .innerJoin(series.member, member)
+            .where(baseWhereCondition(startDate, endDate, creatorId))
+            .groupBy(
+                series.id,
+                series.title,
+                audioContent.id,
+                audioContent.title,
+                order.type,
+                audioContent.price
+            )
+            .orderBy(series.id.asc(), audioContent.id.asc(), order.type.asc())
+            .offset(offset)
+            .limit(limit)
+            .fetch()
+    }
+
+    private fun baseWhereCondition(
+        startDate: LocalDateTime,
+        endDate: LocalDateTime,
+        creatorId: Long
+    ): BooleanExpression {
+        return series.isOriginal.isTrue
+            .and(series.isActive.isTrue)
+            .and(member.isActive.isTrue)
+            .and(member.id.eq(creatorId))
+            .and(order.isActive.isTrue)
+            .and(order.createdAt.goe(startDate))
+            .and(order.createdAt.loe(endDate))
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/originalSeries/AdminOriginalSeriesCalculateService.kt

@@ -0,0 +1,114 @@
+package kr.co.vividnext.sodalive.admin.calculate.originalSeries
+
+import kr.co.vividnext.sodalive.extensions.convertLocalDateTime
+import org.apache.poi.ss.usermodel.Sheet
+import org.apache.poi.ss.util.WorkbookUtil
+import org.apache.poi.xssf.streaming.SXSSFWorkbook
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody
+import java.time.LocalDateTime
+
+@Service
+class AdminOriginalSeriesCalculateService(
+    private val repository: AdminOriginalSeriesCalculateQueryRepository
+) {
+    @Transactional(readOnly = true)
+    fun getOriginalSeriesOwners(): List<GetAdminOriginalSeriesOwnerResponse> {
+        return repository.getOriginalSeriesOwners()
+    }
+
+    @Transactional(readOnly = true)
+    fun getSettlementDetails(
+        startDateStr: String,
+        endDateStr: String,
+        creatorId: Long,
+        offset: Long,
+        limit: Long
+    ): GetAdminOriginalSeriesSettlementDetailListResponse {
+        val (startDate, endDate) = toDateRange(startDateStr, endDateStr)
+        val totalCount = repository.getSettlementDetailTotalCount(startDate, endDate, creatorId)
+        val items = repository
+            .getSettlementDetails(startDate, endDate, creatorId, offset, limit)
+            .map { it.toResponse() }
+
+        return GetAdminOriginalSeriesSettlementDetailListResponse(totalCount, items)
+    }
+
+    @Transactional(readOnly = true)
+    fun downloadSettlementDetailsExcel(startDateStr: String, endDateStr: String): StreamingResponseBody {
+        val (startDate, endDate) = toDateRange(startDateStr, endDateStr)
+        val owners = repository.getOriginalSeriesOwners()
+
+        return StreamingResponseBody { outputStream ->
+            val workbook = SXSSFWorkbook(100)
+            try {
+                if (owners.isNotEmpty()) {
+                    owners.forEach { owner ->
+                        val sheet = workbook.createSheet(toSheetName(owner))
+                        writeHeaders(sheet)
+
+                        val totalCount = repository.getSettlementDetailTotalCount(startDate, endDate, owner.creatorId)
+                        val items = if (totalCount == 0) {
+                            emptyList()
+                        } else {
+                            repository.getSettlementDetails(startDate, endDate, owner.creatorId, 0L, totalCount.toLong())
+                                .map { it.toResponse() }
+                        }
+
+                        writeRows(sheet, items)
+                    }
+                }
+
+                workbook.write(outputStream)
+                outputStream.flush()
+            } finally {
+                workbook.dispose()
+                workbook.close()
+            }
+        }
+    }
+
+    private fun writeHeaders(sheet: Sheet) {
+        val headerRow = sheet.createRow(0)
+        EXCEL_HEADERS.forEachIndexed { index, value ->
+            headerRow.createCell(index).setCellValue(value)
+        }
+    }
+
+    private fun writeRows(sheet: Sheet, items: List<GetAdminOriginalSeriesSettlementDetailResponse>) {
+        items.forEachIndexed { index, item ->
+            val row = sheet.createRow(index + 1)
+            row.createCell(0).setCellValue(item.seriesTitle)
+            row.createCell(1).setCellValue(item.contentTitle)
+            row.createCell(2).setCellValue(item.price.toDouble())
+            row.createCell(3).setCellValue(item.orderType)
+            row.createCell(4).setCellValue(item.salesCount.toDouble())
+            row.createCell(5).setCellValue(item.totalCan.toDouble())
+            row.createCell(6).setCellValue(item.totalPoint.toDouble())
+        }
+    }
+
+    private fun toSheetName(owner: GetAdminOriginalSeriesOwnerResponse): String {
+        return WorkbookUtil.createSafeSheetName(owner.nickname)
+    }
+
+    private fun toDateRange(startDateStr: String, endDateStr: String): Pair<LocalDateTime, LocalDateTime> {
+        val startDate = startDateStr.convertLocalDateTime()
+        val endDate = endDateStr.convertLocalDateTime(hour = 23, minute = 59, second = 59)
+
+        return startDate to endDate
+    }
+
+    companion object {
+        private val EXCEL_HEADERS = listOf(
+            "시리즈 제목",
+            "콘텐츠 제목",
+            "가격(캔)",
+            "구분",
+            "판매 수",
+            "합계(캔)",
+            "합계(포인트)"
+        )
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/originalSeries/GetAdminOriginalSeriesOwnerResponse.kt

@@ -0,0 +1,9 @@
+package kr.co.vividnext.sodalive.admin.calculate.originalSeries
+
+import com.fasterxml.jackson.annotation.JsonProperty
+import com.querydsl.core.annotations.QueryProjection
+
+data class GetAdminOriginalSeriesOwnerResponse @QueryProjection constructor(
+    @JsonProperty("creatorId") val creatorId: Long,
+    @JsonProperty("nickname") val nickname: String
+)

src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/originalSeries/GetAdminOriginalSeriesSettlementDetailQueryData.kt

@@ -0,0 +1,27 @@
+package kr.co.vividnext.sodalive.admin.calculate.originalSeries
+
+import com.querydsl.core.annotations.QueryProjection
+import kr.co.vividnext.sodalive.content.order.OrderType
+import kotlin.math.ceil
+
+data class GetAdminOriginalSeriesSettlementDetailQueryData @QueryProjection constructor(
+    val seriesTitle: String,
+    val contentTitle: String,
+    val basePrice: Int,
+    val orderType: OrderType,
+    val salesCount: Long,
+    val totalCan: Int?,
+    val totalPoint: Int?
+) {
+    fun toResponse(): GetAdminOriginalSeriesSettlementDetailResponse {
+        return GetAdminOriginalSeriesSettlementDetailResponse(
+            seriesTitle = seriesTitle,
+            contentTitle = contentTitle,
+            price = if (orderType == OrderType.RENTAL) ceil(basePrice * 0.7).toInt() else basePrice,
+            orderType = if (orderType == OrderType.RENTAL) "대여" else "소장",
+            salesCount = salesCount.toInt(),
+            totalCan = totalCan ?: 0,
+            totalPoint = totalPoint ?: 0
+        )
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/originalSeries/GetAdminOriginalSeriesSettlementDetailResponse.kt

@@ -0,0 +1,18 @@
+package kr.co.vividnext.sodalive.admin.calculate.originalSeries
+
+import com.fasterxml.jackson.annotation.JsonProperty
+
+data class GetAdminOriginalSeriesSettlementDetailResponse(
+    @JsonProperty("seriesTitle") val seriesTitle: String,
+    @JsonProperty("contentTitle") val contentTitle: String,
+    @JsonProperty("price") val price: Int,
+    @JsonProperty("orderType") val orderType: String,
+    @JsonProperty("salesCount") val salesCount: Int,
+    @JsonProperty("totalCan") val totalCan: Int,
+    @JsonProperty("totalPoint") val totalPoint: Int
+)
+
+data class GetAdminOriginalSeriesSettlementDetailListResponse(
+    @JsonProperty("totalCount") val totalCount: Int,
+    @JsonProperty("items") val items: List<GetAdminOriginalSeriesSettlementDetailResponse>
+)

src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/AdminChatBannerController.kt

@@ -62,7 +62,13 @@ class AdminChatBannerController(
         val banners = bannerService.getActiveBanners(pageable)
         val response = ChatCharacterBannerListPageResponse(
             totalCount = banners.totalElements,
-            content = banners.content.map { ChatCharacterBannerResponse.from(it, imageHost) }
+            content = banners.content.map {
+                ChatCharacterBannerResponse.from(
+                    banner = it,
+                    imageHost = imageHost,
+                    appendLanguageToCharacterName = true
+                )
+            }
         )
 
         ApiResponse.ok(response)

src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/dto/ChatCharacterBannerResponse.kt

@@ -1,6 +1,7 @@
 package kr.co.vividnext.sodalive.admin.chat.dto
 
 import kr.co.vividnext.sodalive.chat.character.ChatCharacterBanner
+import kr.co.vividnext.sodalive.i18n.Lang
 
 /**
  * 캐릭터 배너 응답 DTO
@@ -12,14 +13,30 @@ data class ChatCharacterBannerResponse(
     val characterName: String
 ) {
     companion object {
-        fun from(banner: ChatCharacterBanner, imageHost: String): ChatCharacterBannerResponse {
+        fun from(
+            banner: ChatCharacterBanner,
+            imageHost: String,
+            appendLanguageToCharacterName: Boolean = false
+        ): ChatCharacterBannerResponse {
             return ChatCharacterBannerResponse(
                 id = banner.id!!,
                 imagePath = "$imageHost/${banner.imagePath}",
                 characterId = banner.chatCharacter.id!!,
-                characterName = banner.chatCharacter.name
+                characterName = if (appendLanguageToCharacterName) {
+                    "${banner.chatCharacter.name} (${getLanguageLabel(banner.lang)})"
+                } else {
+                    banner.chatCharacter.name
+                }
             )
         }
+
+        private fun getLanguageLabel(lang: Lang): String {
+            return when (lang) {
+                Lang.KO -> "한국어"
+                Lang.EN -> "영어"
+                Lang.JA -> "일본어"
+            }
+        }
     }
 }
 

src/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentController.kt

@@ -13,10 +13,10 @@ import org.springframework.web.bind.annotation.RestController
 import org.springframework.web.multipart.MultipartFile
 
 @RestController
-@PreAuthorize("hasRole('ADMIN')")
 @RequestMapping("/admin/audio-content")
 class AdminContentController(private val service: AdminContentService) {
     @GetMapping("/list")
+    @PreAuthorize("hasAnyRole('ADMIN', 'CONTENT_MANAGER')")
     fun getAudioContentList(
         @RequestParam(value = "status", required = false) status: ContentReleaseStatus?,
         pageable: Pageable
@@ -28,6 +28,7 @@ class AdminContentController(private val service: AdminContentService) {
     )
 
     @GetMapping("/search")
+    @PreAuthorize("hasAnyRole('ADMIN', 'CONTENT_MANAGER')")
     fun searchAudioContent(
         @RequestParam(value = "status", required = false) status: ContentReleaseStatus?,
         @RequestParam(value = "search_word") searchWord: String,
@@ -41,12 +42,14 @@ class AdminContentController(private val service: AdminContentService) {
     )
 
     @PutMapping(consumes = [MediaType.MULTIPART_FORM_DATA_VALUE])
+    @PreAuthorize("hasRole('ADMIN')")
     fun modifyAudioContent(
         @RequestPart("request") requestString: String,
         @RequestPart("coverImage", required = false) coverImage: MultipartFile? = null
     ) = ApiResponse.ok(service.updateAudioContent(coverImage, requestString))
 
     @GetMapping("/main/tab")
+    @PreAuthorize("hasAnyRole('ADMIN', 'CONTENT_MANAGER')")
     fun getContentMainTabList() = ApiResponse.ok(service.getContentMainTabList())
 }
 

src/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentRepository.kt

@@ -110,6 +110,7 @@ class AdminAudioContentQueryRepositoryImpl(
                     audioContentTheme.theme,
                     audioContentTheme.id,
                     audioContent.price,
+                    audioContent.settlementRatio,
                     audioContent.limited,
                     audioContent.remaining,
                     audioContent.isAdult,

src/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentService.kt

@@ -93,7 +93,8 @@ class AdminContentService(
 
     @Transactional
     fun updateAudioContent(coverImage: MultipartFile?, requestString: String) {
-        val request = objectMapper.readValue(requestString, UpdateAdminContentRequest::class.java)
+        val requestNode = objectMapper.readTree(requestString)
+        val request = objectMapper.treeToValue(requestNode, UpdateAdminContentRequest::class.java)
         val audioContent = repository.findByIdOrNull(id = request.id)
             ?: throw SodaException(messageKey = "admin.content.not_found")
 
@@ -145,6 +146,18 @@ class AdminContentService(
             val theme = themeRepository.findByIdAndActive(id = request.themeId)
             audioContent.theme = theme
         }
+
+        if (request.isSettlementRatioDeleted == true) {
+            if (requestNode.has("settlementRatio")) {
+                throw SodaException(messageKey = "common.error.invalid_request")
+            }
+            audioContent.settlementRatio = null
+        } else if (request.settlementRatio != null) {
+            if (request.settlementRatio !in 0..100) {
+                throw SodaException(messageKey = "common.error.invalid_request")
+            }
+            audioContent.settlementRatio = request.settlementRatio
+        }
     }
 
     fun getContentMainTabList(): List<GetContentMainTabItem> {

src/main/kotlin/kr/co/vividnext/sodalive/admin/content/GetAdminContentListResponse.kt

@@ -18,6 +18,7 @@ data class GetAdminContentListItem @QueryProjection constructor(
     val theme: String,
     val themeId: Long,
     val price: Int,
+    val settlementRatio: Int?,
     val totalContentCount: Int?,
     val remainingContentCount: Int?,
     val isAdult: Boolean,

src/main/kotlin/kr/co/vividnext/sodalive/admin/content/UpdateAdminContentRequest.kt

@@ -7,6 +7,8 @@ data class UpdateAdminContentRequest(
     val detail: String?,
     val curationId: Long?,
     val themeId: Long?,
+    val settlementRatio: Int?,
+    val isSettlementRatioDeleted: Boolean?,
     val isAdult: Boolean?,
     val isActive: Boolean?,
     val isCommentAvailable: Boolean?

src/main/kotlin/kr/co/vividnext/sodalive/admin/content/banner/AdminContentBannerService.kt

@@ -72,7 +72,7 @@ class AdminContentBannerService(
             null
         }
 
-        val audioContentBanner = AudioContentBanner(type = request.type)
+        val audioContentBanner = AudioContentBanner(type = request.type, lang = request.lang)
         audioContentBanner.link = request.link
         audioContentBanner.isAdult = request.isAdult
         audioContentBanner.event = event

src/main/kotlin/kr/co/vividnext/sodalive/admin/content/banner/CreateContentBannerRequest.kt

@@ -1,9 +1,11 @@
 package kr.co.vividnext.sodalive.admin.content.banner
 
 import kr.co.vividnext.sodalive.content.main.banner.AudioContentBannerType
+import kr.co.vividnext.sodalive.i18n.Lang
 
 data class CreateContentBannerRequest(
     val type: AudioContentBannerType,
+    val lang: Lang,
     val tabId: Long?,
     val eventId: Long?,
     val creatorId: Long?,

src/main/kotlin/kr/co/vividnext/sodalive/admin/content/series/banner/AdminContentSeriesBannerController.kt

@@ -56,7 +56,9 @@ class AdminContentSeriesBannerController(
         val banners = bannerService.getActiveBanners(pageable)
         val response = SeriesBannerListPageResponse(
             totalCount = banners.totalElements,
-            content = banners.content.map { SeriesBannerResponse.from(it, imageHost) }
+            content = banners.content.map {
+                SeriesBannerResponse.from(it, imageHost, appendLanguageToSeriesTitle = true)
+            }
         )
         ApiResponse.ok(response)
     }
@@ -82,7 +84,7 @@ class AdminContentSeriesBannerController(
         val objectMapper = ObjectMapper()
         val request = objectMapper.readValue(requestString, SeriesBannerRegisterRequest::class.java)
 
-        val banner = bannerService.registerBanner(seriesId = request.seriesId, imagePath = "")
+        val banner = bannerService.registerBanner(seriesId = request.seriesId, imagePath = "", lang = request.lang)
         val imagePath = saveImage(banner.id!!, image)
         val updatedBanner = bannerService.updateBanner(banner.id!!, imagePath)
         val response = SeriesBannerResponse.from(updatedBanner, imageHost)

src/main/kotlin/kr/co/vividnext/sodalive/admin/content/series/banner/dto/SeriesBannerDtos.kt

@@ -2,10 +2,12 @@ package kr.co.vividnext.sodalive.admin.content.series.banner.dto
 
 import com.fasterxml.jackson.annotation.JsonProperty
 import kr.co.vividnext.sodalive.content.series.main.banner.SeriesBanner
+import kr.co.vividnext.sodalive.i18n.Lang
 
 // 시리즈 배너 등록 요청 DTO
 data class SeriesBannerRegisterRequest(
-    @JsonProperty("seriesId") val seriesId: Long
+    @JsonProperty("seriesId") val seriesId: Long,
+    @JsonProperty("lang") val lang: Lang? = null
 )
 
 // 시리즈 배너 수정 요청 DTO
@@ -22,14 +24,30 @@ data class SeriesBannerResponse(
     val seriesTitle: String
 ) {
     companion object {
-        fun from(banner: SeriesBanner, imageHost: String): SeriesBannerResponse {
+        fun from(
+            banner: SeriesBanner,
+            imageHost: String,
+            appendLanguageToSeriesTitle: Boolean = false
+        ): SeriesBannerResponse {
             return SeriesBannerResponse(
                 id = banner.id!!,
                 imagePath = "$imageHost/${banner.imagePath}",
                 seriesId = banner.series.id!!,
-                seriesTitle = banner.series.title
+                seriesTitle = if (appendLanguageToSeriesTitle) {
+                    "${banner.series.title} (${getLanguageLabel(banner.lang)})"
+                } else {
+                    banner.series.title
+                }
             )
         }
+
+        private fun getLanguageLabel(lang: Lang): String {
+            return when (lang) {
+                Lang.KO -> "한국어"
+                Lang.EN -> "영어"
+                Lang.JA -> "일본어"
+            }
+        }
     }
 }
 

src/main/kotlin/kr/co/vividnext/sodalive/admin/live/AdminLiveController.kt

@@ -39,9 +39,10 @@ class AdminLiveController(private val service: AdminLiveService) {
         @RequestParam("creator_id") creatorId: Long,
         @RequestParam("start_date") startDate: String,
         @RequestParam("end_date") endDate: String,
-        @RequestParam("is_adult") isAdult: Boolean
+        @RequestParam("is_adult") isAdult: Boolean,
+        @RequestParam("lang") lang: String
     ) = ApiResponse.ok(
-        service.createRecommendCreatorBanner(image, creatorId, startDate, endDate, isAdult),
+        service.createRecommendCreatorBanner(image, creatorId, startDate, endDate, isAdult, lang),
         "등록되었습니다."
     )
 

src/main/kotlin/kr/co/vividnext/sodalive/admin/live/AdminLiveService.kt

@@ -17,6 +17,7 @@ import kr.co.vividnext.sodalive.fcm.FcmDeepLinkValue
 import kr.co.vividnext.sodalive.fcm.FcmEvent
 import kr.co.vividnext.sodalive.fcm.FcmEventType
 import kr.co.vividnext.sodalive.fcm.notification.PushNotificationCategory
+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.i18n.LangContext
 import kr.co.vividnext.sodalive.i18n.SodaMessageSource
 import kr.co.vividnext.sodalive.live.recommend.RecommendLiveCreatorBanner
@@ -122,7 +123,8 @@ class AdminLiveService(
         creatorId: Long,
         startDateString: String,
         endDateString: String,
-        isAdult: Boolean
+        isAdult: Boolean,
+        lang: String
     ): Long {
         if (creatorId < 1) throw SodaException(messageKey = "admin.live.creator_required")
 
@@ -150,10 +152,17 @@ class AdminLiveService(
         if (endDate < nowDate) throw SodaException(messageKey = "admin.live.end_after_now")
         if (endDate <= startDate) throw SodaException(messageKey = "admin.live.start_before_end")
 
+        val bannerLang = try {
+            Lang.fromCode(lang)
+        } catch (_: IllegalArgumentException) {
+            throw SodaException(messageKey = "common.error.invalid_request")
+        }
+
         val recommendCreatorBanner = RecommendLiveCreatorBanner(
             startDate = startDate,
             endDate = endDate,
-            isAdult = isAdult
+            isAdult = isAdult,
+            lang = bannerLang
         )
         recommendCreatorBanner.creator = creator
         recommendCreatorBannerRepository.save(recommendCreatorBanner)

src/main/kotlin/kr/co/vividnext/sodalive/admin/member/AdminMemberLoginController.kt

@@ -0,0 +1,15 @@
+package kr.co.vividnext.sodalive.admin.member
+
+import kr.co.vividnext.sodalive.common.ApiResponse
+import kr.co.vividnext.sodalive.member.login.LoginRequest
+import org.springframework.web.bind.annotation.PostMapping
+import org.springframework.web.bind.annotation.RequestBody
+import org.springframework.web.bind.annotation.RequestMapping
+import org.springframework.web.bind.annotation.RestController
+
+@RestController
+@RequestMapping("/admin/member")
+class AdminMemberLoginController(private val service: AdminMemberLoginService) {
+    @PostMapping("/login")
+    fun login(@RequestBody request: LoginRequest) = ApiResponse.ok(service.login(request))
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/member/AdminMemberLoginResponse.kt

@@ -0,0 +1,8 @@
+package kr.co.vividnext.sodalive.admin.member
+
+import kr.co.vividnext.sodalive.member.MemberRole
+
+data class AdminMemberLoginResponse(
+    val token: String,
+    val role: MemberRole
+)

src/main/kotlin/kr/co/vividnext/sodalive/admin/member/AdminMemberLoginService.kt

@@ -0,0 +1,39 @@
+package kr.co.vividnext.sodalive.admin.member
+
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.jwt.TokenProvider
+import kr.co.vividnext.sodalive.member.MemberAdapter
+import kr.co.vividnext.sodalive.member.MemberRole
+import kr.co.vividnext.sodalive.member.login.LoginRequest
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
+import org.springframework.security.crypto.password.PasswordEncoder
+import org.springframework.stereotype.Service
+
+@Service
+class AdminMemberLoginService(
+    private val repository: AdminMemberRepository,
+    private val passwordEncoder: PasswordEncoder,
+    private val tokenProvider: TokenProvider
+) {
+    fun login(request: LoginRequest): AdminMemberLoginResponse {
+        val member = repository.findByEmail(request.email)
+            ?: throw SodaException(messageKey = "common.error.bad_credentials")
+
+        if (member.role != MemberRole.ADMIN && member.role != MemberRole.CONTENT_MANAGER) {
+            throw SodaException(messageKey = "common.error.bad_credentials")
+        }
+
+        if (!member.isActive || !passwordEncoder.matches(request.password, member.password)) {
+            throw SodaException(messageKey = "common.error.bad_credentials")
+        }
+
+        val authentication = UsernamePasswordAuthenticationToken(
+            MemberAdapter(member),
+            null,
+            MemberAdapter(member).authorities
+        )
+        val token = tokenProvider.createToken(authentication = authentication, memberId = member.id!!)
+
+        return AdminMemberLoginResponse(token = token, role = member.role)
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/member/AdminMemberRepository.kt

@@ -6,7 +6,9 @@ import kr.co.vividnext.sodalive.member.MemberRole
 import kr.co.vividnext.sodalive.member.QMember.member
 import org.springframework.data.jpa.repository.JpaRepository
 
-interface AdminMemberRepository : JpaRepository<Member, Long>, AdminMemberQueryRepository
+interface AdminMemberRepository : JpaRepository<Member, Long>, AdminMemberQueryRepository {
+    fun findByEmail(email: String?): Member?
+}
 
 interface AdminMemberQueryRepository {
     fun getMemberTotalCount(role: MemberRole? = null): Int

src/main/kotlin/kr/co/vividnext/sodalive/admin/member/AdminMemberService.kt

@@ -101,6 +101,10 @@ class AdminMemberService(
                     MemberRole.CREATOR -> messageSource.getMessage("admin.member.role.creator", langContext.lang).orEmpty()
                     MemberRole.AGENT -> messageSource.getMessage("admin.member.role.agent", langContext.lang).orEmpty()
                     MemberRole.BOT -> messageSource.getMessage("admin.member.role.bot", langContext.lang).orEmpty()
+                    MemberRole.CONTENT_MANAGER ->
+                        messageSource
+                            .getMessage("admin.member.role.content_manager", langContext.lang)
+                            .orEmpty()
                 }
 
                 val loginType = when (it.provider) {

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorController.kt

@@ -0,0 +1,21 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.assignment
+
+import kr.co.vividnext.sodalive.common.ApiResponse
+import kr.co.vividnext.sodalive.partner.agent.assignment.AssignAgentCreatorRequest
+import kr.co.vividnext.sodalive.partner.agent.assignment.RemoveAgentCreatorRequest
+import org.springframework.security.access.prepost.PreAuthorize
+import org.springframework.web.bind.annotation.PostMapping
+import org.springframework.web.bind.annotation.RequestBody
+import org.springframework.web.bind.annotation.RequestMapping
+import org.springframework.web.bind.annotation.RestController
+
+@RestController
+@PreAuthorize("hasRole('ADMIN')")
+@RequestMapping("/admin/partner/agent/assignment")
+class AdminAgentCreatorController(private val service: AdminAgentCreatorService) {
+    @PostMapping
+    fun assignCreator(@RequestBody request: AssignAgentCreatorRequest) = ApiResponse.ok(service.assignCreator(request))
+
+    @PostMapping("/remove")
+    fun removeCreator(@RequestBody request: RemoveAgentCreatorRequest) = ApiResponse.ok(service.removeCreator(request))
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/assignment/AdminAgentCreatorService.kt

@@ -0,0 +1,90 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.assignment
+
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.extensions.convertToUtc
+import kr.co.vividnext.sodalive.member.MemberRepository
+import kr.co.vividnext.sodalive.member.MemberRole
+import kr.co.vividnext.sodalive.partner.agent.assignment.AgentCreatorRelation
+import kr.co.vividnext.sodalive.partner.agent.assignment.AgentCreatorRelationRepository
+import kr.co.vividnext.sodalive.partner.agent.assignment.AssignAgentCreatorRequest
+import kr.co.vividnext.sodalive.partner.agent.assignment.RemoveAgentCreatorRequest
+import org.springframework.dao.DataIntegrityViolationException
+import org.springframework.data.repository.findByIdOrNull
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+import java.time.LocalDateTime
+
+@Service
+class AdminAgentCreatorService(
+    private val relationRepository: AgentCreatorRelationRepository,
+    private val memberRepository: MemberRepository
+) {
+    @Transactional
+    fun assignCreator(request: AssignAgentCreatorRequest) {
+        if (request.agentId == request.creatorId) {
+            throw SodaException(messageKey = "partner.agent.assignment.invalid_relation")
+        }
+
+        val agent = memberRepository.findByIdOrNull(request.agentId)
+            ?: throw SodaException(messageKey = "partner.agent.assignment.agent_not_found")
+        if (agent.role != MemberRole.AGENT) {
+            throw SodaException(messageKey = "partner.agent.assignment.invalid_agent")
+        }
+
+        val creator = memberRepository.findByIdForUpdate(request.creatorId)
+            ?: throw SodaException(messageKey = "partner.agent.assignment.creator_not_found")
+        if (creator.role != MemberRole.CREATOR) {
+            throw SodaException(messageKey = "partner.agent.assignment.invalid_creator")
+        }
+
+        val existingRelations = relationRepository.findAllByCreatorIdOrderByAssignedAtAsc(request.creatorId)
+        val assignedAt = request.assignedAt.convertToUtc()
+        if (hasAssignmentOverlap(existingRelations, assignedAt)) {
+            throw SodaException(messageKey = "partner.agent.assignment.assignment_overlap")
+        }
+
+        val relation = AgentCreatorRelation()
+        relation.agent = agent
+        relation.creator = creator
+        relation.assignedAt = assignedAt
+        try {
+            relationRepository.saveAndFlush(relation)
+        } catch (e: DataIntegrityViolationException) {
+            relationRepository.findFirstByCreatorIdAndUnassignedAtIsNull(request.creatorId)
+                ?: throw e
+            throw SodaException(messageKey = "partner.agent.assignment.assignment_overlap")
+        }
+    }
+
+    @Transactional
+    fun removeCreator(request: RemoveAgentCreatorRequest) {
+        val creator = memberRepository.findByIdForUpdate(request.creatorId)
+            ?: throw SodaException(messageKey = "partner.agent.assignment.creator_not_found")
+        if (creator.role != MemberRole.CREATOR) {
+            throw SodaException(messageKey = "partner.agent.assignment.invalid_creator")
+        }
+
+        val relation = relationRepository.findFirstByCreatorIdAndUnassignedAtIsNull(request.creatorId)
+            ?: throw SodaException(messageKey = "partner.agent.assignment.not_found")
+
+        val assignedAt = relation.assignedAt
+            ?: throw SodaException(messageKey = "partner.agent.assignment.not_found")
+        val unassignedAt = request.unassignedAt.convertToUtc()
+        if (!unassignedAt.isAfter(assignedAt)) {
+            throw SodaException(messageKey = "partner.agent.assignment.invalid_unassigned_at")
+        }
+
+        relation.unassignedAt = unassignedAt
+        relationRepository.save(relation)
+    }
+
+    private fun hasAssignmentOverlap(
+        existingRelations: List<AgentCreatorRelation>,
+        assignedAt: LocalDateTime
+    ): Boolean {
+        return existingRelations.any { relation ->
+            val existingUnassignedAt = relation.unassignedAt
+            existingUnassignedAt == null || assignedAt.isBefore(existingUnassignedAt)
+        }
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioController.kt

@@ -0,0 +1,32 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.ratio
+
+import kr.co.vividnext.sodalive.common.ApiResponse
+import kr.co.vividnext.sodalive.partner.agent.ratio.CreateAgentSettlementRatioRequest
+import org.springframework.data.domain.Pageable
+import org.springframework.security.access.prepost.PreAuthorize
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.PostMapping
+import org.springframework.web.bind.annotation.RequestBody
+import org.springframework.web.bind.annotation.RequestMapping
+import org.springframework.web.bind.annotation.RestController
+
+@RestController
+@PreAuthorize("hasRole('ADMIN')")
+@RequestMapping("/admin/partner/agent/ratio")
+class AdminAgentSettlementRatioController(private val service: AdminAgentSettlementRatioService) {
+    @PostMapping
+    fun createAgentSettlementRatio(@RequestBody request: CreateAgentSettlementRatioRequest) =
+        ApiResponse.ok(service.createAgentSettlementRatio(request))
+
+    @PostMapping("/update")
+    fun updateAgentSettlementRatio(@RequestBody request: CreateAgentSettlementRatioRequest) =
+        ApiResponse.ok(service.updateAgentSettlementRatio(request))
+
+    @GetMapping
+    fun getAgentSettlementRatio(pageable: Pageable) = ApiResponse.ok(
+        service.getAgentSettlementRatio(
+            offset = pageable.offset,
+            limit = pageable.pageSize.toLong()
+        )
+    )
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/ratio/AdminAgentSettlementRatioService.kt

@@ -0,0 +1,114 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.ratio
+
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.member.MemberRepository
+import kr.co.vividnext.sodalive.member.MemberRole
+import kr.co.vividnext.sodalive.partner.agent.ratio.AgentSettlementRatio
+import kr.co.vividnext.sodalive.partner.agent.ratio.AgentSettlementRatioRepository
+import kr.co.vividnext.sodalive.partner.agent.ratio.CreateAgentSettlementRatioRequest
+import kr.co.vividnext.sodalive.partner.agent.ratio.GetAgentSettlementRatioResponse
+import kr.co.vividnext.sodalive.partner.agent.ratio.toGroupedResponseItems
+import org.springframework.dao.DataIntegrityViolationException
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+import java.time.LocalDateTime
+
+@Service
+class AdminAgentSettlementRatioService(
+    private val repository: AgentSettlementRatioRepository,
+    private val memberRepository: MemberRepository
+) {
+    @Transactional
+    fun createAgentSettlementRatio(request: CreateAgentSettlementRatioRequest) {
+        validateSettlementRatio(request.settlementRatio)
+        val agent = getAgent(request.memberId)
+        closeCurrentRatioIfExists(request)
+        validateClosedHistory(request)
+
+        val ratio = request.toEntity()
+        ratio.member = agent
+        saveRatioOrThrow(ratio)
+    }
+
+    @Transactional
+    fun updateAgentSettlementRatio(request: CreateAgentSettlementRatioRequest) {
+        validateSettlementRatio(request.settlementRatio)
+        val agent = getAgent(request.memberId)
+
+        val existing = repository.findFirstByMemberIdAndEffectiveToIsNull(request.memberId)
+            ?: throw SodaException(messageKey = "partner.agent.ratio.not_found")
+        validateNewEffectiveFrom(existing.effectiveFrom, request.effectiveFrom)
+        existing.close(request.effectiveFrom)
+        repository.saveAndFlush(existing)
+
+        val ratio = request.toEntity()
+        ratio.member = agent
+        saveRatioOrThrow(ratio)
+    }
+
+    @Transactional(readOnly = true)
+    fun getAgentSettlementRatio(offset: Long, limit: Long): GetAgentSettlementRatioResponse {
+        val totalCount = repository.getAgentSettlementRatioTotalCount()
+        val items = repository.getAgentSettlementRatio(offset = offset, limit = limit)
+            .toGroupedResponseItems()
+        return GetAgentSettlementRatioResponse(totalCount = totalCount, items = items)
+    }
+
+    private fun getAgent(memberId: Long) = memberRepository.findByIdForUpdate(memberId)
+        ?.also {
+            if (it.role != MemberRole.AGENT) {
+                throw SodaException(messageKey = "partner.agent.ratio.invalid_agent")
+            }
+        }
+        ?: throw SodaException(messageKey = "partner.agent.ratio.agent_not_found")
+
+    private fun closeCurrentRatioIfExists(request: CreateAgentSettlementRatioRequest) {
+        val existing = repository.findFirstByMemberIdAndEffectiveToIsNull(request.memberId) ?: return
+        validateNewEffectiveFrom(existing.effectiveFrom, request.effectiveFrom)
+        existing.close(request.effectiveFrom)
+        repository.save(existing)
+    }
+
+    private fun validateNewEffectiveFrom(
+        currentEffectiveFrom: LocalDateTime,
+        newEffectiveFrom: LocalDateTime
+    ) {
+        if (!newEffectiveFrom.isAfter(currentEffectiveFrom)) {
+            throw SodaException(messageKey = "partner.agent.ratio.invalid_effective_from")
+        }
+    }
+
+    private fun validateClosedHistory(request: CreateAgentSettlementRatioRequest) {
+        val hasOverlap = repository.findAllByMemberIdOrderByEffectiveFromAsc(request.memberId)
+            .any { history ->
+                val effectiveTo = history.effectiveTo ?: return@any false
+                !request.effectiveFrom.isBefore(history.effectiveFrom) && request.effectiveFrom.isBefore(effectiveTo)
+            }
+        if (hasOverlap) {
+            throw SodaException(messageKey = "partner.agent.ratio.invalid_effective_from")
+        }
+    }
+
+    private fun validateSettlementRatio(settlementRatio: Int) {
+        if (settlementRatio !in 0..100) {
+            throw SodaException(messageKey = "common.error.invalid_request")
+        }
+    }
+
+    private fun saveRatioOrThrow(ratio: AgentSettlementRatio) {
+        try {
+            repository.saveAndFlush(ratio)
+        } catch (e: DataIntegrityViolationException) {
+            if (isActiveRatioConflict(e)) {
+                throw SodaException(messageKey = "partner.agent.ratio.invalid_effective_from")
+            }
+            throw e
+        }
+    }
+
+    private fun isActiveRatioConflict(exception: Throwable): Boolean {
+        return generateSequence(exception) { it.cause }
+            .mapNotNull { it.message }
+            .any { it.contains("uk_agent_settlement_ratio_member_active") }
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/read/AdminAgentReadController.kt

@@ -0,0 +1,127 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.read
+
+import kr.co.vividnext.sodalive.admin.member.AdminSimpleMemberResponse
+import kr.co.vividnext.sodalive.common.ApiResponse
+import org.springframework.data.domain.Pageable
+import org.springframework.security.access.prepost.PreAuthorize
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.PathVariable
+import org.springframework.web.bind.annotation.RequestMapping
+import org.springframework.web.bind.annotation.RequestParam
+import org.springframework.web.bind.annotation.RestController
+
+@RestController
+@PreAuthorize("hasRole('ADMIN')")
+@RequestMapping("/admin/partner/agent")
+class AdminAgentReadController(
+    private val service: AdminAgentReadService
+) {
+    @GetMapping("/list")
+    fun getAgentList(pageable: Pageable) = ApiResponse.ok(
+        service.getAgentList(offset = pageable.offset, limit = pageable.pageSize.toLong())
+    )
+
+    @GetMapping("/creator/search")
+    fun searchAssignableCreators(
+        @RequestParam(value = "search_word") searchWord: String,
+        pageable: Pageable
+    ) = ApiResponse.ok(
+        service.searchAssignableCreators(searchWord = searchWord, offset = pageable.offset, limit = pageable.pageSize.toLong())
+    )
+
+    @GetMapping("/search-by-nickname")
+    fun searchAgentByNickname(
+        @RequestParam(value = "search_word") searchWord: String,
+        @RequestParam(value = "size", required = false) size: Int?
+    ): ApiResponse<List<AdminSimpleMemberResponse>> = ApiResponse.ok(
+        service.searchAgentByNickname(searchWord = searchWord, size = size ?: 20)
+    )
+
+    @GetMapping("/{agentId}/creator/list")
+    fun getAssignedCreators(
+        @PathVariable agentId: Long,
+        pageable: Pageable
+    ) = ApiResponse.ok(
+        service.getAssignedCreators(agentId = agentId, offset = pageable.offset, limit = pageable.pageSize.toLong())
+    )
+
+    @GetMapping("/{agentId}/calculate/live-by-creator")
+    fun getCalculateLiveByCreator(
+        @PathVariable agentId: Long,
+        @RequestParam startDateStr: String,
+        @RequestParam endDateStr: String,
+        pageable: Pageable
+    ) = ApiResponse.ok(
+        service.getCalculateLiveByCreator(
+            agentId,
+            startDateStr,
+            endDateStr,
+            pageable.offset,
+            pageable.pageSize.toLong()
+        )
+    )
+
+    @GetMapping("/{agentId}/calculate/content-by-creator")
+    fun getCalculateContentByCreator(
+        @PathVariable agentId: Long,
+        @RequestParam startDateStr: String,
+        @RequestParam endDateStr: String,
+        pageable: Pageable
+    ) = ApiResponse.ok(
+        service.getCalculateContentByCreator(
+            agentId,
+            startDateStr,
+            endDateStr,
+            pageable.offset,
+            pageable.pageSize.toLong()
+        )
+    )
+
+    @GetMapping("/{agentId}/calculate/community-by-creator")
+    fun getCalculateCommunityByCreator(
+        @PathVariable agentId: Long,
+        @RequestParam startDateStr: String,
+        @RequestParam endDateStr: String,
+        pageable: Pageable
+    ) = ApiResponse.ok(
+        service.getCalculateCommunityByCreator(
+            agentId,
+            startDateStr,
+            endDateStr,
+            pageable.offset,
+            pageable.pageSize.toLong()
+        )
+    )
+
+    @GetMapping("/{agentId}/calculate/channel-donation-by-creator")
+    fun getChannelDonationByCreator(
+        @PathVariable agentId: Long,
+        @RequestParam startDateStr: String,
+        @RequestParam endDateStr: String,
+        pageable: Pageable
+    ) = ApiResponse.ok(
+        service.getChannelDonationByCreator(
+            agentId,
+            startDateStr,
+            endDateStr,
+            pageable.offset,
+            pageable.pageSize.toLong()
+        )
+    )
+
+    @GetMapping("/{agentId}/calculate/content-donation-by-creator")
+    fun getCalculateContentDonationByCreator(
+        @PathVariable agentId: Long,
+        @RequestParam startDateStr: String,
+        @RequestParam endDateStr: String,
+        pageable: Pageable
+    ) = ApiResponse.ok(
+        service.getCalculateContentDonationByCreator(
+            agentId,
+            startDateStr,
+            endDateStr,
+            pageable.offset,
+            pageable.pageSize.toLong()
+        )
+    )
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/read/AdminAgentReadQueryRepository.kt

@@ -0,0 +1,196 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.read
+
+import com.querydsl.core.types.dsl.BooleanExpression
+import com.querydsl.core.types.dsl.Expressions
+import com.querydsl.jpa.impl.JPAQueryFactory
+import kr.co.vividnext.sodalive.admin.member.AdminSimpleMemberResponse
+import kr.co.vividnext.sodalive.admin.member.QAdminSimpleMemberResponse
+import kr.co.vividnext.sodalive.member.MemberRole
+import kr.co.vividnext.sodalive.member.QMember
+import kr.co.vividnext.sodalive.member.QMember.member
+import kr.co.vividnext.sodalive.partner.agent.assignment.QAgentCreatorRelation.agentCreatorRelation
+import kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepository
+import org.springframework.stereotype.Repository
+import java.time.LocalDateTime
+import java.time.ZoneId
+import java.time.ZonedDateTime
+
+@Repository
+class AdminAgentReadQueryRepository(
+    private val queryFactory: JPAQueryFactory,
+    private val calculateQueryRepository: AgentCalculateQueryRepository
+) {
+    private val kstZoneId = ZoneId.of("Asia/Seoul")
+    private val utcZoneId = ZoneId.of("UTC")
+
+    fun getAgentListTotalCount(): Int {
+        return queryFactory
+            .select(member.id.count())
+            .from(member)
+            .where(member.role.eq(MemberRole.AGENT))
+            .fetchOne()
+            ?.toInt()
+            ?: 0
+    }
+
+    fun getAgentList(offset: Long, limit: Long, currentTime: ZonedDateTime): List<GetAdminAgentListItem> {
+        val kstCurrentTime = currentTime.withZoneSameInstant(kstZoneId)
+        val currentMonthStartKst = kstCurrentTime.toLocalDate().withDayOfMonth(1).atStartOfDay(kstZoneId)
+        val nextMonthStartKst = currentMonthStartKst.plusMonths(1)
+        val currentMonthStart = currentMonthStartKst.withZoneSameInstant(utcZoneId).toLocalDateTime()
+        val currentMonthEnd = nextMonthStartKst.withZoneSameInstant(utcZoneId).toLocalDateTime().minusNanos(1)
+
+        return queryFactory
+            .select(
+                QGetAdminAgentListItem(
+                    member.id,
+                    member.nickname,
+                    agentCreatorRelation.id.countDistinct().intValue(),
+                    Expressions.numberTemplate(Int::class.java, "0"),
+                    Expressions.numberTemplate(Int::class.java, "0"),
+                    Expressions.numberTemplate(Int::class.java, "0"),
+                    Expressions.numberTemplate(Int::class.java, "0"),
+                    Expressions.numberTemplate(Int::class.java, "0")
+                )
+            )
+            .from(member)
+            .leftJoin(agentCreatorRelation)
+            .on(
+                agentCreatorRelation.agent.id.eq(member.id)
+                    .and(isActiveAssignment(kstCurrentTime.toLocalDateTime()))
+            )
+            .where(member.role.eq(MemberRole.AGENT))
+            .groupBy(member.id, member.nickname)
+            .orderBy(member.id.desc())
+            .offset(offset)
+            .limit(limit)
+            .fetch()
+            .map { item ->
+                item.copy(
+                    liveAgentSettlementAmount = calculateQueryRepository
+                        .getCalculateLiveByCreatorTotal(currentMonthStart, currentMonthEnd, item.agentId)
+                        .agentSettlementAmount,
+                    contentAgentSettlementAmount = calculateQueryRepository
+                        .getCalculateContentByCreatorTotal(currentMonthStart, currentMonthEnd, item.agentId)
+                        .agentSettlementAmount,
+                    communityAgentSettlementAmount = calculateQueryRepository
+                        .getCalculateCommunityByCreatorTotal(currentMonthStart, currentMonthEnd, item.agentId)
+                        .agentSettlementAmount,
+                    contentDonationAgentSettlementAmount = calculateQueryRepository
+                        .getCalculateContentDonationByCreatorTotal(currentMonthStart, currentMonthEnd, item.agentId)
+                        .agentSettlementAmount,
+                    channelDonationAgentSettlementAmount = calculateQueryRepository
+                        .getChannelDonationByCreatorTotal(currentMonthStart, currentMonthEnd, item.agentId)
+                        .agentSettlementAmount
+                )
+            }
+    }
+
+    fun searchAssignableCreatorsTotalCount(searchWord: String, currentTime: LocalDateTime): Int {
+        return queryFactory
+            .select(member.id.countDistinct())
+            .from(member)
+            .leftJoin(agentCreatorRelation)
+            .on(
+                agentCreatorRelation.creator.id.eq(member.id)
+                    .and(isActiveAssignment(currentTime))
+            )
+            .where(
+                member.role.eq(MemberRole.CREATOR)
+                    .and(member.nickname.contains(searchWord))
+            )
+            .fetchOne()
+            ?.toInt()
+            ?: 0
+    }
+
+    fun searchAssignableCreators(
+        searchWord: String,
+        offset: Long,
+        limit: Long,
+        currentTime: LocalDateTime
+    ): List<SearchAdminAgentAssignableCreatorItem> {
+        val currentAgent = QMember("currentAgent")
+
+        return queryFactory
+            .select(
+                QSearchAdminAgentAssignableCreatorItem(
+                    member.id,
+                    member.nickname,
+                    currentAgent.id,
+                    currentAgent.nickname
+                )
+            )
+            .from(member)
+            .leftJoin(agentCreatorRelation)
+            .on(
+                agentCreatorRelation.creator.id.eq(member.id)
+                    .and(isActiveAssignment(currentTime))
+            )
+            .leftJoin(agentCreatorRelation.agent, currentAgent)
+            .where(
+                member.role.eq(MemberRole.CREATOR)
+                    .and(member.nickname.contains(searchWord))
+            )
+            .orderBy(member.id.desc())
+            .offset(offset)
+            .limit(limit)
+            .fetch()
+    }
+
+    fun searchAgentByNickname(searchWord: String, limit: Long): List<AdminSimpleMemberResponse> {
+        return queryFactory
+            .select(
+                QAdminSimpleMemberResponse(
+                    member.id,
+                    member.nickname
+                )
+            )
+            .from(member)
+            .where(
+                member.role.eq(MemberRole.AGENT)
+                    .and(member.nickname.contains(searchWord))
+                    .and(member.isActive.isTrue)
+            )
+            .orderBy(member.id.desc())
+            .limit(limit)
+            .fetch()
+    }
+
+    fun getAssignedCreatorTotalCount(agentId: Long, currentTime: LocalDateTime): Int {
+        return queryFactory
+            .select(agentCreatorRelation.id.count())
+            .from(agentCreatorRelation)
+            .where(agentCreatorRelation.agent.id.eq(agentId).and(isActiveAssignment(currentTime)))
+            .fetchOne()
+            ?.toInt()
+            ?: 0
+    }
+
+    fun getAssignedCreators(
+        agentId: Long,
+        offset: Long,
+        limit: Long,
+        currentTime: LocalDateTime
+    ): List<GetAdminAgentAssignedCreatorItem> {
+        return queryFactory
+            .select(
+                QGetAdminAgentAssignedCreatorItem(
+                    agentCreatorRelation.creator.id,
+                    agentCreatorRelation.creator.nickname,
+                    agentCreatorRelation.assignedAt
+                )
+            )
+            .from(agentCreatorRelation)
+            .where(agentCreatorRelation.agent.id.eq(agentId).and(isActiveAssignment(currentTime)))
+            .orderBy(agentCreatorRelation.creator.id.desc())
+            .offset(offset)
+            .limit(limit)
+            .fetch()
+    }
+
+    private fun isActiveAssignment(currentTime: LocalDateTime): BooleanExpression {
+        return agentCreatorRelation.assignedAt.loe(currentTime)
+            .and(agentCreatorRelation.unassignedAt.isNull.or(agentCreatorRelation.unassignedAt.gt(currentTime)))
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/read/AdminAgentReadService.kt

@@ -0,0 +1,144 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.read
+
+import kr.co.vividnext.sodalive.admin.member.AdminSimpleMemberResponse
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.member.MemberRepository
+import kr.co.vividnext.sodalive.member.MemberRole
+import kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateService
+import kr.co.vividnext.sodalive.partner.agent.calculate.GetAgentChannelDonationSettlementByCreatorResponse
+import kr.co.vividnext.sodalive.partner.agent.calculate.GetAgentSettlementByCreatorResponse
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+import java.time.LocalDateTime
+import java.time.ZoneId
+import java.time.ZonedDateTime
+
+@Service
+class AdminAgentReadService(
+    private val queryRepository: AdminAgentReadQueryRepository,
+    private val memberRepository: MemberRepository,
+    private val calculateService: AgentCalculateService
+) {
+    private val kstZoneId = ZoneId.of("Asia/Seoul")
+
+    @Transactional(readOnly = true)
+    fun getAgentList(offset: Long, limit: Long): GetAdminAgentListResponse {
+        val now = ZonedDateTime.now(kstZoneId)
+        return GetAdminAgentListResponse(
+            totalCount = queryRepository.getAgentListTotalCount(),
+            items = queryRepository.getAgentList(offset = offset, limit = limit, currentTime = now)
+        )
+    }
+
+    @Transactional(readOnly = true)
+    fun searchAssignableCreators(searchWord: String, offset: Long, limit: Long): SearchAdminAgentAssignableCreatorResponse {
+        if (searchWord.length < 2) throw SodaException(messageKey = "admin.member.search_word_min_length")
+        val now = LocalDateTime.now()
+        return SearchAdminAgentAssignableCreatorResponse(
+            totalCount = queryRepository.searchAssignableCreatorsTotalCount(searchWord = searchWord, currentTime = now),
+            items = queryRepository.searchAssignableCreators(
+                searchWord = searchWord,
+                offset = offset,
+                limit = limit,
+                currentTime = now
+            )
+        )
+    }
+
+    @Transactional(readOnly = true)
+    fun searchAgentByNickname(searchWord: String, size: Int = 20): List<AdminSimpleMemberResponse> {
+        if (searchWord.length < 2) throw SodaException(messageKey = "admin.member.search_word_min_length")
+        val limit = if (size <= 0) 20 else size
+        return queryRepository.searchAgentByNickname(searchWord = searchWord, limit = limit.toLong())
+    }
+
+    @Transactional(readOnly = true)
+    fun getAssignedCreators(agentId: Long, offset: Long, limit: Long): GetAdminAgentAssignedCreatorResponse {
+        validateAgent(agentId)
+        val now = LocalDateTime.now()
+        val items = queryRepository.getAssignedCreators(agentId = agentId, offset = offset, limit = limit, currentTime = now)
+            .map {
+                it.copy(
+                    assignedAt = it.assignedAt
+                        .atZone(ZoneId.of("UTC"))
+                        .withZoneSameInstant(kstZoneId)
+                        .toLocalDateTime()
+                )
+            }
+
+        return GetAdminAgentAssignedCreatorResponse(
+            totalCount = queryRepository.getAssignedCreatorTotalCount(agentId = agentId, currentTime = now),
+            items = items
+        )
+    }
+
+    @Transactional(readOnly = true)
+    fun getCalculateLiveByCreator(
+        agentId: Long,
+        startDateStr: String,
+        endDateStr: String,
+        offset: Long,
+        limit: Long
+    ): GetAgentSettlementByCreatorResponse {
+        validateAgent(agentId)
+        return calculateService.getCalculateLiveByCreator(startDateStr, endDateStr, agentId, offset, limit)
+    }
+
+    @Transactional(readOnly = true)
+    fun getCalculateContentByCreator(
+        agentId: Long,
+        startDateStr: String,
+        endDateStr: String,
+        offset: Long,
+        limit: Long
+    ): GetAgentSettlementByCreatorResponse {
+        validateAgent(agentId)
+        return calculateService.getCalculateContentByCreator(startDateStr, endDateStr, agentId, offset, limit)
+    }
+
+    @Transactional(readOnly = true)
+    fun getCalculateCommunityByCreator(
+        agentId: Long,
+        startDateStr: String,
+        endDateStr: String,
+        offset: Long,
+        limit: Long
+    ): GetAgentSettlementByCreatorResponse {
+        validateAgent(agentId)
+        return calculateService.getCalculateCommunityByCreator(startDateStr, endDateStr, agentId, offset, limit)
+    }
+
+    @Transactional(readOnly = true)
+    fun getCalculateContentDonationByCreator(
+        agentId: Long,
+        startDateStr: String,
+        endDateStr: String,
+        offset: Long,
+        limit: Long
+    ): GetAgentSettlementByCreatorResponse {
+        validateAgent(agentId)
+        return calculateService.getCalculateContentDonationByCreator(startDateStr, endDateStr, agentId, offset, limit)
+    }
+
+    @Transactional(readOnly = true)
+    fun getChannelDonationByCreator(
+        agentId: Long,
+        startDateStr: String,
+        endDateStr: String,
+        offset: Long,
+        limit: Long
+    ): GetAgentChannelDonationSettlementByCreatorResponse {
+        validateAgent(agentId)
+        return calculateService.getChannelDonationByCreator(startDateStr, endDateStr, agentId, offset, limit)
+    }
+
+    private fun validateAgent(agentId: Long) {
+        val member = memberRepository.findById(agentId).orElseThrow {
+            SodaException(messageKey = "partner.agent.ratio.agent_not_found")
+        }
+
+        if (member.role != MemberRole.AGENT) {
+            throw SodaException(messageKey = "partner.agent.ratio.invalid_agent")
+        }
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/read/GetAdminAgentAssignedCreatorResponse.kt

@@ -0,0 +1,15 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.read
+
+import com.querydsl.core.annotations.QueryProjection
+import java.time.LocalDateTime
+
+data class GetAdminAgentAssignedCreatorResponse(
+    val totalCount: Int,
+    val items: List<GetAdminAgentAssignedCreatorItem>
+)
+
+data class GetAdminAgentAssignedCreatorItem @QueryProjection constructor(
+    val creatorId: Long,
+    val creatorNickname: String,
+    val assignedAt: LocalDateTime
+)

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/read/GetAdminAgentListResponse.kt

@@ -0,0 +1,19 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.read
+
+import com.querydsl.core.annotations.QueryProjection
+
+data class GetAdminAgentListResponse(
+    val totalCount: Int,
+    val items: List<GetAdminAgentListItem>
+)
+
+data class GetAdminAgentListItem @QueryProjection constructor(
+    val agentId: Long,
+    val agentNickname: String,
+    val assignedCreatorCount: Int,
+    val liveAgentSettlementAmount: Int = 0,
+    val contentAgentSettlementAmount: Int = 0,
+    val communityAgentSettlementAmount: Int = 0,
+    val contentDonationAgentSettlementAmount: Int = 0,
+    val channelDonationAgentSettlementAmount: Int = 0
+)

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/read/SearchAdminAgentAssignableCreatorResponse.kt

@@ -0,0 +1,15 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.read
+
+import com.querydsl.core.annotations.QueryProjection
+
+data class SearchAdminAgentAssignableCreatorResponse(
+    val totalCount: Int,
+    val items: List<SearchAdminAgentAssignableCreatorItem>
+)
+
+data class SearchAdminAgentAssignableCreatorItem @QueryProjection constructor(
+    val creatorId: Long,
+    val creatorNickname: String,
+    val currentAgentId: Long?,
+    val currentAgentNickname: String?
+)

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotController.kt

@@ -0,0 +1,26 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.settlement
+
+import kr.co.vividnext.sodalive.common.ApiResponse
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.partner.agent.settlement.snapshot.FinalizeAgentSettlementSnapshotRequest
+import org.springframework.security.access.prepost.PreAuthorize
+import org.springframework.security.core.annotation.AuthenticationPrincipal
+import org.springframework.web.bind.annotation.PostMapping
+import org.springframework.web.bind.annotation.RequestBody
+import org.springframework.web.bind.annotation.RequestMapping
+import org.springframework.web.bind.annotation.RestController
+
+@RestController
+@PreAuthorize("hasRole('ADMIN')")
+@RequestMapping("/admin/partner/agent/settlement")
+class AdminAgentSettlementSnapshotController(private val service: AdminAgentSettlementSnapshotService) {
+    @PostMapping("/finalize")
+    fun finalizeSettlement(
+        @RequestBody request: FinalizeAgentSettlementSnapshotRequest,
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?
+    ) = run {
+        val admin = member ?: throw SodaException(messageKey = "common.error.bad_credentials")
+        ApiResponse.ok(service.finalizeSnapshots(request, admin.id!!))
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/admin/partner/agent/settlement/AdminAgentSettlementSnapshotService.kt

@@ -0,0 +1,381 @@
+package kr.co.vividnext.sodalive.admin.partner.agent.settlement
+
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.member.MemberRepository
+import kr.co.vividnext.sodalive.member.MemberRole
+import kr.co.vividnext.sodalive.partner.agent.calculate.AgentCalculateQueryRepository
+import kr.co.vividnext.sodalive.partner.agent.calculate.GetAgentChannelDonationSettlementByCreatorItem
+import kr.co.vividnext.sodalive.partner.agent.calculate.GetAgentChannelDonationSettlementByCreatorQueryData
+import kr.co.vividnext.sodalive.partner.agent.calculate.GetAgentCreatorSettlementSummaryQueryData
+import kr.co.vividnext.sodalive.partner.agent.calculate.GetAgentSettlementByCreatorItem
+import kr.co.vividnext.sodalive.partner.agent.settlement.snapshot.AgentSettlementSnapshot
+import kr.co.vividnext.sodalive.partner.agent.settlement.snapshot.AgentSettlementSnapshotRepository
+import kr.co.vividnext.sodalive.partner.agent.settlement.snapshot.AgentSettlementSnapshotSourceDetail
+import kr.co.vividnext.sodalive.partner.agent.settlement.snapshot.AgentSettlementSnapshotSourceDetailRepository
+import kr.co.vividnext.sodalive.partner.agent.settlement.snapshot.AgentSettlementSnapshotType
+import kr.co.vividnext.sodalive.partner.agent.settlement.snapshot.FinalizeAgentSettlementSnapshotRequest
+import kr.co.vividnext.sodalive.partner.agent.settlement.snapshot.FinalizeAgentSettlementSnapshotResponse
+import org.springframework.data.repository.findByIdOrNull
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+import java.time.LocalDateTime
+
+@Service
+class AdminAgentSettlementSnapshotService(
+    private val snapshotRepository: AgentSettlementSnapshotRepository,
+    private val sourceDetailRepository: AgentSettlementSnapshotSourceDetailRepository,
+    private val calculateRepository: AgentCalculateQueryRepository,
+    private val memberRepository: MemberRepository
+) {
+    private data class SourceDetailDraft(
+        val creatorId: Long,
+        val assignmentId: Long?,
+        val agentSettlementRatioId: Long?,
+        val appliedAgentSettlementRatio: Int?,
+        val count: Int,
+        val totalCan: Int,
+        val krw: Int,
+        val fee: Int,
+        val settlementAmount: Int,
+        val tax: Int,
+        val depositAmount: Int,
+        val agentSettlementAmount: Int
+    )
+
+    private data class SnapshotFinalizeDraft(
+        val snapshots: List<AgentSettlementSnapshot>,
+        val sourceDetailsByCreatorId: Map<Long, List<SourceDetailDraft>>
+    )
+
+    private data class SnapshotAggregateDraft(
+        val creatorId: Long,
+        val creatorNickname: String,
+        var assignmentId: Long? = null,
+        var agentSettlementRatioId: Long? = null,
+        var appliedAgentSettlementRatio: Int? = null,
+        var sourceRowCount: Int = 0,
+        var count: Int = 0,
+        var totalCan: Int = 0,
+        var krw: Int = 0,
+        var fee: Int = 0,
+        var settlementAmount: Int = 0,
+        var tax: Int = 0,
+        var depositAmount: Int = 0,
+        var agentSettlementAmount: Int = 0,
+        val sourceDetails: MutableList<SourceDetailDraft> = mutableListOf()
+    ) {
+        fun add(
+            assignmentId: Long?,
+            agentSettlementRatioId: Long?,
+            appliedAgentSettlementRatio: Int?,
+            count: Int,
+            totalCan: Int,
+            krw: Int,
+            fee: Int,
+            settlementAmount: Int,
+            tax: Int,
+            depositAmount: Int,
+            agentSettlementAmount: Int,
+            sourceDetail: SourceDetailDraft
+        ) {
+            sourceRowCount += 1
+            this.assignmentId = if (sourceRowCount == 1) assignmentId else null
+            this.agentSettlementRatioId = if (sourceRowCount == 1) agentSettlementRatioId else null
+            this.appliedAgentSettlementRatio = if (sourceRowCount == 1) appliedAgentSettlementRatio else null
+            this.count += count
+            this.totalCan += totalCan
+            this.krw += krw
+            this.fee += fee
+            this.settlementAmount += settlementAmount
+            this.tax += tax
+            this.depositAmount += depositAmount
+            this.agentSettlementAmount += agentSettlementAmount
+            sourceDetails.add(sourceDetail)
+        }
+    }
+
+    @Transactional
+    fun finalizeSnapshots(
+        request: FinalizeAgentSettlementSnapshotRequest,
+        finalizedByMemberId: Long
+    ): FinalizeAgentSettlementSnapshotResponse {
+        val (startDate, endDate) = request.toDateRange()
+        if (
+            snapshotRepository.existsByPeriodStartAndPeriodEndAndSettlementTypeAndAgentId(
+                periodStart = startDate,
+                periodEnd = endDate,
+                settlementType = request.settlementType,
+                agentId = request.agentId
+            )
+        ) {
+            return FinalizeAgentSettlementSnapshotResponse(finalizedCount = 0, alreadyFinalized = true)
+        }
+
+        val agent = getAgent(request.agentId)
+        val finalizedAt = LocalDateTime.now()
+
+        val draft = when (request.settlementType) {
+            AgentSettlementSnapshotType.LIVE -> buildGenericSnapshots(
+                request = request,
+                agent = agent,
+                finalizedAt = finalizedAt,
+                finalizedByMemberId = finalizedByMemberId,
+                rows = calculateRepository.getCalculateLiveByCreator(startDate, endDate, request.agentId)
+            )
+
+            AgentSettlementSnapshotType.CONTENT -> buildGenericSnapshots(
+                request = request,
+                agent = agent,
+                finalizedAt = finalizedAt,
+                finalizedByMemberId = finalizedByMemberId,
+                rows = calculateRepository.getCalculateContentByCreator(startDate, endDate, request.agentId)
+            )
+
+            AgentSettlementSnapshotType.COMMUNITY -> buildGenericSnapshots(
+                request = request,
+                agent = agent,
+                finalizedAt = finalizedAt,
+                finalizedByMemberId = finalizedByMemberId,
+                rows = calculateRepository.getCalculateCommunityByCreator(startDate, endDate, request.agentId)
+            )
+
+            AgentSettlementSnapshotType.CONTENT_DONATION -> buildGenericSnapshots(
+                request = request,
+                agent = agent,
+                finalizedAt = finalizedAt,
+                finalizedByMemberId = finalizedByMemberId,
+                rows = calculateRepository.getCalculateContentDonationByCreator(startDate, endDate, request.agentId)
+            )
+
+            AgentSettlementSnapshotType.CHANNEL_DONATION -> buildChannelSnapshots(
+                request = request,
+                agent = agent,
+                finalizedAt = finalizedAt,
+                finalizedByMemberId = finalizedByMemberId,
+                rows = calculateRepository.getChannelDonationByCreator(startDate, endDate, request.agentId)
+            )
+        }
+
+        if (draft.snapshots.isNotEmpty()) {
+            snapshotRepository.saveAll(draft.snapshots)
+            sourceDetailRepository.saveAll(buildSourceDetails(draft))
+        }
+
+        return FinalizeAgentSettlementSnapshotResponse(finalizedCount = draft.snapshots.size, alreadyFinalized = false)
+    }
+
+    private fun getAgent(agentId: Long): Member {
+        val agent = memberRepository.findByIdOrNull(agentId)
+            ?: throw SodaException(messageKey = "partner.agent.ratio.agent_not_found")
+        if (agent.role != MemberRole.AGENT) {
+            throw SodaException(messageKey = "partner.agent.ratio.invalid_agent")
+        }
+        return agent
+    }
+
+    private fun buildGenericSnapshots(
+        request: FinalizeAgentSettlementSnapshotRequest,
+        agent: Member,
+        finalizedAt: LocalDateTime,
+        finalizedByMemberId: Long,
+        rows: List<GetAgentCreatorSettlementSummaryQueryData>
+    ): SnapshotFinalizeDraft {
+        val (startDate, endDate) = request.toDateRange()
+        val aggregateDrafts = linkedMapOf<Long, SnapshotAggregateDraft>()
+
+        rows.forEach { row ->
+            val item = row.toResponseItem()
+            val sourceDetail = item.toSourceDetailDraft(
+                assignmentId = row.assignmentId,
+                agentSettlementRatioId = row.agentSettlementRatioId,
+                appliedAgentSettlementRatio = row.agentSettlementRatio
+            )
+            val aggregate = aggregateDrafts.getOrPut(row.creatorId) {
+                SnapshotAggregateDraft(
+                    creatorId = row.creatorId,
+                    creatorNickname = item.creatorNickname
+                )
+            }
+            aggregate.add(
+                assignmentId = row.assignmentId,
+                agentSettlementRatioId = row.agentSettlementRatioId,
+                appliedAgentSettlementRatio = row.agentSettlementRatio,
+                count = item.count,
+                totalCan = item.totalCan,
+                krw = item.krw,
+                fee = item.fee,
+                settlementAmount = item.settlementAmount,
+                tax = item.tax,
+                depositAmount = item.depositAmount,
+                agentSettlementAmount = item.agentSettlementAmount,
+                sourceDetail = sourceDetail
+            )
+        }
+
+        val snapshots = aggregateDrafts.values.map { aggregate ->
+            AgentSettlementSnapshot(
+                periodStart = startDate,
+                periodEnd = endDate,
+                settlementType = request.settlementType,
+                agentId = agent.id!!,
+                agentNickname = agent.nickname,
+                creatorId = aggregate.creatorId,
+                creatorNickname = aggregate.creatorNickname,
+                assignmentId = aggregate.assignmentId,
+                agentSettlementRatioId = aggregate.agentSettlementRatioId,
+                appliedAgentSettlementRatio = aggregate.appliedAgentSettlementRatio,
+                count = aggregate.count,
+                totalCan = aggregate.totalCan,
+                krw = aggregate.krw,
+                fee = aggregate.fee,
+                settlementAmount = aggregate.settlementAmount,
+                tax = aggregate.tax,
+                depositAmount = aggregate.depositAmount,
+                agentSettlementAmount = aggregate.agentSettlementAmount,
+                finalizedAt = finalizedAt,
+                finalizedByMemberId = finalizedByMemberId
+            )
+        }
+
+        return SnapshotFinalizeDraft(
+            snapshots = snapshots,
+            sourceDetailsByCreatorId = aggregateDrafts.mapValues { (_, aggregate) ->
+                aggregate.sourceDetails.toList()
+            }
+        )
+    }
+
+    private fun buildChannelSnapshots(
+        request: FinalizeAgentSettlementSnapshotRequest,
+        agent: Member,
+        finalizedAt: LocalDateTime,
+        finalizedByMemberId: Long,
+        rows: List<GetAgentChannelDonationSettlementByCreatorQueryData>
+    ): SnapshotFinalizeDraft {
+        val (startDate, endDate) = request.toDateRange()
+        val aggregateDrafts = linkedMapOf<Long, SnapshotAggregateDraft>()
+
+        rows.forEach { row ->
+            val item = row.toResponseItem()
+            val sourceDetail = item.toSourceDetailDraft(
+                assignmentId = row.assignmentId,
+                agentSettlementRatioId = row.agentSettlementRatioId,
+                appliedAgentSettlementRatio = row.agentSettlementRatio
+            )
+            val aggregate = aggregateDrafts.getOrPut(row.creatorId) {
+                SnapshotAggregateDraft(
+                    creatorId = row.creatorId,
+                    creatorNickname = item.creatorNickname
+                )
+            }
+            aggregate.add(
+                assignmentId = row.assignmentId,
+                agentSettlementRatioId = row.agentSettlementRatioId,
+                appliedAgentSettlementRatio = row.agentSettlementRatio,
+                count = item.count,
+                totalCan = item.totalCan,
+                krw = item.krw,
+                fee = item.fee,
+                settlementAmount = item.settlementAmount,
+                tax = item.withholdingTax,
+                depositAmount = item.depositAmount,
+                agentSettlementAmount = item.agentSettlementAmount,
+                sourceDetail = sourceDetail
+            )
+        }
+
+        val snapshots = aggregateDrafts.values.map { aggregate ->
+            AgentSettlementSnapshot(
+                periodStart = startDate,
+                periodEnd = endDate,
+                settlementType = request.settlementType,
+                agentId = agent.id!!,
+                agentNickname = agent.nickname,
+                creatorId = aggregate.creatorId,
+                creatorNickname = aggregate.creatorNickname,
+                assignmentId = aggregate.assignmentId,
+                agentSettlementRatioId = aggregate.agentSettlementRatioId,
+                appliedAgentSettlementRatio = aggregate.appliedAgentSettlementRatio,
+                count = aggregate.count,
+                totalCan = aggregate.totalCan,
+                krw = aggregate.krw,
+                fee = aggregate.fee,
+                settlementAmount = aggregate.settlementAmount,
+                tax = aggregate.tax,
+                depositAmount = aggregate.depositAmount,
+                agentSettlementAmount = aggregate.agentSettlementAmount,
+                finalizedAt = finalizedAt,
+                finalizedByMemberId = finalizedByMemberId
+            )
+        }
+
+        return SnapshotFinalizeDraft(
+            snapshots = snapshots,
+            sourceDetailsByCreatorId = aggregateDrafts.mapValues { (_, aggregate) ->
+                aggregate.sourceDetails.toList()
+            }
+        )
+    }
+
+    private fun buildSourceDetails(draft: SnapshotFinalizeDraft): List<AgentSettlementSnapshotSourceDetail> {
+        val snapshotsByCreatorId = draft.snapshots.associateBy { it.creatorId }
+        return draft.sourceDetailsByCreatorId.flatMap { (creatorId, sourceDetails) ->
+            val snapshot = snapshotsByCreatorId.getValue(creatorId)
+            sourceDetails.map { detail ->
+                AgentSettlementSnapshotSourceDetail(
+                    snapshot = snapshot,
+                    assignmentId = detail.assignmentId,
+                    agentSettlementRatioId = detail.agentSettlementRatioId,
+                    appliedAgentSettlementRatio = detail.appliedAgentSettlementRatio,
+                    count = detail.count,
+                    totalCan = detail.totalCan,
+                    krw = detail.krw,
+                    fee = detail.fee,
+                    settlementAmount = detail.settlementAmount,
+                    tax = detail.tax,
+                    depositAmount = detail.depositAmount,
+                    agentSettlementAmount = detail.agentSettlementAmount
+                )
+            }
+        }
+    }
+
+    private fun GetAgentSettlementByCreatorItem.toSourceDetailDraft(
+        assignmentId: Long?,
+        agentSettlementRatioId: Long?,
+        appliedAgentSettlementRatio: Int?
+    ) = SourceDetailDraft(
+        creatorId = creatorId,
+        assignmentId = assignmentId,
+        agentSettlementRatioId = agentSettlementRatioId,
+        appliedAgentSettlementRatio = appliedAgentSettlementRatio,
+        count = count,
+        totalCan = totalCan,
+        krw = krw,
+        fee = fee,
+        settlementAmount = settlementAmount,
+        tax = tax,
+        depositAmount = depositAmount,
+        agentSettlementAmount = agentSettlementAmount
+    )
+
+    private fun GetAgentChannelDonationSettlementByCreatorItem.toSourceDetailDraft(
+        assignmentId: Long?,
+        agentSettlementRatioId: Long?,
+        appliedAgentSettlementRatio: Int?
+    ) = SourceDetailDraft(
+        creatorId = creatorId,
+        assignmentId = assignmentId,
+        agentSettlementRatioId = agentSettlementRatioId,
+        appliedAgentSettlementRatio = appliedAgentSettlementRatio,
+        count = count,
+        totalCan = totalCan,
+        krw = krw,
+        fee = fee,
+        settlementAmount = settlementAmount,
+        tax = withholdingTax,
+        depositAmount = depositAmount,
+        agentSettlementAmount = agentSettlementAmount
+    )
+}

src/main/kotlin/kr/co/vividnext/sodalive/api/home/HomeService.kt

@@ -124,7 +124,8 @@ class HomeService(
         val bannerList = bannerService.getBannerList(
             tabId = 1,
             memberId = member?.id,
-            isAdult = isAdult
+            isAdult = isAdult,
+            lang = langContext.lang
         )
 
         val originalAudioDramaList = seriesService.getOriginalAudioDramaList(

src/main/kotlin/kr/co/vividnext/sodalive/api/live/LiveApiService.kt

@@ -3,6 +3,7 @@ package kr.co.vividnext.sodalive.api.live
 import kr.co.vividnext.sodalive.content.AudioContentService
 import kr.co.vividnext.sodalive.content.ContentType
 import kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityService
+import kr.co.vividnext.sodalive.i18n.LangContext
 import kr.co.vividnext.sodalive.live.recommend.LiveRecommendService
 import kr.co.vividnext.sodalive.live.room.LiveRoomService
 import kr.co.vividnext.sodalive.live.room.LiveRoomStatus
@@ -20,8 +21,8 @@ class LiveApiService(
     private val recommendService: LiveRecommendService,
     private val creatorCommunityService: CreatorCommunityService,
     private val memberContentPreferenceService: MemberContentPreferenceService,
-
-    private val blockMemberRepository: BlockMemberRepository
+    private val blockMemberRepository: BlockMemberRepository,
+    private val langContext: LangContext
 ) {
     fun fetchData(
         timezone: String,
@@ -49,7 +50,7 @@ class LiveApiService(
             listOf()
         }
 
-        val recommendLiveList = recommendService.getRecommendLive(member)
+        val recommendLiveList = recommendService.getRecommendLive(member, langContext.lang)
 
         val latestFinishedLiveList = liveService.getLatestFinishedLive(member)
 

src/main/kotlin/kr/co/vividnext/sodalive/can/CanController.kt

@@ -17,8 +17,12 @@ class CanController(private val service: CanService) {
     fun getCans(
         @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?
     ): ApiResponse<List<CanResponse>> {
-        val isNotSelectedCurrency = member != null && member.id == 2L
-        return ApiResponse.ok(service.getCans(isNotSelectedCurrency = isNotSelectedCurrency))
+        val forcedCurrency = if (member != null && (member.id == 2L || member.id == 4L || member.id == 44144L)) {
+            "JPY"
+        } else {
+            null
+        }
+        return ApiResponse.ok(service.getCans(forcedCurrency = forcedCurrency))
     }
 
     @GetMapping("/status")

src/main/kotlin/kr/co/vividnext/sodalive/can/CanService.kt

@@ -14,14 +14,10 @@ class CanService(
     private val repository: CanRepository,
     private val countryContext: CountryContext
 ) {
-    fun getCans(isNotSelectedCurrency: Boolean): List<CanResponse> {
-        val currency = if (isNotSelectedCurrency) {
-            null
-        } else {
-            when (countryContext.countryCode) {
-                "KR" -> "KRW"
-                else -> "USD"
-            }
+    fun getCans(forcedCurrency: String? = null): List<CanResponse> {
+        val currency = forcedCurrency ?: when (countryContext.countryCode) {
+            "KR" -> "KRW"
+            else -> "USD"
         }
         return repository.findAllByStatusAndCurrency(status = CanStatus.SALE, currency = currency)
     }

src/main/kotlin/kr/co/vividnext/sodalive/can/charge/ChargeService.kt

@@ -85,6 +85,13 @@ class ChargeService(
     @Value("\${payverse.usd-secret-key}")
     private val payverseUsdSecretKey: String,
 
+    @Value("\${payverse.jpy-mid}")
+    private val payverseJpyMid: String,
+    @Value("\${payverse.jpy-client-key}")
+    private val payverseJpyClientKey: String,
+    @Value("\${payverse.jpy-secret-key}")
+    private val payverseJpySecretKey: String,
+
     @Value("\${payverse.host}")
     private val payverseHost: String,
 
@@ -106,18 +113,18 @@ class ChargeService(
         return when (charge.payment?.status) {
             PaymentStatus.REQUEST -> {
                 // 성공 조건 검증
-                val mid = if (request.requestCurrency == "KRW") {
-                    payverseMid
-                } else {
-                    payverseUsdMid
+                val mid = when (request.requestCurrency) {
+                    "KRW" -> payverseMid
+                    "JPY" -> payverseJpyMid
+                    else -> payverseUsdMid
                 }
                 val expectedSign = DigestUtils.sha512Hex(
                     String.format(
                         "||%s||%s||%s||%s||%s||",
-                        if (request.requestCurrency == "KRW") {
-                            payverseSecretKey
-                        } else {
-                            payverseUsdSecretKey
+                        when (request.requestCurrency) {
+                            "KRW" -> payverseSecretKey
+                            "JPY" -> payverseJpySecretKey
+                            else -> payverseUsdSecretKey
                         },
                         mid,
                         request.orderId,
@@ -126,9 +133,8 @@ class ChargeService(
                     )
                 )
 
-                val isAmountMatch = request.requestAmount.compareTo(
-                    charge.payment!!.price
-                ) == 0
+                val expectedAmount = computePayverseAmount(charge.payment!!.price, request.requestCurrency)
+                val isAmountMatch = request.requestAmount.compareTo(expectedAmount) == 0
 
                 val isSuccess = request.resultStatus == "SUCCESS" &&
                     request.mid == mid &&
@@ -241,21 +247,20 @@ class ChargeService(
             ?: throw SodaException(messageKey = "can.charge.invalid_request_restart")
 
         val requestCurrency = can.currency
-        val isKrw = requestCurrency == "KRW"
-        val mid = if (isKrw) {
-            payverseMid
-        } else {
-            payverseUsdMid
+        val mid = when (requestCurrency) {
+            "KRW" -> payverseMid
+            "JPY" -> payverseJpyMid
+            else -> payverseUsdMid
         }
-        val clientKey = if (isKrw) {
-            payverseClientKey
-        } else {
-            payverseUsdClientKey
+        val clientKey = when (requestCurrency) {
+            "KRW" -> payverseClientKey
+            "JPY" -> payverseJpyClientKey
+            else -> payverseUsdClientKey
         }
-        val secretKey = if (isKrw) {
-            payverseSecretKey
-        } else {
-            payverseUsdSecretKey
+        val secretKey = when (requestCurrency) {
+            "KRW" -> payverseSecretKey
+            "JPY" -> payverseJpySecretKey
+            else -> payverseUsdSecretKey
         }
 
         val charge = Charge(can.can, can.rewardCan)
@@ -270,12 +275,7 @@ class ChargeService(
         val savedCharge = chargeRepository.save(charge)
 
         val chargeId = savedCharge.id!!
-        val amount = BigDecimal(
-            savedCharge.payment!!.price
-                .setScale(4, RoundingMode.HALF_UP)
-                .stripTrailingZeros()
-                .toPlainString()
-        )
+        val amount = computePayverseAmount(savedCharge.payment!!.price, requestCurrency)
         val reqDate = savedCharge.createdAt!!.format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"))
         val sign = DigestUtils.sha512Hex(
             String.format(
@@ -312,16 +312,16 @@ class ChargeService(
         val member = memberRepository.findByIdOrNull(memberId)
             ?: throw SodaException(messageKey = "common.error.bad_credentials")
 
-        val isKrw = charge.can?.currency == "KRW"
-        val mid = if (isKrw) {
-            payverseMid
-        } else {
-            payverseUsdMid
+        val currency = charge.can?.currency
+        val mid = when (currency) {
+            "KRW" -> payverseMid
+            "JPY" -> payverseJpyMid
+            else -> payverseUsdMid
         }
-        val clientKey = if (isKrw) {
-            payverseClientKey
-        } else {
-            payverseUsdClientKey
+        val clientKey = when (currency) {
+            "KRW" -> payverseClientKey
+            "JPY" -> payverseJpyClientKey
+            else -> payverseUsdClientKey
         }
 
         // 결제수단 확인
@@ -351,11 +351,12 @@ class ChargeService(
                     val verifyResponse = objectMapper.readValue(body, PayverseVerifyResponse::class.java)
 
                     val customerId = "${serverEnv}_user_${member.id!!}"
+                    val expectedAmount = computePayverseAmount(charge.can!!.price, charge.can!!.currency)
                     val isSuccess = verifyResponse.resultStatus == "SUCCESS" &&
                         verifyResponse.transactionStatus == "SUCCESS" &&
                         verifyResponse.orderId.toLongOrNull() == charge.id &&
                         verifyResponse.customerId == customerId &&
-                        verifyResponse.requestAmount.compareTo(charge.can!!.price) == 0
+                        verifyResponse.requestAmount.compareTo(expectedAmount) == 0
 
                     if (isSuccess) {
                         // verify 함수의 232~248 라인과 동일 처리
@@ -737,4 +738,16 @@ class ChargeService(
         }
         return messageSource.getMessage("can.charge.payment_method.card", langContext.lang)
     }
+
+    // Payverse 금액 포맷: 통화별 규칙 적용
+    private fun computePayverseAmount(price: BigDecimal, currency: String): BigDecimal {
+        val scaled = if (currency == "JPY") {
+            // JPY: 강제 정수화, 소수점 버림
+            price.setScale(0, RoundingMode.FLOOR)
+        } else {
+            // 그 외: 4자리까지 반올림 후 불필요 0 제거
+            price.setScale(4, RoundingMode.HALF_UP).stripTrailingZeros()
+        }
+        return BigDecimal(scaled.stripTrailingZeros().toPlainString())
+    }
 }

src/main/kotlin/kr/co/vividnext/sodalive/chat/character/controller/ChatCharacterController.kt

@@ -14,8 +14,6 @@ import kr.co.vividnext.sodalive.chat.character.dto.RecentCharacter
 import kr.co.vividnext.sodalive.chat.character.dto.RecentCharactersResponse
 import kr.co.vividnext.sodalive.chat.character.service.ChatCharacterBannerService
 import kr.co.vividnext.sodalive.chat.character.service.ChatCharacterService
-import kr.co.vividnext.sodalive.chat.character.translate.AiCharacterTranslation
-import kr.co.vividnext.sodalive.chat.character.translate.AiCharacterTranslationRenderedPayload
 import kr.co.vividnext.sodalive.chat.character.translate.AiCharacterTranslationRepository
 import kr.co.vividnext.sodalive.chat.character.translate.TranslatedAiCharacterBackground
 import kr.co.vividnext.sodalive.chat.character.translate.TranslatedAiCharacterDetail
@@ -24,8 +22,8 @@ import kr.co.vividnext.sodalive.chat.room.service.ChatRoomService
 import kr.co.vividnext.sodalive.common.ApiResponse
 import kr.co.vividnext.sodalive.common.SodaException
 import kr.co.vividnext.sodalive.i18n.LangContext
-import kr.co.vividnext.sodalive.i18n.translation.PapagoTranslationService
-import kr.co.vividnext.sodalive.i18n.translation.TranslateRequest
+import kr.co.vividnext.sodalive.i18n.translation.LanguageTranslationTargetType
+import kr.co.vividnext.sodalive.i18n.translation.ResourceTranslationJobScheduler
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import org.springframework.beans.factory.annotation.Value
@@ -46,7 +44,7 @@ class ChatCharacterController(
     private val characterCommentService: CharacterCommentService,
     private val curationQueryService: CharacterCurationQueryService,
 
-    private val translationService: PapagoTranslationService,
+    private val resourceTranslationJobScheduler: ResourceTranslationJobScheduler,
     private val aiCharacterTranslationRepository: AiCharacterTranslationRepository,
 
     private val langContext: LangContext,
@@ -212,89 +210,11 @@ class ChatCharacterController(
                     tags = payload.tags
                 )
             } else {
-                val texts = mutableListOf<String>()
-                texts.add(character.name)
-                texts.add(character.description)
-                texts.add(character.gender ?: "")
-
-                val hasPersonality = personality != null
-                if (hasPersonality) {
-                    texts.add(personality!!.trait)
-                    texts.add(personality.description)
-                }
-
-                val hasBackground = background != null
-                if (hasBackground) {
-                    texts.add(background!!.topic)
-                    texts.add(background.description)
-                }
-
-                texts.add(tags)
-
-                val sourceLanguage = character.languageCode ?: "ko"
-
-                val response = translationService.translate(
-                    request = TranslateRequest(
-                        texts = texts,
-                        sourceLanguage = sourceLanguage,
-                        targetLanguage = langContext.lang.code
-                    )
+                resourceTranslationJobScheduler.scheduleResourceTranslation(
+                    resourceType = LanguageTranslationTargetType.CHARACTER,
+                    resourceId = character.id!!,
+                    targetLanguage = langContext.lang.code
                 )
-
-                val translatedTexts = response.translatedText
-                if (translatedTexts.size == texts.size) {
-                    var index = 0
-
-                    val translatedName = translatedTexts[index++]
-                    val translatedDescription = translatedTexts[index++]
-                    val translatedGender = translatedTexts[index++]
-
-                    var translatedPersonality: TranslatedAiCharacterPersonality? = null
-                    if (hasPersonality) {
-                        translatedPersonality = TranslatedAiCharacterPersonality(
-                            trait = translatedTexts[index++],
-                            description = translatedTexts[index++]
-                        )
-                    }
-
-                    var translatedBackground: TranslatedAiCharacterBackground? = null
-                    if (hasBackground) {
-                        translatedBackground = TranslatedAiCharacterBackground(
-                            topic = translatedTexts[index++],
-                            description = translatedTexts[index++]
-                        )
-                    }
-
-                    val translatedTags = translatedTexts[index]
-
-                    val payload = AiCharacterTranslationRenderedPayload(
-                        name = translatedName,
-                        description = translatedDescription,
-                        gender = translatedGender,
-                        personalityTrait = translatedPersonality?.trait ?: "",
-                        personalityDescription = translatedPersonality?.description ?: "",
-                        backgroundTopic = translatedBackground?.topic ?: "",
-                        backgroundDescription = translatedBackground?.description ?: "",
-                        tags = translatedTags
-                    )
-
-                    val entity = AiCharacterTranslation(
-                        characterId = character.id!!,
-                        locale = langContext.lang.code,
-                        renderedPayload = payload
-                    )
-
-                    aiCharacterTranslationRepository.save(entity)
-
-                    translated = TranslatedAiCharacterDetail(
-                        name = translatedName,
-                        description = translatedDescription,
-                        gender = translatedGender,
-                        personality = translatedPersonality,
-                        background = translatedBackground,
-                        tags = translatedTags
-                    )
-                }
             }
         }
 

src/main/kotlin/kr/co/vividnext/sodalive/chat/original/service/OriginalWorkTranslationService.kt

@@ -1,28 +1,22 @@
 package kr.co.vividnext.sodalive.chat.original.service
 
 import kr.co.vividnext.sodalive.chat.original.OriginalWork
-import kr.co.vividnext.sodalive.chat.original.translation.OriginalWorkTranslation
-import kr.co.vividnext.sodalive.chat.original.translation.OriginalWorkTranslationPayload
 import kr.co.vividnext.sodalive.chat.original.translation.OriginalWorkTranslationRepository
 import kr.co.vividnext.sodalive.chat.original.translation.TranslatedOriginalWork
-import kr.co.vividnext.sodalive.i18n.translation.PapagoTranslationService
-import kr.co.vividnext.sodalive.i18n.translation.TranslateRequest
-import org.slf4j.LoggerFactory
+import kr.co.vividnext.sodalive.i18n.translation.LanguageTranslationTargetType
+import kr.co.vividnext.sodalive.i18n.translation.ResourceTranslationJobScheduler
 import org.springframework.stereotype.Service
 import org.springframework.transaction.annotation.Transactional
 
 @Service
 class OriginalWorkTranslationService(
     private val translationRepository: OriginalWorkTranslationRepository,
-    private val papagoTranslationService: PapagoTranslationService
+    private val resourceTranslationJobScheduler: ResourceTranslationJobScheduler
 ) {
-
-    private val log = LoggerFactory.getLogger(javaClass)
-
     /**
      * 원작의 언어와 요청 언어가 다를 때 번역 데이터를 확보하고 반환한다.
      * - 기존 번역이 있으면 그대로 사용
-     * - 없으면 파파고 번역 수행 후 저장
+     * - 없으면 누락 번역 job 예약 후 null 반환
      * - 실패/불필요 시 null 반환
      */
     @Transactional
@@ -55,70 +49,11 @@ class OriginalWorkTranslationService(
             }
         }
 
-        // 파파고 번역 수행
-        return try {
-            val tags = originalWork.tagMappings.map { it.tag.tag }.filter { it.isNotBlank() }
-            val texts = buildList {
-                add(originalWork.title)
-                add(originalWork.contentType)
-                add(originalWork.category)
-                add(originalWork.description)
-                addAll(tags)
-            }
-
-            val response = papagoTranslationService.translate(
-                TranslateRequest(
-                    texts = texts,
-                    sourceLanguage = source,
-                    targetLanguage = target
-                )
-            )
-
-            val out = response.translatedText
-            if (out.isEmpty()) return null
-
-            // 앞 4개는 필드, 나머지는 태그
-            val title = out.getOrNull(0)?.trim().orEmpty()
-            val contentType = out.getOrNull(1)?.trim().orEmpty()
-            val category = out.getOrNull(2)?.trim().orEmpty()
-            val description = out.getOrNull(3)?.trim().orEmpty()
-            val translatedTags = if (out.size > 4) {
-                out.drop(4).map { it.trim() }.filter { it.isNotEmpty() }
-            } else {
-                emptyList()
-            }
-
-            val hasAny = title.isNotEmpty() || contentType.isNotEmpty() ||
-                category.isNotEmpty() || description.isNotEmpty() || translatedTags.isNotEmpty()
-            if (!hasAny) return null
-
-            val payload = OriginalWorkTranslationPayload(
-                title = title,
-                contentType = contentType,
-                category = category,
-                description = description,
-                tags = translatedTags
-            )
-
-            val entity = existed?.apply { this.renderedPayload = payload }
-                ?: OriginalWorkTranslation(
-                    originalWorkId = originalWork.id!!,
-                    locale = target,
-                    renderedPayload = payload
-                )
-
-            translationRepository.save(entity)
-
-            TranslatedOriginalWork(
-                title = title,
-                contentType = contentType,
-                category = category,
-                description = description,
-                tags = translatedTags
-            )
-        } catch (e: Exception) {
-            log.warn("Failed to translate OriginalWork(id={}) from {} to {}: {}", originalWork.id, source, target, e.message)
-            null
-        }
+        resourceTranslationJobScheduler.scheduleResourceTranslation(
+            resourceType = LanguageTranslationTargetType.ORIGINAL_WORK,
+            resourceId = originalWork.id!!,
+            targetLanguage = target
+        )
+        return null
     }
 }

src/main/kotlin/kr/co/vividnext/sodalive/chat/quota/room/ChatRoomQuotaController.kt

@@ -27,7 +27,9 @@ class ChatRoomQuotaController(
 ) {
 
     data class PurchaseRoomQuotaRequest(
-        val container: String
+        val container: String,
+        val chargeType: ChatRoomQuotaChargeType = ChatRoomQuotaChargeType.CAN,
+        val canOption: ChatRoomQuotaCanOption? = null
     )
 
     data class PurchaseRoomQuotaResponse(
@@ -45,8 +47,9 @@ class ChatRoomQuotaController(
     /**
      * 채팅방 유료 쿼터 구매 API
      * - 참여 여부 검증(내가 USER로 참여 중인 활성 방)
-     * - 30캔 결제 (UseCan에 chatRoomId:characterId 기록)
-     * - 방 유료 쿼터 40 충전
+     * - 요청 DTO로 캔 충전 / 광고 충전을 구분
+     * - 캔 충전은 옵션별 캔 차감 후 방 유료 쿼터 지급
+     * - 광고 충전은 캔 차감 없이 방 유료 쿼터 5 지급
      */
     @PostMapping("/{chatRoomId}/quota/purchase")
     fun purchaseRoomQuota(
@@ -74,13 +77,28 @@ class ChatRoomQuotaController(
         val characterId = character.id
             ?: throw SodaException(messageKey = "chat.room.quota.character_required")
 
-        val status = chatRoomQuotaService.purchase(
-            memberId = member.id!!,
-            chatRoomId = chatRoomId,
-            characterId = characterId,
-            addPaid = 12,
-            container = req.container
-        )
+        val chargeType = req.chargeType
+        val status = when (chargeType) {
+            ChatRoomQuotaChargeType.CAN -> {
+                val canOption = req.canOption ?: ChatRoomQuotaCanOption.CAN_10
+
+                chatRoomQuotaService.purchaseWithCan(
+                    memberId = member.id!!,
+                    chatRoomId = chatRoomId,
+                    characterId = characterId,
+                    canOption = canOption,
+                    container = req.container
+                )
+            }
+
+            ChatRoomQuotaChargeType.AD -> {
+                chatRoomQuotaService.purchaseWithAd(
+                    memberId = member.id!!,
+                    chatRoomId = chatRoomId,
+                    characterId = characterId
+                )
+            }
+        }
 
         ApiResponse.ok(
             PurchaseRoomQuotaResponse(

src/main/kotlin/kr/co/vividnext/sodalive/chat/quota/room/ChatRoomQuotaPurchaseOption.kt

@@ -0,0 +1,14 @@
+package kr.co.vividnext.sodalive.chat.quota.room
+
+enum class ChatRoomQuotaChargeType {
+    CAN,
+    AD
+}
+
+enum class ChatRoomQuotaCanOption(
+    val needCan: Int,
+    val quota: Int
+) {
+    CAN_10(10, 15),
+    CAN_20(20, 40)
+}

src/main/kotlin/kr/co/vividnext/sodalive/chat/quota/room/ChatRoomQuotaService.kt

@@ -13,6 +13,10 @@ class ChatRoomQuotaService(
     private val repo: ChatRoomQuotaRepository,
     private val canPaymentService: CanPaymentService
 ) {
+    companion object {
+        private const val AD_REWARD_QUOTA = 5
+    }
+
     data class RoomQuotaStatus(
         val totalRemaining: Int,
         val nextRechargeAtEpochMillis: Long?,
@@ -122,23 +126,50 @@ class ChatRoomQuotaService(
     }
 
     @Transactional
-    fun purchase(
+    fun purchaseWithCan(
         memberId: Long,
         chatRoomId: Long,
         characterId: Long,
-        addPaid: Int = 12,
+        canOption: ChatRoomQuotaCanOption,
         container: String
     ): RoomQuotaStatus {
-        // 요구사항: 10캔 결제 및 UseCan에 방/캐릭터 기록
         canPaymentService.spendCan(
             memberId = memberId,
-            needCan = 10,
+            needCan = canOption.needCan,
             canUsage = CanUsage.CHAT_QUOTA_PURCHASE,
             chatRoomId = chatRoomId,
             characterId = characterId,
             container = container
         )
 
+        return addPaidQuota(
+            memberId = memberId,
+            chatRoomId = chatRoomId,
+            characterId = characterId,
+            addPaid = canOption.quota
+        )
+    }
+
+    @Transactional
+    fun purchaseWithAd(
+        memberId: Long,
+        chatRoomId: Long,
+        characterId: Long
+    ): RoomQuotaStatus {
+        return addPaidQuota(
+            memberId = memberId,
+            chatRoomId = chatRoomId,
+            characterId = characterId,
+            addPaid = AD_REWARD_QUOTA
+        )
+    }
+
+    private fun addPaidQuota(
+        memberId: Long,
+        chatRoomId: Long,
+        characterId: Long,
+        addPaid: Int
+    ): RoomQuotaStatus {
         val quota = repo.findForUpdate(memberId, chatRoomId) ?: repo.save(
             ChatRoomQuota(
                 memberId = memberId,

src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt

@@ -74,6 +74,7 @@ class SecurityConfig(
             .antMatchers("/member/login/kakao").permitAll()
             .antMatchers("/member/login/apple").permitAll()
             .antMatchers("/member/login/line").permitAll()
+            .antMatchers("/admin/member/login").permitAll()
             .antMatchers("/creator-admin/member/login").permitAll()
             .antMatchers("/member/forgot-password").permitAll()
             .antMatchers("/stplat/terms_of_service").permitAll()

src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContent.kt

@@ -35,6 +35,7 @@ data class AudioContent(
     var languageCode: String?,
     var playCount: Long = 0,
     var price: Int = 0,
+    var settlementRatio: Int? = null,
     var releaseDate: LocalDateTime? = null,
     val limited: Int? = null,
     var remaining: Int? = null,

src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentService.kt

@@ -22,8 +22,6 @@ import kr.co.vividnext.sodalive.content.pin.PinContent
 import kr.co.vividnext.sodalive.content.pin.PinContentRepository
 import kr.co.vividnext.sodalive.content.theme.AudioContentThemeQueryRepository
 import kr.co.vividnext.sodalive.content.theme.translation.ContentThemeTranslationRepository
-import kr.co.vividnext.sodalive.content.translation.ContentTranslation
-import kr.co.vividnext.sodalive.content.translation.ContentTranslationPayload
 import kr.co.vividnext.sodalive.content.translation.ContentTranslationRepository
 import kr.co.vividnext.sodalive.content.translation.TranslatedContent
 import kr.co.vividnext.sodalive.explorer.ExplorerQueryRepository
@@ -36,8 +34,7 @@ import kr.co.vividnext.sodalive.i18n.LangContext
 import kr.co.vividnext.sodalive.i18n.SodaMessageSource
 import kr.co.vividnext.sodalive.i18n.translation.LanguageTranslationEvent
 import kr.co.vividnext.sodalive.i18n.translation.LanguageTranslationTargetType
-import kr.co.vividnext.sodalive.i18n.translation.PapagoTranslationService
-import kr.co.vividnext.sodalive.i18n.translation.TranslateRequest
+import kr.co.vividnext.sodalive.i18n.translation.ResourceTranslationJobScheduler
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.block.BlockMemberRepository
 import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
@@ -70,7 +67,7 @@ class AudioContentService(
     private val audioContentLikeRepository: AudioContentLikeRepository,
     private val pinContentRepository: PinContentRepository,
 
-    private val translationService: PapagoTranslationService,
+    private val resourceTranslationJobScheduler: ResourceTranslationJobScheduler,
     private val contentTranslationRepository: ContentTranslationRepository,
 
     private val s3Uploader: S3Uploader,
@@ -770,7 +767,7 @@ class AudioContentService(
          * TranslatedContent로 가공한다
          *
          * 번역 콘텐츠가 없으면
-         * 파파고 API를 통해 번역한 후 저장한다.
+         * 누락 번역 job을 예약하고 원문 응답을 유지한다.
          *
          * 번역 대상: title, detail, tags
          *
@@ -792,49 +789,11 @@ class AudioContentService(
                     tags = payload.tags
                 )
             } else {
-                val texts = mutableListOf<String>()
-                texts.add(audioContent.title)
-                texts.add(audioContent.detail)
-                texts.add(tag)
-
-                val sourceLanguage = audioContent.languageCode ?: "ko"
-
-                val response = translationService.translate(
-                    request = TranslateRequest(
-                        texts = texts,
-                        sourceLanguage = sourceLanguage,
-                        targetLanguage = langContext.lang.code
-                    )
+                resourceTranslationJobScheduler.scheduleResourceTranslation(
+                    resourceType = LanguageTranslationTargetType.CONTENT,
+                    resourceId = audioContent.id!!,
+                    targetLanguage = langContext.lang.code
                 )
-
-                val translatedTexts = response.translatedText
-                if (translatedTexts.size == texts.size) {
-                    var index = 0
-
-                    val translatedTitle = translatedTexts[index++]
-                    val translatedDetail = translatedTexts[index++]
-                    val translatedTags = translatedTexts[index]
-
-                    val payload = ContentTranslationPayload(
-                        title = translatedTitle,
-                        detail = translatedDetail,
-                        tags = translatedTags
-                    )
-
-                    contentTranslationRepository.save(
-                        ContentTranslation(
-                            contentId = audioContent.id!!,
-                            locale = langContext.lang.code,
-                            renderedPayload = payload
-                        )
-                    )
-
-                    translated = TranslatedContent(
-                        title = translatedTitle,
-                        detail = translatedDetail,
-                        tags = translatedTags
-                    )
-                }
             }
         }
 

src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectEvent.kt

@@ -60,6 +60,7 @@ class LanguageDetectListener(
     private val seriesRepository: ContentSeriesRepository,
     private val originalWorkRepository: OriginalWorkRepository,
     private val categoryRepository: CategoryRepository,
+    private val languageDetectionCacheService: LanguageDetectionCacheService,
 
     private val applicationEventPublisher: ApplicationEventPublisher,
 
@@ -116,7 +117,7 @@ class LanguageDetectListener(
             return
         }
 
-        val langCode = requestPapagoLanguageCode(event.query, characterId) ?: return
+        val langCode = detectLanguageCode(event, characterId) ?: return
 
         character.languageCode = langCode
         chatCharacterRepository.save(character)
@@ -154,7 +155,7 @@ class LanguageDetectListener(
             return
         }
 
-        val langCode = requestPapagoLanguageCode(event.query, contentId) ?: return
+        val langCode = detectLanguageCode(event, contentId) ?: return
 
         audioContent.languageCode = langCode
 
@@ -194,7 +195,7 @@ class LanguageDetectListener(
             return
         }
 
-        val langCode = requestPapagoLanguageCode(event.query, commentId) ?: return
+        val langCode = detectLanguageCode(event, commentId) ?: return
 
         comment.languageCode = langCode
         audioContentCommentRepository.save(comment)
@@ -226,7 +227,7 @@ class LanguageDetectListener(
             return
         }
 
-        val langCode = requestPapagoLanguageCode(event.query, commentId) ?: return
+        val langCode = detectLanguageCode(event, commentId) ?: return
 
         comment.languageCode = langCode
         characterCommentRepository.save(comment)
@@ -257,7 +258,7 @@ class LanguageDetectListener(
             return
         }
 
-        val langCode = requestPapagoLanguageCode(event.query, cheersId) ?: return
+        val langCode = detectLanguageCode(event, cheersId) ?: return
 
         cheers.languageCode = langCode
         creatorCheersRepository.save(cheers)
@@ -288,7 +289,7 @@ class LanguageDetectListener(
             return
         }
 
-        val langCode = requestPapagoLanguageCode(event.query, seriesId) ?: return
+        val langCode = detectLanguageCode(event, seriesId) ?: return
 
         series.languageCode = langCode
         seriesRepository.save(series)
@@ -326,7 +327,7 @@ class LanguageDetectListener(
             return
         }
 
-        val langCode = requestPapagoLanguageCode(event.query, originalWorkId) ?: return
+        val langCode = detectLanguageCode(event, originalWorkId) ?: return
 
         originalWork.languageCode = langCode
         originalWorkRepository.save(originalWork)
@@ -352,7 +353,7 @@ class LanguageDetectListener(
         val category = categoryRepository.findByIdOrNull(categoryId) ?: return
         if (!category.languageCode.isNullOrBlank()) return
 
-        val langCode = requestPapagoLanguageCode(event.query, categoryId) ?: return
+        val langCode = detectLanguageCode(event, categoryId) ?: return
 
         category.languageCode = langCode
         categoryRepository.save(category)
@@ -365,6 +366,12 @@ class LanguageDetectListener(
         )
     }
 
+    private fun detectLanguageCode(event: LanguageDetectEvent, targetIdForLog: Long): String? {
+        return languageDetectionCacheService.detectWithCache(event.query) {
+            requestPapagoLanguageCode(event.query, targetIdForLog)
+        }
+    }
+
     private fun requestPapagoLanguageCode(query: String, targetIdForLog: Long): String? {
         return try {
             val headers = HttpHeaders().apply {

src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionCacheService.kt

@@ -0,0 +1,46 @@
+package kr.co.vividnext.sodalive.content
+
+import kr.co.vividnext.sodalive.i18n.translation.SourceTextNormalizer
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+
+@Service
+class LanguageDetectionCacheService(
+    private val languageDetectionResultRepository: LanguageDetectionResultRepository
+) {
+    @Transactional
+    fun detectWithCache(
+        query: String,
+        provider: String = DEFAULT_PROVIDER,
+        detector: () -> String?
+    ): String? {
+        val normalizedQuery = SourceTextNormalizer.normalize(query)
+        if (normalizedQuery.isBlank()) return null
+
+        val sourceHash = SourceTextNormalizer.hash(normalizedQuery)
+        val cached = languageDetectionResultRepository.findBySourceHashAndProviderAndNormalizationVersion(
+            sourceHash = sourceHash,
+            provider = provider,
+            normalizationVersion = SourceTextNormalizer.NORMALIZATION_VERSION
+        )
+        if (cached != null) return cached.detectedLanguage
+
+        val detectedLanguage = detector()?.takeIf { it.isNotBlank() } ?: return null
+        languageDetectionResultRepository.save(
+            LanguageDetectionResult(
+                sourceHash = sourceHash,
+                sourceTextSample = normalizedQuery.take(MAX_SAMPLE_LENGTH),
+                detectedLanguage = detectedLanguage.lowercase(),
+                provider = provider,
+                confidence = null,
+                normalizationVersion = SourceTextNormalizer.NORMALIZATION_VERSION
+            )
+        )
+        return detectedLanguage.lowercase()
+    }
+
+    companion object {
+        const val DEFAULT_PROVIDER = "papago"
+        private const val MAX_SAMPLE_LENGTH = 500
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionResult.kt

@@ -0,0 +1,38 @@
+package kr.co.vividnext.sodalive.content
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import kr.co.vividnext.sodalive.i18n.translation.SourceTextNormalizer
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.Table
+import javax.persistence.UniqueConstraint
+
+@Entity
+@Table(
+    name = "language_detection_result",
+    uniqueConstraints = [
+        UniqueConstraint(
+            name = "uk_language_detection_result_hash_provider_version",
+            columnNames = ["source_hash", "provider", "normalization_version"]
+        )
+    ]
+)
+class LanguageDetectionResult(
+    @Column(name = "source_hash", nullable = false, length = 64)
+    val sourceHash: String,
+
+    @Column(name = "source_text_sample", nullable = false, length = 500)
+    val sourceTextSample: String,
+
+    @Column(name = "detected_language", nullable = false, length = 10)
+    val detectedLanguage: String,
+
+    @Column(name = "provider", nullable = false, length = 50)
+    val provider: String,
+
+    @Column(name = "confidence")
+    val confidence: Double? = null,
+
+    @Column(name = "normalization_version", nullable = false, length = 20)
+    val normalizationVersion: String = SourceTextNormalizer.NORMALIZATION_VERSION
+) : BaseEntity()

src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectionResultRepository.kt

@@ -0,0 +1,11 @@
+package kr.co.vividnext.sodalive.content
+
+import org.springframework.data.jpa.repository.JpaRepository
+
+interface LanguageDetectionResultRepository : JpaRepository<LanguageDetectionResult, Long> {
+    fun findBySourceHashAndProviderAndNormalizationVersion(
+        sourceHash: String,
+        provider: String,
+        normalizationVersion: String
+    ): LanguageDetectionResult?
+}

src/main/kotlin/kr/co/vividnext/sodalive/content/category/CategoryService.kt

@@ -7,8 +7,7 @@ import kr.co.vividnext.sodalive.content.LanguageDetectTargetType
 import kr.co.vividnext.sodalive.i18n.LangContext
 import kr.co.vividnext.sodalive.i18n.translation.LanguageTranslationEvent
 import kr.co.vividnext.sodalive.i18n.translation.LanguageTranslationTargetType
-import kr.co.vividnext.sodalive.i18n.translation.PapagoTranslationService
-import kr.co.vividnext.sodalive.i18n.translation.TranslateRequest
+import kr.co.vividnext.sodalive.i18n.translation.ResourceTranslationJobScheduler
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.block.BlockMemberRepository
 import org.springframework.context.ApplicationEventPublisher
@@ -25,7 +24,7 @@ class CategoryService(
 
     private val langContext: LangContext,
     private val applicationEventPublisher: ApplicationEventPublisher,
-    private val translationService: PapagoTranslationService
+    private val resourceTranslationJobScheduler: ResourceTranslationJobScheduler
 ) {
     @Transactional
     fun createCategory(request: CreateCategoryRequest, member: Member) {
@@ -148,7 +147,7 @@ class CategoryService(
             .findByCategoryIdInAndLocale(categoryIds, locale)
             .associateBy { it.categoryId }
 
-        // 각 항목에 대해 번역 적용. 없으면 Papago로 번역 저장 후 적용
+        // 각 항목에 대해 번역 적용. 없으면 누락 번역 job만 예약하고 원문을 반환한다.
         val result = mutableListOf<GetCategoryListResponse>()
         for (item in baseList) {
             val entity = entityMap[item.categoryId]
@@ -165,38 +164,11 @@ class CategoryService(
                     continue
                 }
 
-                // 번역본이 없으면 Papago 번역 후 저장
-                val texts = listOf(entity.title)
-                val response = translationService.translate(
-                    request = TranslateRequest(
-                        texts = texts,
-                        sourceLanguage = sourceLang,
-                        targetLanguage = locale
-                    )
+                resourceTranslationJobScheduler.scheduleResourceTranslation(
+                    resourceType = LanguageTranslationTargetType.CREATOR_CONTENT_CATEGORY,
+                    resourceId = entity.id!!,
+                    targetLanguage = locale
                 )
-
-                val translatedTexts = response.translatedText
-                if (translatedTexts.size == texts.size) {
-                    val translatedCategory = translatedTexts[0]
-
-                    val existingOne = categoryTranslationRepository
-                        .findByCategoryIdAndLocale(entity.id!!, locale)
-                    if (existingOne == null) {
-                        categoryTranslationRepository.save(
-                            CategoryTranslation(
-                                categoryId = entity.id!!,
-                                locale = locale,
-                                category = translatedCategory
-                            )
-                        )
-                    } else {
-                        existingOne.category = translatedCategory
-                        categoryTranslationRepository.save(existingOne)
-                    }
-
-                    result.add(GetCategoryListResponse(categoryId = item.categoryId, category = translatedCategory))
-                    continue
-                }
             }
 
             // 번역이 필요 없거나 실패한 경우 원본 사용

src/main/kotlin/kr/co/vividnext/sodalive/content/main/banner/AudioContentBanner.kt

@@ -4,6 +4,7 @@ import kr.co.vividnext.sodalive.common.BaseEntity
 import kr.co.vividnext.sodalive.content.main.tab.AudioContentMainTab
 import kr.co.vividnext.sodalive.creator.admin.content.series.Series
 import kr.co.vividnext.sodalive.event.Event
+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.member.Member
 import javax.persistence.Column
 import javax.persistence.Entity
@@ -22,6 +23,9 @@ data class AudioContentBanner(
     @Enumerated(value = EnumType.STRING)
     var type: AudioContentBannerType,
     @Column(nullable = false)
+    @Enumerated(value = EnumType.STRING)
+    var lang: Lang = Lang.KO,
+    @Column(nullable = false)
     var isAdult: Boolean = false,
     @Column(nullable = false)
     var isActive: Boolean = true,

src/main/kotlin/kr/co/vividnext/sodalive/content/main/banner/AudioContentBannerRepository.kt

@@ -4,19 +4,20 @@ import com.querydsl.jpa.impl.JPAQueryFactory
 import kr.co.vividnext.sodalive.content.main.banner.QAudioContentBanner.audioContentBanner
 import kr.co.vividnext.sodalive.content.main.tab.QAudioContentMainTab.audioContentMainTab
 import kr.co.vividnext.sodalive.event.QEvent.event
+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.member.QMember.member
 import org.springframework.data.jpa.repository.JpaRepository
 
 interface AudioContentBannerRepository : JpaRepository<AudioContentBanner, Long>, AudioContentBannerQueryRepository
 
 interface AudioContentBannerQueryRepository {
-    fun getAudioContentMainBannerList(tabId: Long, isAdult: Boolean): List<AudioContentBanner>
+    fun getAudioContentMainBannerList(tabId: Long, isAdult: Boolean, lang: Lang? = null): List<AudioContentBanner>
 }
 
 class AudioContentBannerQueryRepositoryImpl(
     private val queryFactory: JPAQueryFactory
 ) : AudioContentBannerQueryRepository {
-    override fun getAudioContentMainBannerList(tabId: Long, isAdult: Boolean): List<AudioContentBanner> {
+    override fun getAudioContentMainBannerList(tabId: Long, isAdult: Boolean, lang: Lang?): List<AudioContentBanner> {
         var where = audioContentBanner.isActive.isTrue
 
         where = if (tabId == 1L) {
@@ -29,6 +30,10 @@ class AudioContentBannerQueryRepositoryImpl(
             where = where.and(audioContentBanner.isAdult.isFalse)
         }
 
+        if (lang != null) {
+            where = where.and(audioContentBanner.lang.eq(lang))
+        }
+
         return queryFactory
             .selectFrom(audioContentBanner)
             .leftJoin(audioContentBanner.tab, audioContentMainTab)

src/main/kotlin/kr/co/vividnext/sodalive/content/main/banner/AudioContentBannerService.kt

@@ -1,6 +1,7 @@
 package kr.co.vividnext.sodalive.content.main.banner
 
 import kr.co.vividnext.sodalive.event.EventItem
+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.member.block.BlockMemberRepository
 import org.springframework.beans.factory.annotation.Value
 import org.springframework.stereotype.Service
@@ -13,8 +14,8 @@ class AudioContentBannerService(
     @Value("\${cloud.aws.cloud-front.host}")
     private val imageHost: String
 ) {
-    fun getBannerList(tabId: Long, memberId: Long?, isAdult: Boolean): List<GetAudioContentBannerResponse> {
-        return repository.getAudioContentMainBannerList(tabId, isAdult)
+    fun getBannerList(tabId: Long, memberId: Long?, isAdult: Boolean, lang: Lang? = null): List<GetAudioContentBannerResponse> {
+        return repository.getAudioContentMainBannerList(tabId, isAdult, lang)
             .filter {
                 if (it.type == AudioContentBannerType.CREATOR && it.creator != null && memberId != null) {
                     !isBlockedBetweenMembers(memberId = memberId, creatorId = it.creator!!.id!!)