test: subrequest 예산 회귀 테스트 및 AI 핸들러 분리 문서화

- tests/subrequest-budget.test.js: 5파일 PR 시나리오에서 tagPatterns(22회), postLearningStatus(15회) fetch 호출 수 검증 (Cloudflare 50 한도 하회)
- handlers/internal-dispatch.test.js: 내부 디스패치 엔드포인트 인증·라우팅·에러 처리 테스트
- handlers/webhooks.test.js: AI 핸들러 self-fetch 디스패치 통합 테스트 추가
- AGENTS.md, README.md: AI 핸들러 Worker 분리 아키텍처 다이어그램 및 테스트 실행 가이드
- integration.yaml: vi.mock 전역 누출 회피를 위해 bun test handlers/, tests/ 를 별도 스텝으로 실행
- handlers/webhooks.js, wrangler.jsonc: WORKER_URL 을 명시적 env 로 요구하고 기본값은 wrangler vars 로 이동

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: soobing

.github/workflows/integration.yaml

@@ -14,4 +14,5 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: oven-sh/setup-bun@v2
-      - run: bun test
+      - run: bun test handlers/
+      - run: bun test tests/

AGENTS.md

@@ -244,6 +244,27 @@ GitHub Organization webhook 수신용 엔드포인트
 4. Week 없음 → 경고 댓글 작성 (중복 방지: Bot이 작성한 경고 댓글이 이미 있으면 스킵)
 5. Week 있음 → 기존 경고 댓글 삭제 (Bot이 작성한 Week 경고 댓글만)
 
+### 4. AI 핸들러 Worker 분리 아키텍처
+
+PR 이벤트를 받으면 webhook 핸들러가 두 AI 핸들러(`tagPatterns`, `postLearningStatus`)를 **별도 Worker invocation**으로 분리 디스패치한다. 각 invocation은 독립적인 Cloudflare subrequest 예산(50)을 가지므로 파일이 많은 PR에서도 예산 초과를 방지한다.
+
+```
+GitHub webhook
+   │
+   ▼
+[Invocation #1] webhook 핸들러           ← 50 subrequest 예산
+   │  ctx.waitUntil(fetch("/internal/tag-patterns"))      ─┐  self-fetch는
+   │  ctx.waitUntil(fetch("/internal/learning-status"))   ─┤  외부 요청이라
+   │                                                       │  새 invocation 트리거
+   ├──────────────▶ [Invocation #2] tagPatterns          ◀─┘  ← 독립 50 예산
+   │
+   └──────────────▶ [Invocation #3] postLearningStatus      ← 독립 50 예산
+```
+
+- `INTERNAL_SECRET`과 `WORKER_URL`이 모두 설정되어야 활성화된다. 둘 중 하나라도 없으면 기존처럼 같은 invocation에서 순차 실행(subrequest 예산 공유)되어 파일이 많은 PR에서 예산을 초과할 수 있다.
+- 내부 엔드포인트는 `/internal/tag-patterns`, `/internal/learning-status`이며 `X-Internal-Secret` 헤더로 인증한다.
+- 참고: `tests/subrequest-budget.test.js`가 5개 파일 변경 시나리오에서 각 핸들러의 fetch 호출 수(각각 22, 15회)를 회귀 테스트로 박아둔다.
+
 ## 보안 및 권한
 
 ### DaleStudy Organization 전용
@@ -330,11 +351,14 @@ wrangler secret put OPENAI_API_KEY
 wrangler secret put WEBHOOK_SECRET
 
 # Internal Dispatch Secret (AI 핸들러 Worker 분리용, 권장)
