日時選択、内容入力、確定、変更、取消を一つの受付構造として扱う

あなたは Codex。Cloudflare 上で “予約受付魔法 / Booking Intake Spell” という production-shaped prototype を構築する。

仕事は concept page を書くことではない。予約、確認、日程変更、取消を一体の intake flow として扱う、実際に動く reservation intake system prototype を実装すること。

質問で止まらない。妥当な判断を自分で行い、コード、コメント、型安全、バリデーション、deployability を備えた完全実装を end-to-end で作る。

重要な実行制約:
- scaffolding で止まらない
- plan だけを出力しない
- core route を未実装のまま残さない
- main booking flow を mock JSON に置き換えない
- D1 migration を省略しない
- test を省略しない
- すでに明記された要件について追加質問しない
- tradeoff が発生したら acceptance criteria を満たす最小で明快な実装を選ぶ
- 完了時には architecture、routes、env vars、local run/deploy steps を短く要約する

Project goal

予約、面接、訪問、相談、レッスン、施術など appointment-based workflow 全般に再利用できる booking intake system を作る。

このシステムは以下をサポートする:
1. public intake page
2. date/time selection
3. input form
4. availability check
5. provisional acceptance or confirmation
6. modification flow
7. cancellation flow
8. notification abstraction
9. optional waitlist-ready architecture
10. staff-only admin view

Core product concept

booking、interview scheduling、treatment booking、lesson booking、visit booking、consultation intake を同じ parent structure として扱う:
- date/time を選ぶ
- intake details を入力する
- rules に照らして validate する
- booking record を作成する
- 後から reschedule / cancel できる
- すべての action を一つの history thread に残す
- notification を record history から概念的に切り離さない

コードコメントや naming では必要に応じて次の framing を使ってよい:
- Intake Familiar = validates input and intake rules
- Schedule Familiar = checks time, duration, staff/resource constraints
- Notification Familiar = sends confirmation, reschedule, cancellation messages

Fixed stack

絶対に不可能でない限り、次の stack をそのまま使う:
- Frontend: React + Vite + TypeScript
- Styling: simple clean CSS or CSS Modules, no UI library required
- Backend API: Cloudflare Workers
- Database: Cloudflare D1
- Async jobs: Cloudflare Queues-ready abstraction。prototype では synchronous fallback を実装してよいが、後から async delivery を差し込める構造にする
- Auth for admin: simple Cloudflare Access compatible header-based stub または lightweight password gate abstraction。admin route が staff-only ready であることを明確にする
- Email delivery abstraction: provider interface を作り、development log provider を default にする
- Calendar integration abstraction: provider interface を作り、no-op/mock provider を default にする
- Validation: Zod
- Testing: 少なくとも logic と validation に対して Vitest
- Dates/times: robust な方式を使い、timestamp は UTC で保存し、表示では local timezone support を持たせる

Architecture

monorepo もしくは clean two-app structure を一つの repository 内で使う:
- apps/web = React public UI and admin UI
- apps/api = Cloudflare Worker API
- packages/shared = shared types, validation schemas, utilities

もっと単純な layout を選ぶのは許容するが、UI、API、shared domain logic の分離は明確に保つ。

Functional requirements

1. Public booking flow

public page を作り、user が次を行えるようにする:
- service type または intake category を選ぶ
- date を選ぶ
- available time slots を見る
- time slot を選ぶ
- required fields を入力する
- 必要なら attendee count を入力する
- service が variable duration を許すなら duration を入力する
- booking を submit する

intake form は次の fields をサポートする:
- name
- email
- phone optional
- booking type/category
- date
- start time
- duration minutes
- party size or attendee count
- note/message
- optional staff preference
- optional location or mode field such as in-person / phone / online
- consent checkbox if needed

2. Unified booking lifecycle

すべての booking は次のような lifecycle status を持つ:
- pending
- confirmed
- cancelled

すべての booking は次のような event history も保持する:
- created
- availability_checked
- confirmed
- rescheduled
- cancelled
- notification_sent
- notification_failed

reschedule と cancel は row を silently に置き換えるのではなく、同じ booking identity/history chain の上で動かす。

3. Availability model

次をサポートできる availability model を実装する:
- opening hours or bookable windows
- slot duration
- buffer before/after
- max concurrent bookings
- optional staff/resource constraint
- blackout/unavailable times
- lead time rules
- cutoff rules for same-day or late bookings

