Skip to content
TaijiFlow Phase 3 Research

สถาปัตยกรรมจาวาสคริปต์และสารบัญระบบโค้ดฉบับสมบูรณ์ 99 ไฟล์ ​

(TaijiFlow AI - Comprehensive JavaScript Architecture & 99-File Catalog Specification) ​

โครงการ: TaijiFlow AI - Taiji Digital Twin & Movement Biomechanics Evaluation System
ผู้จัดทำ: ทีมวิจัยและพัฒนาระบบชีวกลศาสตร์ดิจิทัล TaijiFlow AI
วันที่ปรับปรุงล่าสุด: 23 ตุลาคม 2026
สถานะสถาปัตยกรรม: Phase 4 Modular Micro-Subsystems (100% Production Ready, 19/19 Test Suites Passed)


สารบัญหลัก (Table of Contents) ​


บทที่ 1: บทนำและภาพรวมวิวัฒนาการสถาปัตยกรรม (Architecture Evolution) ​

1.1 จาก Monolithic Script (57 ไฟล์) สู่ Modular Micro-Subsystems (99 ไฟล์) ​

ในระยะแรกเริ่มของการพัฒนา (กุมภาพันธ์ 2026) ระบบ TaijiFlow AI ประกอบด้วยไฟล์สคริปต์ 57 ไฟล์ โดยมีลักษณะของ "God Files" (ไฟล์ก้อนมหึมาที่รวมทุกอย่างไว้ในที่เดียว) อยู่หลายจุด เช่น landing_controller.js (1,375 บรรทัด), drawing_manager.js (1,403 บรรทัด), main_controller.js (1,548 บรรทัด), และ research_mode_controller.js (1,682 บรรทัด) ซึ่งส่งผลให้การดูแลรักษา การทดสอบ Unit Test และการแยกความรับผิดชอบทำได้ยากลำบาก

ในไตรมาสที่ 3-4 ปี 2026 จึงได้มีการดำเนินงานตาม Codebase Refactoring Master Plan แตกไฟล์ออกเป็นโครงสร้างย่อย (Micro-Subsystems) โดยปัจจุบันระบบประกอบด้วยไฟล์ JavaScript ทั้งหมด 99 ไฟล์ ภายใต้ไดเรกทอรี src/js/ ซึ่งจัดหมวดหมู่อย่างเป็นระเบียบตามหลักวิศวกรรมซอฟต์แวร์สากล

1.2 สถิติเชิงปริมาณของระบบรหัสต้นฉบับ (Quantitative Codebase Metrics) ​

หมวดหมู่สถิติ (Metric Category)สถิติเดิม (กุมภาพันธ์ 2026)สถิติปัจจุบัน (ตุลาคม 2026)การเปลี่ยนแปลง (Delta)
จำนวนไฟล์ JavaScript รวม (src/js/)57 ไฟล์99 ไฟล์เพิ่มขึ้น +73.6% (แตกเป็นโมดูลอิสระ)
ขนาดไฟล์สูงสุดเดี่ยว (Max File Size)1,682 บรรทัด1,239 บรรทัดลดลง -26.3%
ขนาดของ Controller หน้าแรก (landing_controller.js)1,375 บรรทัด53 บรรทัดลดลง -96.1% (เหลือเฉพาะ Orchestrator)
ขนาดของ Canvas Drawing Coordinator (drawing_manager.js)1,403 บรรทัด253 บรรทัดลดลง -81.9% (แตกเป็น 4 Sub-renderers)
จำนวน Sub-renderers บนผืนผ้าใบ Canvas0 โมดูล4 โมดูลเฉพาะทางแยกระบบเรนเดอร์โครงกระดูก, วิถี, แสงชี่ และ HUD
จำนวนกฎเกณฑ์การประเมินมวยไท่เก๊ก (Rules Engine)9 กฎ12 กฎ (4 Categories)ครอบคลุม Bimanual Coordination สมบูรณ์
เครื่องยนต์คำนวณชีวกลศาสตร์ (SPARC, CRP, Delay)0 โมดูล2 โมดูลทางคลินิกสนับสนุนงานวิจัยระดับปริญญาเอก
จำนวนชุดทดสอบอัตโนมัติ (Jest Unit Test Suites)10 Suites (98 Tests)19 Suites (170 Tests)ผ่าน 100% ครอบคลุมการทำงาน

บทที่ 2: ผังภาพสถาปัตยกรรมระบบรวมและการแบ่งเลเยอร์ (System Topology & Layering) ​

สถาปัตยกรรมของ TaijiFlow AI ถูกจัดระเบียบตามแนวคิด Layered Architecture & Inversion of Control เพื่อให้การทำงานในแต่ละส่วนเป็นอิสระต่อกัน (Decoupled) และสามารถทดสอบแยกส่วนได้

📊 Diagram 1: System Layer Topology & Component Interaction ​

แผนภาพแสดงความสัมพันธ์ของ 6 เลเยอร์หลัก และการส่งผ่านข้อมูลในระบบ:


📊 Diagram 2: Dual Entry Point Architecture ​

โครงสร้างระบบแบ่งออกเป็น 2 สภาพแวดล้อมทางสถาปัตยกรรม (Dual Entry Points) อย่างชัดเจน:


บทที่ 3: เส้นทางการไหลของข้อมูลและวงจรชีวิตของระบบ (Data Pipelines & Lifecycle States) ​

3.1 Pipeline A: การประเมินผลท่ารำแบบเรียลไทม์ (Real-Time Vision-to-Feedback Loop) ​

ระบบประมวลผลวิดีโอแบบ Local Client-Side ที่ความเร็ว 30-60 เฟรมต่อวินาที (FPS) โดยไม่มีการส่งภาพวิดีโอออกนอกเครื่องของผู้ใช้ เพื่อรักษาความเป็นส่วนตัวสูงสุด (Privacy-Preserving Edge Architecture)

📊 Diagram 3: Real-Time Frame Evaluation Pipeline (Sequence Diagram) ​


3.2 Pipeline B: วงจรชีวิตการคาลิเบรตสรีระและการนอร์มัลไลซ์ (Body Calibration Lifecycle) ​

📊 Diagram 4: Body Calibration Lifecycle ​


3.3 Pipeline C: เวิร์กโฟลว์การทดลองวิจัยระดับคลินิก (Research Mode Protocol) ​

📊 Diagram 5: Research Mode Protocol State Machine ​


3.4 Pipeline D: สถาปัตยกรรมการเรนเดอร์ผืนผ้าใบแบบแยกส่วน (Canvas Sub-Rendering Architecture) ​

📊 Diagram 6: DrawingManager & Sub-Renderers Modular Architecture ​


บทที่ 4: สารบัญแจกแจงไฟล์ทั้ง 99 ไฟล์อย่างละเอียด (Comprehensive 99-File Catalog) ​

สารบัญนี้แจกแจงไฟล์ JavaScript ทั้ง 99 ไฟล์ในระบบ src/js/ โดยแบ่งออกเป็น 10 ซับซิสเต็มและไฟล์ระดับราก พร้อมระบุขนาด คลาสหลัก หน้าที่ความรับผิดชอบ และความสัมพันธ์ในการเชื่อมต่อ:


4.1 แกนกลางของระบบ (Core Engine - 8 ไฟล์) ​

