English {#english}

PREGO v4.0 Worker and API Overview

Summary of implemented Workers and HTTP/Cron endpoints. Deploy URLs are per Wrangler/Cloudflare dashboard.

Control Plane (workers/control-plane)

Method	Path	Description
POST	/webhooks/stripe	Stripe webhook (signature verification, idempotent). Updates tenants_master, provision_jobs, trace_events, audit_logs; triggers workflow_dispatch.
GET	/health	Liveness.
GET	/trace/:trace_id	LogPath: list trace_events for the given trace_id (SEV1 lookup).
GET	/audit?tenant_id=...&since=...&limit=100	Audit log query (PDPA/dashboard). tenant_id, since (ISO), limit (default 100, max 500).

Usage Writer (workers/usage-writer)

Method	Path	Description
POST	/usage	Body: { tenant_id, meter_key?, qty?, path?, status? }. Appends one JSONL line to R2 usage_raw/tenant_id=.../dt=.../hour=.... (Optional: Bearer USE_WRITER_SECRET)

Usage Aggregator (workers/usage-aggregator)

Trigger	Description
Cron	*/15 * * * * (every 15 min). R2 usage_raw → D1 usage_rollups Upsert.
POST	/aggregate

Cycle Close (workers/cycle-close)

Trigger	Description
Cron	0 0 1 * * (monthly, 1st 00:00 UTC). usage_rollups sum → usage_cycle_totals, overage → Stripe Usage.
POST	/cycle-close

Purge Job (workers/purge-job)

Trigger	Description
Cron	0 2 * * * (daily 02:00 UTC). Pending_Deletion tenants after 30 days → Hard Purge (§5.8).
POST	/purge

Autoscaler (workers/autoscaler)

Trigger	Description
Cron	*/10 * * * * (every 10 min). nodes + node_metrics_rollups → Health Score → scaling_events, triggers Scale Out when needed.
POST	/run

---

Authentication

• Stripe webhook: Stripe-Signature + STRIPE_WEBHOOK_SECRET.
• Usage Writer: optional Bearer USE_WRITER_SECRET.
• Trace/Audit: no auth currently; in production, protect with CF Access or API Key.

---

한국어 {#korean}

PREGO v4.0 Worker·API 개요

구현된 Worker와 HTTP/Cron 엔드포인트 요약. 배포 URL은 Wrangler/Cloudflare 대시보드 기준.

Control Plane (workers/control-plane)

Method	Path	설명
POST	/webhooks/stripe	Stripe Webhook (서명 검증, 멱등). tenants_master, provision_jobs, trace_events, audit_logs 갱신; workflow_dispatch 트리거.
GET	/health	Liveness.
GET	/trace/:trace_id	LogPath: 해당 trace_id의 trace_events 목록 (SEV1 조회).
GET	/audit?tenant_id=...&since=...&limit=100	Audit log 조회 (PDPA/대시보드). tenant_id, since(ISO), limit(기본 100, 최대 500).

Usage Writer (workers/usage-writer)

Method	Path	설명
POST	/usage	Body: { tenant_id, meter_key?, qty?, path?, status? }. R2 usage_raw/tenant_id=.../dt=.../hour=... 에 JSONL 1줄 적재. (선택: Bearer USE_WRITER_SECRET)

Usage Aggregator (workers/usage-aggregator)

Trigger	설명
Cron	*/15 * * * * (15분). R2 usage_raw → D1 usage_rollups Upsert.
POST	/aggregate

Cycle Close (workers/cycle-close)

Trigger	설명
Cron	0 0 1 * * (매월 1일 00:00 UTC). usage_rollups 합계 → usage_cycle_totals, overage → Stripe Usage.
POST	/cycle-close

Purge Job (workers/purge-job)

Trigger	설명
Cron	0 2 * * * (매일 02:00 UTC). Pending_Deletion 30일 경과 테넌트 → Hard Purge (§5.8).
POST	/purge

Autoscaler (workers/autoscaler)

Trigger	설명
Cron	*/10 * * * * (10분). nodes + node_metrics_rollups → Health Score → scaling_events, 필요 시 Scale Out 트리거.
POST	/run

---

인증

• Stripe Webhook: Stripe-Signature + STRIPE_WEBHOOK_SECRET.
• Usage Writer: 선택적 Bearer USE_WRITER_SECRET.
• Trace/Audit: 현재 인증 없음; 운영 환경에서는 CF Access 또는 API Key로 보호 권장.