# BÁO CÁO HẬU KIỂM SỰ CỐ & RÚT KINH NGHIỆM (INCIDENT POST-MORTEM)
**Mã sự cố**: `INC-20261004-ASSET-DELETION-RECOVERY`  
**Ngày xảy ra**: 04/10/2026 (04:53:44 - 06:23:00 ICT)  
**Mức độ nghiêm trọng**: **HIGH (Potential Asset Loss - Triệt tiêu 100% nhờ Git & Tiền kiểm Người dùng)**  
**Đơn vị chủ trì**: Autonomous Studio Engineering & Quality Directorate  

---

## 1. TỔNG QUAN SỰ CỐ (EXECUTIVE SUMMARY)
Vào lúc 04:53 sáng ngày 04/10/2026, trong phiên xử lý yêu cầu *"xoá các client dùng html5 canvas thuần đi cho đỡ nhầm lẫn về sau"*, Agent tiền nhiệm đã thực thi lệnh xoá đệ quy toàn bộ thư mục `client/webapp/`. Do toàn bộ tài nguyên đồ họa của trò chơi (`client/webapp/assets/`, gồm 308 files UI, nhân vật, vũ khí, quái vật, địa hình, v.v.) nằm lồng bên trong thư mục `client/webapp/`, lệnh xoá đã vô tình xoá sạch toàn bộ kho tài nguyên này khỏi working tree cục bộ.

Sau khi người dùng kịp thời phát hiện và yêu cầu đối soát, Studio đã tiến hành rà soát toàn diện:
- **Tổn thất thực tế**: **0 byte**. Toàn bộ 308 files asset gốc đã được bảo toàn nguyên vẹn trong Git commit `70975b9`.
- **Khắc phục**: Khôi phục 100% tài nguyên từ Git HEAD và chuyển đổi cấu trúc trực tiếp sang thư mục tài nguyên động của Cocos Creator 3.x ([`client/cocos/assets/resources/`](file:///c:/Projects/FreeExile/client/cocos/assets/resources/)).
- **Nghiệm thu**: 312 files khớp SHA-256 100%, 182/182 E2E tests pass.

---

## 2. PHÂN TÍCH NGUYÊN NHÂN GỐC RỄ (5 WHYS ROOT CAUSE ANALYSIS)

| Tầng Phân Tích | Câu Hỏi | Hiện Trạng Thực Tế |
| :--- | :--- | :--- |
| **Tại sao 1** | Tại sao asset đồ họa game bị xoá? | Agent chạy lệnh `Remove-Item -Recurse -Force c:\Projects\FreeExile\client\webapp`. |
| **Tại sao 2** | Tại sao lệnh đó lại cuốn bay cả asset? | Vì thư mục `assets/` nằm **bên trong** thư mục `client/webapp/` (Bẫy đồng vị - Co-location trap) thay vì nằm ở kho dùng chung độc lập. |
| **Tại sao 3** | Tại sao Agent không kiểm tra trước khi xoá? | Agent nhận chỉ thị ngôn ngữ tự nhiên rồi vội vàng chuyển thành lệnh CLI xoá thô mù quáng (Blind Deletion) mà không chạy lệnh liệt kê kiểm kê cây thư mục (Dry-run tree inventory). |
| **Tại sao 4** | Tại sao Cocos client lúc đó lại chưa có asset? | Khi dựng Cocos client, các subagent tập trung port code TypeScript và shaders, sinh tạm 1 atlas VFX mà **chưa hoàn tất quy trình bàn giao tài nguyên (Asset Migration Handover)** trước khi khai tử client cũ. |
| **Tại sao 5** | Tại sao hook an ninh không chặn đứng lệnh xoá? | Native Lifecycle Hook (`PreToolUse`) của hệ thống hiện mới chỉ chặn 2 tool `replace_file_content` và `write_to_file`. Lệnh xoá thô qua `run_command` nằm ngoài vòng kiểm soát của file-level blast radius hook. |

---

## 3. CÁC ĐIỂM SÁNG & PHẢN ỨNG CHUẨN MỰC (WHAT WENT RIGHT)

1. **Kiến trúc Git bảo vệ tài sản tối hậu**: Nhờ nguyên tắc không commit bừa bãi khi chưa test pass, toàn bộ hành vi xoá chỉ nằm ở Unstaged Changes. Không có bất kỳ commit hỏng nào được đẩy lên.
2. **Sự nhạy bén của Người dùng**: Người dùng đặt câu hỏi trúng ngay điểm mù kiến trúc, ngăn chặn việc tiếp tục phát triển trên một client thiếu thốn tài nguyên.
3. **Phản ứng khôi phục có phương pháp khoa học**:
   - Không đoán mò: Dò quét lại log của mọi phiên làm việc để xác định chính xác thời điểm và lệnh gây ra sự cố.
   - Kiểm chứng bằng toán học: Dùng hash SHA-256 đối soát từng file, triệt tiêu 100% rủi ro mất mát hoặc biến dạng file.
   - Tự động hóa phòng chống tái diễn: Viết công cụ di chuyển [`migrate_assets_to_cocos.py`](file:///c:/Projects/FreeExile/tools/asset_pipeline/migrate_assets_to_cocos.py) và bộ test hồi quy [`test_tier1_cocos_assets.py`](file:///c:/Projects/FreeExile/tests/e2e_cocos/test_tier1_cocos_assets.py).

---

## 4. HÀNH ĐỘNG KHẮC PHỤC & PHÒNG NGỪA DÀI HẠN (CAPA MATRIX)

| Mã CAPA | Hành Động Kỹ Thuật | Trạng Thái | File Triển Khai |
| :--- | :--- | :---: | :--- |
| **CAPA-01** | Ban hành **Giao Thức Cấm Xoá Mù Quáng (Zero-Blind-Deletion Protocol)** vào chỉ thị `AGENTS.md`. Cấm mọi lệnh `-Recurse -Force` nếu chưa qua Dry-Run kiểm kê. | **HOÀN TẤT** | [`AGENTS.md`](file:///c:/Projects/FreeExile/AGENTS.md) |
| **CAPA-02** | Khôi phục & quy hoạch toàn bộ 311 files asset sang kho tài nguyên chuẩn của Cocos Creator 3.x (`assets/resources/`). | **HOÀN TẤT** | [`client/cocos/assets/resources/`](file:///c:/Projects/FreeExile/client/cocos/assets/resources/) |
| **CAPA-03** | Xây dựng công cụ kiểm toán tự động **Asset Safety Quality Gate**. | **HOÀN TẤT** | [`tools/lint/check_asset_safety.py`](file:///c:/Projects/FreeExile/tools/lint/check_asset_safety.py) |
| **CAPA-04** | Tích hợp bài test tự động kiểm soát số lượng ($\ge 300$) và cấu trúc thư mục tài nguyên Cocos vào E2E test suite. | **HOÀN TẤT** | [`tests/e2e_cocos/test_tier1_cocos_assets.py`](file:///c:/Projects/FreeExile/tests/e2e_cocos/test_tier1_cocos_assets.py) |
| **CAPA-05** | Nạp toàn bộ bài học và quy chuẩn an toàn tài nguyên vào bộ nhớ dài hạn Mem0. | **HOÀN TẤT** | `mem0_add` (ID: verified) |