ไดเรกทอรี: src/js/core/
หน้าที่หลัก: บรรจุกลไกการคำนวณและประมวลผลพื้นฐานของระบบ เช่น การสร้าง Instance, การคาลิเบรต, การให้คะแนน และการจัดการกล้อง

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
app_bootstrap.jsAppBootstrap389ศูนย์กลาง Dependency Injection (DI) สร้างอินสแตนซ์ของ Managers ทั้งหมด และลงทะเบียนลงใน window.TaijiFlowสร้าง: ทุก Managers ในระบบ
ถูกเรียกใช้โดย: app.html เมื่อเริ่มต้นโหลดหน้าจอ
calibration_manager.jsCalibrationManager395จัดการขั้นตอนการตรวจจับท่ายืน T-Pose นับถอยหลัง 3 วินาที และคำนวณสัดส่วนร่างกายเพื่อใช้ Normalizationเรียกใช้: MathUtils
ถูกเรียกใช้โดย: MainController, PoseProcessor, HeuristicsEngine
camera_manager.jsCameraManager354ควบคุมสตรีมวิดีโอจากเว็บแคม การสลับกล้องหน้า/หลัง การ Mirror ภาพ และการเชื่อมต่อกับ MediaPipe Loopเรียกใช้: navigator.mediaDevices
ถูกเรียกใช้โดย: AppBootstrap, MainController
heuristics_engine.jsHeuristicsEngine420เอนจินวิเคราะห์ความถูกต้องของมวยไท่เก๊ก ทำหน้าที่ลงทะเบียนและเรียกประมวลผลกฎ 12 ข้อตามแต่ละท่ารำเรียกใช้: rules/ (12 Rules), MathUtils
ถูกเรียกใช้โดย: PoseProcessor, ScoringManager
performance_monitor.jsPerformanceMonitor71ตรวจวัดและเก็บสถิติอัตราเฟรมภาพต่อวินาที (FPS) และความหน่วงของการประมวลผล (Processing Latency)เรียกใช้: performance.now()
ถูกเรียกใช้โดย: CameraManager, PoseProcessor, DebugManager
replay_manager.jsReplayManager208จัดการการบันทึกเฟรมภาพลงบัฟเฟอร์ และเล่นย้อนหลังการรำ (Replay Playback) พร้อมปรับความเร็วได้เรียกใช้: Memory Array Buffer
ถูกเรียกใช้โดย: ReplayController, ScoringManager
robot_manager.jsRobotManager295จัดการระบบครูฝึกหุ่นยนต์จำลอง (Virtual Robot Avatar Guide) สำหรับช่วยนำการรำเรียกใช้: DOM Elements
ถูกเรียกใช้โดย: RobotPopupManager, MainController
scoring_manager.jsScoringManager360ประมวลผลคะแนนรวม (0-100) ถ่วงน้ำหนักความผิดพลาดตามกฎ คำนวณเกรด และผนวกข้อมูลชีวกลศาสตร์ (SPARC/CRP)เรียกใช้: BiomechanicalAnalytics, I18nManager
ถูกเรียกใช้โดย: HeuristicsEngine, ScorePopupManager

4.2 การวิเคราะห์ชีวกลศาสตร์ (Biomechanics Analytics - 2 ไฟล์) ​

ไดเรกทอรี: src/js/biomechanics/
หน้าที่หลัก: การวิเคราะห์สมการชีวกลศาสตร์ขั้นสูงสำหรับงานวิจัยปริญญาเอกและระบบจำลองกายวิภาค

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
biomechanical_analytics.jsBiomechanicalAnalytics447คำนวณความนุ่มนวลการเคลื่อนไหวผ่าน Spectral Arc Length (SPARC), Continuous Relative Phase (CRP) และ Proximal-to-Distal Delayเรียกใช้: MathUtils
ถูกเรียกใช้โดย: ScoringManager, ResearchModeController
skeleton_simulator.jsSkeletonSimulator488จำลองการเคลื่อนไหวของกระดูกเชิงชีวกลศาสตร์สำหรับสร้าง Synthetic Motion Data และทดสอบโมเดลเรียกใช้: MathUtils
ถูกเรียกใช้โดย: Unit Tests, ResearchModeController

4.3 กฎการประเมินวิถีมวย (Heuristic Rules Engine - 15 ไฟล์) ​

ไดเรกทอรี: src/js/rules/
หน้าที่หลัก: ถอดรหัสคัมภีร์มวยไท่เก๊กตระกูลเฉินเป็นกฎทางคณิตศาสตร์ 12 ข้อ ครอบคลุม 4 หมวดหมู่

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
base_rule.jsBaseRule86คลาสแม่บท (Abstract Base Class) กำหนดโครงสร้างมาตรฐานสำหรับคลาสประเมินกฎทุกข้อถูกสืบทอดโดย: กฎ R1 ถึง R12 ทุกไฟล์
biomechanics_rules_config.jsBIOMECH_RULES_CONFIG96จัดเก็บค่าคอนฟิกพารามิเตอร์ เกณฑ์คะแนน และ Threshold ทางชีวกลศาสตร์ของกฎแต่ละข้อถูกเรียกใช้โดย: HeuristicsEngine, RulesConfigManager
kinematic_pose_model.jsKinematicPoseModel168คำนวณพิกัดกายวิภาคตามโมเดล Kinematics สำหรับใช้ตรวจสอบตำแหน่งทางสรีระถูกเรียกใช้โดย: HeuristicsEngine, Unit Tests
rule_path_shape.jsRulePathShape (R-01)120ตรวจสอบวิถีโค้งรูปวงกลม/วงรีของการรำสาวไหม (Circular Path Completeness)สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_arm_rotation.jsRuleArmRotation (R-02)94ตรวจสอบการควงเกลียวของแขนและทิศทางการหงาย/คว่ำของฝ่ามือ (Spiral Rotation)สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_elbow_sinking.jsRuleElbowSinking (R-03)52ตรวจสอบการจมข้อศอกคลายหัวไหล่ ไม่ให้ศอกลอยสูงเกินแนวไหล่ (Sunken Elbow)สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_waist_initiation.jsRuleWaistInitiation (R-04)85ตรวจสอบการเคลื่อนไหวเริ่มต้นจากเอว โดยเอวต้องหมุนนำพาแขน (Waist Leads Hands)สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_vertical_stability.jsRuleVerticalStability (R-05)72ตรวจสอบความนิ่งของแกนศีรษะและลำตัว ไม่ให้กระเพื่อมขึ้นลงผิดธรรมชาติสืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_smoothness.jsRuleSmoothness (R-06)75ตรวจสอบความสม่ำเสมอและความนุ่มนวลของการเคลื่อนไหว (Movement Smoothness)สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_continuity.jsRuleContinuity (R-07)43ตรวจสอบความต่อเนื่องของการเคลื่อนไหว ไม่ให้เกิดการหยุดชะงักระหว่างท่วงท่าสืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_weight_shift.jsRuleWeightShift (R-08)63ตรวจสอบการถ่ายเทน้ำหนักระหว่างขาซ้ายและขวาอย่างสมดุล (Rooting & Stance)สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_coordination.jsRuleCoordination (R-09)87ตรวจสอบการสอดประสานบนล่างระหว่างมือกับสะโพก (Upper-Lower Coordination)สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_bilateral_symmetry.jsRuleBilateralSymmetry (R-10)127ตรวจสอบความสมมาตรสองซีกร่างและระดับความลาดเอียงของหัวไหล่ (Symmetry)สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_opposition_and_phase.jsRuleOppositionAndPhase (R-11)153ตรวจสอบความต่างเฟสและการเคลื่อนที่ตรงกันข้ามของสองมือในท่าเมฆา (Phase Offset)สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine
rule_hand_coordination.jsRuleHandCoordination (R-12)127ตรวจสอบความเร็วและการสอดประสานของมือทั้งสอง ป้องกันอาการมือตาย (Dead Hand)สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine

4.4 การแสดงผลและผืนผ้าใบ (Display & Canvas Renderers - 10 ไฟล์) ​

