第18堂第1關｜可啟動參考包

本包是第18堂第1關的參考成果（checkpoint-01），不代表自己的操作已通過。先保留正常作品與資料，解壓到新位置。

看畫面，與啟動完整參考包

先選這一次要做的事

**改自己的作品：**沿用自己的 student-work 與真正案件資料，按關卡Prompt修改；每堂起始ZIP是乾淨備援，不要每堂都覆蓋自己的資料夾。
**只看參考畫面：**關卡的線上參考連結只能看HTML與樣式。教材網址不提供案件API，即使自己的本機後端啟動，線上參考也不等於已連上；讀取失敗／找不到API是這個位置的限制。
**操作完整參考：**下載該關「可啟動參考包」。它含同一階段的前端、後端與HTML指南，請在全新資料夾操作，不覆蓋自己的作品、不放入真實案件。

第17堂只有讀服務；第18堂開始真正保存詢問；第19堂才有管理頁；第23堂是靜態作品除錯，依包內OPEN_REFERENCE啟動8793預覽即可、不需要案件後端；第27–28堂的交付包含兩項作品。依階段核對，不把尚未製作的功能當成漏檔。

1．解壓到新的位置

例如把第19堂第一關參考包放在 student-work/reference-L19-q1/。裡面應有 service-site/frontend、service-site/backend、START_HERE.html、API_CONTRACT.html、TEST_MODES.html、BACKUP_RESTORE.html 與 OPEN_REFERENCE.html。第27–28堂最外層為 delivery，包含 portfolio 與 service-site。

先讀包內 OPEN_REFERENCE.html，辨認自己下載的堂次與階段。這些是教學參考成果，不是自己已做的驗收證據。

2．避免同埠與資料混用

若自己的正常後端正在8780執行，先回它的終端按 Ctrl+C 停止，保留原目錄與資料，不刪檔、不關掉不認識的服務。
用 Cursor 開啟這份參考的 service-site 資料夾，新增終端，確認在該 service-site 根目錄。第27–28堂是 reference-Lxx/delivery/service-site。
**先讀自己的環境設定。**若曾設過 DATA_DIR、FRONTEND_DIR 或 PORT，這個新終端也可能繼承。按隨包OPEN_REFERENCE的命令明確指定本包 frontend、backend/.reference-data 與8780，避免讀寫正常作品的案件。
帳號預設teacher，練習密碼由自己設定至少12字元；不用原正式密碼，不貼給AI。

3．明確啟動本包

先執行 node --version，需22以上；安裝與終端使用見本機預覽指南（教材中的「本機HTTP預覽」；也可由Node官方下載https://nodejs.org/en/download安裝）。本包無第三方套件，不需npm install。

macOS／Linux，在本包service-site執行：

ADMIN_PASSWORD='請換自己的至少12字元練習密碼' DATA_DIR='./backend/.reference-data' FRONTEND_DIR='./frontend' PORT=8780 PUBLIC_ORIGIN='http://127.0.0.1:8780' ALLOWED_ORIGINS='http://127.0.0.1:8780' TEACHING_MODE=1 node backend/server.mjs

Windows PowerShell，在本包service-site執行：

$env:ADMIN_PASSWORD='請換自己的至少12字元練習密碼'
$env:DATA_DIR='./backend/.reference-data'
$env:FRONTEND_DIR='./frontend'
$env:PORT='8780'
$env:PUBLIC_ORIGIN='http://127.0.0.1:8780'
$env:ALLOWED_ORIGINS='http://127.0.0.1:8780'
$env:TEACHING_MODE='1'
node backend/server.mjs

保持終端運作，在瀏覽器開 http://127.0.0.1:8780/inquiry.html。從後端提供的網址進入，不從教材正式站或靜態預覽位置期待API。第27–28堂apiBase空字串仍可在這裡取得同來源API。參考用的TEACHING_MODE=1只供本機練習；正式環境仍依交付指南關閉。

4．建立自己的虛構案例

參考ZIP不帶任何案件檔或session。第18堂起可在詢問表單送一筆唯一主旨，記回應的真實id，再登入管理頁讀同id。

若只想在第19堂以後對照列表，可另開第二個終端、仍在同一份參考service-site，執行以下其中一種：

# macOS／Linux，明確使用同一參考資料目錄
DATA_DIR='./backend/.reference-data' node backend/manage.mjs seed

# PowerShell
$env:DATA_DIR='./backend/.reference-data'
node backend/manage.mjs seed

它只新增兩筆固定的虛構參考案，不是你第18堂送出的那一案；正式同案驗收仍要使用自己實際POST取得的id。第17堂只讀服務，不需要seed或管理頁。

切換異常時在第二終端讀 TEST_MODES.html，逐項測完恢復normal。沒有實做的項目保持待完成。

第26堂參考的備份資料位置

本參考明確用backend/.reference-data，與一般起始包的backend/.data不同。先停止本參考後端，再在本參考service-site執行；目的必須全新且私有：

node backend/maintenance.mjs backup --source . --data ./backend/.reference-data --out ../reference-backup-new --stopped
node backend/maintenance.mjs verify --backup ../reference-backup-new

還原工具會把資料放回新副本的backend/.data；之後依還原指南明確設定DATA_DIR為還原副本的backend/.data，不繼承參考用的.reference-data。參考備份不是自己正常作品的備份。

5．結束參考，回自己的作品

在參考後端終端 Ctrl+C，停止本包；關閉這次參考用終端，避免將參考DATA_DIR帶回正常作品。
回自己的正常service-site，照原本已記錄的啟動方式啟動，確認原DATA_DIR與正常前端，不指向 .reference-data。
重新登入，核對自己先前的案件id、主旨與備註仍在。重啟會讓登入身份失效，但不應刪除案件。
不要把參考前端、資料或筆記覆蓋自己的唯一作品。需要借用程式時先備份、逐檔看差異，只帶入本關必要修改。

自己的教材勾選與筆記仍由原教材網址保存，不會因啟動這份參考包而遷移。