PackIt
เว็บออกแบบบรรจุภัณฑ์: กำหนดขนาดและวัสดุ ดูภาพพับ 3D ออกแบบลาย และส่งออกแบบผลิต
เริ่มใช้งานในเครื่อง — ไม่ต้องมีคีย์หรือ Docker
ต้องมี Node.js 24.x และ npm 11.x (รุ่นที่ใช้ทดสอบโปรเจกต์; มี .nvmrc / .node-version ให้เครื่องมือจัดการเวอร์ชัน)
จากโฟลเดอร์โปรเจกต์ที่ clone/pull มา:
npm ci
npm run dev:local
เปิด http://127.0.0.1:5173 แล้วกด เริ่มใช้งานบนเครื่องนี้
- ไม่ต้องสร้าง
.env.local, login Google, ติดตั้ง Supabase CLI เพิ่ม หรือเปิด Docker
- ออกแบบ 3D, จัด artwork, บันทึกงานในเบราว์เซอร์ และ export/import ไฟล์งานได้
dev:local ข้ามไฟล์ env และไม่ใช้ Supabase/AI keys ที่ค้างอยู่ใน shell จึงไม่แตะข้อมูล Cloud ของทีม- แถบ AI ใช้ตัวจำลองเมื่อไม่ได้กรอกคีย์ หากกรอก Anthropic API key ใน UI แล้วกดสร้าง จะเรียก API จริงและอาจมีค่าใช้จ่าย; คีย์อยู่ใน memory ของแท็บ ไม่บันทึกลงไฟล์งาน (ช่องกรอกคีย์มีเฉพาะโหมดนี้ — Cloud ใช้คีย์ของระบบ)
- โหมดนี้ไม่มีแพ็กเกจ/paywall: ดาวน์โหลดไฟล์ผลิตได้ทันทีและพรีวิวไม่มีลายน้ำ
- งานอยู่ในเบราว์เซอร์และ origin นี้เท่านั้น ไม่ sync ข้ามเครื่อง ควร export เป็น
.genpkg.json ก่อนล้างข้อมูลเบราว์เซอร์หรือย้ายเครื่อง
- ใช้
127.0.0.1:5173 ให้เหมือนเดิมเสมอ: localhost:5173 และ URL/port อื่นมีพื้นที่เก็บงานแยกกัน
โหมดนี้แยกจาก Cloud โดยตั้งใจ ไม่ใช่การจำลองสิทธิ์เข้าถึงข้อมูล Cloud
เลือกหน้าตา V1 / V2
กด V1 / V2 ที่มุมขวาบน เพื่อสลับหน้าตาได้ทันที โดยใช้ชิ้นงานและประวัติ undo ชุดเดิม เบราว์เซอร์จำเวอร์ชันที่เลือกไว้ (ครั้งแรกเริ่ม V1)
V2 อ้างอิงเฉพาะกรอบสีเทา Example Responsive ใน Figma: แถบเครื่องมือซ้าย, คลังรูปทรง, toolbar ลอย, พรีวิว 3D และแถบซูม บนจอแคบกด ••• เพื่อเปิดเครื่องมือเพิ่มเติม และกด × ที่แผงซ้ายเพื่อคืนพื้นที่วาด ไฟล์ Figma เป็นแหล่งอ้างอิงแบบอ่านอย่างเดียว
ตัวเอียง/ขีดเส้นใต้ถูกเก็บในไฟล์งาน schema 25 และยังเปิดไฟล์งานเวอร์ชันเก่าได้
หลัง pull เวอร์ชันใหม่
เมื่อ branch นี้รวมเข้า main แล้ว และไม่มีงานในเครื่องค้างอยู่:
git switch main
git pull --ff-only
npm ci
npm run dev:local
หยุด dev server เก่าก่อนรันใหม่ หาก Git แจ้งงานค้างหรือ merge conflict ให้จัดเก็บ/แก้งานนั้นก่อน อย่าใช้ reset --hard เพื่อล้างปัญหา ไฟล์ .env.local ไม่ถูก track และคำสั่งข้างต้นไม่เขียนทับมัน
ถ้าเคยตั้ง Cloud ไว้แล้ว ให้ใช้ npm run dev แทน dev:local เพื่อใช้ config เดิม ไม่ต้องตั้ง Google OAuth ใหม่ทุกครั้งที่ pull
ใช้งาน Cloud ของทีม (เลือกทำ)
ต้องได้รับสิทธิ์จากผู้ดูแลโปรเจกต์ก่อน ไม่จำเป็นต้องสร้าง Supabase หรือ Google OAuth client ใหม่สำหรับทุกคน
npm run setup:cloud
คำสั่งสร้าง .env.local จาก .env.cloud.example เฉพาะเมื่อยังไม่มีไฟล์ ถ้ามีอยู่แล้วจะไม่ทับ ไม่เติมค่า และไม่แสดงคีย์ ให้เทียบสองไฟล์ด้วยตัวเอง
ให้ผู้ดูแลส่งค่าผ่านช่องทางปลอดภัย แล้วเติม 4 ช่องใน .env.local:
| ตัวแปร | ค่า |
|---|
VITE_SUPABASE_URL | URL ของ Supabase development/staging |
VITE_SUPABASE_PUBLISHABLE_KEY | publishable/anon key ของโปรเจกต์เดียวกัน (เปิดเผยใน browser ได้) |
SUPABASE_URL | URL เดียวกับฝั่ง browser |
SUPABASE_SECRET_KEY | secret/service-role key สำหรับ server เท่านั้น |
ตัวเลือกเพิ่มเติม (ไม่บังคับ): ANTHROPIC_API_KEY = คีย์ Anthropic ของระบบ ฝั่ง server (ห้ามใส่ใน VITE_*) ใช้กับแถบ AI บน Cloud และ BOX_SPEC_MODEL เลือกโมเดล (ค่าเริ่มต้น claude-opus-5-5; รุ่นที่รองรับและข้อแลกเปลี่ยนต้นทุน/ความเร็ว: docs/billing-freemium-pro.md §6) ถ้าไม่ตั้งคีย์ แถบ AI บน Cloud จะแจ้งว่า server ยังไม่ได้ตั้งค่า (503) — Cloud ไม่รับคีย์จากผู้ใช้ใน UI อีกต่อไป (การกรอกคีย์เองมีเฉพาะ local demo)
แพ็กเกจบน Cloud (ดู docs/billing-freemium-pro.md): Freemium ออกแบบ/ดู blueprint และ 3D ได้ แต่ไม่มีเครดิต AI และดาวน์โหลดไฟล์ผลิตไม่ได้ (พรีวิวมีลายน้ำ; ไฟล์สำรอง .genpkg.json ยังใช้ได้); ซื้อรายแบบ 149 บาท หรือ Pro 399 บาท/เดือน ยังไม่เลือกผู้ให้บริการชำระเงิน จึง ยังไม่เปิดขาย: staging/production ซ่อนปุ่มซื้อทั้งหมดและแสดง "เปิดขายเร็ว ๆ นี้" ส่วน APP_ENV เป็น development หรือ test เปิดให้ลองสั่งซื้อและกด "จำลองการชำระ (dev)" ได้ (ห้ามใช้สองค่านี้กับ environment ที่มีผู้ใช้จริง)
จากนั้นรัน:
npm run dev
เปิด http://127.0.0.1:5173 แล้วเข้าสู่ระบบ Google จริง ผู้ดูแลต้องเตรียม migrations, private buckets, Google provider, redirect URL และเพิ่มบัญชีเป็น test user ถ้า OAuth app ยังเป็น Testing ดู คู่มือ backend
ห้ามใส่ secret/service-role key ในตัวแปร VITE_*, commit env จริง หรือส่งคีย์ใน issue/PR คีย์ server มีสิทธิ์สูง ผู้ที่ไม่ได้รับสิทธิ์ควรใช้ local demo หรือขอ Supabase development แยก ไม่ใช้ production credentials
การ pull/build/dev ไม่ push migration และไม่แก้ remote project อัตโนมัติ ถ้าต้องทดสอบ backend แบบแยกในเครื่องจริง ๆ จึงค่อยใช้ Docker ตามคู่มือ backend; db:reset ล้างข้อมูล local database ไม่ใช่คำสั่งติดตั้งแอปทั่วไป
ทดสอบและดู production build แบบ Local
npm test
npm run build:local
npm run preview:local
หยุด dev server ก่อน preview เพราะใช้ port 5173 เหมือนกัน build:local ไม่ใช้ค่า Cloud ส่วน npm run build และ npm run preview ปกติยังอ่าน env ตาม mode เพื่อรองรับ Cloud/Vercel อย่า deploy build:local เป็น Cloud app
Browser regression ของตัวโหลด: รัน npm run dev:local เปิด /tests/browser/loading-continuity.html แล้วกด Run (เป็นชุดทดสอบแยก ไม่รวมใน npm test); fixture ตรวจ paywall/ลายน้ำด้วยตาอยู่ที่ /tests/browser/paywall.html (สลับสถานะ free / ซื้อแล้ว / Pro / Pro หมดเครดิต โดยไม่ต้องมี Supabase)
ปัญหาที่พบบ่อย
- ไม่รู้จัก
node/npm: ติดตั้ง Node.js 24 แล้วเปิด terminal ใหม่ บน PowerShell ถ้า npm.ps1 ถูกบล็อก ให้ใช้ npm.cmd แทน ไม่ต้องลดนโยบายความปลอดภัยของเครื่อง
EBADENGINE: ตรวจ node --version / npm --version ให้ตรงรุ่นที่ระบุ แล้วรัน npm ci ใหม่- Port 5173 ถูกใช้: หยุด dev/preview เก่าหรือโปรแกรมที่ยึด port ก่อน อย่าเปลี่ยน port โดยไม่ตั้ง OAuth redirect ใหม่ถ้าใช้ Cloud
- หน้า “ตั้งค่าแอปไม่ครบ”:
npm run dev กำลังใช้ Cloud config ที่ยังไม่ครบ ถ้าต้องการออกแบบในเครื่องให้รัน npm run dev:local
- Google login ไม่ผ่าน/บัญชีทดสอบเข้าไม่ได้: ตรวจสิทธิ์ test user และ URL ใน Supabase/Google กับผู้ดูแล ไม่ต้องแจก Google client secret ให้ผู้ใช้
- เปลี่ยน env แล้วไม่เห็นผล: หยุดแล้วเปิด server ใหม่; ค่า frontend ของ build ต้อง build ใหม่
sharp/native module ติดตั้งไม่ครบ: ใช้ Node รุ่นที่ระบุและ npm ci บนเครื่องนั้น ไม่คัดลอก node_modules ข้าม Windows/macOS/Linux หรือปิด optional dependencies- ไม่เห็นงานเดิม: ตรวจว่าเป็น local/Cloud โหมดเดิม, บัญชีเดิม และ URL เดิม ห้ามล้าง storage ก่อนตรวจหรือสำรองงาน
เอกสารสำหรับผู้ดูแล