ไดเรกทอรี: src/js/display/ และ src/js/display/renderers/
หน้าที่หลัก: วาดกราฟิกโครงกระดูก วิถีการรำ อนิเมชันพลังชี่ และการเล่นรีเพลย์บนผืนผ้าใบ Canvas

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
display/background_manager.jsBackgroundManager408จัดการฉากหลังเสมือนจริง การเบลอพื้นหลัง และการสลับโหมดห้องฝึกซ้อมดิจิทัลเรียกใช้: Canvas 2D
ถูกเรียกใช้โดย: DrawingManager, DisplaySettingsManager
display/drawing_manager.jsDrawingManager253ผู้ประสานงานการวาดภาพหลัก ควบคุม Frame Loop และสั่งงาน Sub-renderers 4 โมดูลเรียกใช้: 4 Sub-renderers
ถูกเรียกใช้โดย: MainController, PoseProcessor
display/ghost_manager.jsGhostManager261วาดร่างเงาโปร่งแสงของครูฝึกต้นแบบ (Ghost Master Avatar) ซ้อนทับให้ผู้ฝึกรำตามเรียกใช้: Skeleton Datasets
ถูกเรียกใช้โดย: DrawingManager
display/inline_skeleton_player.jsInlineSkeletonPlayer251คอมโพเนนต์วาดโครงกระดูกอนิเมชันขนาดเล็กแบบ Reusable สำหรับหน้า Dashboard และตารางสถิติเรียกใช้: Canvas 2D
ถูกเรียกใช้โดย: ResearchModeView, AdminLogsTab
display/silk_animation.jsSilkParticle358ระบบอนุภาคและคลื่นเส้นไหมจำลองพลังชี่ (Silk Flow Particle System)เรียกใช้: Canvas 2D
ถูกเรียกใช้โดย: BaseLayout.astro, QiEffectRenderer
display/webgl_manager.jsWebGLManager525เรนเดอร์เอฟเฟกต์ 3 มิติและการประมวลผลเชเดอร์ขั้นสูงผ่าน WebGL Contextเรียกใช้: WebGL Context
ถูกเรียกใช้โดย: DrawingManager (เมื่อเปิดโหมด GPU)
display/renderers/canvas_hud_renderer.jsCanvasHudRenderer230วาดมุมองศาข้อต่อ เส้นวัดระดับ และกล่องบอกสถานะคะแนนบน Canvas HUDถูกเรียกใช้โดย: DrawingManager
display/renderers/mask_renderer.jsMaskRenderer182วาดหน้ากากเงากั้นขอบเขต ป้องกันแสงสะท้อน และเพิ่มมิติความลึกของการแสดงผลถูกเรียกใช้โดย: DrawingManager
display/renderers/skeleton_renderer.jsPoseSkeletonRenderer417วาดกระดูกและข้อต่อ 33 จุด พร้อมปรับเปลี่ยนสีตามผลการตรวจจับข้อผิดพลาดถูกเรียกใช้โดย: DrawingManager
display/renderers/trajectory_renderer.jsTrajectoryRenderer422วาดวิถีการโค้งของมือ เส้นนำทางการหมุนเกลียว และการจางหายของรอยรำถูกเรียกใช้โดย: DrawingManager

4.5 คอนโทรลเลอร์ควบคุมพฤติกรรม (Application Controllers - 14 ไฟล์) ​

ไดเรกทอรี: src/js/controllers/
หน้าที่หลัก: ควบคุมตรรกะการไหลของระบบ (Workflow Logic), State Machine, การรับส่งข้อมูลระหว่าง UI และ Core

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
auth_manager.jsAuthManager397จัดการการยืนยันตัวตน สิทธิ์การเข้าถึงระบบวิจัย และรหัสการเข้าร่วมโครงการ (Access Codes)เรียกใช้: SupabaseClient
ถูกเรียกใช้โดย: AuthPopupManager, ResearchModeController
display_controller.jsDisplayController958ควบคุมการตั้งค่าหน้าจอ การเปิด/ปิดกระจก การแสดงผลมุมกล้อง และสเกล Canvasถูกเรียกใช้โดย: DisplayPopupManager, MainController
env_controller.jsEnvController241ตรวจสอบและปรับสภาพแวดล้อม เช่น แสงสว่างในห้อง (Lighting) และเสียงรอบข้างถูกเรียกใช้โดย: LightingManager, MainController
flowstate_controller.jsFlowStateController536ตรวจวัดและกระตุ้นสภาวะลื่นไหล (Flow State / Zen Mind) เมื่อผู้ฝึกรำได้อย่างต่อเนื่องถูกเรียกใช้โดย: FlowStateManager, ScoringManager
keyboard_controller.jsKeyboardController573จัดการ Event ปุ่มกดคีย์บอร์ดทั้งหมดในหน้าห้องฝึกซ้อม (Spacebar, Reset, Mute ฯลฯ)ถูกเรียกใช้โดย: AppEventBinder, ShortcutsManager
landing_controller.jsinitLandingController53Master Orchestrator สั่งเริ่มการทำงานของโมดูลหน้าแรกทั้งหมด (Nav, Metrics, Widgets)เรียกใช้: LandingNav, LandingMetrics, LandingWidgets
ถูกเรียกใช้โดย: BaseLayout.astro
main_controller.jsMainController363State Machine ผู้ดูแลวงจรชีวิตการฝึกซ้อม (Ready ➡️ Calibrating ➡️ Training ➡️ End)เรียกใช้: TrainingFlowController, CalibrationManager
ถูกเรียกใช้โดย: AppEventBinder
mobile_controller.jsMobileController378ปรับแต่ง Layout และควบคุมการโต้ตอบแบบสัมผัส (Touch) เมื่อรันบนสมาร์ตโฟน/แท็บเล็ตถูกเรียกใช้โดย: DeviceManager, MainController
pose_processor.jsPoseProcessor935กลไกประมวลผลเฟรมภาพ รับพิกัดดิบจาก MediaPipe กรองสัญญาณรบกวน และส่งต่อให้ Rulesเรียกใช้: HeuristicsEngine, CalibrationManager
ถูกเรียกใช้โดย: CameraManager
replay_controller.jsReplayController728ควบคุมหน้าต่างและแถบควบคุมการเล่นซ้ำท่ารำ (Timeline, Pause, Fast Forward)เรียกใช้: ReplayManager
ถูกเรียกใช้โดย: AppEventBinder, UIManager
research_mode_controller.jsResearchModeController1,239ตัวควบคุมโปรโตคอลวิจัยทางคลินิก (RCT) ดูแลลำดับ 12 ท่า เวลาพักเบรก และการซิงก์ Cloudเรียกใช้: ResearchModeView, DataExporter, SupabaseClient
ถูกเรียกใช้โดย: AppEventBinder
training_flow_controller.jsTrainingFlowController769ดูแลลำดับขั้นตอนการเริ่มรำ การนับเวลาถอยหลัง และการสรุปผลการฝึกซ้อมถูกเรียกใช้โดย: MainController, AppEventBinder
video_analysis_controller.jsVideoAnalysisController469ควบคุมการอัปโหลดไฟล์วิดีโอจากภายนอกเข้ามาประเมินวิเคราะห์แทนการใช้กล้องสดถูกเรียกใช้โดย: AppEventBinder, PoseProcessor
vip_capture_controller.jsVIPCaptureController418จัดการการบันทึกภาพถ่ายและวิดีโอไฮไลต์ความละเอียดสูงระหว่างการรำที่สมบูรณ์แบบถูกเรียกใช้โดย: UIManager, DataExporter

4.6 โมดูลหน้าแรกของเว็บไซต์ (Landing Page Modules - 3 ไฟล์) ​