-# 설정하면 tagPatterns, learningStatus, complexityAnalysis가
-# 별도 Worker 호출로 디스패치되어 각각 독립적인 subrequest 예산을 가짐
+# 설정하면 tagPatterns, learningStatus가 별도 Worker 호출로
+# 디스패치되어 각각 독립적인 subrequest 예산을 가짐.
+# WORKER_URL과 함께 설정되어야 활성화된다.
 wrangler secret put INTERNAL_SECRET
 ```
 
+`WORKER_URL`은 `wrangler.jsonc`의 `vars`에 정의되어 있어 기본 배포에는 추가 설정이 필요 없다. 스테이징/다른 계정 등으로 배포할 때만 덮어쓰면 된다.
+
 ### 5. GitHub App 설치
 
 저장소에 App이 설치되어 있는지 확인:
@@ -364,15 +388,79 @@ curl -X POST https://github.dalestudy.com/check-weeks \
 - ❌ npm 패키지 대부분 호환 안 됨 (@octokit/app 등)
 - ✅ 순수 JavaScript + Web APIs로 구현
 
+## 테스트
+
+이 프로젝트는 [Bun](https://bun.sh)의 내장 테스트 러너를 사용합니다. 별도의 `package.json`이나 의존성 설치 없이 테스트를 작성하고 실행할 수 있습니다.
+
+### 테스트 실행
+
+테스트는 `handlers/`(핸들러별 단위 테스트)와 `tests/`(프로세스 격리가 필요한 테스트)로 나뉘어 있다. Bun의 `vi.mock()`은 프로세스 전역 레지스트리에 등록되어 같은 실행 내에서 다른 파일로 누출되므로, 같은 모듈을 모킹하는 테스트와 실제 구현을 호출하는 테스트는 **별도 `bun test` 프로세스로 실행**해야 한다.
+
+```bash
+# 전체 테스트 실행 (두 디렉토리를 별도 프로세스로)
+bun test handlers/ && bun test tests/
+
+# 특정 파일만 실행
+bun test handlers/webhooks.test.js
+
+# 감시 모드 (파일 변경 시 자동 재실행)
+bun test handlers/ --watch
+```
+
+Bun 설치: https://bun.sh/docs/installation
+
+### 테스트 파일 작성 규칙
+
+- 테스트 파일은 대상 파일과 같은 디렉토리에 `*.test.js` 이름으로 배치합니다.
+  - 예: `handlers/webhooks.js` → `handlers/webhooks.test.js`
+- `bun:test`에서 제공하는 API(`describe`, `it`, `expect`, `vi`)를 사용합니다.
+- 외부 의존성(`utils/github.js` 등)은 `vi.mock()`으로 대체하고, `fetch`는 `globalThis.fetch = vi.fn()...`로 스텁합니다.
+
+```javascript
+import { describe, it, expect, vi, beforeEach } from "bun:test";
+
+vi.mock("../utils/github.js", () => ({
+  generateGitHubAppToken: vi.fn().mockResolvedValue("fake-token"),
+}));
+
+import { checkWeeks } from "./check-weeks.js";
+
+describe("checkWeeks", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    });
+  });
+
+  it("returns 403 for non-DaleStudy organization", async () => {
+    const request = new Request("https://example.com/check-weeks", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ repo_owner: "OtherOrg", repo_name: "leetcode-study" }),
+    });
+
+    const response = await checkWeeks(request, {});
+    expect(response.status).toBe(403);
+  });
+});
+```
+
+### CI 자동 실행
+
+`.github/workflows/integration.yaml`이 모든 Pull Request와 `main` 브랜치 푸시에서 `bun test handlers/`와 `bun test tests/`를 각각 별도 스텝으로 자동 실행합니다. 테스트가 실패하면 PR 체크가 실패하므로, 머지 전에 반드시 통과시켜야 합니다.
+
 ## 새 기능 추가 가이드
 
 새로운 자동화 기능을 추가할 때 다음 단계를 따르세요:
 
 1. **엔드포인트 추가**: `index.js`의 `fetch()` 함수에 새로운 pathname 라우팅 추가
 2. **핸들러 함수 작성**: 비즈니스 로직을 별도 함수로 분리 (예: `handleCheckAllPrs`)
 3. **GitHub App 권한 확인**: 필요한 권한이 있는지 확인하고 없으면 추가
-4. **문서 업데이트**: AGENTS.md, README.md에 새 기능 문서화
-5. **테스트**: 로컬(`wrangler dev`)에서 먼저 테스트 후 배포
+4. **테스트 작성**: 핸들러 옆에 `*.test.js`를 추가하고 `bun test`로 통과 확인 (위 "테스트" 섹션 참고)
+5. **문서 업데이트**: AGENTS.md, README.md에 새 기능 문서화
+6. **로컬 실행 테스트**: `wrangler dev`로 실제 엔드포인트 동작 확인 후 배포
 
 ## 코드 수정 시 주의사항
 

README.md

@@ -168,13 +168,40 @@ https://github.dalestudy.com
 # 개발 서버 시작
 wrangler dev
 
-# 로컬 테스트 (별도 터미널)
+# 로컬 엔드포인트 호출 (별도 터미널)
 curl -X POST http://localhost:8787/check-weeks \
   -H "Content-Type: application/json" \
   -d '{"repo_owner": "DaleStudy", "repo_name": "leetcode-study"}'
 ```
 
