AURALITH · VERSION 37
Database & API Design
ออกแบบโครงสร้างข้อมูลและสัญญา API ให้รองรับระบบนิยายและโรลเพลย์ครบชุด ตั้งแต่ต้น โดยพัฒนาและตรวจสอบทีละส่วน
Design only · ยังไม่เชื่อมต่อระบบจริง1. หลักการสถาปัตยกรรม
- หน้าเว็บเป็นส่วนแสดงผล ไม่ใช่แหล่งยืนยันสิทธิ์
- คำขอข้อมูลทุกครั้งผ่าน Worker ใหม่ที่แยกจากระบบเดิม
- Worker ตรวจ session และสิทธิ์สมาชิกก่อนอ่านหรือแก้ไขข้อมูล
- D1 ใหม่เป็นแหล่งข้อมูลถาวรเมื่อได้รับอนุญาตให้เริ่มเชื่อมต่อ
- ทุกระเบียนที่เป็นข้อมูลของโปรเจกต์ต้องมี
project_idและตรวจสิทธิ์แบบ server-side - การลบความทรงจำเป็น soft delete; การเปลี่ยน schema ใช้ migration แบบเพิ่มและย้อนกลับได้
ข้อห้าม: ไฟล์ SQL ในแผนนี้เป็นข้อเสนอสำหรับตรวจทานเท่านั้น ห้ามนำไปรันกับ D1 ใด ๆ ก่อนยืนยัน schema จริงและอนุมัติฐานข้อมูลใหม่โดยชัดแจ้ง ห้ามแก้ Worker/D1 เดิม
2. Logical data model
| กลุ่ม | ตารางที่เสนอ | จุดประสงค์ / ความสัมพันธ์ |
|---|---|---|
| บัญชีและสิทธิ์ | users, project_memberships | ผู้ใช้และบทบาทต่อโปรเจกต์ (owner/editor/viewer); ห้ามเชื่อ role จาก client |
| โปรเจกต์ | projects, project_settings | ประเภท Novel/Roleplay/Experimental, สถานะ, การตั้งค่าและค่าเฉพาะโปรเจกต์ |
| เนื้อหา | characters, scenes, worldbuilding_entries | ตัวละคร ฉาก และข้อมูลโลก; ทุกแถวผูกกับโปรเจกต์ |
| โครงเรื่อง | events, relationships, timeline_events, story_bible_entries | เหตุการณ์ ความสัมพันธ์ ลำดับเวลา และ canon ที่ยืนยันแล้ว |
| ความทรงจำ | memories, memory_reviews | short/long-term, character knowledge, relationship/event memory, pending review และ soft delete |
| พรอมต์และ AI | prompt_profiles, model_preferences, ai_request_logs (minimal) | พรอมต์และค่ารุ่นโมเดล; ห้ามเก็บ API secrets หรือเนื้อหาละเอียดเกินจำเป็นใน log |
| ไฟล์และการกู้คืน | export_jobs, backup_manifests | ติดตามงานส่งออก/สำรอง; ตรวจสิทธิ์ก่อนสร้างหรือดาวน์โหลด |
| ความปลอดภัย/การเปลี่ยนแปลง | audit_events, schema_migrations | บันทึกเหตุการณ์ที่จำเป็นโดยไม่ใส่รหัสผ่าน/secret; ติดตาม migration |
รายชื่อตารางเป็นแบบจำลองเชิงตรรกะ ไม่ใช่คำสั่งสร้างตาราง และยังไม่ยืนยันชนิดคอลัมน์หรือ index กับฐานข้อมูลที่ใช้งานจริง
3. ความสัมพันธ์หลัก
users 1 ── * project_memberships * ── 1 projects projects 1 ── * characters / scenes / events / relationships projects 1 ── * memories / story_bible_entries / prompt_profiles scenes 1 ── * memory_reviews (source scene, optional) projects 1 ── * export_jobs / backup_manifests / audit_events
ทุก endpoint ที่ใช้ resource ID ต้องตรวจว่า resource นั้นอยู่ในโปรเจกต์ที่ผู้ใช้มีสิทธิ์ ไม่ใช่ตรวจแค่รูปแบบ ID
4. API contract ที่เสนอ
| Method / Path | หน้าที่ | ข้อกำหนด |
|---|---|---|
GET /api/health | สถานะบริการ | ไม่ส่ง secret หรือข้อมูลผู้ใช้ |
POST /api/auth/login | เข้าสู่ระบบ | ตรวจ origin, body limit, rate limit และตั้ง cookie ปลอดภัย |
POST /api/auth/logout | ออกจากระบบ | ล้าง session cookie |
GET /api/projects | รายการโปรเจกต์ที่ผู้ใช้เข้าถึงได้ | ผลลัพธ์ต้องผ่าน membership filter |
POST /api/projects | สร้างโปรเจกต์ | สร้าง owner membership ในธุรกรรมเดียวกัน |
GET/PATCH/DELETE /api/projects/:projectId | อ่าน/แก้ไข/ลบโปรเจกต์ | ตรวจ role และตรวจวิธี HTTP; ลบแบบปลอดภัยตามนโยบาย |
/api/projects/:projectId/characters | CRUD ตัวละคร | ตรวจ project membership ทุกคำขอ |
/api/projects/:projectId/scenes | CRUD ฉาก | ตรวจ membership และ payload schema |
/api/projects/:projectId/memories | อ่าน/เสนอ/ยืนยันความทรงจำ | pending review เป็นค่าเริ่มต้น; soft delete |
/api/projects/:projectId/exports | ส่งออกข้อมูล | ตรวจสิทธิ์ก่อนสร้างและดาวน์โหลด; จำกัดขนาด |
เส้นทางเหล่านี้เป็นข้อเสนอสำหรับอนาคต ไม่ได้ถูกเปิดใช้งานใน Worker ปัจจุบัน
5. มาตรฐาน request/response
// Success
{ "ok": true, "data": { /* resource */ }, "requestId": "..." }
// Error
{ "ok": false, "error": "forbidden", "requestId": "..." }- ใช้ HTTP status ที่สอดคล้องกัน: 400 validation, 401 unauthenticated, 403 forbidden (หรือ 404 เพื่อไม่เปิดเผยการมีอยู่ของ resource ตามนโยบาย), 409 conflict, 413 too large, 429 rate limit
- ตรวจชนิดข้อมูลและขนาด request ฝั่ง Worker; ไม่รับ field ที่ไม่ได้อนุญาตโดยไม่ตั้งใจ
- ใช้ pagination สำหรับรายการขนาดใหญ่ และไม่ส่งข้อมูลทั้งหมดของโปรเจกต์ในคำขอเดียว
- เพิ่ม versioning เมื่อจำเป็น และใช้ optimistic concurrency สำหรับการแก้ไขฉาก/ความทรงจำที่ชนกัน
6. ลำดับพัฒนา
Integration Readiness (v38)- ตรวจสอบ schema ที่มีอยู่จริงใน D1 ใหม่ที่ได้รับอนุญาต โดยไม่แตะฐานข้อมูลเดิม
- ยืนยันแบบจำลองข้อมูลและ migration กับเจ้าของโครงการ
- ทำ API contract tests และ authorization integration tests
- เชื่อม read-only endpoints ก่อน แล้วจึงเปิด create/update ทีละ resource
- ทดสอบแยกโปรเจกต์, backup/restore, error handling และ rollback ก่อน deploy
- เพิ่ม AI integration หลัง authorization และ storage ผ่านการทดสอบแล้วเท่านั้น