ไดเรกทอรี: src/js/landing/
หน้าที่หลัก: โมดูลที่เพิ่งได้รับการ Refactor แยกส่วนออกมาใน Phase 4 เพื่อเพิ่มความเร็วในการโหลดและการโต้ตอบบนหน้าแรก

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
landing_nav.jsLandingNav389ดูแลเมนูมือถือ (Hamburger), แถบ Silk Scroll Progress, ปุ่ม Back to Top และคีย์ลัดหน้าแรก (1-5, M, C, ?)ถูกเรียกใช้โดย: landing_controller.js, BaseLayout.astro
landing_metrics.jsLandingMetrics195ควบคุม Scroll Reveal Animation แบบ Play-Once และการนับตัวเลขอัตโนมัติ (Animated Number Count-Up)ถูกเรียกใช้โดย: landing_controller.js, BaseLayout.astro
landing_widgets.jsLandingWidgets1,047จัดการสไลเดอร์คำคม 12s, ป๊อปอัป PromptPay QR, สเตจสวิตเชอร์ About/Guide, และแบบทดสอบ Taiji Matcherเรียกใช้: I18nManager
ถูกเรียกใช้โดย: landing_controller.js, BaseLayout.astro

4.7 ส่วนต่อประสานผู้ใช้และการแจ้งเตือน (UI & Popups - 25 ไฟล์) ​

ไดเรกทอรี: src/js/ui/
หน้าที่หลัก: ควบคุมกล่องข้อความ โมดอล ป๊อปอัปตั้งค่า เสียงสังเคราะห์ และการตอบสนองผู้ใช้

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
app_event_binder.jsAppEventBinder307ศูนย์กลางการผูก DOM Event Listeners ทั้งหมดในหน้าห้องฝึกซ้อม (app.html)เรียกใช้: Controllers ทั้งหมด
ถูกเรียกใช้โดย: AppBootstrap
audio_manager.jsAudioManager654สังเคราะห์คลื่นเสียงผ่าน Web Audio API (เสียงคอร์ดหยินหยาง, เสียงกระดิ่งเมื่อทำถูก, เสียงโดรนสมาธิ)ถูกเรียกใช้โดย: ScoringManager, FeedbackManager
auth_popup_manager.jsAuthPopupManager933ควบคุมหน้าต่างป๊อปอัปเข้าสู่ระบบ กรอกรหัสการวิจัย และการจัดการสิทธิ์การใช้งานเรียกใช้: AuthManager
ถูกเรียกใช้โดย: AppEventBinder
chatbot.jsTaijiChatbot332ระบบแชตบอตปรึกษาหลักวิชาการมวยไท่เก๊ก (Master Dao AI Assistant)ถูกเรียกใช้โดย: BaseLayout.astro, LandingNav
dashboard_popup_manager.jsDashboardPopupManager667จัดการเปิด/ปิดหน้าต่างโมดอลแผงควบคุมสถิติผู้เรียนและนักวิจัยเรียกใช้: AdminDashboardView
ถูกเรียกใช้โดย: AppEventBinder
debug_manager.jsDebugManager247แสดงผลแผงตัวชี้วัดทางเทคนิค (FPS, Processing Latency, Landmark Coordinates)ถูกเรียกใช้โดย: PerformanceMonitor, KeyboardController
display_popup_manager.jsDisplayPopupManager706ควบคุมหน้าต่างป๊อปอัปปรับแต่งมุมมองภาพและขนาดตัวแสดงผลถูกเรียกใช้โดย: DisplayController
display_settings_manager.jsDisplaySettingsManager529บันทึกและคืนค่าคอนฟิกการแสดงผลลงใน LocalStorageถูกเรียกใช้โดย: DisplayPopupManager
feedback_manager.jsFeedbackManager265ควบคุมการแสดงกล่องข้อความแนะนำการปรับปรุงท่ารำแบบเรียลไทม์ (HUD Alert Box)ถูกเรียกใช้โดย: ScoringManager, MainController
feedback_summary_manager.jsFeedbackSummaryManager728แสดงผลหน้าต่างสรุปคะแนนเรดาร์ชาร์ตและจุดที่ต้องปรับปรุงหลังจบเซสชันการฝึกถูกเรียกใช้โดย: ScoringManager, TrainingFlowController
feedback_survey_manager.jsSurveyManager280จัดการแบบสอบถามประเมินความพึงพอใจและประสบการณ์ใช้งาน (SUS Questionnaire)ถูกเรียกใช้โดย: FeedbackSummaryManager
flowstate_manager.jsZenModeManager131ควบคุมเอฟเฟกต์หน้าจอเมื่อเข้าสู่โหมดเซน (ซ่อน UI ที่ไม่จำเป็นทั้งหมด)ถูกเรียกใช้โดย: FlowStateController
gesture_manager.jsGestureManager400ตรวจจับท่าทางมือ (Hand Gestures) สำหรับสั่งงานระบบโดยไม่ต้องแตะหน้าจอหรือคีย์บอร์ดถูกเรียกใช้โดย: PoseProcessor
landing_flowstate_easter_egg.jsQiMote352อนิเมชัน Easter Egg ละอองแสงพลังชี่เมื่อกดคีย์บอร์ดสูตรลับ Konami Codeถูกเรียกใช้โดย: BaseLayout.astro
lighting_manager.jsLightingManager221วิเคราะห์ความสว่างของภาพจากกล้องและแจ้งเตือนเมื่อแสงไม่เพียงพอถูกเรียกใช้โดย: EnvController
research_mode_view.jsResearchModeView456โมดูลมุมมอง (View) ของระบบวิจัย สร้าง HTML Layout, ตาราง 12 ท่า และนาฬิกาพักเบรกเรียกใช้: InlineSkeletonPlayer
ถูกเรียกใช้โดย: ResearchModeController
robot_popup_manager.jsRobotPopupManager176ควบคุมป๊อปอัปแนะนำท่าทางโดยครูฝึกหุ่นยนต์จำลองถูกเรียกใช้โดย: RobotManager
rules_config_manager.jsRulesConfigManager535ควบคุมหน้าต่างปรับแต่งค่า Threshold ทางคณิตศาสตร์ของกฎ 12 ข้อสำหรับนักวิจัยเรียกใช้: BIOMECH_RULES_CONFIG
ถูกเรียกใช้โดย: AppEventBinder
rules_popup_manager.jsRulesPopupManager441ควบคุมหน้าต่างอธิบายทฤษฎีและหลักปรัชญาของกฎแต่ละข้อถูกเรียกใช้โดย: AppEventBinder
score_popup_manager.jsScorePopupManager526ควบคุมการแสดงผลการ์ดคะแนนลอยตัวและการเฉลิมฉลองเมื่อได้เกรด Aถูกเรียกใช้โดย: ScoringManager
shortcuts_manager.jsShortcutsManager303จัดการหน้าต่างแสดงรายการคีย์ลัดคีย์บอร์ดทั้งหมดในหน้าห้องฝึกถูกเรียกใช้โดย: KeyboardController
theater_controller.jsTheaterController263ควบคุมโหมดโรงละคร (Theater Mode) ดิมไฟหน้าจอเพื่อเน้นเฉพาะการรำถูกเรียกใช้โดย: AppEventBinder
tutorial_manager.jsTutorialManager959แนะนำขั้นตอนการใช้งานระบบแบบทีละสเต็ป (Interactive Guided Onboarding Tour)ถูกเรียกใช้โดย: AppBootstrap
ui_manager.jsUIManager853ศูนย์กลางควบคุมการสลับหน้าจอ การซ่อน/แสดงพาเนล และสไตล์ธีมถูกเรียกใช้โดย: AppBootstrap, MainController
wisdom_manager.jsWisdomManager247สุ่มแสดงคำสอนและคติธรรมมวยไท่เก๊กโบราณเพื่อสร้างแรงบันดาลใจถูกเรียกใช้โดย: UIManager