-### 프로덕션 테스트
+### 테스트 코드 실행
+
+이 프로젝트는 **[Bun](https://bun.sh)의 내장 테스트 러너**를 사용합니다. `package.json`이나 `node_modules`가 없는 이유는 Bun이 런타임·테스트 러너·모킹 API(`vi.mock`, `vi.fn`)를 모두 내장하고 있어서 별도 설치 없이 바로 실행되기 때문입니다.
+
+```bash
+# Bun 설치 (최초 1회) — https://bun.sh/docs/installation
+curl -fsSL https://bun.sh/install | bash
+
+# 전체 테스트 실행 (두 디렉토리를 별도 프로세스로)
+bun test handlers/ && bun test tests/
+
+# 특정 파일만 실행
+bun test handlers/webhooks.test.js
+
+# 감시 모드 (파일 변경 시 자동 재실행)
+bun test handlers/ --watch
+```
+
+테스트는 두 디렉토리로 나뉘어 있습니다:
+
+- `handlers/*.test.js`: 대상 파일 옆에 두는 단위 테스트
+- `tests/*.test.js`: Bun `vi.mock()`의 전역 레지스트리 누출을 피하기 위해 별도 프로세스로 실행하는 테스트 (예: `subrequest-budget.test.js`)
+
+자세한 작성 규칙과 예제는 `AGENTS.md`의 "테스트" 섹션을 참고하세요.
+
+모든 Pull Request와 `main` 브랜치 푸시에서 `.github/workflows/integration.yaml`이 두 디렉토리의 테스트를 자동 실행합니다.
+
+### 프로덕션 엔드포인트 호출
 
 ```bash
 curl -X POST https://github.dalestudy.com/check-weeks \

handlers/internal-dispatch.test.js

@@ -0,0 +1,211 @@
+import { describe, it, expect, vi, beforeEach } from "bun:test";
+
+vi.mock("../utils/github.js", () => ({
+  generateGitHubAppToken: vi.fn().mockResolvedValue("fake-token"),
+}));
+
+vi.mock("./tag-patterns.js", () => ({
+  tagPatterns: vi.fn().mockResolvedValue({ tagged: true }),
+}));
+
+vi.mock("./learning-status.js", () => ({
+  postLearningStatus: vi.fn().mockResolvedValue({ posted: true }),
+}));
+
+import { handleInternalDispatch } from "./internal-dispatch.js";
+import { tagPatterns } from "./tag-patterns.js";
+import { postLearningStatus } from "./learning-status.js";
+import { generateGitHubAppToken } from "../utils/github.js";
+
+const VALID_SECRET = "test-secret-123";
+
+function makeRequest(pathname, { secret, body } = {}) {
+  const headers = { "Content-Type": "application/json" };
+  if (secret !== undefined) {
+    headers["X-Internal-Secret"] = secret;
+  }
+  return new Request(`https://example.com${pathname}`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body ?? {}),
+  });
+}
+
+describe("handleInternalDispatch — authentication", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns 401 when INTERNAL_SECRET is not configured in env", async () => {
+    const request = makeRequest("/internal/tag-patterns", {
+      secret: "anything",
+      body: { repoOwner: "DaleStudy", repoName: "leetcode-study", prNumber: 1 },
+    });
+
+    const response = await handleInternalDispatch(
+      request,
+      {},
+      "/internal/tag-patterns"
+    );
+
+    expect(response.status).toBe(401);
+    const body = await response.json();
+    expect(body.error).toBe("Unauthorized");
+    expect(generateGitHubAppToken).not.toHaveBeenCalled();
+    expect(tagPatterns).not.toHaveBeenCalled();
+  });
+
+  it("returns 401 when X-Internal-Secret header is missing", async () => {
+    const request = makeRequest("/internal/tag-patterns", {
+      body: { repoOwner: "DaleStudy", repoName: "leetcode-study", prNumber: 1 },
+    });
+
+    const response = await handleInternalDispatch(
+      request,
+      { INTERNAL_SECRET: VALID_SECRET },
+      "/internal/tag-patterns"
+    );
+
+    expect(response.status).toBe(401);
+    expect(tagPatterns).not.toHaveBeenCalled();
+  });
+
+  it("returns 401 when X-Internal-Secret header does not match env.INTERNAL_SECRET", async () => {
+    const request = makeRequest("/internal/tag-patterns", {
+      secret: "wrong-secret",
+      body: { repoOwner: "DaleStudy", repoName: "leetcode-study", prNumber: 1 },
+    });
+
+    const response = await handleInternalDispatch(
+      request,
+      { INTERNAL_SECRET: VALID_SECRET },
+      "/internal/tag-patterns"
+    );
+
+    expect(response.status).toBe(401);
+    expect(tagPatterns).not.toHaveBeenCalled();
+  });
+});
+
+describe("handleInternalDispatch — routing", () => {
+  const env = { INTERNAL_SECRET: VALID_SECRET, OPENAI_API_KEY: "fake-openai" };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("routes /internal/tag-patterns to tagPatterns with payload fields", async () => {
+    const prData = { number: 42, head: { sha: "abc123" } };
+    const request = makeRequest("/internal/tag-patterns", {
+      secret: VALID_SECRET,
+      body: {
+        repoOwner: "DaleStudy",
+        repoName: "leetcode-study",
+        prNumber: 42,
+        headSha: "abc123",
+        prData,
+      },
+    });
+
+    const response = await handleInternalDispatch(
+      request,
+      env,
+      "/internal/tag-patterns"
+    );
+
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(body.handler).toBe("tag-patterns");
+    expect(tagPatterns).toHaveBeenCalledWith(
+      "DaleStudy",
+      "leetcode-study",
+      42,
+      "abc123",
+      prData,
+      "fake-token",
+      "fake-openai"
+    );
+    expect(postLearningStatus).not.toHaveBeenCalled();
+  });
+
+  it("routes /internal/learning-status to postLearningStatus with payload fields", async () => {
+    const request = makeRequest("/internal/learning-status", {
+      secret: VALID_SECRET,
+      body: {
+        repoOwner: "DaleStudy",
+        repoName: "leetcode-study",
+        prNumber: 42,
+        username: "testuser",
+      },
+    });
+
+    const response = await handleInternalDispatch(
+      request,
+      env,
+      "/internal/learning-status"
+    );
+
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(body.handler).toBe("learning-status");
+    expect(postLearningStatus).toHaveBeenCalledWith(
+      "DaleStudy",
+      "leetcode-study",
+      42,
+      "testuser",
+      "fake-token",
+      "fake-openai"
+    );
+    expect(tagPatterns).not.toHaveBeenCalled();
+  });
+
+  it("returns 404 for an unknown /internal/* pathname", async () => {
+    const request = makeRequest("/internal/unknown", {
+      secret: VALID_SECRET,
+      body: {},
+    });
+
+    const response = await handleInternalDispatch(
+      request,
+      env,
+      "/internal/unknown"
+    );
+
+    expect(response.status).toBe(404);
+    expect(tagPatterns).not.toHaveBeenCalled();
+    expect(postLearningStatus).not.toHaveBeenCalled();
+  });
+});
+
+describe("handleInternalDispatch — error handling", () => {
+  const env = { INTERNAL_SECRET: VALID_SECRET, OPENAI_API_KEY: "fake-openai" };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns 500 when the handler throws", async () => {
+    tagPatterns.mockRejectedValueOnce(new Error("boom"));
+
+    const request = makeRequest("/internal/tag-patterns", {
+      secret: VALID_SECRET,
+      body: {
+        repoOwner: "DaleStudy",
+        repoName: "leetcode-study",
+        prNumber: 1,
+        headSha: "sha",
+        prData: {},
+      },
+    });
+
+    const response = await handleInternalDispatch(
+      request,
+      env,
+      "/internal/tag-patterns"
+    );
+
+    expect(response.status).toBe(500);
+    const body = await response.json();
+    expect(body.error).toContain("boom");
+  });
+});