แอปสะสมแต้มและรางวัล

ภาพรวม

แอป loyalty คือระบบบัตรสะสมแต้มหรือแสตมป์และการแลกรางวัลผ่าน LINE ประกอบด้วยองค์ประกอบหลักดังนี้

องค์ประกอบ	ความหมาย
Program	ตัวโปรแกรมหลัก กำหนดโหมดแต้มหรือแสตมป์ ขนาดบัตร และสถานะเปิดปิด
Milestones	เป้าหมายสะสม สะสมครบตามกำหนดแล้วได้รางวัลที่ระบุ
Tiers	ระดับสมาชิก ใช้ได้เฉพาะโหมดแต้ม จัดอันดับด้วยค่า rank
Branches	สาขาที่ให้แต้มและแลกรางวัลได้
Staff	พนักงานที่มีสิทธิ์ให้แต้ม บริหารด้วยระบบคำเชิญ
Activity / Customers	ประวัติการทำรายการและข้อมูลลูกค้าสมาชิก

โมดูลนี้ใช้ ชุด error code เดียวกับ client-api เพื่อให้ทั้งสองฝั่งสื่อสารด้วยรหัสข้อผิดพลาดชุดเดียวกัน

Business Flow

ตั้งค่าโปรแกรม

1. GET /api/apps/loyalty/program อ่านโปรแกรมปัจจุบัน หากยังไม่มีจะได้ error LOYALTY_PROGRAM_MISSING
2. PUT /api/apps/loyalty/program บันทึกโปรแกรม เช่น โหมดและขนาดบัตร หากขนาดบัตรไม่ถูกต้องจะได้ LOYALTY_CARD_SIZE_INVALID
3. PUT /api/apps/loyalty/program/status เปิดหรือปิดโปรแกรม

สร้างบันไดรางวัล

4. Milestones จัดการผ่าน GET /api/apps/loyalty/milestones, POST /api/apps/loyalty/milestones, PUT /api/apps/loyalty/milestones/:id และ DELETE /api/apps/loyalty/milestones/:id
5. Tiers จัดการผ่าน GET /api/apps/loyalty/tiers, POST /api/apps/loyalty/tiers, PUT /api/apps/loyalty/tiers/:id และ DELETE /api/apps/loyalty/tiers/:id
   • ใช้ได้เฉพาะโหมดแต้ม หากโปรแกรมอยู่ในโหมดอื่นจะได้ LOYALTY_TIER_POINT_MODE_ONLY
   • หากตัวเลขไม่สมเหตุสมผลจะได้ LOYALTY_TIER_INVALID
   • หากค่า rank ซ้ำกับระดับที่มีอยู่จะได้ LOYALTY_TIER_RANK_TAKEN
6. POST /api/apps/loyalty/tiers/recalculate คำนวณระดับสมาชิกใหม่ทันที นอกเหนือจาก job รายคืน endpoint นี้มีไว้เพราะร้านที่เพิ่งตั้งบันไดรางวัลเสร็จไม่ควรต้องรอถึงตีสามเพื่อตรวจว่าตั้งค่าถูกต้องหรือไม่

สาขาและพนักงาน

7. Branches จัดการผ่าน GET /api/apps/loyalty/branches, POST /api/apps/loyalty/branches และ DELETE /api/apps/loyalty/branches/:id
8. Staff จัดการผ่าน GET /api/apps/loyalty/staff, POST /api/apps/loyalty/staff/invite สำหรับส่งคำเชิญ, PUT /api/apps/loyalty/staff/:id สำหรับแก้ไข และ DELETE /api/apps/loyalty/staff/:id สำหรับเพิกถอนคำเชิญ

ดูข้อมูลลูกค้า

9. GET /api/apps/loyalty/activity ดูประวัติการให้แต้มและการแลกรางวัล
10. GET /api/apps/loyalty/customers ค้นหาลูกค้าสมาชิก
11. GET /api/apps/loyalty/customer ดูข้อมูลลูกค้ารายคนแบบ lookup