4.8 แดชบอร์ดวิจัยและระบบผู้ดูแล (Admin & Research Dashboard - 6 ไฟล์) ​

ไดเรกทอรี: src/js/ui/dashboard/
หน้าที่หลัก: ระบบสถิติขั้นสูงสำหรับนักวิจัย วิเคราะห์เส้นทางการเรียนรู้ และการจัดการข้อมูลผู้เข้าร่วมโครงการ

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
admin_analysis_tab.jsAdminAnalysisTab950เรนเดอร์กราฟวิเคราะห์แนวโน้มพัฒนาการ (Learning Curves) และ Radar Chart 6 มิติเรียกใช้: Chart.js, DashboardChartConfig
ถูกเรียกใช้โดย: AdminDashboardView
admin_dashboard.jsAdminDashboardView293คอนเทนเนอร์หลักของแผงควบคุมแอดมิน จัดการการสลับแท็บและการควบคุมสิทธิ์เรียกใช้: ทุกแท็บใน dashboard/
ถูกเรียกใช้โดย: DashboardPopupManager
admin_database_tab.jsAdminDatabaseTab280จัดการและตรวจสอบตารางข้อมูลบน Supabase Cloud Telemetryเรียกใช้: SupabaseClient
ถูกเรียกใช้โดย: AdminDashboardView
admin_logs_tab.jsAdminLogsTab1,674แสดงตารางประวัติผู้เข้าร่วมวิจัย การกรองข้อมูล และการส่งออก CSV ขนาดใหญ่เรียกใช้: InlineSkeletonPlayer, DataExporter
ถูกเรียกใช้โดย: AdminDashboardView
admin_overview_tab.jsAdminOverviewTab554สรุปภาพรวม KPI ระบบ สถิติจำนวนชั่วโมงการฝึกซ้อม และผู้ใช้งานที่กำลัง Activeถูกเรียกใช้โดย: AdminDashboardView
dashboard_chart_config.jsDashboardChartConfig197จัดเก็บการตั้งค่าสไตล์ สี พาเลตต์ และฟอนต์สำหรับกราฟ Chart.js ทั้งหมดถูกเรียกใช้โดย: AdminAnalysisTab

4.9 เครื่องมือสนับสนุนและบริการ (Utilities & Services - 12 ไฟล์) ​

ไดเรกทอรี: src/js/utils/
หน้าที่หลัก: คลาสยูทิลิตี้สำหรับงานคำนวณ เชื่อมต่อฐานข้อมูล แปลภาษา และตรวจจับอุปกรณ์

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
data_exporter.jsDataExporter361เครื่องยนต์สร้างชุดข้อมูลวิจัย ส่งออกไฟล์ CSV รายเฟรม และ JSON Snapshot คุณภาพสูงถูกเรียกใช้โดย: ResearchModeController, AdminLogsTab
device_manager.jsDeviceManager466วิเคราะห์ประสิทธิภาพชิปประมวลผล (GPU/CPU Tiering) และปรับระดับการแสดงผลอัตโนมัติ 3 ระดับถูกเรียกใช้โดย: AppBootstrap, DrawingManager
i18n_manager.jsI18nManager268ตัวจัดการระบบสองภาษา (ไทย/อังกฤษ) สลับข้อความทั้งแอปแบบ On-the-Flyเรียกใช้: translations.js
ถูกเรียกใช้โดย: ทุกคอมโพเนนต์ในระบบ
math_utils.jsMathUtils79ฟังก์ชันคณิตศาสตร์บริสุทธิ์: คำนวณระยะห่าง 3 มิติ, มุมเวกเตอร์, และมุมองศาข้อต่อถูกเรียกใช้โดย: rules/, biomechanics/, core/
path_generator.jsgenerateWristCirclePath85สร้างพิกัดวิถีวงกลมและเกลียวไหมในอุดมคติสำหรับเป็นเกณฑ์เปรียบเทียบถูกเรียกใช้โดย: GhostManager, Unit Tests
session_manager.jsgetOrCreateUserId121จัดการการระบุตัวตนของผู้ใช้ (Anonymous User ID) และรหัสเซสชันการฝึกถูกเรียกใช้โดย: AppBootstrap, ScoringManager
skeleton_renderer.jsSkeletonRenderer105ฟังก์ชันยูทิลิตี้วาดโครงกระดูกแบบ Standalone สำหรับสคริปต์ขนาดเล็กถูกเรียกใช้โดย: InlineSkeletonPlayer
smart_fov_controller.jsSmartFovController287ควบคุมขอบเขตมุมมองกล้อง (Field of View) แบบอัตโนมัติตามระยะห่างของผู้ฝึกถูกเรียกใช้โดย: CameraManager
supabase_client.jstryNextCdn75ตัวเชื่อมต่อฐานข้อมูล Supabase Cloud พร้อมระบบ Fallback สลับ CDN อัตโนมัติถูกเรียกใช้โดย: AuthManager, AdminDatabaseTab
theme_manager.jsThemeManager147ควบคุมและสลับโหมดสี Dark / Light Mode และบันทึกลง LocalStorageถูกเรียกใช้โดย: AppBootstrap, UIManager
time_utils.jsTimeUtils85ฟังก์ชันแปลงวินาทีเป็นรูปแบบเวลา (MM:SS) และจัดการประทับเวลาสถิติถูกเรียกใช้โดย: TrainingFlowController, ReplayManager
translations.jstranslations35พจนานุกรมคำศัพท์และข้อความแปลภาษาพื้นฐานของระบบถูกเรียกใช้โดย: I18nManager

4.10 ระบบทดลองและต้นแบบอนาคต (Experimental & Future Prototypes - 2 ไฟล์) ​

ไดเรกทอรี: src/js/experimental/
หน้าที่หลัก: พื้นที่ทดลองเทคโนโลยีระดับ Edge AI และการเร่งความเร็วด้วย WebGPU สำหรับ Phase 3-4

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
sequence_controller.jsSequenceController384ตัวควบคุมการจัดลำดับการเคลื่อนไหวแบบต่อเนื่องสำหรับโมเดลลำดับเวลา (Time-Series)ถูกเรียกใช้โดย: Experimental Sandbox
webgpu_manager.jsWebGPUManager196ทดสอบการรัน Neural Network บนเบราว์เซอร์ผ่าน WebGPU Compute Shadersถูกเรียกใช้โดย: Experimental Sandbox

4.11 การตั้งค่าระดับราก (Root Configs - 2 ไฟล์) ​

ไดเรกทอรี: src/js/
หน้าที่หลัก: กำหนดตัวแปรสภาพแวดล้อม รหัสเชื่อมต่อฐานข้อมูล และการตั้งค่าระบบวิจัย

ชื่อไฟล์คลาส/ฟังก์ชันหลักบรรทัดหน้าที่รับผิดชอบเดี่ยว (Single Responsibility)ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By)
config.example.jsconfig.example21แม่แบบตัวแปรสภาพแวดล้อม (Supabase URL, Anon Key, Access Codes)ใช้เป็นต้นแบบ: สำหรับการสร้าง config.js
config.jsconfig18ค่าคอนฟิกสภาพแวดล้อมจริงที่ถูกใช้งานขณะรันแอปพลิเคชันถูกเรียกใช้โดย: SupabaseClient, AuthManager

บทที่ 5: การออกแบบ Dependency Injection และการสื่อสารข้ามโมดูล (DI & Event Bus) ​

5.1 สถาปัตยกรรม Dependency Injection ผ่าน AppBootstrap ​

