จัดการกลุ่มเป้าหมาย

ภาพรวม

Audience คือกลุ่มเป้าหมายที่ใช้เล็งการส่งข้อความในแคมเปญ ผูกกับ rich menu หรือใช้เป็นเงื่อนไขจุด trigger จุดออกแบบที่สำคัญคือสมาชิกของ audience ถูกเก็บเป็นไฟล์ CSV บน object storage ไม่ใช่แถวในฐานข้อมูล เพื่อรองรับสมาชิกจำนวนมหาศาล การอ่านรายชื่อสมาชิกกลับมาจึงต้องผ่าน CSV Engine

โมดูลนี้ยังมี cron ที่ทำงานทุกนาทีเพื่อ auto-refresh audience ที่ตั้งค่าไว้ และเก็บ audit log การเข้าออกของสมาชิกไว้ในตาราง audience_member_log

Business Flow

สร้างและเรียกดู

1. GET /api/audiences ลิสต์ audience แบบแบ่งหน้า
2. POST /api/audiences (multipart/form-data) สร้าง audience ใหม่ โดยระบบตรวจโควตา maxSegments ตามแพ็กเกจก่อน หากชื่อซ้ำจะตอบ error AUD_001 ผู้ใช้อัปโหลดไฟล์ CSV หรือระบุเงื่อนไข filter จากนั้นระบบ publish งานลง queue create_audience ให้ worker สร้างไฟล์สมาชิกต่อไป
3. GET /api/audiences/:id ดูรายละเอียด ได้แก่ จำนวนสมาชิก เงื่อนไข และสถานะปัจจุบัน
4. GET /api/audiences/:id/member ดูรายชื่อสมาชิกแบบแบ่งหน้า โดยอ่านไฟล์ CSV ผ่าน CSV Engine พร้อม cache 30 วินาที
5. PUT /api/audiences/:id แก้ไข ซึ่งจะ publish งานลง queue update_audience
6. DELETE /api/audiences/:id ลบ ซึ่งจะ publish งานลง queue delete_audience

ส่งออกข้อมูล

7. GET /api/audiences/:id/export ส่งออกรายชื่อสมาชิกเป็น CSV โดย stream ตรงลง response
8. GET /api/audiences/:id/export-detail ส่งออกพร้อมรายละเอียดของสมาชิก หากส่งออกไม่ได้จะตอบ error AUD_004 และหากไม่พบสมาชิกจะตอบ AUD_005

Auto-refresh

9. PATCH /api/audiences/:id/auto-refresh เปิดหรือปิด auto-refresh เป็นราย audience ทั้งนี้แพ็กเกจขององค์กรต้องมีสิทธิ์ autoRefresh ด้วย
10. cron ชื่อ AudienceRefreshScheduler ทำงานทุกนาทีตาม schedule * * * * * โดยใช้ Redis lock ป้องกันไม่ให้หลาย replica ทำงานซ้อนกัน เมื่อพบ audience ที่ครบกำหนดจะ publish ลง queue audience_refresh
11. POST /api/audiences/:id/refresh สั่ง refresh ทันทีแบบ manual โดยไม่ต้องรอรอบ cron

ติดตามการเปลี่ยนแปลงสมาชิก

12. GET /api/audiences/:id/member-logs ดูประวัติการเข้าออกของสมาชิกจากตาราง audience_member_log
13. การเข้าออกของสมาชิกยัง publish เป็น event ลง queue audience_membership_trigger เพื่อให้ Trigger Rule นำไปสั่งงานต่อได้

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

โค้ดหลักอยู่ที่ internal/modules/audience/ ประกอบด้วย controller.go, service.go, scheduler.go, helpers.go, types.go และ dto.go โดย register บน group authed.Group("/audiences") พร้อม modulegate.ModuleGate(d, "audiences")

Method	Route	Handler	Policy (metadata)
GET	/api/audiences	svc.getListHandler	readAll audiences
GET	/api/audiences/:id	svc.getByIDHandler	read audiences
GET	/api/audiences/:id/member	svc.getMemberByAudienceIDHandler	read audiences
GET	/api/audiences/:id/member-logs	svc.getMemberLogsHandler	read audiences
GET	/api/audiences/:id/export	svc.getExportReportAllFriendHandler	export audiences
GET	/api/audiences/:id/export-detail	svc.exportMembersDetailHandler	export audiences
POST	/api/audiences	svc.createHandler	create audiences
PUT	/api/audiences/:id	svc.updateHandler	update audiences
PATCH	/api/audiences/:id/auto-refresh	svc.updateAutoRefreshHandler	update audiences
POST	/api/audiences/:id/refresh	svc.triggerManualRefreshHandler	update audiences
DELETE	/api/audiences/:id	svc.deleteByIDHandler	delete audiences

Scheduler ลงทะเบียนผ่าน audience.RegisterScheduler(d) ซึ่งเรียก d.Scheduler.Register("* * * * *", "AudienceRefreshScheduler", s.handleAudienceRefresh) โดยถูกเรียกทั้งใน RegisterRoutes และใน cmd/api/modules.go ที่ฟังก์ชัน registerSchedulers

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

• สิทธิ์การเข้าถึง — ต้องผ่าน ModuleGate("audiences") โดย PolicyModuleAudiences เป็น metadata
• ตารางที่เกี่ยวข้อง — audience, audience_member_log, line_user, line_oa, api_client, organization
• RabbitMQ — queue create_audience, update_audience, delete_audience, audience_refresh และ audience_membership_trigger
• Redis — ใช้เป็น lock ของ cron refresh เพื่อกันการทำงานซ้อนกันระหว่าง replica
• Storage และ CSV Engine — ไฟล์รายชื่อสมาชิกถูกเก็บบน MinIO หรือ S3 และอ่านกลับผ่าน CSV Engine
• Cross-module — planlimits สำหรับโควตา maxSegments และสิทธิ์ autoRefresh รวมถึงโมดูล apiclient
• รหัสข้อผิดพลาด — AUD_001 ชื่อซ้ำ, AUD_002 ไม่ใช่ audience, AUD_003 CSV ไม่ถูกต้อง, AUD_004 ส่งออกไม่ได้ และ AUD_005 ไม่พบ LINE user
• โมดูลที่เกี่ยวข้อง — Audience Filter (ตัวสร้าง audience จากเงื่อนไข), Campaign Management, Rich Menu และ Trigger Rule