ฝั่งผู้ใช้และพนักงานหน้าร้าน

การให้แต้มและการแลกรางวัลจริงทำผ่าน client-api ในรูปแบบ LIFF ไม่ได้ทำผ่าน endpoint ในเอกสารนี้

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

โค้ดอยู่ที่ internal/modules/loyalty/

ไฟล์	บทบาท
controller.go	ลงทะเบียน route โดยทุก route มี apps.AppEnabledGuard(d)
service_program.go	ProgramService ดูแลโปรแกรมหลักและนิยาม error code
service_catalog.go	CatalogService ดูแลบันไดรางวัล สาขา และ allowlist ของพนักงาน

ทุก route อยู่บน group authed ต่อด้วย appEnabled และ policy (PolicyModuleLineOa)

Method	Route	Handler	Policy
GET	/api/apps/loyalty/program	ct.getProgram	read
PUT	/api/apps/loyalty/program	ct.saveProgram	update
PUT	/api/apps/loyalty/program/status	ct.setProgramStatus	update
GET	/api/apps/loyalty/milestones	ct.listMilestones	readAll
POST	/api/apps/loyalty/milestones	ct.createMilestone	create
PUT	/api/apps/loyalty/milestones/:id	ct.updateMilestone	update
DELETE	/api/apps/loyalty/milestones/:id	ct.deleteMilestone	delete
GET	/api/apps/loyalty/tiers	ct.listTiers	readAll
POST	/api/apps/loyalty/tiers	ct.createTier	create
PUT	/api/apps/loyalty/tiers/:id	ct.updateTier	update
DELETE	/api/apps/loyalty/tiers/:id	ct.deleteTier	delete
POST	/api/apps/loyalty/tiers/recalculate	ct.recalculateTiers	update
GET	/api/apps/loyalty/branches	ct.listBranches	readAll
POST	/api/apps/loyalty/branches	ct.createBranch	create
DELETE	/api/apps/loyalty/branches/:id	ct.deleteBranch	delete
GET	/api/apps/loyalty/activity	ct.listActivity	readAll
GET	/api/apps/loyalty/customers	ct.searchCustomers	readAll
GET	/api/apps/loyalty/customer	ct.lookupCustomer	readAll
GET	/api/apps/loyalty/staff	ct.listStaff	readAll
POST	/api/apps/loyalty/staff/invite	ct.createInvite	create
PUT	/api/apps/loyalty/staff/:id	ct.updateStaff	update
DELETE	/api/apps/loyalty/staff/:id	ct.revokeInvite	delete

Error code ทั้งหมดนิยามใน service_program.go ได้แก่ LOYALTY_PROGRAM_MISSING, LOYALTY_TIER_POINT_MODE_ONLY, LOYALTY_TIER_INVALID, LOYALTY_TIER_RANK_TAKEN และ LOYALTY_CARD_SIZE_INVALID

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

• สิทธิ์การเข้าถึง — ทุก route ผ่าน apps.AppEnabledGuard(d) แอปต้องถูกเปิดให้องค์กรก่อน (ดู ระบบ Apps เสริม) ส่วน policy metadata ใช้ PolicyModuleLineOa
• ตารางที่เกี่ยวข้อง — กลุ่ม loyalty ที่นิยามใน internal/entities/loyalty.go ครอบคลุม program, milestone, tier, branch, staff, activity หรือ transaction และ customer membership รวมถึง line_oa_app, line_oa และ line_user
• Job รายคืน — การคำนวณ tier ใหม่รอบ 03:00 ทำที่ worker
• Cross-service — line-management-client-api-go ใช้ชุด error code เดียวกัน
• โมดูลที่เกี่ยวข้อง — ระบบ Apps เสริม, แอปจองคิว/นัดหมาย, แอปกระดานประกาศ และ จัดการผู้ใช้ LINE