เพื่อแก้ไขปัญหาการพึ่งพากันแบบผูกติดแน่น (Tight Coupling) ระบบจึงใช้คลาส AppBootstrap เป็นศูนย์กลางการสร้างอินสแตนซ์และทำ Dependency Injection โดยจัดเก็บตัวแปรที่ถูกสร้างทั้งหมดไว้ใน Global Namespace กลาง:

javascript
// ตัวอย่างโครงสร้างการจัดเก็บ Service Registry บน window.TaijiFlow
window.TaijiFlow = {
  // Core Services
  cameraManager: CameraManager,
  heuristicsEngine: HeuristicsEngine,
  scoringManager: ScoringManager,
  calibrationManager: CalibrationManager,
  
  // Display Services
  drawingManager: DrawingManager,
  ghostManager: GhostManager,
  
  // Controllers & UI
  mainController: MainController,
  trainingFlowController: TrainingFlowController,
  researchModeController: ResearchModeController,
  audioManager: AudioManager,
  feedbackManager: FeedbackManager,
  i18nManager: I18nManager
};

5.2 แผนภาพวงจรชีวิตการบูตสแตรประบบ (Bootstrap Lifecycle & Initialization Sequence) ​

ในการเริ่มต้นทำงานของระบบแอปพลิเคชัน การเรียงลำดับการสร้างอ็อบเจกต์ (Instantiation Order) มีความสำคัญอย่างยิ่งเพื่อป้องกันปัญหา undefined reference และกำจัดภาวะพึ่งพากันเป็นวงกลม (Circular Dependency):

5.3 กลยุทธ์การขจัด Circular Dependency ด้วย Context Bundle ​

เพื่อรักษาหลักการ Inversion of Control (IoC) และป้องกันไม่ให้คอนโทรลเลอร์หรือคลาสใดๆ สร้างอินสแตนซ์ของคลาสอื่นโดยตรง ระบบจึงส่งผ่านอ็อบเจกต์รวมศูนย์ชื่อ context เพียงก้อนเดียว:

javascript
// โครงสร้าง Context Bundle ที่ส่งมอบผ่าน AppBootstrap
const context = {
  elements: {
    video: document.getElementById('webcam'),
    canvas: document.getElementById('output_canvas'),
    hud: document.getElementById('hud_canvas'),
    // ... UI elements
  },
  services: {
    camera: new CameraManager(),
    audio: new AudioManager(),
    device: new DeviceManager(),
    storage: new LocalStorageAdapter()
  },
  engine: {
    poseProcessor: new PoseProcessor(),
    heuristics: new HeuristicsEngine(),
    scoring: new ScoringManager(),
    analytics: BiomechanicalAnalytics
  },
  display: {
    drawing: new DrawingManager(canvasCtx),
    ghost: new GhostManager()
  },
  controllers: {} // จะถูก populate ในลำดับถัดไป
};

// Controllers จะรับ context เข้าทาง Constructor โดยไม่สร้าง Dependencies ขึ้นมาเอง
context.controllers.trainingFlow = new TrainingFlowController(context);
context.controllers.researchMode = new ResearchModeController(context);

5.4 สถาปัตยกรรม Event Bus และรายการ Custom Event มาตรฐาน ​

การสื่อสารข้ามโมดูลที่ไม่ต้องการให้มีการผูกโยงกันแบบแน่นหนา (Loose-Coupling) จะกระทำผ่าน DOM Custom Events บน window หรือ document โดยมีรายการ Event มาตรฐานดังนี้:

ชื่อ Event Identifierผู้ส่ง (Emitter)ผู้รับ (Listener)โครงสร้าง Payload (event.detail)วัตถุประสงค์
taiji:frame-evaluatedPoseProcessorScoringManager, DrawingManager, Audio{ frameIndex, landmarks, scores, rulesStatus, timestamp }ส่งผลการประเมินเฟรมปัจจุบันไปอัปเดตคะแนน เรนเดอร์ และเสียง
taiji:calibration-startCalibrationManagerCanvasHudRenderer, AudioManager{ durationSec: 3, poseType: 'T-POSE' }เริ่มกระบวนการนับถอยหลังยืนคาลิเบรตสรีระ
taiji:calibration-completeCalibrationManagerTrainingFlowController, MainController{ scale, shoulderWidth, armLength, torsoHeight }บันทึกสเกลสรีระเข้าสู่ LocalStorage และปลดล็อกการเริ่มรำ
taiji:pose-changedAppEventBinderKinematicPoseModel, FeedbackManager{ poseId: 'single_whip', poseIndex: 2 }สลับแม่แบบท่ารำและข้อความแนะนำทางชีวกลศาสตร์
taiji:break-startedResearchModeControllerResearchModeView, AudioManager{ breakType: 'SHORT'|'LONG', durationSec: 60|300 }แสดงหน้าต่างบังคับให้อาสาสมัครหยุดพักระหว่างการทดลอง RCT
taiji:tier-changedDeviceManagerDrawingManager, SilkAnimation{ currentTier: 1|2|3, targetFps: 60|30, reason: string }แจ้งให้เอนจินกราฟิกลดทอนหรือเพิ่มเอฟเฟกต์ตามสมรรถนะเครื่อง

5.5 การจัดการสถานะร่วมและการรองรับ Deep Linking ​

ระบบใช้ Finite State Machine (FSM) ภายใน TrainingFlowController เพื่อควบคุมการทำงานของแอป:

[ IDLE ] ──(Click Start)──> [ CALIBRATING ] ──(Hold 3s)──> [ TRAINING ]
   ▲                                                             │
   │                                                       (Click Stop /
   │                                                        Pose Finish)
   │                                                             ▼
[ RESET ] <────────(Dismiss)──────── [ REPLAY / SUMMARY ] ◄──────┘

พร้อมทั้งซิงก์ State เข้ากับ URL Query Parameters เพื่อรองรับการเปิดจากลิงก์วิจัยหรือ QR Code:

  • ?mode=research : บังคับเปิด Research Mode ทันทีโดยซ่อนปุ่มฝึกอิสระ
  • ?pose=cloud_hands : กำหนดท่ารำเริ่มต้นอัตโนมัติ
  • ?tier=3 : บังคับใช้งานโหมดประหยัดพลังงาน (Lite Mode) ทันที

บทที่ 6: กลยุทธ์การเรนเดอร์กราฟิกและสถาปัตยกรรมประสิทธิภาพสูง (Rendering Architecture & Performance Optimization) ​

6.1 สถาปัตยกรรม Multi-Layer Canvas Topology ​

เพื่อป้องกันคอขวดของการประมวลผลกราฟิก (Canvas Invalidation Bottleneck) แพลตฟอร์ม TaijiFlow จึงไม่วาดทุกอย่างลงบนผืนผ้าใบเดียวกัน แต่ใช้เทคนิคการแยกชั้นแคนวาสซ้อนทับกัน (Z-Index Layering):

ข้อดีเชิงสถาปัตยกรรม:

  1. Partial Redraw: เส้นวิถีไหม (Trajectory) ใน Layer 3 สามารถวาดทับและค่อยๆ จางหาย (Fade Out) โดยใช้ fillStyle = 'rgba(0,0,0,0.05)' โดยไม่ต้องสั่งล้างและวาดโครงกระดูกใน Layer 2 ใหม่ทุกเฟรม
  2. GPU Composition: เบราว์เซอร์สามารถใช้ Hardware Compositor แยกเธรดการซ้อนภาพแต่ละเลเยอร์ ทำให้ได้เฟรมเรตที่ราบรื่นระดับ 60 FPS แม้บนอุปกรณ์พกพา

6.2 การควบคุมวงรอบเรนเดอร์และเทคนิคการลดขยะหน่วยความจำ (Garbage Collection Optimization) ​

