หน้าแดชบอร์ด

ภาพรวม

แดชบอร์ดคือหน้าแรกที่ผู้ใช้เห็นหลังเลือก LINE OA เข้าใช้งาน ทำหน้าที่สรุปภาพรวมจำนวนเพื่อน (friend) ของ channel นั้น แยกเป็นกลุ่มสมาชิก (member) กลุ่มผู้เยี่ยมชม (guest) และกลุ่มที่บล็อก พร้อมกราฟแนวโน้มและรายการแคมเปญที่ตั้งเวลาไว้ในอีก 7 วันข้างหน้า

หน้านี้เปิดให้ทุกบทบาทที่มีสิทธิ์ดูข้อมูลแดชบอร์ด ตัวเลขหลักทั้งหมดมาจากปลายทางเดียวคือ GET /dashboard/total-friends ส่วนรายการแคมเปญด้านล่างยืมข้อมูลมาจากโมดูลจัดการแคมเปญ

ข้อควรทราบสำคัญ — ในเวอร์ชันปัจจุบัน มีเพียงการ์ดตัวเลขด้านบนเท่านั้นที่เป็นข้อมูลจริงจากเซิร์ฟเวอร์ กราฟเส้นแนวโน้มและกราฟแท่งกิจกรรมรายวันถูกประมาณขึ้นในฝั่งหน้าเว็บจากยอดต้นช่วงและปลายช่วง ไม่ใช่ยอดรายวันจริง รายละเอียดอยู่ในหัวข้อถัดไป

Business Flow

1. เปิดหน้าและกำหนดช่วงเวลา

1. ระบบตรวจสิทธิ์ดูข้อมูลแดชบอร์ดก่อน หากไม่ผ่านจะแสดงหน้าแจ้งว่าไม่มีสิทธิ์
2. ตั้งค่า breadcrumb และเมนูที่กำลังใช้งานให้สอดคล้องกัน
3. ช่วงเวลาที่ใช้ดึงข้อมูลถูกกำหนดเป็น 7 วันล่าสุด เสมอ นับจากวันปัจจุบันย้อนหลังไป 7 วัน หน้านี้ยังไม่มีตัวเลือกให้ผู้ใช้เปลี่ยนช่วงเวลาเอง

2. ดึงข้อมูลและคำนวณค่าที่แสดง

1. ระบบเรียก GET /dashboard/total-friends พร้อมช่วงวันที่ที่กำหนดไว้
2. เซิร์ฟเวอร์ตอบกลับเป็นชุดของเมตริก แต่ละเมตริกมีสี่ค่า คือ ยอด ณ ต้นช่วง ยอด ณ ปลายช่วง ส่วนต่างของช่วง และส่วนต่างเป็นเปอร์เซ็นต์
3. การ์ดแต่ละใบเลือกใช้ค่าที่ต่างกันตามความหมายที่ต้องการสื่อ การ์ดที่แสดงยอดสะสมใช้ค่า ณ ปลายช่วง ส่วนการ์ดที่แสดงความเคลื่อนไหวใช้ส่วนต่างของช่วง
4. ระหว่างที่ข้อมูลยังโหลดไม่เสร็จ ทุกการ์ดบนหน้าจะแสดงสถานะกำลังโหลดพร้อมกัน เพราะใช้คำขอเดียวกันทั้งหน้า

3. องค์ประกอบที่แสดงบนหน้า

แถวบนสุด ประกอบด้วยสามการ์ด

1. เพื่อนทั้งหมด — ยอดสะสมของเพื่อนทั้งหมด ณ ปัจจุบัน แสดงเป็นตัวเลขขนาดใหญ่พร้อมคำอธิบายสั้น
2. เพื่อนที่ยังใช้งานอยู่ — กราฟวงแหวนแบ่งสัดส่วนระหว่างสมาชิกกับผู้เยี่ยมชม โดยหักจำนวนที่บล็อกออกจากแต่ละกลุ่มแล้ว
3. ผู้ที่บล็อก — กราฟวงแหวนแสดงสัดส่วนผู้ที่บล็อก แยกเป็นสมาชิกกับผู้เยี่ยมชม หากไม่มีข้อมูลทั้งสองกลุ่มจะแสดงวงแหวนสีเทาพร้อมข้อความว่าไม่มีข้อมูล

