Bluehair 시간표 운영·유지보수·디버깅·확장 인덱스#

이 문서는 timetable-cloudflare 저장소의 현재 구현을 기준으로 작성한 운영자·개발자용 색인입니다. 기능을 수정하거나 장애를 조사할 때는 먼저 이 문서를 보고, 이어서 연결된 파일을 여십시오. 배포·시크릿 변경·D1 데이터 변경은 되돌리기 어렵거나 서비스에 영향을 줄 수 있으므로, 로컬 검증과 백업 확인 뒤에만 수행합니다.

기준: 현재 단일 워크스페이스(default), 시간대 Asia/Seoul, 주 서비스 이름 timetable.

0. 가장 빠른 길#

1. 시스템 구성요소 지도#

브라우저 PWA ───────────────┐
Windows TodayWidget(WebView2) ─┼─▶ 주 Timetable Worker ─▶ D1(권위 데이터)
                              │          ├─▶ public/(정적 화면)
ChatGPT Web ─▶ OAuth MCP Worker ┘          └─▶ SyncHub ─▶ WebSocket 무효화 신호
                    └─▶ OAUTH_KV

MCP Worker ── TIMETABLE_API Service Binding + 서버 측 Bearer ──▶ 주 Worker

권한과 데이터의 단일 원천#

• D1이 일정·일회성 할 일·체크리스트·완료 기록·현재 revision의 권위 있는 저장소다.
• 주 Worker만 D1에 연결되어 입력 검증, 인증, 변경 commit, revision 증가를 수행한다.
• **Durable Object SyncHub**은 상태를 저장하지 않는다. 연결된 클라이언트에 { type: "invalidate", revision }를 보내는 fan-out 용도다.
• MCP Worker는 D1을 직접 읽거나 쓰지 않는다. TIMETABLE_API Service Binding을 통해 주 Worker의 같은 API를 호출한다.
• SSE는 구현되어 있지 않다. 실시간 전달 방식은 인증된 WebSocket 하나다.

2. 디렉터리와 핵심 파일 인덱스#

3. 데이터·API·실시간 흐름#

D1 스키마#

migrations/0001_initial.sql에는 다음 테이블이 있다.

모든 정상적인 변경은 D1 batch에서 데이터 조작 뒤 sync_meta.revision을 1 증가시킨다. commit이 끝난 후에만 SyncHub.invalidate(revision)을 호출한다. 알림 전송 실패는 이미 성공한 데이터 commit을 되돌리지 않는다. 따라서 클라이언트는 WebSocket 메시지를 정답 데이터로 취급하지 않고 스냅샷을 다시 읽어야 한다.

API 요약#