ในแอปพลิเคชันคอมพิวเตอร์วิทัศน์แบบเรียลไทม์ การจองหน่วยความจำชั่วคราวซ้ำๆ ใน requestAnimationFrame จะทำให้ Garbage Collector (GC) ทำงานบ่อยครั้ง ส่งผลให้เกิดอาการกระตุก (Micro-Stutter):

javascript
// แนวปฏิบัติที่ TaijiFlow ใช้: Object Pooling & In-Place Vector Math
class TrajectoryPool {
  constructor(maxSize = 200) {
    // จอง TypedArray เพียงครั้งเดียวตอนเริ่มต้น ไม่มีการ new Array() ในระหว่างรัน
    this.bufferX = new Float32Array(maxSize);
    this.bufferY = new Float32Array(maxSize);
    this.head = 0;
    this.count = 0;
  }

  push(x, y) {
    this.bufferX[this.head] = x;
    this.bufferY[this.head] = y;
    this.head = (this.head + 1) % this.bufferX.length;
    if (this.count < this.bufferX.length) this.count++;
  }
}

นอกจากนี้ การคำนวณเวกเตอร์มุมมวยและระยะทางทั้งหมดใน HeuristicsEngine จะใช้การคำนวณแบบสเกลาร์ดิบ (Primitive Scalars) หลีกเลี่ยงการสร้าง Object { x, y, z } ใหม่ในลูป

6.3 ตารางเปรียบเทียบฮาร์ดแวร์เชิงลึก (Hardware Tiering Benchmark Matrix) ​

ผ่านคลาส DeviceManager ระบบจะประเมินคุณสมบัติของเครื่องและจัดระดับการประมวลผลออกเป็น 3 ระดับ:

คุณลักษณะเชิงเทคนิคTier 1: Quality Mode (เรือธง / เดสก์ท็อป)Tier 2: Balanced Mode (มือถือระดับกลาง)Tier 3: Lite Mode (อุปกรณ์ระดับเริ่มต้น / ประหยัดพลังงาน)
เกณฑ์การตรวจจับ GPUApple Silicon (M1–M4), A16–A18, Snapdragon 8 Gen 2–4, Dedicated Nvidia/AMDSnapdragon 7xx, Dimensity 8xxx, Apple A13–A15, Intel Iris Xeชิปเซ็ตรุ่นเก่า, RAM < 4GB, หรือตรวจพบเบราว์เซอร์เปิดโหมด Low Power
ความถี่เป้าหมาย (FPS)60 FPS30–60 FPSล็อกคงที่ 30 FPS
จำนวนพิกัดเส้นไหม (Trajectory Buffer)สูงสุด 120 จุดสูงสุด 40 จุดปิดการแสดงผลเส้นไหม (0 จุด)
อนุภาคชี่เรืองแสง (Qi Aura Particles)เปิดเต็มรูปแบบ (80 อนุภาค)ลดทอนเหลือ 20 อนุภาคปิดอนุภาคทั้งหมด
การเรนเดอร์แสงเงา (Canvas ShadowBlur)เปิดใช้งาน (Bloom/Glow Effects)ปิด (ctx.shadowBlur = 0)ปิดทั้งหมด
สเกลความละเอียดแคนวาส (DPI Scaling)DevicePixelRatio เต็มสเกล (1.5x – 2.0x)1.0x คงที่ดาวน์สเกลเหลือ 0.75x เพื่อลด Fill-Rate
การเรนเดอร์กระดูกครูฝึก (Ghost Pose)3D Skeleton + Semi-transparent Mesh2D Stick Figure เส้นประ2D Stick Figure เส้นเดี่ยว

6.4 ระบบลดสเปกอัตโนมัติ (Adaptive Performance Fallback) ​

หากเครื่องผู้ใช้เกิดความร้อนสะสม (Thermal Throttling) ระบบมี Watchdog คอยตรวจจับค่าเฉลี่ย FPS ต่อเนื่อง:

  • หาก FPS ต่ำกว่า 24 FPS ติดต่อกันเป็นเวลาเกิน 3.0 วินาที ➡️ ระบบจะลดระดับอัตโนมัติจาก Tier 1 ➡️ Tier 2
  • หากยังคงต่ำกว่า 18 FPS ติดต่อกันอีก 3.0 วินาที ➡️ ลดระดับลงสู่ Tier 3 ทันที พร้อมแสดงข้อความแนะนำให้ผู้ใช้ทราบผ่าน FeedbackManager

บทที่ 7: กรอบการทดสอบ การประกันคุณภาพ และ Safety Gates (Testing Framework & QA) ​

7.1 พีระมิดการทดสอบของแพลตฟอร์ม (Testing Pyramid & Coverage Distribution) ​

ระบบมีกลยุทธ์การทดสอบแบ่งออกเป็น 3 ระดับเพื่อให้มั่นใจว่าโค้ดทั้ง 99 ไฟล์สามารถทำงานร่วมกันได้อย่างสมบูรณ์:

7.2 กลยุทธ์การจำลอง Web APIs (Mocking Strategy) ​

ในการรัน Jest ภายใต้สภาพแวดล้อม Node.js ระบบได้ออกแบบ Mocks จำลอง Web APIs สำคัญไว้ในไดเรกทอรี tests/:

  • MediaPipe Pose Mock: จำลองสตรีมพิกัด 33 Landmark แบบ 3 มิติ (x,y,z,visibility) ที่ผ่านการคำนวณทางตรีโกณมิติเพื่อทดสอบท่ารำที่สมบูรณ์แบบและท่ารำที่มีจุดบกพร่อง
  • Web Audio API Mock: จำลอง AudioContext, createOscillator(), createGain() เพื่อตรวจสอบว่าเสียงจังหวะชี่กงทำงานถูกต้องโดยไม่เกิด Error ใน CI
  • HTML5 Canvas Context2D Mock: จำลองฟังก์ชัน arc(), lineTo(), stroke(), measureText() เพื่อทดสอบความถูกต้องของตรรกะใน Sub-renderers

7.3 ตารางกรณีทดสอบเชิงคณิตศาสตร์และชีวกลศาสตร์ (Mathematical Edge Cases Matrix) ​

เพื่อให้สอดคล้องกับระเบียบวิธีวิจัยดุษฎีนิพนธ์ กฎการคำนวณทางชีวกลศาสตร์ได้รับการทดสอบกรณีขอบเขตอย่างเข้มงวด:

กรณีทดสอบ (Edge Case)ปัญหาที่อาจเกิดขึ้นหากไม่ดักจับวิธีการแก้ไขในระดับโค้ดชุดทดสอบที่ตรวจสอบ
Angle Wrap-around (170∘→−170∘)การลบค่าตรงๆ จะได้ผลต่าง 340∘ ซึ่งทำให้ค่าความเร่งพุ่งสูงผิดปกติใช้อัลกอริทึม Normalization: diff = ((diff + 180) % 360) - 180tests/unit/heuristics_engine.test.js
Division by Zero in Angular Velocityเมื่อ Δt→0 หรือระยะเวลาเฟรมเท่ากับศูนย์ ค่าความเร็วจะกลายเป็น Infinityตรวจสอบ if (dt <= 0.0001) return 0;tests/unit/heuristics_engine.test.js
High Frequency Landmark Jitterสัญญาณรบกวนจากกล้องทำให้ค่า Jerk สูงเกินจริงกรองสัญญาณด้วย 2nd-order Butterworth Filter ตัดความถี่เกิน 6Hztests/unit/biomechanical_analytics.test.js
SPARC Peak Amplitude Cutoffสเปกตรัมที่ความถี่สูงเกินไปอาจหลุดช่วง Cutoff ωcกำหนดขอบเขตความถี่การคำนวณ [0.1,10.0 Hz] และแอมพลิจูดขีดต่ำ 0.05tests/unit/biomechanical_analytics.test.js
Score Clamping Boundaryผลคะแนนจากสมการอาจคำนวณได้ค่าน้อยกว่า 0 หรือมากกว่า 100ล็อกค่าผลลัพธ์ผ่าน Math.max(0, Math.min(100, Math.round(rawScore)))tests/unit/scoring_manager.test.js

