English {#english}

Tenant Onboarding Flow (www → Provisioning Complete)

End-to-end reference from demo web (www) to Control Plane, workflow, Ansible, and Zuplo. Env: PREGO_CONTROL_PLANE_URL, PREGO_AUTH_URL, PREGO_BILLING_PROXY_URL. 6 steps: 1 Package → 2 Login → 3 Payment → 4 Tenant info → 5 Confirm → 6 Provisioning.

Ref: tenant-onboarding-demo-www-plan, provision-tenant-pipeline. Post-submit resource allocation (7 steps, case handling, R1–R8, Phase, Runbook): tenant-onboard-resource-allocation-flow-plan §1, §6–§8.

1. Demo web environment variables

Site	Variable	Description
www	`PREGO_ADMIN_BASE_URL`	Redirect after package selection. Default `https://prego-admin.pages.dev`.
admin-web	`PREGO_CONTROL_PLANE_URL`	Control Plane Worker URL. When set, createTenantFree, getJobStatus, checkSubdomainAvailable, createCheckoutSession call real API.
admin-web	`PREGO_AUTH_URL`	Auth service base URL. Step 2 / header “Sign in with email”.
admin-web	`PREGO_BILLING_PROXY_URL`	Billing proxy URL. billing.html GET with `?tenant_id=xxx`, display JSON.
admin-web	`PREGO_WWW_BASE_URL`	Step 2 “Previous”, nav “Choose package”. Default `https://prego-www.pages.dev`.

Inject at deploy via <script>window.PREGO_*=...;</script>. www does package selection; admin-web does onboarding wizard (Steps 2–6) and tenant admin (dashboard, billing).

2. Control Plane integration summary

Use	Method/Path	Notes
Free tenant create	POST /v1/tenants	tier, region, subdomain_slug, subdomain_name, company_name (max 60), abbr (2–5), admin_email, admin_name, admin_phone (opt), additional_users. 202 + job_id.
Paid Checkout	POST /v1/checkout	plan_tier, region, subdomain_slug, subdomain_name, company_name, abbr, success_url, cancel_url. STRIPE_SECRET_KEY, STRIPE_PRICE_ID.
Job status	GET /v1/jobs/:id	Includes origin_url.
Subdomain check	GET /v1/subdomain/check	?slug=, optional subdomain_name, use_same_as_slug.
Tenant billing (internal)	GET /internal/billing?tenant_id=	Bearer INTERNAL_API_KEY. company_name, abbr, admin_email, admin_name, admin_phone, additional_users, stripe_*.
Admin test	GET /internal/billing-test	Bearer. Tenant·billing list HTML.

Migrations: 0008_tenant_subdomain_billing.sql, 0009_additional_users.sql, 0010_abbr.sql, 0012_admin_phone.sql, 0013_workflow_dispatch_log.sql.
Flow: www package → admin-web Steps 2–6 (login → payment → tenant info → confirm → provisioning). Plan: www-admin-web-folder-restructure-plan, tenant-onboarding-demo-www-plan §16.

Option B (Queue): Stripe webhook → Control Plane sends to prego-provision-queue → same Worker’s Queue consumer uses D1 workflow_dispatch_log for idempotency then calls workflow_dispatch. Needs wrangler [[queues.producers]] / [[queues.consumers]], PROVISION_QUEUE binding, wrangler queues create prego-provision-queue. Consumer uses GITHUB_TOKEN, GITHUB_WORKFLOW_DISPATCH_URL.

2.1 Stripe test mode

For local/staging Step 3: Control Plane STRIPE_SECRET_KEY (sk_test_…), STRIPE_PRICE_ID (test price); Stripe Dashboard Test mode, test Products/Prices; admin-web NEXT_PUBLIC_PREGO_CONTROL_PLANE_URL; test card 4242 4242 4242 4242. Flow: Step 2 → Step 3 → Pay → Stripe Checkout → test card → success_url → Step 4.

3. Workflow input (workflow_dispatch)

Control Plane: on Stripe Webhook, Option B sends to Queue; consumer calls workflow_dispatch idempotently via workflow_dispatch_log. (Option A: Webhook calls workflow_dispatch directly.) Inputs: job_id, tenant_id, region, target_server_id, create_new_server; subdomain_slug, canonical_hostname (for DNS and callback); callback origin_url = https://{subdomain_slug}.pregoi.com → tenant_runtime.origin_url.

4. Troubleshooting order

“Available” not shown in admin-web → Control Plane GET /v1/subdomain/check, admin-web PREGO_CONTROL_PLANE_URL.
No provisioning after paid payment → Stripe Webhook received?, D1 provider_events, provision_jobs, tenants_master, GITHUB_WORKFLOW_DISPATCH_URL, GITHUB_TOKEN.
No link after provisioning complete → Callback sends origin_url?, GET /v1/jobs/:id origin_url.
Billing page empty → PREGO_BILLING_PROXY_URL, proxy calls GET /internal/billing (Bearer), tenant_id (localStorage or URL).
additional_users → provision-tenant-pipeline §3.5. GET /internal/billing?tenant_id= then pass to Ansible.
Provisioning failure → Control Plane GET /internal/onboarding-dashboard, enter job_id or tenant_id, check step status. prego-control-plane-dashboard.
Resource allocation, plan limits, saturation → prego-control-plane-dashboard#배포 후 검증 R1–R8. Pre-deploy checklist: tenant-onboard-resource-allocation-flow-plan §10.

5. Admin page URLs (Control Plane Worker)

Use	Path	Notes
Dashboard (metrics)	GET /internal/dashboard	HTML. Bearer for metrics.
Metrics API	GET /internal/metrics/summary	Bearer. JSON.
Tenant·billing list	GET /internal/billing-test	Bearer. HTML.
Single tenant billing	GET /internal/billing?tenant_id=	Bearer. JSON.
Onboarding step status	GET /internal/onboarding-status?job_id= or ?tenant_id=	Bearer. JSON. Step progress/errors.
Onboarding dashboard	GET /internal/onboarding-dashboard	HTML. job_id/tenant_id visual.
Trace	GET /internal/trace/:trace_id	Bearer.
Email flow	GET /internal/email-flow-dashboard	HTML.

한국어 {#korean}

테넌트 온보딩 플로우 (www → 프로비저닝 완료)

데모 웹(www)부터 Control Plane·워크플로·Ansible·Zuplo까지 전 구간 연동 시 참고용 요약.

flowchart LR
  subgraph www["www (apps/www)"]
    W1[1 패키지 선택]
  end
  subgraph admin["admin-web (apps/admin-web)"]
    W2[2 로그인] --> W3[3 결제]
    W3 --> W4[4 테넌트 정보]
    W4 --> W5[5 확인]
    W5 --> W6[6 프로비저닝 대기]
  end
  W1 -->|?plan=&region=| admin
  W5 -->|POST /v1/tenants| CP[Control Plane]
  CP -->|202 + job_id| W6
  CP --> WF[workflow_dispatch]
  WF --> P[Pulumi]
  P --> AN[Ansible]
  AN --> ZU[Zuplo Sync]
  ZU --> CB[provision-complete]
  CB --> CP

Ref: tenant-onboarding-demo-www-plan, provision-tenant-pipeline. 제출 후 리소스 할당 단계별 상세(7단계)·케이스별 관리·R1~R8 상세 요건·구현 Phase·Runbook 운영 절차: tenant-onboard-resource-allocation-flow-plan §1·§6·§7·§8.

1. 데모 웹 환경 변수

사이트	변수	설명
www	`PREGO_ADMIN_BASE_URL`	패키지 선택 후 리다이렉트 대상. 기본 `https://prego-admin.pages.dev`.
admin-web	`PREGO_CONTROL_PLANE_URL`	Control Plane Worker URL. 설정 시 createTenantFree, getJobStatus, checkSubdomainAvailable, createCheckoutSession이 실제 API 호출.
admin-web	`PREGO_AUTH_URL`	인증 서비스 기본 URL. Step 2·헤더에서 “이메일로 로그인” 표시.
admin-web	`PREGO_BILLING_PROXY_URL`	결제 정보 조회 프록시 URL. billing.html에서 `?tenant_id=xxx`로 GET 후 JSON 표시.
admin-web	`PREGO_WWW_BASE_URL`	Step 2 “Previous”, nav “Choose package” 링크. 기본 `https://prego-www.pages.dev`.

위 변수는 브라우저에서 사용하므로, 배포 시 HTML에 <script>window.PREGO_*=...;</script> 형태로 주입. www는 패키지 선택만 담당하고, admin-web이 온보딩 위저드(Step 2~6) 및 tenant admin(dashboard, billing 등)을 담당.

2. Control Plane 연동 요약

용도	메서드/경로	비고
무료 테넌트 생성	POST /v1/tenants	tier, region, subdomain_slug, subdomain_name, company_name(최대 60자), abbr(2~5자 선택), admin_email, admin_name, admin_phone(선택), additional_users. 202 + job_id.
유료 Checkout	POST /v1/checkout	plan_tier, region, subdomain_slug, subdomain_name, company_name(최대 60자), abbr, success_url, cancel_url. STRIPE_SECRET_KEY·STRIPE_PRICE_ID 필요.
작업 상태	GET /v1/jobs/:id	origin_url 포함.
서브도메인 중복	GET /v1/subdomain/check	?slug=, optional subdomain_name, use_same_as_slug.
테넌트 결제(내부)	GET /internal/billing?tenant_id=	Bearer INTERNAL_API_KEY. company_name, abbr, admin_email, admin_name, admin_phone, additional_users, stripe_* 등.
관리자 테스트	GET /internal/billing-test	Bearer. 테넌트·결제 목록 HTML.

마이그레이션: 0008_tenant_subdomain_billing.sql, 0009_additional_users.sql, 0010_abbr.sql, 0012_admin_phone.sql, 0013_workflow_dispatch_log.sql 적용 필요.
온보딩 플로우: www에서 패키지 선택 → admin-web Step 2~6 (로그인 → 결제 → 테넌트 정보(서브도메인·회사명·관리자·팀원) → 확인 → 프로비저닝). 기획: www-admin-web-folder-restructure-plan, tenant-onboarding-demo-www-plan §16.

Option B (Queue): Stripe webhook → Control Plane가 prego-provision-queue로 메시지 전송 → 동일 Worker의 Queue consumer가 D1 workflow_dispatch_log로 중복 방지 후 workflow_dispatch 호출.
필요: wrangler에 [[queues.producers]] / [[queues.consumers]] (queue = prego-provision-queue), PROVISION_QUEUE 바인딩, Queue 생성(wrangler queues create prego-provision-queue 등). Consumer는 GITHUB_TOKEN, GITHUB_WORKFLOW_DISPATCH_URL 사용.

2.1 Stripe 테스트 모드 연동

Step 3 결제 플로우를 로컬/스테이징에서 검증하려면 Stripe 테스트 모드를 사용한다.

항목	설정
Control Plane	`wrangler secret put STRIPE_SECRET_KEY` (sk_test_…), `STRIPE_PRICE_ID` (price_xxx 테스트)
Stripe Dashboard	Test mode 활성화 → Products → Prices에서 테스트 가격 생성
admin-web	`NEXT_PUBLIC_PREGO_CONTROL_PLANE_URL` = Control Plane Worker URL
테스트 카드	4242 4242 4242 4242 (기타: Stripe Testing)

플로우: Step 2 → Step 3 → Pay 클릭 → Stripe Checkout → 테스트 카드 결제 → success_url 리다이렉트 → Step 4.

3. 워크플로 입력(workflow_dispatch)

Control Plane: Stripe Webhook 수신 시 Option B면 Queue에 메시지 전송; Queue consumer가 workflow_dispatch_log로 idempotent하게 GitHub Actions workflow_dispatch 호출. (Option A는 Webhook에서 직접 workflow_dispatch 호출.) 전달되는 입력:

job_id, tenant_id, region, target_server_id, create_new_server
subdomain_slug, canonical_hostname (전달 시 DNS·콜백에서 사용)
콜백 시 origin_url = https://{subdomain_slug}.pregoi.com 전달 시 tenant_runtime.origin_url 저장.

4. 장애 시 확인 순서

admin-web에서 “사용 가능” 안 나옴 → Control Plane GET /v1/subdomain/check, admin-web의 PREGO_CONTROL_PLANE_URL 설정 확인.
유료 결제 후 프로비저닝 안 됨 → Stripe Webhook 수신 여부, Control Plane D1 provider_events·provision_jobs·tenants_master, GITHUB_WORKFLOW_DISPATCH_URL·GITHUB_TOKEN.
프로비저닝 완료 후 링크 안 나옴 → 워크플로 콜백에서 origin_url 전달 여부, GET /v1/jobs/:id 응답의 origin_url.
결제 정보 페이지 빈 화면 → PREGO_BILLING_PROXY_URL, 프록시가 GET /internal/billing (Bearer) 호출하는지, tenant_id(localStorage 또는 URL).
팀원(additional_users) 활용 → provision-tenant-pipeline §3.5 참고. GET /internal/billing?tenant_id= 로 조회 후 Ansible 등에 전달.
프로비저닝 실패·단계별 확인 → Control Plane GET /internal/onboarding-dashboard 에서 job_id 또는 tenant_id 입력 후, 단계별(done/pending/failed) 진행 확인. prego-control-plane-dashboard 참고.
리소스 할당·플랜 한도·포화 검증 → 배포 후 R1–R8 동작 확인은 prego-control-plane-dashboard#배포 후 검증 R1–R8 참고. 구현·배포 전 체크리스트는 tenant-onboard-resource-allocation-flow-plan §10 참고.

5. 관리자 페이지 URL (Control Plane Worker 기준)

테넌트·온보딩·결제 확인용 내부 URL. 실제 Worker 도메인은 배포 환경에 따라 다름.

용도	경로	비고
대시보드 (메트릭)	GET /internal/dashboard	HTML. Bearer 입력 시 메트릭 로드.
메트릭 API	GET /internal/metrics/summary	Bearer. JSON.
테넌트·결제 목록	GET /internal/billing-test	Bearer. HTML.
단일 테넌트 결제	GET /internal/billing?tenant_id=	Bearer. JSON.
온보딩 단계별 상태	GET /internal/onboarding-status?job_id= 또는 ?tenant_id=	Bearer. JSON. 단계별 진행/에러.
온보딩 단계별 대시보드	GET /internal/onboarding-dashboard	HTML. job_id/tenant_id로 시각 확인.
트레이스	GET /internal/trace/:trace_id	Bearer.
이메일 플로우 검증	GET /internal/email-flow-dashboard	HTML.