AURALITH · VERSION 37

Database & API Design

ออกแบบโครงสร้างข้อมูลและสัญญา API ให้รองรับระบบนิยายและโรลเพลย์ครบชุด ตั้งแต่ต้น โดยพัฒนาและตรวจสอบทีละส่วน

Design only · ยังไม่เชื่อมต่อระบบจริง

1. หลักการสถาปัตยกรรม

  1. หน้าเว็บเป็นส่วนแสดงผล ไม่ใช่แหล่งยืนยันสิทธิ์
  2. คำขอข้อมูลทุกครั้งผ่าน Worker ใหม่ที่แยกจากระบบเดิม
  3. Worker ตรวจ session และสิทธิ์สมาชิกก่อนอ่านหรือแก้ไขข้อมูล
  4. D1 ใหม่เป็นแหล่งข้อมูลถาวรเมื่อได้รับอนุญาตให้เริ่มเชื่อมต่อ
  5. ทุกระเบียนที่เป็นข้อมูลของโปรเจกต์ต้องมี project_id และตรวจสิทธิ์แบบ server-side
  6. การลบความทรงจำเป็น 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_reviewsshort/long-term, character knowledge, relationship/event memory, pending review และ soft delete
พรอมต์และ AIprompt_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/charactersCRUD ตัวละครตรวจ project membership ทุกคำขอ
/api/projects/:projectId/scenesCRUD ฉากตรวจ 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": "..." }

6. ลำดับพัฒนา

Integration Readiness (v38)
  1. ตรวจสอบ schema ที่มีอยู่จริงใน D1 ใหม่ที่ได้รับอนุญาต โดยไม่แตะฐานข้อมูลเดิม
  2. ยืนยันแบบจำลองข้อมูลและ migration กับเจ้าของโครงการ
  3. ทำ API contract tests และ authorization integration tests
  4. เชื่อม read-only endpoints ก่อน แล้วจึงเปิด create/update ทีละ resource
  5. ทดสอบแยกโปรเจกต์, backup/restore, error handling และ rollback ก่อน deploy
  6. เพิ่ม AI integration หลัง authorization และ storage ผ่านการทดสอบแล้วเท่านั้น
ย้อนกลับ: Authorization DesignProject Isolation TestsREADME