7.4 ไปป์ไลน์การตรวจสอบความปลอดภัยก่อน Deploy (Pre-Deployment Safety Gates) ​

ก่อนที่โค้ดจะถูกส่งขึ้นระบบโปรดักชัน จะต้องผ่านการตรวจสอบความถูกต้อง 4 ขั้นตอนอย่างเคร่งครัด:

[ Git Stage ] ──> [ Step 1: ESLint / Syntax Check ]
                         │
                         ▼
                  [ Step 2: Jest Unit Tests (170/170 Pass) ]
                         │
                         ▼
                  [ Step 3: Astro App Build (`npm run build`) ]
                         │
                         ▼
                  [ Step 4: VitePress Docs Build (`npm run docs:build`) ] ──> [ Ready for Deploy ]

บทที่ 8: ยุทธศาสตร์การบำรุงรักษาและการขยายระบบในอนาคต (Extensibility & Refactoring Roadmap) ​

8.1 คู่มือการขยายระบบทีละขั้นตอน (Step-by-Step Extension Recipes) ​

📝 Recipe 1: ขั้นตอนการเพิ่มกฎการประเมินชีวกลศาสตร์ข้อใหม่ (Adding a New Heuristic Rule) ​

เมื่อต้องการเพิ่มกฎใหม่ (เช่น กฎข้อที่ 13: Spinal Wave / 척추 파동):

  1. สร้างไฟล์กฎใหม่: สร้าง src/js/rules/rule_spinal_wave.js โดยสืบทอดหรือใช้โครงสร้างเมธอด evaluate(landmarks, history, context) ซึ่งต้องส่งคืนค่า { pass: boolean, score: number, errorMagnitude: number, message: string }
  2. ลงทะเบียนใน Engine: เพิ่มกฎใหม่ลงใน src/js/rules/rules_engine.js ในอาร์เรย์ this.rules
  3. แมปเข้าสู่ Principle: เปิดไฟล์ src/js/core/scoring_manager.js แล้วเพิ่มการจับคู่รหัสกฎ R-13 เข้ากับ 1 ใน 6 หลักการไท้เก๊ก (เช่น Trunk Coordination)
  4. เพิ่มคำแปลภาษา: เพิ่มคีย์ข้อความแนะนำและชื่อกฎลงใน src/js/utils/i18n.js (รองรับทั้งภาษาไทยและอังกฤษ)
  5. เขียนชุดทดสอบ: เพิ่มกรณีทดสอบ PASS/FAIL ลงใน tests/unit/rules_engine.test.js แล้วรัน npm test ยืนยันผล 100%

🥋 Recipe 2: ขั้นตอนการเพิ่มกระบวนท่ารำใหม่ (Adding a New Form/Pose Template) ​

  1. กำหนดโครงสร้างทางชีวกลศาสตร์: เปิด src/js/core/kinematic_pose_model.js และเพิ่มฟังก์ชันสร้างพิกัดแม่แบบ generatePoseTemplate(poseName, t)
  2. เพิ่มตัวเลือกใน UI: เพิ่ม <option value="new_pose"> ใน public/app.html หรือผ่านคอมโพเนนต์ src/components/
  3. อัปเดตเกณฑ์คะแนนเฉพาะท่า: กำหนดค่าน้ำหนักกฎ (Rule Weights Matrix) สำหรับท่านั้นๆ ใน src/js/controllers/training_flow_controller.js

🎨 Recipe 3: ขั้นตอนการสร้าง Sub-Renderer สำหรับการแสดงผลใหม่ ​

  1. สร้างคลาสเรนเดอร์ใหม่ใน src/js/display/ เช่น force_vector_renderer.js
  2. กำหนดเมธอดมาตรฐาน render(ctx, landmarks, metrics, tier)
  3. นำเข้าและเชื่อมต่อเข้ากับ DrawingManager ใน src/js/display/drawing_manager.js โดยครอบด้วยการตรวจสอบ Tiering เพื่อประสิทธิภาพ

8.2 แผนการยกระดับสถาปัตยกรรมซอฟต์แวร์ (Architectural Refactoring Roadmap) ​

เพื่อรองรับการเติบโตของโครงการใน Phase 3 และ Phase 4 คณะผู้วิจัยและทีมพัฒนาได้กำหนดแผนที่การยกระดับสถาปัตยกรรมไว้ 3 ระยะ:

  1. การยกระดับสู่ระบบ Type Safety (TypeScript .d.ts): ปัจจุบันระบบใช้ JSDoc เต็มรูปแบบ ในระยะถัดไปจะสร้างไฟล์ Type Declaration (@types/taijiflow.d.ts) เพื่อให้ IDE สามารถตรวจสอบ Types ได้โดยไม่ต้องแปลง Build Pipeline
  2. การแยกเธรดคำนวณชีวกลศาสตร์สู่ Web Worker: การคำนวณ SPARC FFT และ Continuous Relative Phase จะถูกย้ายไปทำงานบน Background Web Worker เพื่อให้เธรดหลัก (Main Thread) ทำงานเรนเดอร์ Canvas 60 FPS ได้อย่างอิสระโดยไม่สะดุด
  3. การเปลี่ยนผ่านสู่ Native ES Modules (Vite Bundler): เมื่อระบบเข้าสู่ระยะสุดท้ายของการทดลองทางคลินิก โค้ดทั้งหมดจะถูก Bundle ด้วย Vite เพื่อรองรับ Tree-shaking และ Code Splitting อัตโนมัติ

8.3 กลไกการเฝ้าระวังความคลาดเคลื่อนของเอกสาร (Catalog Drift Prevention Guardrails) ​

เพื่อให้มั่นใจว่าเอกสาร 99 ไฟล์นี้จะไม่มีทางล้าสมัย (Zero Documentation Drift):

  • สคริปต์ตรวจสอบจำนวนไฟล์อัตโนมัติ: ทีมงานสามารถรันสคริปต์ตรวจสอบ:
    bash
    # ตรวจสอบจำนวนไฟล์ JS จริงเทียบกับสารบัญ
    ACTUAL_COUNT=$(find src/js -name "*.js" | wc -l | tr -d ' ')
    echo "Current JavaScript Files Count: $ACTUAL_COUNT"
    # หากไม่เท่ากับ 99 ให้แจ้งเตือนนักพัฒนาให้อัปเดตเอกสารสารบัญทันที
  • Living Documentation CI Check: ในรอบการ Merge ใหญ่เข้าสู่กิ่ง main จะมีการตรวจสอบว่าเอกสารสถาปัตยกรรมฉบับนี้และ research/thesis/ ได้รับการอ้างอิงและปรับปรุงอย่างสอดคล้องกันทุกครั้ง

📚การอ้างอิงเอกสารวิจัยฉบับนี้ (Cite this Document)
TaijiFlow Research Group. (2026). สถาปัตยกรรมจาวาสคริปต์และสารบัญระบบโค้ดฉบับสมบูรณ์ 99 ไฟล์. TaijiFlow AI & Biomechanics Repository. https://research.taijiflow.org/phase-3/technical-reports/frontend-and-devices/taijiflow_javascript_architecture_and_file_catalog

TaijiFlow AI Research & Development Project (Chán Sī Jìng Biomechanics)