讓預約真的存下來：
第一次接上資料庫與 API

1. PHASE 01認識 Vibe Coding 和工具
2. PHASE 02第一次做出東西
3. PHASE 03規劃你的產品
4. PHASE 04做出小店預約
5. PHASE 05上線前要懂的事
6. PHASE 06換成你的點子
7. PHASE 07往商用產品前進

這一課動到：API、資料庫

你現在在這裡：第 4 階段的第二課。上一課 Docker 工作箱跑起來了，這一課加上資料和 API，讓預約第一次真的存下來。

怎麼讓預約真的存進資料庫？

請 Codex 建立服務項目、營業時間、預約三種資料，再用 FastAPI 做出存取這些資料的 API。做好後打開 http://localhost:8000/docs，在自動產生的 API 文件頁按幾下，就能新增一筆預約、再把它讀回來。讀得回剛才存的那一筆，就代表預約真的存進資料庫了。

資料庫：店裡的預約本

資料庫像店裡的預約本，每一筆預約都寫在上面，關店再開門也還在。預約本裡分成幾頁表格：一頁寫服務項目和價格，一頁寫營業時間，一頁寫客人的預約；每一頁就叫一張資料表。這門課用的資料庫叫 PostgreSQL，第 07 課已經放進 Docker 工作箱裡跑著。官方說明 ↗

API：客人不進廚房，到窗口點餐

API 像餐廳的點餐窗口。網頁和 App 不直接翻預約本，而是到窗口說「我要看服務項目」「我要預約這個時段」，窗口替它們查好、寫好，再把結果交回來。網頁、店家後台和 App 都走同一個窗口，看到的資料才會一致。負責這些窗口的地方叫後端，像店的後場。

這門課的後端用 FastAPI 來做。FastAPI 像一套現成的櫃台，裝好就有窗口，還會自動貼出一張說明：每個窗口辦什麼事、要填哪些欄位，而且能直接在說明上試辦。這張說明就是本課要打開的 API 文件頁。官方說明 ↗

路由：窗口上掛的牌子

每個窗口上方掛著一塊牌子，寫著它辦什麼事，這塊牌子就是路由。路由由兩部分組成：一個動作加一個網址。動作最常見的兩個是 GET（查）和 POST（送出一筆新的）；網址寫的是要處理哪一種資料，例如 /api/bookings 就是預約。所以 POST /api/bookings 讀起來就是「送出一筆新的預約」。MDN 說明 ↗

好的路由 vs 不好的路由

第 07 課起點包裡的專案守則檔（AGENTS.md）寫好了命名規則：英文小寫、用複數名詞、單字之間用減號；客人用的放在 /api/ 底下，店家用的放在 /api/admin/ 底下。它就是標準答案。

看出不好的地方，不用自己改程式。把不符合守則的地方告訴 Codex，請它照守則改好，再回 API 文件頁看一次。操作步驟的步驟 3 附了固定提示詞。

成果預覽：在 API 文件頁新增第一筆預約

你的 API 文件頁不會和這張一模一樣，Codex 每次寫的說明文字都不同。新增得進去、讀得回來，就是做對了。

上課前：準備好這三樣

上一課的專案

第 07 課準備好的 shop-booking 資料夾，Docker 工作箱跑得起來。還沒做好的話，到第 07 課的成果檢查下載進度存檔，解開後放進「文件」裡。

Docker Desktop

第 07 課裝好的 Docker Desktop。資料庫和後端都在它裡面跑。

Codex 與瀏覽器

ChatGPT 桌面 App，和平常用的瀏覽器（Safari 或 Chrome）。

這兩步要你自己按

打開 Docker Desktop、決定讓 Codex 在哪個資料夾工作，都要你自己來。

步驟 1打開 Docker Desktop

1. 從「應用程式」資料夾打開 Docker Desktop。
2. 等它顯示正在執行。

做完應看到：Docker Desktop 顯示正在執行，視窗左下角寫著 Engine running。

如果一直停在啟動中：等一兩分鐘；還是不動，把 Docker Desktop 結束再打開一次。

步驟 2在 App 打開 shop-booking 資料夾，開新對話

1. 打開 ChatGPT 桌面 App，確認上方選的是「Codex」。
2. 選擇要在哪裡工作時，選「打開資料夾」，選「文件」裡的 shop-booking。
3. 按「New chat」開新對話。

做完應看到：新對話的畫面標示著 shop-booking。

如果 Codex 要執行 Docker 前先問你同不同意：看清楚它要做什麼、是不是在 shop-booking 裡，再同意。

Windows：從開始選單打開 Docker Desktop，鯨魚圖示在右下角的系統匣；其他步驟和 Mac 一樣。

操作步驟：建資料、做 API、存進第一筆預約

步驟 1請 Codex 建立三種資料

1. 按「複製」，貼到 Codex 的輸入框，送出。
2. 等 Codex 做完，看它用白話說明建了哪些資料。

請照 AGENTS.md 的資料夾與命名規則，在 backend/app/models/ 建立三種資料，存進 Docker 裡的 PostgreSQL 資料庫：
1. 服務項目：名稱、時長（分鐘）、價格（元）。先放入小森髮廊的三項：剪髮 60 分鐘 600 元、洗髮造型 30 分鐘 300 元、染髮 120 分鐘 1,800 元。
2. 營業時間：週二到週日 10:00–19:00，週一公休；時段每 30 分鐘一格。
3. 預約：服務項目、日期、開始時間、客人姓名、電話、Email、狀態、建立時間。
資料要保存下來，重開電腦或 Docker 也不會不見。做好後用白話告訴我建了哪幾種資料、每種有哪些欄位。

複製