모든 /api/*와 /ws는 아래 둘 중 하나로 인증해야 한다.

• 브라우저: POST /api/auth/session에서 토큰을 HttpOnly/SameSite=Strict 세션 쿠키로 교환
• 자동화·네이티브·Service Binding: Authorization: Bearer <APP_TOKEN>

쿠키를 사용한 쓰기 요청은 현재 Origin과 같은 Origin 헤더가 반드시 필요하다. API JSON 본문은 Content-Type: application/json이며 16 KiB를 넘을 수 없다.

범위는 서울 날짜 기준이고 기본값은 오늘이며, 최장 31일이다. Worker가 허용하는 category는 english, exam, content, review, rest다.

클라이언트 동기화 순서#

1. public/app.js가 인증 상태를 확인한다.
2. 지정한 주간 범위의 /api/snapshot을 받아 localStorage의 timetable.snapshot.v2에 마지막 정상 데이터를 보관한다.
3. 인증된 온라인 클라이언트가 /ws에 연결한다.
4. 어느 클라이언트/ChatGPT가 변경을 commit하면 revision이 증가하고 SyncHub가 invalidate를 push한다.
5. 메시지의 revision이 로컬 값보다 새로우면 클라이언트가 /api/changes 또는 snapshot으로 다시 읽고 렌더링한다.
6. WebSocket이 끊기면 재접속한다. 오프라인일 때는 마지막 정상 스냅샷을 표시한다.

public/sw.js는 앱 셸의 GET 요청만 캐시하며 /api/*와 /ws는 명시적으로 제외한다. API 응답도 Cache-Control: no-store다.

4. 설정·시크릿·Cloudflare·도메인#

주 Worker 설정 (wrangler.jsonc)#

MCP Worker 설정 (integrations/chatgpt-mcp/wrangler.jsonc)#

시크릿 규칙#

• .dev.vars와 integrations/chatgpt-mcp/.dev.vars는 Git ignore 대상이다. 예제 파일만 커밋한다.
• 운영 APP_TOKEN은 두 Worker의 Cloudflare secret에 함께 설정한다. 교체 시 새 값이 양쪽에 적용되기 전까지 MCP 호출이 실패할 수 있다.
• 입력 토큰과 HMAC 세션 서명의 원천이 같은 APP_TOKEN이므로, 유출 또는 분실이 의심되면 즉시 두 Worker에서 교체하고 기존 브라우저 세션이 무효화됨을 전제한다.
• CI의 local-development-token-not-for-production은 테스트용이며 운영 시크릿이 아니다.

5. 로컬 개발과 검증#

필요한 도구#

• root 및 MCP: Node.js 22, pnpm 10, 프로젝트의 lockfile에 맞는 의존성
• Windows: .NET SDK 8 (windows/global.json은 8.0.423), Windows SDK, WebView2 Runtime
• Cloudflare 실제 배포/원격 D1 조작: 해당 계정에 인증된 Wrangler

다음으로 셸의 도구 상태를 먼저 확인한다.

node --version
pnpm --version
pnpm exec wrangler --version

node가 인식되지 않거나 22 계열이 아니면, 먼저 Node.js 22를 설치/활성화한 뒤 새 PowerShell 창에서 재시도한다.

주 Worker/PWA 안전 검증#

저장소 root에서 실행한다.

pnpm install --frozen-lockfile
pnpm docs:check
pnpm types
pnpm types:check
pnpm typecheck
pnpm test
pnpm check

pnpm docs:check는 Markdown 원본과 배포용 HTML이 같은지 확인한다. 실패하면 pnpm docs:build로 HTML을 다시 생성한다. pnpm check과 pnpm deploy:dry-run은 wrangler deploy --dry-run이며 실제 배포를 하지 않는다. 생성된 타입 파일의 변경이 의도된 것인지 확인한 뒤 커밋한다.

로컬 데이터로 UI를 실행하는 순서는 다음과 같다.

Copy-Item .dev.vars.example .dev.vars
# .dev.vars의 APP_TOKEN을 개발용 긴 난수로 교체한다.
pnpm db:migrate:local
pnpm db:seed:local
pnpm dev

브라우저에서 http://localhost:8787을 열고, 개발용 토큰으로 로그인한다. .wrangler/의 로컬 D1 상태는 운영 DB가 아니다.

ChatGPT MCP 패키지 검증#

다음 명령은 MCP 하위 디렉터리에서 실행한다.

Set-Location integrations/chatgpt-mcp
pnpm install --frozen-lockfile --ignore-workspace
pnpm types
pnpm typecheck
pnpm test
pnpm check

로컬 OAuth/MCP 실험은 Copy-Item .dev.vars.example .dev.vars 뒤에 실행한다. Service Binding을 포함한 end-to-end 로컬 검증은 두 Worker를 함께 Wrangler 개발 런타임으로 실행해야 한다. 이 저장소에는 이를 한 번에 띄우는 compose/script는 없다.

Windows 위젯 검증#

Set-Location windows
.\scripts\Build.ps1 -Configuration Release
.\scripts\Publish.ps1
.\scripts\Smoke-Test.ps1

Build.ps1은 CI용 빌드이고, Publish.ps1은 self-contained x64 산출물과 ZIP을 만든다. 설치 전 Smoke Test를 통과시킨다.

CI가 보장하는 범위#

.github/workflows/ci.yml은 pull request, push, 수동 실행에서 다음 세 job을 수행한다.

CI에는 배포 권한이나 운영 secret을 주지 않는다.

6. 배포·롤백·백업·복구#

주 Worker 배포 전 점검#

1. pull request CI가 모두 녹색인지 확인한다.

2. wrangler.jsonc의 서비스명, today.bluehair.blue, D1 binding/ID, DO binding을 확인한다.

3. 운영 APP_TOKEN이 이미 주 Worker에 설정됐는지 확인한다. 새 환경이면 대화형으로 설정한다.

   pnpm exec wrangler secret put APP_TOKEN
   

4. 새 migration이 있으면 배포 전에 원격 D1에 적용할 대상과 백업 상태를 재확인한다.

   pnpm exec wrangler d1 migrations apply timetable --remote
   

5. 사람이 dry-run 결과를 검토한 뒤 배포한다.

   pnpm deploy:dry-run
   pnpm exec wrangler deploy
   

seed.sql은 INSERT OR IGNORE를 사용하지만, 운영 seed 실행은 새 기본 행을 추가할 수 있다. 운영 데이터에 필요한지 확인하지 않은 상태에서 재실행하지 않는다.

MCP Worker 배포 순서#

1. TIMETABLE_API의 서비스 대상이 timetable인지 확인한다.

2. MCP Worker에도 같은 운영 APP_TOKEN을 설정한다.

   Set-Location integrations/chatgpt-mcp
   pnpm exec wrangler secret put APP_TOKEN
   pnpm check
   pnpm exec wrangler deploy
   

3. mcp.bluehair.blue/mcp의 OAuth discovery와 인증 전 401을 확인한다. 실제 시간표를 변경하는 smoke test는 피한다.

롤백 원칙#

• 이 저장소에는 자동 배포나 원클릭 롤백 스크립트가 없다.

• 코드 장애는 우선 현재 배포 이력을 읽기 전용으로 확인한다.

  pnpm exec wrangler deployments list
  pnpm exec wrangler deployments status
  

• 즉시 이전 Worker 버전으로 되돌려야 한다면 정상 version ID를 사람이 확인한 뒤 다음 명령을 실행할 수 있다. 이 명령은 운영 배포를 바꾸므로 변경 사유와 version ID를 기록한다.

  pnpm exec wrangler rollback <NORMAL_VERSION_ID> --message "장애 대응: <REASON>"
  

• 또는 마지막 정상 Git commit을 새 브랜치에서 복원한 뒤 같은 검증과 wrangler deploy를 다시 실행하면 소스와 배포 상태를 일치시키기 쉽다.

• D1 migration은 일반적으로 자동 역방향 실행되지 않는다. 잘못된 migration을 이미 원격 적용했다면, 먼저 영향 범위와 최신 백업을 확인하고 별도 forward-fix migration 또는 복구 계획을 작성한다. 기존 migration 파일을 수정해 과거 상태를 바꾸지 않는다.

• custom domain/DNS 변경 롤백은 Worker 코드 롤백과 별개다. Cloudflare DNS/route 상태를 따로 확인한다.

백업·복구 현황과 필수 운영 절차#

• 저장소에는 D1 자동 백업, export 스케줄러, 복구 스크립트가 구현되어 있지 않다.
• 현재 고정된 Wrangler에서 원격 SQL export 문법은 pnpm exec wrangler d1 export timetable --remote --output <BACKUP.sql>이다. 권한·보존 위치를 사전 검증하고, 실행 직전 pnpm exec wrangler d1 export --help로 설치된 CLI 문법을 다시 확인한다.
• 최소 절차는 “변경 전 export를 암호화된 접근 제한 저장소에 보관 → 파일 해시·DB명·시각 기록 → 복구는 격리된 대상에서 먼저 검증 → 원격 복구 승인”이다. Git 저장소나 공개 artifact에 SQL export/토큰을 넣지 않는다.
• 시점 복구가 필요하면 먼저 pnpm exec wrangler d1 time-travel info timetable --timestamp <RFC3339>로 bookmark를 조회한다. time-travel restore는 운영 DB를 덮어쓰므로 최신 export와 별도 승인을 확보한 뒤에만 사용한다.
• 복구 시 revision과 WebSocket 상태도 고려한다. D1을 이전 시점으로 복구하면 연결된 클라이언트의 로컬 snapshot보다 revision이 낮아질 수 있으므로, 사용자 세션을 새로고침/재인증하고 동기화 동작을 수동 점검한다.

7. 로그·관측·점검 순서#

현재 확인 가능한 신호#

현재 알림 규칙, Logpush, Analytics Engine, 외부 APM, 가동률 모니터링은 저장소 설정에 없다. 장기 운영 시 별도 설계·권한 승인 후 추가한다.

8. 증상 → 확인 → 조치#

9. 보안 운영 체크리스트#

배포 전 또는 시크릿/권한 변경 전에 확인한다.

• 실제 APP_TOKEN이 소스, wrangler.jsonc, .dev.vars.example, Git diff, 이슈/PR, 화면 캡처에 없는가?
• 주 Worker와 MCP Worker의 운영 APP_TOKEN이 의도적으로 같은 최신 값인가?
• .dev.vars와 Windows의 Data\WebView2를 공유/커밋하지 않는가?
• API 쓰기 요청은 cookie일 경우 same-origin CSRF 검사를, 자동화일 경우 bearer 인증을 유지하는가?
• 새 API가 readJson, 길이·날짜·시간·category 검증, 에러 코드 정책을 따르는가?
• 모든 성공 mutation이 D1 transaction + revision 증가 + notify 경로를 거치는가?
• MCP의 새 도구가 OAuth scope를 확인하고, Service Binding만 사용하며, upstream 오류 본문/시크릿을 노출하지 않는가?
• 보안 헤더(CSP, HSTS, frame 차단 등)를 바꿀 경우 PWA/WebView2/MCP 동작을 함께 시험했는가?
• Windows 배포 파일을 외부에 배포한다면 Authenticode 서명과 SHA-256 검증 절차가 준비됐는가? 현재 저장소는 서명 자동화를 제공하지 않는다.

10. 기능 확장 지점과 경계#

안전한 변경 순서#

1. 요구사항과 데이터 모델을 먼저 정한다.
2. 저장 구조가 바뀌면 새 D1 migration을 추가한다.
3. src/index.ts에 입력 검증·권한·CRUD를 추가한다.
4. 쓰기라면 mutate와 commitWithBestEffortNotification 경로로 revision/invalidation을 보장한다.
5. API 테스트를 추가한다.
6. public/app.js와 필요 시 timetable-core.js/웹 테스트를 갱신한다.
7. ChatGPT에서도 편집해야 한다면 MCP Zod schema, 도구, scope 검사, MCP 테스트를 추가한다.
8. Windows는 WebView2로 웹 UI를 호스팅하므로, 기본적으로 웹 UI 변경이 반영된다. 네이티브 tray/창 동작 변경만 windows/src/TodayWidget를 수정한다.
9. root/MCP/Windows 검증과 CI를 모두 통과한 뒤 배포한다.

구현되어 있는 확장 지점#

명시적으로 미구현/별도 설계가 필요한 항목#

• Android 네이티브 앱/APK 및 Android 위젯
• 다중 사용자·다중 workspace 권한 모델 (현재 default 한 workspace)
• ChatGPT native Scheduled Tasks 저장소와 D1의 자동 양방향 동기화
• SSE 전송
• 푸시 알림/캘린더 동기화/외부 캘린더 API
• D1 자동 백업·자동 복구·정기 export
• 운영 알림, 외부 로그 수집, 가동률 모니터링
• Windows 코드 서명/공개 배포 파이프라인
• CI 기반 자동 배포와 자동 롤백

이 항목들은 설정만 추가해서 안전하게 완성되지 않는다. 데이터 소유권, 인증, 비용, 장애 복구, 개인정보 보관 정책을 정한 뒤 별도 작업으로 설계한다.

11. 변경 후 최소 인계 기록#

운영 변경 또는 기능 확장 PR에는 아래 정보를 남긴다.

1. 변경한 데이터/라우트/클라이언트/Cloudflare 바인딩
2. migration 이름과 원격 적용 여부
3. 시크릿 교체 여부(값 자체는 기록하지 않음)
4. 실행한 root, MCP, Windows 검증 명령과 결과
5. 배포 Worker 버전/시각, 도메인 확인 결과
6. 백업 위치의 식별자와 복구 책임자(비밀/경로 공개 금지)
7. 롤백 기준 commit과 D1 영향 여부

이 기록이 있어야 다음 운영자가 “코드는 정상인데 데이터/도메인/시크릿이 다르다”는 상황을 빠르게 분리할 수 있다.