แอปจองคิว/นัดหมาย

ภาพรวม

แอป appointment ให้ลูกค้าเปิดระบบจองคิวผ่าน LINE โครงสร้างข้อมูลแบ่งเป็นห้าส่วน

ส่วน	ความหมาย
Location	สาขาหรือสถานที่ให้บริการ
Service	บริการที่จองได้ ผูกกับสาขา
Staff	พนักงานที่ให้บริการ ผูกกับสาขา
Journey	เส้นทางหรือขั้นตอนการจองที่ผู้ใช้เห็น
Booking	รายการจองที่เกิดขึ้นจริง

ฝั่ง cms-api รับผิดชอบการตั้งค่าและการจัดการรายการจอง ส่วนการจองจริงของผู้ใช้ปลายทางทำผ่าน client-web และ client-api

ข้อสังเกตเรื่องความไม่สม่ำเสมอของ guard ซึ่งยกมาจากระบบ TypeScript เดิมโดยตรง คือ endpoint กลุ่ม booking อยู่บน group authed คู่กับ AppEnabledGuard, กลุ่ม journey, service และ staff อยู่บน group public คู่กับ JwtLoginAuth ส่วนกลุ่ม location บาง route อยู่บน group authed เฉย ๆ โดยไม่มี policy

Business Flow

ตั้งค่าครั้งแรก

1. สร้างสาขาด้วย POST /api/apps/appointment/locations
2. เพิ่มบริการในสาขาด้วย POST /api/apps/appointment/locations/:id/services
3. เพิ่มพนักงานในสาขาด้วย POST /api/apps/appointment/locations/:id/staff
4. ออกแบบขั้นตอนการจองด้วย POST /api/apps/appointment/journeys

ผู้ใช้ทำการจอง

5. ผู้ใช้เปิด LIFF จาก LINE แล้วเลือกสาขา บริการ พนักงาน และเวลา ก่อนยืนยัน ขั้นตอนนี้ทำผ่าน client-api ไม่ใช่ endpoint ในเอกสารนี้
6. ระบบสร้างแถวใหม่ในตาราง booking

ผู้ดูแลจัดการรายการจอง

7. GET /api/apps/appointment/bookings พร้อม FilterBookingDto เพื่อดูรายการจอง
8. GET /api/apps/appointment/bookings/:id ดูรายละเอียดการจอง
9. PUT /api/apps/appointment/bookings/:id/status เปลี่ยนสถานะ เช่น ยืนยัน ยกเลิก หรือเสร็จสิ้น
   • การเปลี่ยนสถานะจะ publish ข้อความลง RabbitMQ คิว booking_event_trigger โดย payload มี byte-shape ตรงกับของเดิมทุกประการ รวมถึงลำดับ key
   • ทำให้ กฎทริกเกอร์อัตโนมัติ สั่งส่งข้อความแจ้งผู้จองต่อได้

รูปแบบ CRUD ที่ใช้ร่วมกัน

โครงสร้าง CRUD ของทุกเอนทิตีย่อยใน service_appointment.go เป็นรูปแบบเดียวกัน

• _getCls() ดึง lineOaId, organizationId, selfId และ lang ออกจาก CLS
• findAll และ findAllByLocation ประกอบ where และ order พร้อมกรองแถวที่ถูกลบออก แล้วคืน array ตรง ๆ โดยไม่ห่อ envelope
• findById ค้นด้วยเงื่อนไข id ร่วมกับ lineOaId หากไม่พบจะโยน NotFoundException
• create, update และ remove โดย remove เป็น soft delete
• เอนทิตีกลุ่มนี้มี gorm.DeletedAt ทำให้ GORM เติมเงื่อนไข deleted_date IS NULL และแปลง Delete เป็น soft delete ให้อัตโนมัติ

ไฟล์และฟังก์ชันหลัก

โค้ดอยู่ที่ internal/modules/apps/ ประกอบด้วย controller.go, service.go, service_appointment.go และ guard.go

Bookings (group authed + AppEnabledGuard)

Method	Route	Handler	Policy
GET	/api/apps/appointment/bookings	ct.bookingFindAll	readAll line-oa
GET	/api/apps/appointment/bookings/:id	ct.bookingFindById	read line-oa
PUT	/api/apps/appointment/bookings/:id/status	ct.bookingUpdateStatus	update line-oa

Journeys (group public + JwtLoginAuth)

Method	Route	Handler
GET	/api/apps/appointment/journeys	ct.journeyFindAll
GET	/api/apps/appointment/journeys/:id	ct.journeyFindById
POST	/api/apps/appointment/journeys	ct.journeyCreate
PUT	/api/apps/appointment/journeys/:id	ct.journeyUpdate
DELETE	/api/apps/appointment/journeys/:id	ct.journeyRemove

Locations

Method	Route	Handler	Group
GET	/api/apps/appointment/locations	ct.locationFindAll	authed (ไม่มี policy)
POST	/api/apps/appointment/locations	ct.locationCreate	authed
GET	/api/apps/appointment/locations/:id	ct.locationFindById	authed
PUT	/api/apps/appointment/locations/:id	ct.locationUpdate	authed
DELETE	/api/apps/appointment/locations/:id	ct.locationRemove	authed

Services และ Staff (group public + JwtLoginAuth)

Method	Route	Handler
GET	/api/apps/appointment/locations/:id/services	ct.serviceFindAllByLocation
POST	/api/apps/appointment/locations/:id/services	ct.serviceCreate
GET	/api/apps/appointment/services/:id	ct.serviceFindById
PUT	/api/apps/appointment/services/:id	ct.serviceUpdate
DELETE	/api/apps/appointment/services/:id	ct.serviceRemove
GET	/api/apps/appointment/locations/:id/staff	ct.staffFindAllByLocation
POST	/api/apps/appointment/locations/:id/staff	ct.staffCreate
GET	/api/apps/appointment/staff/:id	ct.staffFindById
PUT	/api/apps/appointment/staff/:id	ct.staffUpdate
DELETE	/api/apps/appointment/staff/:id	ct.staffRemove

หมายเหตุเรื่อง routing: route ที่ใช้ชื่อ param เป็น :id แทน :locationId เป็นเพราะ gin บังคับให้ชื่อ param ใน subtree เดียวกันต้องตรงกัน ขณะที่ระบบ TypeScript เดิมใช้ :locationId

จุดเชื่อมต่อกับ Service อื่น

• สิทธิ์การเข้าถึง — แอปต้องถูกเปิดให้องค์กรก่อนจึงจะเรียกได้ ตรวจโดย AppEnabledGuard (ดู ระบบ Apps เสริม) ส่วน policy metadata ใช้ PolicyModuleLineOa
• ตารางที่เกี่ยวข้อง — booking, location, service, staff, journey, line_oa_app และ line_oa
• RabbitMQ — คิว booking_event_trigger เมื่อมีการเปลี่ยนสถานะการจอง
• โมดูลที่เกี่ยวข้อง — ระบบ Apps เสริม, กฎทริกเกอร์อัตโนมัติ, แอปสะสมแต้ม และ แอปกระดานประกาศ