做完應看到：Codex 說明建好了服務項目、營業時間、預約三種資料，也放進了小森髮廊的三項服務。

步驟 2請 Codex 做出 API，打開 API 文件頁

1. 貼上下面這段，送出。
2. Codex 做好後，在瀏覽器打開 http://localhost:8000/docs。

請照 AGENTS.md 的 API 命名規則，在 backend/app/routers/ 用 FastAPI 做出這幾條 API：
- GET /api/services：列出服務項目
- GET /api/business-hours：列出營業時間
- GET /api/slots：用服務項目和日期，列出這一天可以預約的時段
- POST /api/bookings：新增一筆預約
- GET /api/admin/bookings：店家查預約，range=today 列出今天的，range=week 列出從今天起算的 7 天裡的（店家登入第 11 課再加，先不用鎖）
讓後端跟著 Docker 一起跑。API 文件頁上的預約範例請先填好：剪髮、10:00、王小明、0912345678、test@example.com，日期我自己改。
做好後告訴我怎麼打開 API 文件頁。

複製

做完應看到：API 文件頁列出服務項目、營業時間、時段、預約和店家查預約這幾條路由。

如果網頁打不開：請看下面的「卡住時怎麼辦」。

請對照 AGENTS.md 的 API 命名規則，檢查 API 文件頁上的每一條路由：網址是不是英文小寫、複數名詞、單字用減號；客人用的是不是都在 /api/ 底下，店家用的是不是都在 /api/admin/ 底下。不符合的請改好，改完列出改了哪幾條；都符合就告訴我都符合。

步驟 4在 API 文件頁新增一筆預約

1. 點開 POST /api/bookings 那一條，按右邊的「Try it out」。
2. 下方的 Request body 會出現預約範例。大括號裡一行是一個欄位，冒號左邊是欄位名稱、右邊是要填的值；只改日期那一欄引號裡的值，改成從今天起算的 7 天裡、週二到週日的一天，格式照範例寫成「年-月-日」。
3. 按藍色的「Execute」。

做完應看到：往下捲到 Server response，Code 是 2 開頭的數字（200 或 201），Response body 顯示王小明的預約，還多了一個編號。

如果 Code 是 4 開頭或 5 開頭：2 開頭代表成功，4 開頭多半是欄位填得不對，5 開頭是後端出錯。請看下面的「卡住時怎麼辦」。

步驟 5讀回同一筆預約

1. 點開 GET /api/admin/bookings，按「Try it out」。
2. 在 range 欄位填 week，按「Execute」。

做完應看到：Response body 列出王小明的預約，編號、日期、時間都和上一步存進去的一樣。

如果清單是空的：先確認上一步的日期在從今天起算的 7 天裡；日期沒問題，請看下面的「卡住時怎麼辦」。

請列出這一課你新增和修改了哪些檔案，每個用一句白話說它在做什麼。
列完請幫這個專案存一個版本，說明寫「第 08 課：資料與 API 完成」。

shop-booking/
  backend/
    app/
      models/         資料表
      routers/
        services.py   服務項目
        hours.py      營業時間與公休日
        slots.py      可預約時段
        bookings.py   預約
        admin.py      店家登入與管理

Windows：在 VS Code 打開資料夾一樣是「File」→「Open Folder…」；API 文件頁在瀏覽器裡，操作和 Mac 完全相同。

成果檢查

成功的樣子：

• 打開 http://localhost:8000/docs，看得到 API 文件頁和一條一條的路由。
• 路由名稱符合守則：英文小寫、複數名詞、單字用減號，店家用的在 /api/admin/ 底下。
• 用 POST /api/bookings 新增一筆預約，Code 是 200 或 201。
• 用 GET /api/admin/bookings 讀回來，看得到同一筆預約。

還沒成功的樣子：API 文件頁打不開、按 Execute 後 Code 是 4 開頭或 5 開頭，或讀回來的清單是空的。照下面「卡住時怎麼辦」處理。每個人的畫面不一樣是正常的，路由的說明文字、欄位順序都可能不同，看的是存得進去、讀得回來。

卡住時怎麼辦

打不開 http://localhost:8000/docs

先確認 Docker Desktop 正在執行，再把這段貼給 Codex：

我在瀏覽器打不開 http://localhost:8000/docs。請檢查後端有沒有跟著 Docker 跑起來，找出原因修好，改完告訴我改了什麼。

按 Execute 後，Code 是 4 開頭

多半是欄位填得不對，例如日期格式不同，或引號被刪掉了。把畫面上的 Code 和 Response body 整段複製，接在這段後面貼給 Codex：

我在 API 文件頁用 POST /api/bookings 新增預約，失敗了。下面是畫面上的 Code 和 Response body，請用白話告訴我哪一欄填錯、應該怎麼填：
（貼在這裡）

按 Execute 後，Code 是 5 開頭

這是後端出錯，不是你填錯。

我在 API 文件頁用 POST /api/bookings 新增預約，Code 是 5 開頭。請查後端的錯誤紀錄，找出原因修好，改完告訴我改了什麼，我再試一次。

新增成功，讀回來卻是空的

我用 POST /api/bookings 新增了一筆預約，Code 是成功的，但用 GET /api/admin/bookings 填 range=week 讀回來是空的。請檢查預約有沒有真的存進資料庫，以及 range=week 是不是列出從今天起算的 7 天裡的預約，修好後告訴我改了什麼。

改完之後越改越亂

請 Codex 退回上一個版本，再從頭貼一次步驟的提示詞：

我改壞了，請把專案退回上一個版本，退回後告訴我改回了什麼。

練習：自己查、自己加一筆

請用白話告訴我，API 文件頁上的每一條路由在做什麼、誰會用到它（客人還是店家）。

常見問題