กล่องกิจกรรมใน 7 วันล่าสุด มีการ์ดตัวเลขสองใบแยกตามกลุ่มผู้เยี่ยมชมและสมาชิก แต่ละใบแสดงจำนวนที่เพิ่มขึ้นและจำนวนที่บล็อกในช่วงเวลานั้น ตัวเลขจะเป็นสีเขียวเมื่อเพิ่มขึ้นและสีแดงเมื่อลดลง พร้อมเครื่องหมายบวกกำกับเมื่อเป็นค่าบวก

การ์ดกิจกรรมที่กำลังจะถึง แสดงแคมเปญที่ตั้งเวลาไว้ในอีก 7 วันข้างหน้า

กราฟแนวโน้มจำนวนเพื่อน เป็นกราฟเส้น 7 วัน แสดงสามเส้น คือ เพื่อนทั้งหมด สมาชิก และผู้เยี่ยมชม

กราฟกิจกรรมรายวัน เป็นกราฟแท่ง 7 วัน แสดงจำนวนเพื่อนใหม่และจำนวนผู้ที่บล็อกในแต่ละวัน

4. กิจกรรมที่กำลังจะถึง

1. ระบบคำนวณช่วงเวลาเองเป็นตั้งแต่ต้นวันนี้ถึงสิ้นวันในอีก 7 วันข้างหน้า
2. เรียกข้อมูลแคมเปญที่มีสถานะตั้งเวลาไว้ในช่วงนั้น เรียงตามวันที่เริ่มจากใกล้ที่สุด และจำกัดไม่เกิน 10 รายการ
3. แต่ละรายการแสดงป้ายวันที่ ชื่อแคมเปญ เวลาที่จะส่ง พร้อมคำกำกับว่าเป็นวันนี้ พรุ่งนี้ หรือวันที่ระบุ และป้ายสถานะที่ใช้สีเดียวกับระบบแคมเปญ
4. คลิกที่รายการเพื่อเปิดหน้ารายละเอียดแคมเปญ ปุ่มดูทั้งหมดพาไปยังปฏิทินวางแผนแคมเปญ
5. หากไม่มีแคมเปญในช่วงนั้น จะแสดงสถานะว่างพร้อมปุ่มลัดไปสร้างแคมเปญใหม่

5. ข้อควรระวังเรื่องความถูกต้องของข้อมูล

ประเด็นเหล่านี้สำคัญมากสำหรับผู้ที่นำตัวเลขจากหน้านี้ไปใช้งานต่อ

• กราฟเส้นแนวโน้มไม่ใช่ยอดรายวันจริง — ระบบลากเส้นตรงระหว่างยอด ณ ต้นช่วงกับยอด ณ ปลายช่วง เพราะเซิร์ฟเวอร์ยังไม่มีข้อมูลรายวันให้ ในโค้ดมีหมายเหตุกำกับไว้ชัดเจนว่าต้องเปลี่ยนเมื่อเซิร์ฟเวอร์รองรับ
• กราฟแท่งรายวันเป็นค่าที่กระจายแบบสุ่ม — ระบบนำส่วนต่างของทั้งช่วงมาหารเฉลี่ยเจ็ดวัน แล้วสุ่มกระจายใหม่โดยคงยอดรวมเดิม ค่าของแต่ละแท่งจึงเปลี่ยนทุกครั้งที่หน้าถูกวาดใหม่ มีเพียงยอดรวมทั้งสัปดาห์เท่านั้นที่ตรงกับข้อมูลจริง
• ตัวเลขสองกลุ่มเทียบกันตรงไม่ได้ — การ์ดด้านบนแสดงยอดสะสม ส่วนการ์ดกิจกรรมและกราฟแท่งแสดงส่วนต่างในช่วง 7 วัน
• ไม่มีการจัดการข้อผิดพลาด — หากการเรียกข้อมูลล้มเหลว ทุกการ์ดจะแสดงเลขศูนย์โดยไม่มีข้อความแจ้งเตือน

