From 3e5c4308f964e9393341502a62c9a57c124acc11 Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Sat, 17 Jan 2026 10:31:32 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20=EB=B0=B0=EB=8B=B9=20=EA=B7=80=EC=A1=B1?=
 =?UTF-8?q?=EC=A3=BC=20=EB=A1=9C=EB=B9=99=20=ED=86=B5=ED=95=A9=20=EA=B5=AC?=
 =?UTF-8?q?=ED=98=84=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=EC=9E=91=EC=84=B1=20?=
 =?UTF-8?q?(TDD=20=ED=85=8C=EC=8A=A4=ED=8A=B8=20=EC=8B=9C=EB=82=98?=
 =?UTF-8?q?=EB=A6=AC=EC=98=A4=20=ED=8F=AC=ED=95=A8)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...±μ£Ό_μžλ™_μˆ˜μ§‘_λ‘œλΉ™_톡합_κ΅¬ν˜„.md | 120 ++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 journey/troubleshooting/260117_λ°°λ‹Ή_κ·€μ‘±μ£Ό_μžλ™_μˆ˜μ§‘_λ‘œλΉ™_톡합_κ΅¬ν˜„.md

diff --git a/journey/troubleshooting/260117_λ°°λ‹Ή_κ·€μ‘±μ£Ό_μžλ™_μˆ˜μ§‘_λ‘œλΉ™_톡합_κ΅¬ν˜„.md b/journey/troubleshooting/260117_λ°°λ‹Ή_κ·€μ‘±μ£Ό_μžλ™_μˆ˜μ§‘_λ‘œλΉ™_톡합_κ΅¬ν˜„.md
new file mode 100644
index 0000000..4a38fb5
--- /dev/null
+++ b/journey/troubleshooting/260117_λ°°λ‹Ή_κ·€μ‘±μ£Ό_μžλ™_μˆ˜μ§‘_λ‘œλΉ™_톡합_κ΅¬ν˜„.md
@@ -0,0 +1,120 @@
+# λ°°λ‹Ή κ·€μ‘±μ£Ό μžλ™ μˆ˜μ§‘ λ‘œλΉ™ 톡합 κ΅¬ν˜„
+
+**λ‚ μ§œ**: 2026-01-17
+**μž‘μ„±μž**: Agent
+**κ΄€λ ¨ 파일**: `rb8001/app/services/dividend/dividend_collector_service.py`, `rb8001/app/scheduler/jobs/dividend_collector.py`, `rb8001/app/scheduler/db_loader.py`
+
+**μ°Έκ³  λ¬Έμ„œ**: `plans/260116_λ°°λ‹Ή_κ·€μ‘±μ£Ό_μžλ™_μˆ˜μ§‘_λ‘œλΉ™_톡합_κ³„νš.md`
+
+---
+
+## ν…ŒμŠ€νŠΈ μ‹œλ‚˜λ¦¬μ˜€ (TDD Red)
+
+### μ‹œλ‚˜λ¦¬μ˜€ 1: μŠ€μΌ€μ€„λŸ¬ μž‘μ—… 생성 및 μ‹€ν–‰
+
+**κΈ°λŒ€ λ™μž‘**:
+1. `_run_dividend_collector_with_logging()` ν•¨μˆ˜ 호좜 μ‹œ `collect_all_dividends()` μ„œλΉ„μŠ€ μ‹€ν–‰
+2. λ‘œκΉ…: μ‹œμž‘/μ™„λ£Œ/μ—λŸ¬ 기둝
+3. Supabase 데이터 μ €μž₯ 확인: `dividend_history` ν…Œμ΄λΈ”μ— μ΅œμ‹  λ°°λ‹Ή 데이터 μ €μž₯
+
+**검증 ν•­λͺ©**:
+- ν•¨μˆ˜ μ‹€ν–‰ 성곡 (μ—λŸ¬ μ—†μŒ)
+- λ‘œκ·Έμ— μ‹œμž‘/μ™„λ£Œ λ©”μ‹œμ§€ 기둝
+- DB에 μ΅œμ‹  λ°°λ‹Ή 데이터 μ €μž₯ (였늘 λ‚ μ§œ κΈ°μ€€)
+
+### μ‹œλ‚˜λ¦¬μ˜€ 2: DB μŠ€μΌ€μ€„ 등둝 및 μžλ™ λ‘œλ“œ
+
+**κΈ°λŒ€ λ™μž‘**:
+1. `scheduled_jobs` ν…Œμ΄λΈ”μ— `dividend_collector` λ ˆμ½”λ“œ μΆ”κ°€
+2. `JOB_TYPE_MAP`에 맀핑 μΆ”κ°€
+3. rb8001 μ„œλ²„ μž¬μ‹œμž‘ ν›„ μŠ€μΌ€μ€„ μžλ™ λ‘œλ“œ 확인
+
+**검증 ν•­λͺ©**:
+- `scheduled_jobs` ν…Œμ΄λΈ”μ— λ ˆμ½”λ“œ 쑴재
+- `JOB_TYPE_MAP`에 `'dividend_collector'` ν‚€ 쑴재
+- μ„œλ²„ μž¬μ‹œμž‘ ν›„ μŠ€μΌ€μ€„ 등둝 확인
+
+### μ‹œλ‚˜λ¦¬μ˜€ 3: μˆ˜λ™ μ‹€ν–‰ 및 μžλ™ μ‹€ν–‰
+
+**κΈ°λŒ€ λ™μž‘**:
+1. `POST /api/scheduler/jobs/dividend_collector/run` μ—”λ“œν¬μΈνŠΈλ‘œ μˆ˜λ™ μ‹€ν–‰
+2. 맀주 μΌμš”μΌ μƒˆλ²½ 3μ‹œ μžλ™ μ‹€ν–‰ (cron ν‘œν˜„μ‹)
+
+**검증 ν•­λͺ©**:
+- API μ—”λ“œν¬μΈνŠΈλ‘œ μˆ˜λ™ μ‹€ν–‰ 성곡
+- λ‘œκ·Έμ—μ„œ μ‹€ν–‰ κ²°κ³Ό 확인
+- DB에 μ΅œμ‹  데이터 μ €μž₯ 확인
+
+---
+
+## κ΅¬ν˜„ κ°€μ΄λ“œ
+
+### Phase 1: μ„œλΉ„μŠ€ 및 μŠ€μΌ€μ€„λŸ¬ μž‘μ—… 생성
+
+**1-1. μ„œλΉ„μŠ€ 생성**: `rb8001/app/services/dividend/dividend_collector_service.py`
+
+```python
+async def collect_all_dividends() -> None:
+    """λ°°λ‹Ή κ·€μ‘±μ£Ό 전체 데이터 μˆ˜μ§‘"""
+    # collect_dividends.py의 메인 λ‘œμ§μ„ μ„œλΉ„μŠ€λ‘œ μ΄λ™ν•˜κ±°λ‚˜ import
+    # λ‘œκΉ… 포함
+    pass
+```
+
+**1-2. μŠ€μΌ€μ€„λŸ¬ μž‘μ—… 생성**: `rb8001/app/scheduler/jobs/dividend_collector.py`
+
+```python
+def _run_dividend_collector_with_logging() -> None:
+    """λ°°λ‹Ή κ·€μ‘±μ£Ό μˆ˜μ§‘ μŠ€μΌ€μ€„λŸ¬ μž‘μ—… (sync 래퍼)"""
+    # asyncio.run()으둜 μ„œλΉ„μŠ€ ν•¨μˆ˜ μ‹€ν–‰
+    # λ‘œκΉ… 포함
+    pass
+```
+
+**참고 파일**:
+- `rb8001/app/scheduler/jobs/diary_generator.py`: κΈ°μ‘΄ νŒ¨ν„΄ μ°Έκ³ 
+- `goosefarminvesting/backend/scripts/collect_dividends.py`: μˆ˜μ§‘ 둜직 μ°Έκ³ 
+
+### Phase 2: DB μŠ€μΌ€μ€„ 등둝
+
+**2-1. `scheduled_jobs` ν…Œμ΄λΈ”μ— λ ˆμ½”λ“œ μΆ”κ°€**
+
+```sql
+INSERT INTO scheduled_jobs (name, job_type, cron_expression, enabled, config)
+VALUES ('dividend_collector', 'dividend_collector', '0 3 * * 0', true, '{}');
+```
+
+**2-2. `rb8001/app/scheduler/db_loader.py`의 `JOB_TYPE_MAP`에 맀핑 μΆ”κ°€**
+
+```python
+JOB_TYPE_MAP = {
+    # ... κΈ°μ‘΄ 맀핑 ...
+    "dividend_collector": {
+        "func": "_run_dividend_collector_with_logging",
+        "module": "app.scheduler.jobs.dividend_collector"
+    }
+}
+```
+
+### Phase 3: ν…ŒμŠ€νŠΈ 및 검증
+
+**3-1. μ„œλ²„ μž¬μ‹œμž‘ ν›„ μŠ€μΌ€μ€„ λ‘œλ“œ 확인**
+**3-2. API μ—”λ“œν¬μΈνŠΈλ‘œ μˆ˜λ™ μ‹€ν–‰ ν…ŒμŠ€νŠΈ**
+**3-3. DB 데이터 확인**
+
+---
+
+## 파일 참쑰
+
+- `rb8001/app/scheduler/jobs/diary_generator.py`: μŠ€μΌ€μ€„λŸ¬ μž‘μ—… μ˜ˆμ‹œ
+- `rb8001/app/scheduler/db_loader.py`: `JOB_TYPE_MAP` ꡬ쑰
+- `goosefarminvesting/backend/scripts/collect_dividends.py`: μˆ˜μ§‘ 둜직
+- `DOCS/journey/plans/260116_λ°°λ‹Ή_κ·€μ‘±μ£Ό_μžλ™_μˆ˜μ§‘_λ‘œλΉ™_톡합_κ³„νš.md`: 전체 κ³„νš
+
+---
+
+## λ‹€μŒ 단계
+
+1. Phase 1 κ΅¬ν˜„: μ„œλΉ„μŠ€ 및 μŠ€μΌ€μ€„λŸ¬ μž‘μ—… 생성
+2. Phase 2 κ΅¬ν˜„: DB μŠ€μΌ€μ€„ 등둝
+3. Phase 3 μ‹€ν–‰: ν…ŒμŠ€νŠΈ 및 검증