สถาปัตยกรรมจาวาสคริปต์และสารบัญระบบโค้ดฉบับสมบูรณ์ 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)
- สถาปัตยกรรมจาวาสคริปต์และสารบัญระบบโค้ดฉบับสมบูรณ์ 99 ไฟล์
- (TaijiFlow AI - Comprehensive JavaScript Architecture & 99-File Catalog Specification)
- สารบัญหลัก (Table of Contents)
- บทที่ 1: บทนำและภาพรวมวิวัฒนาการสถาปัตยกรรม (Architecture Evolution)
- บทที่ 2: ผังภาพสถาปัตยกรรมระบบรวมและการแบ่งเลเยอร์ (System Topology & Layering)
- บทที่ 3: เส้นทางการไหลของข้อมูลและวงจรชีวิตของระบบ (Data Pipelines & Lifecycle States)
- 3.1 Pipeline A: การประเมินผลท่ารำแบบเรียลไทม์ (Real-Time Vision-to-Feedback Loop)
- 📊 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)
- 4.1 แกนกลางของระบบ (Core Engine - 8 ไฟล์)
- 4.2 การวิเคราะห์ชีวกลศาสตร์ (Biomechanics Analytics - 2 ไฟล์)
- 4.3 กฎการประเมินวิถีมวย (Heuristic Rules Engine - 15 ไฟล์)
- 4.4 การแสดงผลและผืนผ้าใบ (Display & Canvas Renderers - 10 ไฟล์)
- 4.5 คอนโทรลเลอร์ควบคุมพฤติกรรม (Application Controllers - 14 ไฟล์)
- 4.6 โมดูลหน้าแรกของเว็บไซต์ (Landing Page Modules - 3 ไฟล์)
- 4.7 ส่วนต่อประสานผู้ใช้และการแจ้งเตือน (UI & Popups - 25 ไฟล์)
- 4.8 แดชบอร์ดวิจัยและระบบผู้ดูแล (Admin & Research Dashboard - 6 ไฟล์)
- 4.9 เครื่องมือสนับสนุนและบริการ (Utilities & Services - 12 ไฟล์)
- 4.10 ระบบทดลองและต้นแบบอนาคต (Experimental & Future Prototypes - 2 ไฟล์)
- 4.11 การตั้งค่าระดับราก (Root Configs - 2 ไฟล์)
- บทที่ 5: การออกแบบ Dependency Injection และการสื่อสารข้ามโมดูล (DI & Event Bus)
- บทที่ 6: กลยุทธ์การเรนเดอร์กราฟิกและสถาปัตยกรรมประสิทธิภาพสูง (Rendering Architecture & Performance Optimization)
- บทที่ 7: กรอบการทดสอบ การประกันคุณภาพ และ Safety Gates (Testing Framework & QA)
- บทที่ 8: ยุทธศาสตร์การบำรุงรักษาและการขยายระบบในอนาคต (Extensibility & Refactoring Roadmap)
บทที่ 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 บนผืนผ้าใบ Canvas | 0 โมดูล | 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.js | AppBootstrap | 389 | ศูนย์กลาง Dependency Injection (DI) สร้างอินสแตนซ์ของ Managers ทั้งหมด และลงทะเบียนลงใน window.TaijiFlow | สร้าง: ทุก Managers ในระบบ ถูกเรียกใช้โดย: app.html เมื่อเริ่มต้นโหลดหน้าจอ |
calibration_manager.js | CalibrationManager | 395 | จัดการขั้นตอนการตรวจจับท่ายืน T-Pose นับถอยหลัง 3 วินาที และคำนวณสัดส่วนร่างกายเพื่อใช้ Normalization | เรียกใช้: MathUtilsถูกเรียกใช้โดย: MainController, PoseProcessor, HeuristicsEngine |
camera_manager.js | CameraManager | 354 | ควบคุมสตรีมวิดีโอจากเว็บแคม การสลับกล้องหน้า/หลัง การ Mirror ภาพ และการเชื่อมต่อกับ MediaPipe Loop | เรียกใช้: navigator.mediaDevicesถูกเรียกใช้โดย: AppBootstrap, MainController |
heuristics_engine.js | HeuristicsEngine | 420 | เอนจินวิเคราะห์ความถูกต้องของมวยไท่เก๊ก ทำหน้าที่ลงทะเบียนและเรียกประมวลผลกฎ 12 ข้อตามแต่ละท่ารำ | เรียกใช้: rules/ (12 Rules), MathUtilsถูกเรียกใช้โดย: PoseProcessor, ScoringManager |
performance_monitor.js | PerformanceMonitor | 71 | ตรวจวัดและเก็บสถิติอัตราเฟรมภาพต่อวินาที (FPS) และความหน่วงของการประมวลผล (Processing Latency) | เรียกใช้: performance.now()ถูกเรียกใช้โดย: CameraManager, PoseProcessor, DebugManager |
replay_manager.js | ReplayManager | 208 | จัดการการบันทึกเฟรมภาพลงบัฟเฟอร์ และเล่นย้อนหลังการรำ (Replay Playback) พร้อมปรับความเร็วได้ | เรียกใช้: Memory Array Buffer ถูกเรียกใช้โดย: ReplayController, ScoringManager |
robot_manager.js | RobotManager | 295 | จัดการระบบครูฝึกหุ่นยนต์จำลอง (Virtual Robot Avatar Guide) สำหรับช่วยนำการรำ | เรียกใช้: DOM Elements ถูกเรียกใช้โดย: RobotPopupManager, MainController |
scoring_manager.js | ScoringManager | 360 | ประมวลผลคะแนนรวม (0-100) ถ่วงน้ำหนักความผิดพลาดตามกฎ คำนวณเกรด และผนวกข้อมูลชีวกลศาสตร์ (SPARC/CRP) | เรียกใช้: BiomechanicalAnalytics, I18nManagerถูกเรียกใช้โดย: HeuristicsEngine, ScorePopupManager |
4.2 การวิเคราะห์ชีวกลศาสตร์ (Biomechanics Analytics - 2 ไฟล์)
ไดเรกทอรี: src/js/biomechanics/
หน้าที่หลัก: การวิเคราะห์สมการชีวกลศาสตร์ขั้นสูงสำหรับงานวิจัยปริญญาเอกและระบบจำลองกายวิภาค
| ชื่อไฟล์ | คลาส/ฟังก์ชันหลัก | บรรทัด | หน้าที่รับผิดชอบเดี่ยว (Single Responsibility) | ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By) |
|---|---|---|---|---|
biomechanical_analytics.js | BiomechanicalAnalytics | 447 | คำนวณความนุ่มนวลการเคลื่อนไหวผ่าน Spectral Arc Length (SPARC), Continuous Relative Phase (CRP) และ Proximal-to-Distal Delay | เรียกใช้: MathUtilsถูกเรียกใช้โดย: ScoringManager, ResearchModeController |
skeleton_simulator.js | SkeletonSimulator | 488 | จำลองการเคลื่อนไหวของกระดูกเชิงชีวกลศาสตร์สำหรับสร้าง 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.js | BaseRule | 86 | คลาสแม่บท (Abstract Base Class) กำหนดโครงสร้างมาตรฐานสำหรับคลาสประเมินกฎทุกข้อ | ถูกสืบทอดโดย: กฎ R1 ถึง R12 ทุกไฟล์ |
biomechanics_rules_config.js | BIOMECH_RULES_CONFIG | 96 | จัดเก็บค่าคอนฟิกพารามิเตอร์ เกณฑ์คะแนน และ Threshold ทางชีวกลศาสตร์ของกฎแต่ละข้อ | ถูกเรียกใช้โดย: HeuristicsEngine, RulesConfigManager |
kinematic_pose_model.js | KinematicPoseModel | 168 | คำนวณพิกัดกายวิภาคตามโมเดล Kinematics สำหรับใช้ตรวจสอบตำแหน่งทางสรีระ | ถูกเรียกใช้โดย: HeuristicsEngine, Unit Tests |
rule_path_shape.js | RulePathShape (R-01) | 120 | ตรวจสอบวิถีโค้งรูปวงกลม/วงรีของการรำสาวไหม (Circular Path Completeness) | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_arm_rotation.js | RuleArmRotation (R-02) | 94 | ตรวจสอบการควงเกลียวของแขนและทิศทางการหงาย/คว่ำของฝ่ามือ (Spiral Rotation) | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_elbow_sinking.js | RuleElbowSinking (R-03) | 52 | ตรวจสอบการจมข้อศอกคลายหัวไหล่ ไม่ให้ศอกลอยสูงเกินแนวไหล่ (Sunken Elbow) | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_waist_initiation.js | RuleWaistInitiation (R-04) | 85 | ตรวจสอบการเคลื่อนไหวเริ่มต้นจากเอว โดยเอวต้องหมุนนำพาแขน (Waist Leads Hands) | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_vertical_stability.js | RuleVerticalStability (R-05) | 72 | ตรวจสอบความนิ่งของแกนศีรษะและลำตัว ไม่ให้กระเพื่อมขึ้นลงผิดธรรมชาติ | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_smoothness.js | RuleSmoothness (R-06) | 75 | ตรวจสอบความสม่ำเสมอและความนุ่มนวลของการเคลื่อนไหว (Movement Smoothness) | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_continuity.js | RuleContinuity (R-07) | 43 | ตรวจสอบความต่อเนื่องของการเคลื่อนไหว ไม่ให้เกิดการหยุดชะงักระหว่างท่วงท่า | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_weight_shift.js | RuleWeightShift (R-08) | 63 | ตรวจสอบการถ่ายเทน้ำหนักระหว่างขาซ้ายและขวาอย่างสมดุล (Rooting & Stance) | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_coordination.js | RuleCoordination (R-09) | 87 | ตรวจสอบการสอดประสานบนล่างระหว่างมือกับสะโพก (Upper-Lower Coordination) | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_bilateral_symmetry.js | RuleBilateralSymmetry (R-10) | 127 | ตรวจสอบความสมมาตรสองซีกร่างและระดับความลาดเอียงของหัวไหล่ (Symmetry) | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_opposition_and_phase.js | RuleOppositionAndPhase (R-11) | 153 | ตรวจสอบความต่างเฟสและการเคลื่อนที่ตรงกันข้ามของสองมือในท่าเมฆา (Phase Offset) | สืบทอด: BaseRule / ถูกใช้โดย: HeuristicsEngine |
rule_hand_coordination.js | RuleHandCoordination (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.js | BackgroundManager | 408 | จัดการฉากหลังเสมือนจริง การเบลอพื้นหลัง และการสลับโหมดห้องฝึกซ้อมดิจิทัล | เรียกใช้: Canvas 2D ถูกเรียกใช้โดย: DrawingManager, DisplaySettingsManager |
display/drawing_manager.js | DrawingManager | 253 | ผู้ประสานงานการวาดภาพหลัก ควบคุม Frame Loop และสั่งงาน Sub-renderers 4 โมดูล | เรียกใช้: 4 Sub-renderers ถูกเรียกใช้โดย: MainController, PoseProcessor |
display/ghost_manager.js | GhostManager | 261 | วาดร่างเงาโปร่งแสงของครูฝึกต้นแบบ (Ghost Master Avatar) ซ้อนทับให้ผู้ฝึกรำตาม | เรียกใช้: Skeleton Datasets ถูกเรียกใช้โดย: DrawingManager |
display/inline_skeleton_player.js | InlineSkeletonPlayer | 251 | คอมโพเนนต์วาดโครงกระดูกอนิเมชันขนาดเล็กแบบ Reusable สำหรับหน้า Dashboard และตารางสถิติ | เรียกใช้: Canvas 2D ถูกเรียกใช้โดย: ResearchModeView, AdminLogsTab |
display/silk_animation.js | SilkParticle | 358 | ระบบอนุภาคและคลื่นเส้นไหมจำลองพลังชี่ (Silk Flow Particle System) | เรียกใช้: Canvas 2D ถูกเรียกใช้โดย: BaseLayout.astro, QiEffectRenderer |
display/webgl_manager.js | WebGLManager | 525 | เรนเดอร์เอฟเฟกต์ 3 มิติและการประมวลผลเชเดอร์ขั้นสูงผ่าน WebGL Context | เรียกใช้: WebGL Context ถูกเรียกใช้โดย: DrawingManager (เมื่อเปิดโหมด GPU) |
display/renderers/canvas_hud_renderer.js | CanvasHudRenderer | 230 | วาดมุมองศาข้อต่อ เส้นวัดระดับ และกล่องบอกสถานะคะแนนบน Canvas HUD | ถูกเรียกใช้โดย: DrawingManager |
display/renderers/mask_renderer.js | MaskRenderer | 182 | วาดหน้ากากเงากั้นขอบเขต ป้องกันแสงสะท้อน และเพิ่มมิติความลึกของการแสดงผล | ถูกเรียกใช้โดย: DrawingManager |
display/renderers/skeleton_renderer.js | PoseSkeletonRenderer | 417 | วาดกระดูกและข้อต่อ 33 จุด พร้อมปรับเปลี่ยนสีตามผลการตรวจจับข้อผิดพลาด | ถูกเรียกใช้โดย: DrawingManager |
display/renderers/trajectory_renderer.js | TrajectoryRenderer | 422 | วาดวิถีการโค้งของมือ เส้นนำทางการหมุนเกลียว และการจางหายของรอยรำ | ถูกเรียกใช้โดย: DrawingManager |
4.5 คอนโทรลเลอร์ควบคุมพฤติกรรม (Application Controllers - 14 ไฟล์)
ไดเรกทอรี: src/js/controllers/
หน้าที่หลัก: ควบคุมตรรกะการไหลของระบบ (Workflow Logic), State Machine, การรับส่งข้อมูลระหว่าง UI และ Core
| ชื่อไฟล์ | คลาส/ฟังก์ชันหลัก | บรรทัด | หน้าที่รับผิดชอบเดี่ยว (Single Responsibility) | ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By) |
|---|---|---|---|---|
auth_manager.js | AuthManager | 397 | จัดการการยืนยันตัวตน สิทธิ์การเข้าถึงระบบวิจัย และรหัสการเข้าร่วมโครงการ (Access Codes) | เรียกใช้: SupabaseClientถูกเรียกใช้โดย: AuthPopupManager, ResearchModeController |
display_controller.js | DisplayController | 958 | ควบคุมการตั้งค่าหน้าจอ การเปิด/ปิดกระจก การแสดงผลมุมกล้อง และสเกล Canvas | ถูกเรียกใช้โดย: DisplayPopupManager, MainController |
env_controller.js | EnvController | 241 | ตรวจสอบและปรับสภาพแวดล้อม เช่น แสงสว่างในห้อง (Lighting) และเสียงรอบข้าง | ถูกเรียกใช้โดย: LightingManager, MainController |
flowstate_controller.js | FlowStateController | 536 | ตรวจวัดและกระตุ้นสภาวะลื่นไหล (Flow State / Zen Mind) เมื่อผู้ฝึกรำได้อย่างต่อเนื่อง | ถูกเรียกใช้โดย: FlowStateManager, ScoringManager |
keyboard_controller.js | KeyboardController | 573 | จัดการ Event ปุ่มกดคีย์บอร์ดทั้งหมดในหน้าห้องฝึกซ้อม (Spacebar, Reset, Mute ฯลฯ) | ถูกเรียกใช้โดย: AppEventBinder, ShortcutsManager |
landing_controller.js | initLandingController | 53 | Master Orchestrator สั่งเริ่มการทำงานของโมดูลหน้าแรกทั้งหมด (Nav, Metrics, Widgets) | เรียกใช้: LandingNav, LandingMetrics, LandingWidgetsถูกเรียกใช้โดย: BaseLayout.astro |
main_controller.js | MainController | 363 | State Machine ผู้ดูแลวงจรชีวิตการฝึกซ้อม (Ready ➡️ Calibrating ➡️ Training ➡️ End) | เรียกใช้: TrainingFlowController, CalibrationManagerถูกเรียกใช้โดย: AppEventBinder |
mobile_controller.js | MobileController | 378 | ปรับแต่ง Layout และควบคุมการโต้ตอบแบบสัมผัส (Touch) เมื่อรันบนสมาร์ตโฟน/แท็บเล็ต | ถูกเรียกใช้โดย: DeviceManager, MainController |
pose_processor.js | PoseProcessor | 935 | กลไกประมวลผลเฟรมภาพ รับพิกัดดิบจาก MediaPipe กรองสัญญาณรบกวน และส่งต่อให้ Rules | เรียกใช้: HeuristicsEngine, CalibrationManagerถูกเรียกใช้โดย: CameraManager |
replay_controller.js | ReplayController | 728 | ควบคุมหน้าต่างและแถบควบคุมการเล่นซ้ำท่ารำ (Timeline, Pause, Fast Forward) | เรียกใช้: ReplayManagerถูกเรียกใช้โดย: AppEventBinder, UIManager |
research_mode_controller.js | ResearchModeController | 1,239 | ตัวควบคุมโปรโตคอลวิจัยทางคลินิก (RCT) ดูแลลำดับ 12 ท่า เวลาพักเบรก และการซิงก์ Cloud | เรียกใช้: ResearchModeView, DataExporter, SupabaseClientถูกเรียกใช้โดย: AppEventBinder |
training_flow_controller.js | TrainingFlowController | 769 | ดูแลลำดับขั้นตอนการเริ่มรำ การนับเวลาถอยหลัง และการสรุปผลการฝึกซ้อม | ถูกเรียกใช้โดย: MainController, AppEventBinder |
video_analysis_controller.js | VideoAnalysisController | 469 | ควบคุมการอัปโหลดไฟล์วิดีโอจากภายนอกเข้ามาประเมินวิเคราะห์แทนการใช้กล้องสด | ถูกเรียกใช้โดย: AppEventBinder, PoseProcessor |
vip_capture_controller.js | VIPCaptureController | 418 | จัดการการบันทึกภาพถ่ายและวิดีโอไฮไลต์ความละเอียดสูงระหว่างการรำที่สมบูรณ์แบบ | ถูกเรียกใช้โดย: UIManager, DataExporter |
4.6 โมดูลหน้าแรกของเว็บไซต์ (Landing Page Modules - 3 ไฟล์)
ไดเรกทอรี: src/js/landing/
หน้าที่หลัก: โมดูลที่เพิ่งได้รับการ Refactor แยกส่วนออกมาใน Phase 4 เพื่อเพิ่มความเร็วในการโหลดและการโต้ตอบบนหน้าแรก
| ชื่อไฟล์ | คลาส/ฟังก์ชันหลัก | บรรทัด | หน้าที่รับผิดชอบเดี่ยว (Single Responsibility) | ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By) |
|---|---|---|---|---|
landing_nav.js | LandingNav | 389 | ดูแลเมนูมือถือ (Hamburger), แถบ Silk Scroll Progress, ปุ่ม Back to Top และคีย์ลัดหน้าแรก (1-5, M, C, ?) | ถูกเรียกใช้โดย: landing_controller.js, BaseLayout.astro |
landing_metrics.js | LandingMetrics | 195 | ควบคุม Scroll Reveal Animation แบบ Play-Once และการนับตัวเลขอัตโนมัติ (Animated Number Count-Up) | ถูกเรียกใช้โดย: landing_controller.js, BaseLayout.astro |
landing_widgets.js | LandingWidgets | 1,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.js | AppEventBinder | 307 | ศูนย์กลางการผูก DOM Event Listeners ทั้งหมดในหน้าห้องฝึกซ้อม (app.html) | เรียกใช้: Controllers ทั้งหมด ถูกเรียกใช้โดย: AppBootstrap |
audio_manager.js | AudioManager | 654 | สังเคราะห์คลื่นเสียงผ่าน Web Audio API (เสียงคอร์ดหยินหยาง, เสียงกระดิ่งเมื่อทำถูก, เสียงโดรนสมาธิ) | ถูกเรียกใช้โดย: ScoringManager, FeedbackManager |
auth_popup_manager.js | AuthPopupManager | 933 | ควบคุมหน้าต่างป๊อปอัปเข้าสู่ระบบ กรอกรหัสการวิจัย และการจัดการสิทธิ์การใช้งาน | เรียกใช้: AuthManagerถูกเรียกใช้โดย: AppEventBinder |
chatbot.js | TaijiChatbot | 332 | ระบบแชตบอตปรึกษาหลักวิชาการมวยไท่เก๊ก (Master Dao AI Assistant) | ถูกเรียกใช้โดย: BaseLayout.astro, LandingNav |
dashboard_popup_manager.js | DashboardPopupManager | 667 | จัดการเปิด/ปิดหน้าต่างโมดอลแผงควบคุมสถิติผู้เรียนและนักวิจัย | เรียกใช้: AdminDashboardViewถูกเรียกใช้โดย: AppEventBinder |
debug_manager.js | DebugManager | 247 | แสดงผลแผงตัวชี้วัดทางเทคนิค (FPS, Processing Latency, Landmark Coordinates) | ถูกเรียกใช้โดย: PerformanceMonitor, KeyboardController |
display_popup_manager.js | DisplayPopupManager | 706 | ควบคุมหน้าต่างป๊อปอัปปรับแต่งมุมมองภาพและขนาดตัวแสดงผล | ถูกเรียกใช้โดย: DisplayController |
display_settings_manager.js | DisplaySettingsManager | 529 | บันทึกและคืนค่าคอนฟิกการแสดงผลลงใน LocalStorage | ถูกเรียกใช้โดย: DisplayPopupManager |
feedback_manager.js | FeedbackManager | 265 | ควบคุมการแสดงกล่องข้อความแนะนำการปรับปรุงท่ารำแบบเรียลไทม์ (HUD Alert Box) | ถูกเรียกใช้โดย: ScoringManager, MainController |
feedback_summary_manager.js | FeedbackSummaryManager | 728 | แสดงผลหน้าต่างสรุปคะแนนเรดาร์ชาร์ตและจุดที่ต้องปรับปรุงหลังจบเซสชันการฝึก | ถูกเรียกใช้โดย: ScoringManager, TrainingFlowController |
feedback_survey_manager.js | SurveyManager | 280 | จัดการแบบสอบถามประเมินความพึงพอใจและประสบการณ์ใช้งาน (SUS Questionnaire) | ถูกเรียกใช้โดย: FeedbackSummaryManager |
flowstate_manager.js | ZenModeManager | 131 | ควบคุมเอฟเฟกต์หน้าจอเมื่อเข้าสู่โหมดเซน (ซ่อน UI ที่ไม่จำเป็นทั้งหมด) | ถูกเรียกใช้โดย: FlowStateController |
gesture_manager.js | GestureManager | 400 | ตรวจจับท่าทางมือ (Hand Gestures) สำหรับสั่งงานระบบโดยไม่ต้องแตะหน้าจอหรือคีย์บอร์ด | ถูกเรียกใช้โดย: PoseProcessor |
landing_flowstate_easter_egg.js | QiMote | 352 | อนิเมชัน Easter Egg ละอองแสงพลังชี่เมื่อกดคีย์บอร์ดสูตรลับ Konami Code | ถูกเรียกใช้โดย: BaseLayout.astro |
lighting_manager.js | LightingManager | 221 | วิเคราะห์ความสว่างของภาพจากกล้องและแจ้งเตือนเมื่อแสงไม่เพียงพอ | ถูกเรียกใช้โดย: EnvController |
research_mode_view.js | ResearchModeView | 456 | โมดูลมุมมอง (View) ของระบบวิจัย สร้าง HTML Layout, ตาราง 12 ท่า และนาฬิกาพักเบรก | เรียกใช้: InlineSkeletonPlayerถูกเรียกใช้โดย: ResearchModeController |
robot_popup_manager.js | RobotPopupManager | 176 | ควบคุมป๊อปอัปแนะนำท่าทางโดยครูฝึกหุ่นยนต์จำลอง | ถูกเรียกใช้โดย: RobotManager |
rules_config_manager.js | RulesConfigManager | 535 | ควบคุมหน้าต่างปรับแต่งค่า Threshold ทางคณิตศาสตร์ของกฎ 12 ข้อสำหรับนักวิจัย | เรียกใช้: BIOMECH_RULES_CONFIGถูกเรียกใช้โดย: AppEventBinder |
rules_popup_manager.js | RulesPopupManager | 441 | ควบคุมหน้าต่างอธิบายทฤษฎีและหลักปรัชญาของกฎแต่ละข้อ | ถูกเรียกใช้โดย: AppEventBinder |
score_popup_manager.js | ScorePopupManager | 526 | ควบคุมการแสดงผลการ์ดคะแนนลอยตัวและการเฉลิมฉลองเมื่อได้เกรด A | ถูกเรียกใช้โดย: ScoringManager |
shortcuts_manager.js | ShortcutsManager | 303 | จัดการหน้าต่างแสดงรายการคีย์ลัดคีย์บอร์ดทั้งหมดในหน้าห้องฝึก | ถูกเรียกใช้โดย: KeyboardController |
theater_controller.js | TheaterController | 263 | ควบคุมโหมดโรงละคร (Theater Mode) ดิมไฟหน้าจอเพื่อเน้นเฉพาะการรำ | ถูกเรียกใช้โดย: AppEventBinder |
tutorial_manager.js | TutorialManager | 959 | แนะนำขั้นตอนการใช้งานระบบแบบทีละสเต็ป (Interactive Guided Onboarding Tour) | ถูกเรียกใช้โดย: AppBootstrap |
ui_manager.js | UIManager | 853 | ศูนย์กลางควบคุมการสลับหน้าจอ การซ่อน/แสดงพาเนล และสไตล์ธีม | ถูกเรียกใช้โดย: AppBootstrap, MainController |
wisdom_manager.js | WisdomManager | 247 | สุ่มแสดงคำสอนและคติธรรมมวยไท่เก๊กโบราณเพื่อสร้างแรงบันดาลใจ | ถูกเรียกใช้โดย: UIManager |
4.8 แดชบอร์ดวิจัยและระบบผู้ดูแล (Admin & Research Dashboard - 6 ไฟล์)
ไดเรกทอรี: src/js/ui/dashboard/
หน้าที่หลัก: ระบบสถิติขั้นสูงสำหรับนักวิจัย วิเคราะห์เส้นทางการเรียนรู้ และการจัดการข้อมูลผู้เข้าร่วมโครงการ
| ชื่อไฟล์ | คลาส/ฟังก์ชันหลัก | บรรทัด | หน้าที่รับผิดชอบเดี่ยว (Single Responsibility) | ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By) |
|---|---|---|---|---|
admin_analysis_tab.js | AdminAnalysisTab | 950 | เรนเดอร์กราฟวิเคราะห์แนวโน้มพัฒนาการ (Learning Curves) และ Radar Chart 6 มิติ | เรียกใช้: Chart.js, DashboardChartConfigถูกเรียกใช้โดย: AdminDashboardView |
admin_dashboard.js | AdminDashboardView | 293 | คอนเทนเนอร์หลักของแผงควบคุมแอดมิน จัดการการสลับแท็บและการควบคุมสิทธิ์ | เรียกใช้: ทุกแท็บใน dashboard/ถูกเรียกใช้โดย: DashboardPopupManager |
admin_database_tab.js | AdminDatabaseTab | 280 | จัดการและตรวจสอบตารางข้อมูลบน Supabase Cloud Telemetry | เรียกใช้: SupabaseClientถูกเรียกใช้โดย: AdminDashboardView |
admin_logs_tab.js | AdminLogsTab | 1,674 | แสดงตารางประวัติผู้เข้าร่วมวิจัย การกรองข้อมูล และการส่งออก CSV ขนาดใหญ่ | เรียกใช้: InlineSkeletonPlayer, DataExporterถูกเรียกใช้โดย: AdminDashboardView |
admin_overview_tab.js | AdminOverviewTab | 554 | สรุปภาพรวม KPI ระบบ สถิติจำนวนชั่วโมงการฝึกซ้อม และผู้ใช้งานที่กำลัง Active | ถูกเรียกใช้โดย: AdminDashboardView |
dashboard_chart_config.js | DashboardChartConfig | 197 | จัดเก็บการตั้งค่าสไตล์ สี พาเลตต์ และฟอนต์สำหรับกราฟ Chart.js ทั้งหมด | ถูกเรียกใช้โดย: AdminAnalysisTab |
4.9 เครื่องมือสนับสนุนและบริการ (Utilities & Services - 12 ไฟล์)
ไดเรกทอรี: src/js/utils/
หน้าที่หลัก: คลาสยูทิลิตี้สำหรับงานคำนวณ เชื่อมต่อฐานข้อมูล แปลภาษา และตรวจจับอุปกรณ์
| ชื่อไฟล์ | คลาส/ฟังก์ชันหลัก | บรรทัด | หน้าที่รับผิดชอบเดี่ยว (Single Responsibility) | ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By) |
|---|---|---|---|---|
data_exporter.js | DataExporter | 361 | เครื่องยนต์สร้างชุดข้อมูลวิจัย ส่งออกไฟล์ CSV รายเฟรม และ JSON Snapshot คุณภาพสูง | ถูกเรียกใช้โดย: ResearchModeController, AdminLogsTab |
device_manager.js | DeviceManager | 466 | วิเคราะห์ประสิทธิภาพชิปประมวลผล (GPU/CPU Tiering) และปรับระดับการแสดงผลอัตโนมัติ 3 ระดับ | ถูกเรียกใช้โดย: AppBootstrap, DrawingManager |
i18n_manager.js | I18nManager | 268 | ตัวจัดการระบบสองภาษา (ไทย/อังกฤษ) สลับข้อความทั้งแอปแบบ On-the-Fly | เรียกใช้: translations.jsถูกเรียกใช้โดย: ทุกคอมโพเนนต์ในระบบ |
math_utils.js | MathUtils | 79 | ฟังก์ชันคณิตศาสตร์บริสุทธิ์: คำนวณระยะห่าง 3 มิติ, มุมเวกเตอร์, และมุมองศาข้อต่อ | ถูกเรียกใช้โดย: rules/, biomechanics/, core/ |
path_generator.js | generateWristCirclePath | 85 | สร้างพิกัดวิถีวงกลมและเกลียวไหมในอุดมคติสำหรับเป็นเกณฑ์เปรียบเทียบ | ถูกเรียกใช้โดย: GhostManager, Unit Tests |
session_manager.js | getOrCreateUserId | 121 | จัดการการระบุตัวตนของผู้ใช้ (Anonymous User ID) และรหัสเซสชันการฝึก | ถูกเรียกใช้โดย: AppBootstrap, ScoringManager |
skeleton_renderer.js | SkeletonRenderer | 105 | ฟังก์ชันยูทิลิตี้วาดโครงกระดูกแบบ Standalone สำหรับสคริปต์ขนาดเล็ก | ถูกเรียกใช้โดย: InlineSkeletonPlayer |
smart_fov_controller.js | SmartFovController | 287 | ควบคุมขอบเขตมุมมองกล้อง (Field of View) แบบอัตโนมัติตามระยะห่างของผู้ฝึก | ถูกเรียกใช้โดย: CameraManager |
supabase_client.js | tryNextCdn | 75 | ตัวเชื่อมต่อฐานข้อมูล Supabase Cloud พร้อมระบบ Fallback สลับ CDN อัตโนมัติ | ถูกเรียกใช้โดย: AuthManager, AdminDatabaseTab |
theme_manager.js | ThemeManager | 147 | ควบคุมและสลับโหมดสี Dark / Light Mode และบันทึกลง LocalStorage | ถูกเรียกใช้โดย: AppBootstrap, UIManager |
time_utils.js | TimeUtils | 85 | ฟังก์ชันแปลงวินาทีเป็นรูปแบบเวลา (MM:SS) และจัดการประทับเวลาสถิติ | ถูกเรียกใช้โดย: TrainingFlowController, ReplayManager |
translations.js | translations | 35 | พจนานุกรมคำศัพท์และข้อความแปลภาษาพื้นฐานของระบบ | ถูกเรียกใช้โดย: I18nManager |
4.10 ระบบทดลองและต้นแบบอนาคต (Experimental & Future Prototypes - 2 ไฟล์)
ไดเรกทอรี: src/js/experimental/
หน้าที่หลัก: พื้นที่ทดลองเทคโนโลยีระดับ Edge AI และการเร่งความเร็วด้วย WebGPU สำหรับ Phase 3-4
| ชื่อไฟล์ | คลาส/ฟังก์ชันหลัก | บรรทัด | หน้าที่รับผิดชอบเดี่ยว (Single Responsibility) | ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By) |
|---|---|---|---|---|
sequence_controller.js | SequenceController | 384 | ตัวควบคุมการจัดลำดับการเคลื่อนไหวแบบต่อเนื่องสำหรับโมเดลลำดับเวลา (Time-Series) | ถูกเรียกใช้โดย: Experimental Sandbox |
webgpu_manager.js | WebGPUManager | 196 | ทดสอบการรัน Neural Network บนเบราว์เซอร์ผ่าน WebGPU Compute Shaders | ถูกเรียกใช้โดย: Experimental Sandbox |
4.11 การตั้งค่าระดับราก (Root Configs - 2 ไฟล์)
ไดเรกทอรี: src/js/
หน้าที่หลัก: กำหนดตัวแปรสภาพแวดล้อม รหัสเชื่อมต่อฐานข้อมูล และการตั้งค่าระบบวิจัย
| ชื่อไฟล์ | คลาส/ฟังก์ชันหลัก | บรรทัด | หน้าที่รับผิดชอบเดี่ยว (Single Responsibility) | ความสัมพันธ์และการเชื่อมต่อ (Dependencies & Used By) |
|---|---|---|---|---|
config.example.js | config.example | 21 | แม่แบบตัวแปรสภาพแวดล้อม (Supabase URL, Anon Key, Access Codes) | ใช้เป็นต้นแบบ: สำหรับการสร้าง config.js |
config.js | config | 18 | ค่าคอนฟิกสภาพแวดล้อมจริงที่ถูกใช้งานขณะรันแอปพลิเคชัน | ถูกเรียกใช้โดย: SupabaseClient, AuthManager |
บทที่ 5: การออกแบบ Dependency Injection และการสื่อสารข้ามโมดูล (DI & Event Bus)
5.1 สถาปัตยกรรม Dependency Injection ผ่าน AppBootstrap
เพื่อแก้ไขปัญหาการพึ่งพากันแบบผูกติดแน่น (Tight Coupling) ระบบจึงใช้คลาส AppBootstrap เป็นศูนย์กลางการสร้างอินสแตนซ์และทำ Dependency Injection โดยจัดเก็บตัวแปรที่ถูกสร้างทั้งหมดไว้ใน Global Namespace กลาง:
// ตัวอย่างโครงสร้างการจัดเก็บ 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 เพียงก้อนเดียว:
// โครงสร้าง 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-evaluated | PoseProcessor | ScoringManager, DrawingManager, Audio | { frameIndex, landmarks, scores, rulesStatus, timestamp } | ส่งผลการประเมินเฟรมปัจจุบันไปอัปเดตคะแนน เรนเดอร์ และเสียง |
taiji:calibration-start | CalibrationManager | CanvasHudRenderer, AudioManager | { durationSec: 3, poseType: 'T-POSE' } | เริ่มกระบวนการนับถอยหลังยืนคาลิเบรตสรีระ |
taiji:calibration-complete | CalibrationManager | TrainingFlowController, MainController | { scale, shoulderWidth, armLength, torsoHeight } | บันทึกสเกลสรีระเข้าสู่ LocalStorage และปลดล็อกการเริ่มรำ |
taiji:pose-changed | AppEventBinder | KinematicPoseModel, FeedbackManager | { poseId: 'single_whip', poseIndex: 2 } | สลับแม่แบบท่ารำและข้อความแนะนำทางชีวกลศาสตร์ |
taiji:break-started | ResearchModeController | ResearchModeView, AudioManager | { breakType: 'SHORT'|'LONG', durationSec: 60|300 } | แสดงหน้าต่างบังคับให้อาสาสมัครหยุดพักระหว่างการทดลอง RCT |
taiji:tier-changed | DeviceManager | DrawingManager, 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):
ข้อดีเชิงสถาปัตยกรรม:
- Partial Redraw: เส้นวิถีไหม (Trajectory) ใน Layer 3 สามารถวาดทับและค่อยๆ จางหาย (Fade Out) โดยใช้
fillStyle = 'rgba(0,0,0,0.05)'โดยไม่ต้องสั่งล้างและวาดโครงกระดูกใน Layer 2 ใหม่ทุกเฟรม - GPU Composition: เบราว์เซอร์สามารถใช้ Hardware Compositor แยกเธรดการซ้อนภาพแต่ละเลเยอร์ ทำให้ได้เฟรมเรตที่ราบรื่นระดับ 60 FPS แม้บนอุปกรณ์พกพา
6.2 การควบคุมวงรอบเรนเดอร์และเทคนิคการลดขยะหน่วยความจำ (Garbage Collection Optimization)
ในแอปพลิเคชันคอมพิวเตอร์วิทัศน์แบบเรียลไทม์ การจองหน่วยความจำชั่วคราวซ้ำๆ ใน requestAnimationFrame จะทำให้ Garbage Collector (GC) ทำงานบ่อยครั้ง ส่งผลให้เกิดอาการกระตุก (Micro-Stutter):
// แนวปฏิบัติที่ 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 (อุปกรณ์ระดับเริ่มต้น / ประหยัดพลังงาน) |
|---|---|---|---|
| เกณฑ์การตรวจจับ GPU | Apple Silicon (M1–M4), A16–A18, Snapdragon 8 Gen 2–4, Dedicated Nvidia/AMD | Snapdragon 7xx, Dimensity 8xxx, Apple A13–A15, Intel Iris Xe | ชิปเซ็ตรุ่นเก่า, RAM < 4GB, หรือตรวจพบเบราว์เซอร์เปิดโหมด Low Power |
| ความถี่เป้าหมาย (FPS) | 60 FPS | 30–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 Mesh | 2D 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 มิติ (
) ที่ผ่านการคำนวณทางตรีโกณมิติเพื่อทดสอบท่ารำที่สมบูรณ์แบบและท่ารำที่มีจุดบกพร่อง - 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 ( | การลบค่าตรงๆ จะได้ผลต่าง | ใช้อัลกอริทึม Normalization: diff = ((diff + 180) % 360) - 180 | tests/unit/heuristics_engine.test.js |
| Division by Zero in Angular Velocity | เมื่อ Infinity | ตรวจสอบ if (dt <= 0.0001) return 0; | tests/unit/heuristics_engine.test.js |
| High Frequency Landmark Jitter | สัญญาณรบกวนจากกล้องทำให้ค่า Jerk สูงเกินจริง | กรองสัญญาณด้วย 2nd-order Butterworth Filter ตัดความถี่เกิน 6Hz | tests/unit/biomechanical_analytics.test.js |
| SPARC Peak Amplitude Cutoff | สเปกตรัมที่ความถี่สูงเกินไปอาจหลุดช่วง Cutoff | กำหนดขอบเขตความถี่การคำนวณ | tests/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 / 척추 파동):
- สร้างไฟล์กฎใหม่: สร้าง
src/js/rules/rule_spinal_wave.jsโดยสืบทอดหรือใช้โครงสร้างเมธอดevaluate(landmarks, history, context)ซึ่งต้องส่งคืนค่า{ pass: boolean, score: number, errorMagnitude: number, message: string } - ลงทะเบียนใน Engine: เพิ่มกฎใหม่ลงใน
src/js/rules/rules_engine.jsในอาร์เรย์this.rules - แมปเข้าสู่ Principle: เปิดไฟล์
src/js/core/scoring_manager.jsแล้วเพิ่มการจับคู่รหัสกฎR-13เข้ากับ 1 ใน 6 หลักการไท้เก๊ก (เช่นTrunk Coordination) - เพิ่มคำแปลภาษา: เพิ่มคีย์ข้อความแนะนำและชื่อกฎลงใน
src/js/utils/i18n.js(รองรับทั้งภาษาไทยและอังกฤษ) - เขียนชุดทดสอบ: เพิ่มกรณีทดสอบ PASS/FAIL ลงใน
tests/unit/rules_engine.test.jsแล้วรันnpm testยืนยันผล 100%
🥋 Recipe 2: ขั้นตอนการเพิ่มกระบวนท่ารำใหม่ (Adding a New Form/Pose Template)
- กำหนดโครงสร้างทางชีวกลศาสตร์: เปิด
src/js/core/kinematic_pose_model.jsและเพิ่มฟังก์ชันสร้างพิกัดแม่แบบgeneratePoseTemplate(poseName, t) - เพิ่มตัวเลือกใน UI: เพิ่ม
<option value="new_pose">ในpublic/app.htmlหรือผ่านคอมโพเนนต์src/components/ - อัปเดตเกณฑ์คะแนนเฉพาะท่า: กำหนดค่าน้ำหนักกฎ (Rule Weights Matrix) สำหรับท่านั้นๆ ใน
src/js/controllers/training_flow_controller.js
🎨 Recipe 3: ขั้นตอนการสร้าง Sub-Renderer สำหรับการแสดงผลใหม่
- สร้างคลาสเรนเดอร์ใหม่ใน
src/js/display/เช่นforce_vector_renderer.js - กำหนดเมธอดมาตรฐาน
render(ctx, landmarks, metrics, tier) - นำเข้าและเชื่อมต่อเข้ากับ
DrawingManagerในsrc/js/display/drawing_manager.jsโดยครอบด้วยการตรวจสอบ Tiering เพื่อประสิทธิภาพ
8.2 แผนการยกระดับสถาปัตยกรรมซอฟต์แวร์ (Architectural Refactoring Roadmap)
เพื่อรองรับการเติบโตของโครงการใน Phase 3 และ Phase 4 คณะผู้วิจัยและทีมพัฒนาได้กำหนดแผนที่การยกระดับสถาปัตยกรรมไว้ 3 ระยะ:
- การยกระดับสู่ระบบ Type Safety (TypeScript
.d.ts): ปัจจุบันระบบใช้ JSDoc เต็มรูปแบบ ในระยะถัดไปจะสร้างไฟล์ Type Declaration (@types/taijiflow.d.ts) เพื่อให้ IDE สามารถตรวจสอบ Types ได้โดยไม่ต้องแปลง Build Pipeline - การแยกเธรดคำนวณชีวกลศาสตร์สู่ Web Worker: การคำนวณ SPARC FFT และ Continuous Relative Phase จะถูกย้ายไปทำงานบน Background Web Worker เพื่อให้เธรดหลัก (Main Thread) ทำงานเรนเดอร์ Canvas 60 FPS ได้อย่างอิสระโดยไม่สะดุด
- การเปลี่ยนผ่านสู่ 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/ได้รับการอ้างอิงและปรับปรุงอย่างสอดคล้องกันทุกครั้ง