หน้าจอและองค์ประกอบหลัก

โครงสร้างของหน้า

หน้าแดชบอร์ดแบ่งเป็นชั้นบาง ๆ หลายชั้น โดยตรรกะการดึงข้อมูลอยู่ที่ตัวควบคุมกราฟ (src/components/dashboard/dashboard-chart/dashboard-chart.container.tsx) ซึ่งเรียก API เลือกค่าที่จะแสดง แล้วส่งต่อให้คอมโพเนนต์จัดวางองค์ประกอบทั้งหมดของหน้า

การ์ดและกราฟ

• การ์ดวงแหวน ใช้สำหรับเพื่อนที่ยังใช้งานอยู่และผู้ที่บล็อก มาพร้อมคำอธิบายสองบรรทัดใต้กราฟ
• การ์ดตัวเลข ใช้สำหรับสรุปความเคลื่อนไหวรายกลุ่ม โดยแยกสีพื้นหลังระหว่างกลุ่มผู้เยี่ยมชมกับกลุ่มสมาชิก
• กราฟเส้นและกราฟแท่ง อยู่ในโฟลเดอร์ src/components/dashboard/charts/ พร้อมไฟล์ลงทะเบียนองค์ประกอบของไลบรารีกราฟที่ต้องนำเข้าก่อนใช้งานเสมอ
• ชุดสีของกราฟและป้ายสถานะถูกรวมไว้ในไฟล์ค่าคงที่กลาง เพื่อให้สอดคล้องกันทั้งหน้า

กลุ่มกิจกรรมที่กำลังจะถึง

กลุ่มนี้แยกเป็นตัวควบคุมที่ดึงข้อมูลแคมเปญและจัดการการนำทาง คอมโพเนนต์รายการที่มีส่วนหัวส่วนท้ายและพื้นที่เลื่อน คอมโพเนนต์แถวรายการเดี่ยว และคอมโพเนนต์สถานะว่าง

การจัดวางแบบตอบสนอง

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

ปลายทาง API

การทำงาน	ปลายทาง
ตัวเลขเพื่อนทั้งหมดและกลุ่มย่อย	GET /dashboard/total-friends
แคมเปญที่ตั้งเวลาไว้ 7 วันข้างหน้า	GET /campaign

จุดเชื่อมต่อกับฟีเจอร์อื่น

• เข้าสู่ระบบ — แดชบอร์ดเป็นปลายทางหลังเลือก LINE OA สำเร็จ และข้อมูลที่แสดงถูกจำกัดขอบเขตอยู่ที่ channel ที่เลือกโดยอัตโนมัติ
• สิทธิ์การเข้าถึง — หน้านี้ถูกปลดล็อกจากโมดูล dashboard ฝั่งเซิร์ฟเวอร์ และใช้เพียงสิทธิ์ดูข้อมูลเท่านั้น
• จัดการแคมเปญ — การ์ดกิจกรรมที่กำลังจะถึงดึงข้อมูลจากโมดูลแคมเปญโดยตรง ทั้งข้อมูล สถานะ และปลายทางของลิงก์
• ปฏิทินวางแผนแคมเปญ — ปุ่มดูทั้งหมดบนการ์ดกิจกรรมพาไปยังหน้าปฏิทิน
• ที่มาของตัวเลข — ยอดสมาชิก ผู้เยี่ยมชม และผู้ที่บล็อก มาจากข้อมูลผู้ใช้ LINE ฝั่งเซิร์ฟเวอร์ที่ถูกอัปเดตโดย webhook เมื่อมีการติดตามหรือเลิกติดตาม รวมถึงงานซิงก์ผู้ติดตาม หากตัวเลขไม่ตรงกับความเป็นจริง ควรตรวจสอบที่ระบบเหล่านั้นก่อน ไม่ใช่ที่หน้าแดชบอร์ด