この prototype では:
- one or more bookable services を定義する
- weekly availability rules を定義する
- blackout support を定義する
- capacity support を定義する
- real slot generation を実装する
- invalid or conflicting bookings を API level で reject する

4. Modification and cancellation

各 booking に以下を発行する:
- public booking reference
- secure management token

management token を使い、guest が次を行えるようにする:
- booking details を見る
- booking を reschedule する
- booking を cancel する

以下の page を作る:
- /manage/:reference?token=...
または同等の route

Reschedule flow は次を満たす:
- availability を再チェックする
- history を保全する
- notification abstraction を通して通知する

Cancellation flow は次を満たす:
- booking を cancelled に更新する
- history を保全する
- notification abstraction を通して通知する

5. Notifications

次の provider interface を持つ notification abstraction を実装する:
- sendBookingCreated
- sendBookingConfirmed
- sendBookingRescheduled
- sendBookingCancelled

development mode では:
- payload を console に書き出し、必要なら D1 に notification log row も保存する logging provider を実装する

特定の email vendor を domain logic に深く埋め込まない。
provider は差し替え可能にする。

6. Calendar integration abstraction

次のような methods を持つ calendar provider interface を実装する:
- checkConflicts
- createEvent
- updateEvent
- cancelEvent

この prototype では:
- mock/no-op provider を default に使う
- 将来 Google Calendar などを追加しても domain rewrite が不要な構造にする

7. Admin UI

staff-only admin area を作り、次を行えるようにする:
- bookings を list する
- date/status/category で filter する
- booking details を inspect する
- booking history を inspect する
- 必要なら pending booking を manual confirm する
- notification log status を見る
- availability configuration summary を見る

過剰実装はしない。usable で clean に保つ。

8. Waitlist-ready design

waitlist behavior 全体は必須ではないが、schema と domain design は将来次をサポートできるようにする:
- no slot available -> waitlist request
- slot opens later -> re-notify candidate

適切な場所に TODO marker を残す。

Domain rules

次の sensible default rules を使う:
- bookings must be in the future
- bookings cannot be created inside cutoff window
- duration must match service constraints
- attendee count must be within service constraints
- selected slot must still be available at commit time
- reschedule cannot move cancelled booking
- cancel cannot cancel already cancelled booking
- public manage token must be required for guest self-service actions

少なくとも 2 つの example services を作る:
1. interview
2. consultation

Example defaults:
- interview: fixed 30 minutes, attendee count 1, weekdays only, morning-heavy slots
- consultation: fixed 60 minutes, attendee count 1 to 4, broader availability

必要なら visit または lesson を 3つ目として加えてよい。

Data model

少なくとも次の tables を持つ D1 schema を設計・実装する:

services
- id
- slug
- name
- description
- duration_minutes_default
- duration_minutes_min nullable
- duration_minutes_max nullable
- attendee_min
- attendee_max
- requires_manual_confirmation boolean
- is_active
- created_at
- updated_at

availability_rules
- id
- service_id nullable if global
- weekday
- start_minute
- end_minute
- slot_interval_minutes
- buffer_before_minutes
- buffer_after_minutes
- capacity
- timezone
- is_active
- created_at
- updated_at

blackouts
- id
- service_id nullable
- starts_at
- ends_at
- reason
- created_at

bookings
- id
- reference_code
- manage_token_hash
- service_id
- status
- customer_name
- customer_email
- customer_phone nullable
- attendee_count
- requested_timezone
- starts_at
- ends_at
- note nullable
- preferred_staff nullable
- mode nullable
- created_at
- updated_at
- cancelled_at nullable

booking_events
- id
- booking_id
- event_type
- actor_type
- payload_json
- created_at

notification_logs
- id
- booking_id nullable
- notification_type
- provider
- recipient
- status
- payload_json
- error_message nullable
- created_at

必要なら staff/resources 用 supporting tables を後から足してよいが、first prototype を unnecessary に膨らませない。

Security

次の safe practices を実装する:
- すべての input を Zod で validate する
- 可能なら raw internal IDs を public に露出しない
- manage token の plaintext は保存せず hash だけを保存する
- manage token を secure に verify する
- admin API/routes を clear な auth middleware stub で保護する
- すべての string input を sanitize / bound する
- 明快だが overshare しない error message を返す

API design

おおむね次の JSON API endpoints を実装する:

Public:
GET /api/services
GET /api/availability?service=...&date=YYYY-MM-DD&timezone=...
POST /api/bookings
GET /api/bookings/manage/:reference?token=...
POST /api/bookings/manage/:reference/reschedule
POST /api/bookings/manage/:reference/cancel

Admin:
GET /api/admin/bookings
GET /api/admin/bookings/:reference
POST /api/admin/bookings/:reference/confirm
GET /api/admin/availability-summary

naming は調整してよいが、これらの capability は保つ。

Frontend pages

少なくとも次の pages を作る:
- / = concise landing page for the prototype
- /book = intake entry
- /book/:serviceSlug optional deep-link service booking page
- /manage = management entry page where user pastes reference + token, or redirect helper
- /manage/:reference = booking detail/manage page
- /admin = admin bookings page
- /admin/bookings/:reference = admin booking detail page

UX requirements

UI は次を満たす:
- clean
- responsive
- minimal
- professional
- legible on mobile
- not visually bloated

booking flow は次の感覚で進む:
Step 1. Choose service
Step 2. Choose date/time
Step 3. Enter details
Step 4. Review and submit
Step 5. Confirmation with management link

reschedule/cancel screen は simple で calm にする。

copy は bilingual-ready でもよい。prototype では English only でも許容するが、strings は後から localize しやすいよう centralized にする。
development speed を落とさずに Japanese labels を clean に入れられるなら入れてよい。

Seed/demo data

D1 を次で seed する:
- at least 2 services
- weekly availability rules
- 1 blackout example
- a few example bookings for admin testing

Developer experience

次を用意する:
- clear README
- local setup instructions
- D1 migration instructions
- Wrangler configuration
- sample .dev.vars or environment variable documentation
- scripts for dev, test, build, and deploy

Environment variables

少なくとも次の env vars を定義し、document する:
- BOOKING_BASE_URL
- ADMIN_SHARED_SECRET or equivalent stub
- NOTIFICATION_PROVIDER
- CALENDAR_PROVIDER
- DEFAULT_TIMEZONE

provider abstraction の都合で必要なら、次の placeholder も含めてよい:
- RESEND_API_KEY
- GOOGLE_CLIENT_EMAIL
- GOOGLE_PRIVATE_KEY
- GOOGLE_CALENDAR_ID

ただし external provider がなくても prototype が runnable であることを保つ。

Implementation guidance

visual flourish より booking logic の correctness を優先する。
slot availability は client だけでなく server で生成する。
booking creation 時には API write path の中で final conflict check を行う。
domain logic は route handler に埋め込まず reusable module に置く。
code は readable に保ち、cleverness に寄らない。

Tests

少なくとも次を test する:
- slot generation
- blackout exclusion
- capacity/conflict rejection
- booking creation validation
- reschedule validation
- cancellation rules
- manage token verification

Acceptance criteria

prototype 完了条件は次のすべてが真になること:
1. guest can open the public booking page
2. guest can choose a valid slot
3. guest can submit a booking
4. booking record is stored in D1
5. booking history trail is stored
6. guest receives a management link/token in the response flow
7. guest can use the management route to reschedule
8. guest can use the management route to cancel
9. availability is revalidated server-side during create/reschedule
10. admin can list and inspect bookings
11. notification abstraction exists and logs delivery attempts
12. codebase is deployable to Cloudflare with documented steps
13. tests run successfully

Output expectations

snippet ではなく full codebase を生成する。

さらに次も含める:
- D1 schema/migrations
- seed script or seed SQL
- README
- example screenshots は不要
- core flow に placeholder “TODO app” skeleton を残さない

Tone and naming

code 内では practical English naming を使ってよい。
README と landing page では system を次の名称で記述する:
“予約受付魔法 / Booking Intake Spell”

landing page では次の product meaning を反映する:
- booking, interview, treatment, visit, lesson, and consultation intake handled in one structure
- date selection, input, confirmation, reschedule, and cancellation treated as one reception flow
- can later connect waitlist, reminder, prefill form, and notification extensions

Landing page content guideline

次の ideas に沿って concise な landing page section structure を作る:
- What spell it is
- What it can do
- Why it is useful
- Spell structure
- Familiars
- Grimoires
- Reproduction conditions
- Verification status

ただし decorative page にしない。実際に動く booking flow を必ず実装し、landing page から link する。

Final instruction

将来の vertical-specific booking system に派生できる reusable parent spell として実装する。
extensibility、clarity、operational realism を hype より優先する。
working Cloudflare-native prototype を出荷する。