ติดตามที่มาของเพื่อน (Friend Track)

ภาพรวม

Friend Track ตอบคำถามว่า "เพื่อนคนนี้เข้ามาจากช่องทางไหน" ด้วยการสร้าง แคมเปญติดตาม ที่มีลิงก์เชิญเพิ่มเพื่อนพร้อม ref code แยกตามช่องทาง เมื่อมีคนกดลิงก์แล้วเพิ่มเพื่อน ระบบจะบันทึกว่าเพื่อนรายนั้นมาจาก ref ใด

โมดูลนี้ออกแบบมารองรับ ref จำนวนมาก จึงมีการ อัปโหลด ref เป็นไฟล์ CSV เช่น การสร้าง ref แยกตามพนักงาน แยกตามสาขา หรือแยกตาม QR code หลายพันใบ และสามารถดาวน์โหลดลิงก์ที่สร้างเสร็จแล้วกลับไปเป็น CSV ได้

Business Flow

สร้างและจัดการแคมเปญ

1. POST /api/friend-track สร้างแคมเปญติดตาม โดยระบุชื่อ ช่วงเวลา และการตั้งค่า ref
2. GET /api/friend-track คืนรายการแคมเปญแบบแบ่งหน้า กรองได้ตาม FilterFriendTrackCampaignDto
3. PUT /api/friend-track/:id แก้ไขแคมเปญ และ DELETE /api/friend-track/:id ลบแคมเปญ

จัดการ ref จำนวนมาก

4. POST /api/friend-track/:id/refs/upload รับไฟล์ CSV รายการ ref แบบ multipart โดยระบบใช้ raw SQL แบบ INSERT ... ON CONFLICT เป็น batch เพื่อรองรับปริมาณสูงและป้องกันข้อมูลซ้ำ
5. GET /api/friend-track/:id/refs/status ใช้ poll ดูสถานะการอัปโหลดว่ากำลังทำงาน เสร็จสิ้น หรือเกิดข้อผิดพลาด
6. GET /api/friend-track/:id/refs/download ดาวน์โหลดลิงก์และ ref ทั้งหมดเป็นไฟล์ CSV โดย stream ลง response โดยตรง ไม่โหลดข้อมูลทั้งก้อนเข้า memory

ดูรายงาน

7. GET /api/friend-track/:id ดูรายละเอียดของแคมเปญ
8. GET /api/friend-track/:id/report คืนรายงานว่าแต่ละ ref ได้เพื่อนมากี่คน กรองตามช่วงเวลาหรือ ref ได้ผ่าน FilterFriendTrackReportDto โดยการนับจำนวนผู้ใช้ในรายงานทำผ่าน getRawMany().length ตามระบบเดิม ไม่ได้ใช้ COUNT()
9. เมื่อมีผู้ใช้เพิ่มเพื่อนผ่านลิงก์ ฝั่ง webhook-go จะบันทึก event ลงตาราง friend_track_event พร้อมผูกกับ friend_track_campaign และ ref ที่ถูกใช้

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

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

Method	Route	Handler	Policy
GET	/api/friend-track	ct.findAll	readAll friend-track
GET	/api/friend-track/:id	ct.findByID	read friend-track
GET	/api/friend-track/:id/report	ct.getReport	read friend-track
GET	/api/friend-track/:id/refs/download	ct.downloadRefLinks	read friend-track
GET	/api/friend-track/:id/refs/status	ct.getRefUploadStatus	read friend-track
POST	/api/friend-track	ct.create	create friend-track
POST	/api/friend-track/:id/refs/upload	ct.uploadRefs	update friend-track
PUT	/api/friend-track/:id	ct.update	update friend-track
DELETE	/api/friend-track/:id	ct.delete	delete friend-track

ทุก route ครอบด้วย modulegate.ModuleGate(d, "friend-track")

note

PolicyModuleFriendTrack ยังถูกใช้เป็น policy metadata ของ endpoint GET /api/apps และ PUT /api/apps/:appId ด้วย ซึ่งเป็นพฤติกรรมที่ยกมาจากระบบเดิม

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

• Permission — ต้องผ่าน ModuleGate("friend-track") และมี PolicyModuleFriendTrack เป็น metadata
• ตารางที่เกี่ยวข้อง — friend_track_campaign, friend_track_event, line_user และ line_oa
• Storage — เก็บไฟล์ CSV ของ ref ไว้บน object storage
• ผู้เขียน event — line-management-webhook-go เป็นผู้บันทึก event เมื่อได้รับ follow event
• โมดูลที่เกี่ยวข้อง — LINE User Management, Tracking Link และ All Friend Listing