รายละเอียดฝั่ง Backend (CMS API)

โมดูล dashboard ฝั่ง cms-api เป็นโมดูลที่เล็กที่สุดโมดูลหนึ่งของระบบ — มี endpoint เดียวคือ GET /api/dashboard/total-friends ไม่มีการรวมศูนย์ตัวเลขจากฟีเจอร์อื่นไว้ที่นี่เลย ตัวเลขอื่นบนหน้าจอ เช่น รายการแคมเปญที่กำลังจะถึง มาจาก endpoint ของโมดูลนั้น ๆ โดยตรง

เงื่อนไขที่ backend ใช้นับจำนวนเพื่อน

การนับทำบนตารางผู้ใช้ LINE โดยมีเงื่อนไขพื้นฐาน 4 ข้อที่ใช้กับทุกเมตริก

1. จำกัดขอบเขตด้วยรหัส LINE OA จาก token ไม่ได้รับรหัส OA จากพารามิเตอร์ที่ผู้เรียกส่งมา จึงข้าม channel กันไม่ได้
2. นับเฉพาะแถวที่ถูกสร้างก่อนหรือเท่ากับวันที่ที่ระบุ ซึ่งเป็นกลไกที่ทำให้ดูยอด ณ ต้นช่วงและปลายช่วงย้อนหลังได้
3. นับเฉพาะแถวที่ผูกกับผู้ใช้ LINE จริงแล้วเท่านั้น แถวที่ยังไม่มีการเชื่อมโยงจะถูกตัดออก ตัวเลขจึงอาจน้อยกว่าจำนวนแถวทั้งหมดในตาราง
4. ไม่นับแถวที่ถูกลบแบบ soft delete

จากนั้นจึงเพิ่มเงื่อนไขเฉพาะของแต่ละเมตริกทับลงไป เช่น แยกกลุ่มที่ติดตาม เลิกติดตาม และบล็อก

ทำไมกราฟรายวันจึงเป็นค่าประมาณ

ข้อสังเกตในหัวข้อความถูกต้องของข้อมูลข้างต้นมีคำอธิบายตรงไปตรงมาจากฝั่ง backend: endpoint นี้คืนเฉพาะยอด ณ จุดเวลาที่ระบุ ไม่ได้คืนชุดข้อมูลรายวัน หน้าเว็บจึงมีข้อมูลจริงเพียงยอดต้นช่วงกับปลายช่วงเท่านั้น กราฟเส้นและกราฟแท่งรายวันจึงต้องประมาณขึ้นเอง หากต้องการให้กราฟแสดงข้อมูลจริง ต้องแก้ที่ฝั่ง backend ให้คืนชุดข้อมูลรายวันก่อน แก้เฉพาะฝั่งหน้าเว็บไม่ได้

สิทธิ์ที่ต้องมี

• ต้องผ่าน guard JWT ปกติ ซึ่งบังคับว่า token ต้องมีรหัส LINE OA แล้ว — เป็นเหตุผลเชิงเทคนิคที่แดชบอร์ดเป็นปลายทางหลังเลือก channel เท่านั้น
• ไม่มี ModuleGate และไม่มี guard ระดับ super admin บนเส้นทางนี้ ผู้ใช้ทุกคนที่มี token ที่ระบุ OA แล้วเรียกได้จริง
• ข้อมูลกำกับสิทธิ์ระดับโมดูล dashboard มีอยู่แต่ยังไม่ถูกบังคับใช้ การซ่อนเมนูฝั่งหน้าเว็บจึงเป็นการควบคุมที่ผู้ใช้เห็น ไม่ใช่การปิดกั้นที่ API