# SPEC 76: Daily 3:00 AM Automated Audit & Unified IPC / Coordinate SSoT Specification

**Mốc thời gian xác lập**: `28/09/2026`  
**Trạng thái**: `[PRODUCTION / CODE-PRESENT & TEST-VERIFIED]`  
**Phạm vi áp dụng**: Toàn hệ thống AutoPOE2 (C++23 Core 120Hz Hot Path + Python 3.11 Companion + Rule 7 AGENTS.md)

---

## 1. Bối Cảnh & Mục Tiêu Kỹ Thuật

Theo kết quả kiểm toán toàn diện mã nguồn ngày 28/09/2026 thông qua quy chuẩn **Alibaba Open Code Review (Delegation Mode)**, hệ thống AutoPOE2 đã xác định 3 hạng mục hoàn thiện trọng yếu nhằm triệt tiêu nợ kỹ thuật và nguy cơ lệch pha kiến trúc:
1. **Đồng nhất hóa Unpack Routine trong `core_shm_bridge.py`**: Xóa bỏ sự phân mảnh schema dữ liệu giữa hàm đọc tức thời (`_read_telemetry_once`) và luồng nền 30Hz (`_worker_loop`).
2. **Chuẩn hóa Phép Chiếu Isometric SSoT trong `src/common/coordinate_transform.py`**: Cung cấp hàm chuyển đổi 2D chuẩn hóa (`world_to_screen_isometric`, `world_to_wasd`) khớp 100% với thuật toán C++ trong `src/core/common/math2d.hpp`.
3. **Hiện thực hóa Chu Trình Rà Soát Định Kỳ 3:00 AM (Rule 7 AGENTS.md)**: Xây dựng công cụ kiểm toán tự động `tools/daily_audit_3am.py` tự động đối soát toàn bộ cấu trúc nhị phân, bất biến kiến trúc, phím tắt an toàn và tần số nhịp vòng lặp.

---

## 2. Kiến Trúc Giải Pháp & Chi Tiết Triển Khai

### 2.1. Unified Unpack Telemetry Routine (`core_shm_bridge.py`)
Trước đây, `_worker_loop` bỏ sót các trường `hp`, `max_hp`, `stagger`, `anim` của thực thể và bỏ qua 13 trạng thái vòng đời `CharacterLifecycleState` từ bitmask `(mov_flags >> 16) & 0xFF`.

**Giải pháp SSoT**:
- Triển khai hàm dùng chung duy nhất:
  ```python
  def unpack_telemetry_packet(slot_buf: bytes) -> CoreTelemetrySnapshot:
      # Giải mã 39,112 bytes TelemetryPacket khớp 100% protocol.hpp
  ```
- Cung cấp đồng thời cả `flags` và `extra_flags` trong dictionary của từng entity để tương thích ngược 100%.
- Cả `_read_telemetry_once` và `_worker_loop` đều gọi qua `unpack_telemetry_packet(slot_buf)`.
- Bổ sung Opcode 11 (`FORCE_PORTAL_RETURN`) và Opcode 12 (`SET_COMBAT_PROFILE`) cùng enum `CombatProfile` (`MOB_CLEARING=0`, `BOSS_BURST=1`, `SURVIVAL_KITING=2`).

### 2.2. SSoT Isometric Projection & Direction Mapping (`coordinate_transform.py`)
- **`world_to_screen_isometric(dx, dy, dist, screen_w, screen_h, margin)`**:
  - Tọa độ X: $\text{targetX} = c_x + (\hat{dx} - \hat{dy}) \times \text{dist} \times 0.70710678$
  - Tọa độ Y: $\text{targetY} = c_y - (\hat{dx} + \hat{dy}) \times \text{dist} \times 0.45000000$
  - Clamping tự động trong khoảng $[margin, \text{dim} - margin]$.
- **`world_to_wasd(dx, dy, deadzone=0.01, threshold=0.38)`**:
  - Chiếu vector thế giới sang 2 trục màn hình nghiêng 45 độ và phân định 8 hướng phím WASD.
  - Phím Up (W thuần túy) tương ứng với vector $(\Delta X > 0, \Delta Y > 0)$.
  - Trục Bắc thế giới $(0, +Y)$ chiếu thành tổ hợp $(W + A)$.

### 2.3. Daily 3:00 AM Automated Audit Engine (`tools/daily_audit_3am.py`)
Thực thi 7 chốt kiểm toán tự động độc lập:
1. `audit_binary_struct_alignment()`: So khớp kích thước `SharedMemoryHeader` (64B), `CommandPacket` (36B), `TelemetryPacket` (39112B), `PlayerTelemetryData` (84B), `EntityTelemetryData` (88B), `AreaTelemetryData` (96B).
2. `audit_panic_killswitch_hotkeys()`: Kiểm tra `VK_PAUSE` và `Ctrl+Shift+VK_F12` trong C++ Core và tài liệu docs (loại trừ phím F12 đơn lẻ).
3. `audit_loop_frequencies()`: Kiểm tra nhịp 120Hz (~8.33ms) trong `main.cpp`.
4. `audit_master_invariants()`: Kiểm tra đủ 20+ Bất biến Kiến trúc SSoT trong `zero_day_gate.py`.
5. `audit_zero_mock_data()`: Kiểm tra không chứa số liệu giả lập bịa đặt theo Rule 14.
6. `audit_watchdog_timeout()`: Kiểm tra `kAgentWatchdogTimeoutMs == 5000`.
7. `run_automated_unit_tests()`: Chạy `pytest` trên toàn bộ các test suite hồi quy.

Xuất báo cáo định dạng Markdown tại:
- `docs/development/daily_audits/AUDIT_<YYYYMMDD_HHMMSS>.md`
- `docs/development/daily_audits/LATEST_AUDIT.md`

---

## 3. Bằng Chứng Thực Nghiệm & Kết Quả Đo Lường (28/09/2026)

### 3.1. Kết Quả Kiểm Toán 3:00 AM (`tools/daily_audit_3am.py`)
```text
[DailyAudit] Bắt đầu kiểm toán hệ thống AutoPOE2...
[DailyAudit 3:00 AM] Hoàn tất kiểm toán: THÀNH CÔNG (100% PASS) (15/15 checks passed in 5.10s)
[DailyAudit 3:00 AM] Báo cáo đã lưu tại: docs/development/daily_audits/AUDIT_20260928_173111.md
```

### 3.2. Bộ Kiểm Thử C++ Core Engine (`AutoPOE2_Tests.exe`)
```text
[RESULT] TẤT CẢ 1230 KIỂM TRA ĐỀU ĐẠT (PASS)
1230/1230 assertions PASSED (0 failures)
```

### 3.3. Bộ Kiểm Thử Python Companion & Invariant Tests (`pytest`)
```text
tests/test_audit_invariants_fixes.py ..... PASSED [ 20%]
tests/test_coordinate_isometric_parity.py ..... PASSED [ 40%]
tests/test_ocr_coordinate_contract.py .... PASSED [ 60%]
tests/test_waystone_crafter.py .......... PASSED [100%]
============================== 24 passed in 4.24s ==============================
```