Hybrid Engine — Tài liệu

Hybrid Engine — a WP Remap tool

"The spreadsheet-database hybrid for WordPress"

Công cụ tạo bảng dữ liệu có quan hệ + tính toán theo kỳ + chốt sổ ngay trong WordPress, chạy được trên shared hosting (nơi NocoDB/Baserow không chạy được).

Cấu trúc thư mục

Thư mục / File	Chứa gì
excel-analysis.md	Nền tảng thực nghiệm — phân tích file lương MHF (vấn đề, nguyên nhân gốc, số liệu khả thi). Đọc trước.
loi-tham-chieu-vong-va-tham-chieu-treo-trong-excel.md	Báo cáo: lỗi tham chiếu vòng & tham chiếu treo trong Excel — nguyên nhân, tác hại, phòng ngừa, khắc phục
plans/	Lộ trình hiện tại → tương lai, sơ đồ kiến trúc MVP. Bao gồm research bổ sung pros-cons & competitive positioning (hybrid-engine-strategic-pros-cons-research.md).
decisions/	Các quyết định kiến trúc đã thống nhất qua trao đổi (ADR)
ideations/	Ý tưởng chưa chốt — đừng code theo cái ở đây
archive/	File đã hết vòng đời (prompt dùng một lần, đã giao xong việc) — giữ để tra, đừng làm theo
mockups/	Mockup UI (mở trực tiếp bằng trình duyệt). Hiện có: nhan-vien-grid.html — grid nhân viên cấu hình giống sheet lương Excel

AI Agent Context (bắt buộc cho mọi AI task):

• .context/ — AI working memory (GLOBAL, MILESTONES, TENSIONS, modules, planning). Đọc trước mọi task theo protocol trong AGENTS.md.
• AGENTS.md (root) — Protocol bắt buộc: load order, invariants, tension, coding standards, self-check.
• docs/workflows/context-map-workflow.md — Khi nào update .context/ vs docs/.
• docs/standards/ai-rules.md + security-guidelines.md — Quy tắc AI + PHP security.

Trạng thái hiện tại (2026-06-30)

• Đã xác định: tên, định vị, môi trường mục tiêu, data model, mô hình kỳ/snapshot.
• Use case dẫn đường (north-star): bảng lương MHF — đã phân tích khả thi (45.555 công thức → 117 shapes → 21 hàm phổ thông → chuỗi tính sâu 11 bước).
• Bước kế tiếp: POC PHP thuần tái hiện 1 chuỗi tính lương 1 nhân viên / 1 kỳ (Phase 0 / 0.1.0).
• Đang để ngỏ (ideation): "Excel formula engine" (viết công thức kiểu Excel, tự dịch sang PHP) — KHÔNG làm trong MVP vì tốn thời gian (xem Phase 4).
• Cấu trúc Agent mới: Đã áp dụng context-mapping (.context/, AGENTS.md, MILESTONES, TENSIONS) giống skvn-marine. Mọi AI task phải tuân thủ load protocol và invariants. Xem AGENTS.md + .context/README.md.
• Research bổ sung (mới):
  • plans/hybrid-engine-strategic-pros-cons-research.md — bảng so sánh chi tiết vs Excel/Airtable/NocoDB/Baserow/WP plugins..., pros/cons, moat, risks, khuyến nghị chiến lược.
  • plans/excel-functions-php-mapping-research.md (đã mở rộng) — 60+ hàm Excel phổ biến + mapping sang PHP logic, định nghĩa Cell chính thức cho Hybrid (record + field model), so sánh chi tiết NocoDB (Formula fields + AST parsed_tree + 100+ funcs) và Supabase (Generated Columns), đánh giá tận dụng (học patterns nhưng không copy code/runtime). Mirror/ tham chiếu trong GLOBAL. Đọc khi làm computed hoặc engine.
  • plans/mvp-luong-cong-nhat-update-flow.md — Kiến trúc + luồng chạy chi tiết (end-to-end) MVP: cập nhật chấm công hiệu suất → tính lương công nhật (theo đơn giá công việc) → cập nhật bảng lương + phiếu cá nhân từng người → chốt sổ snapshot. Có pseudocode, checklist phải làm cho dev. Đọc khi bắt đầu implement Phase 1. Mirror ngắn ở .context/planning/005_....
  • plans/positioning-giua-excel-va-erp.md — Định vị giữa Excel↔ERP + cái BẪY khi tổng quát hoá (nếu làm-dùng-lại bảng+công thức mà quên mang chốt sổ → rơi vào đám đông Airtable/NocoDB → thua). Có sơ đồ mermaid. Đọc khi bàn chiến lược/lộ trình engine.
  • plans/luong-cong-nhat-data-flow.md — 3 sơ đồ mermaid luồng dữ liệu công nhật tuần: hiện trạng Excel (AS-IS) / cơ chế bug rò tiền tuần trước / mô hình MVP (TO-BE). Đọc kèm payroll-template-mapping.md §10.
  • plans/mvp-system-design.md — Sơ đồ system-design MVP end-to-end (import → calc lọc-theo-kỳ → snapshot/chốt → phiếu; nhánh open/closed; Excel-reconcile #5) + 6 bước phương pháp thiết kế (ADR-driven layered) + caveat cái chưa chắc. Đọc để nắm toàn cảnh runtime.
  • plans/phase0-skeleton.md — 🏗️ BỘ KHUNG POC ĐÃ DỰNG + TEST PASS (2026-07-01). Cây file plugin (hybrid-engine.php bootstrap + includes/calc/class-payroll-calc.php hand-coded + includes/db/schema.php 7 bảng thật + tests/poc-mh027.php). Chạy php tests/poc-mh027.php → MH027-CN = 270.000 khớp Excel. Đánh dấu seam Phase 1. Đọc để biết code hiện có gì + chạy test.
  • plans/payroll-formulas-spec.md — 🟢 SPEC CÔNG THỨC ĐÃ GIẢI MÃ + VERIFY từ file thật (openpyxl, 198/216 dòng khớp). Đầy đủ: pipeline 4 lớp, công thức DATA từng dòng (AC/AD/AE/AF/AG), hằng 25.000=cơm + 1.2=TC, quy tắc bữa cơm suy từ giờ, bug carryover trong công thức thật, factor-mapping + code PHP hand-coded, kết quả chạy thử (18 lệch = Excel stale/gõ tay = bằng chứng #5). Đọc đầu tiên khi code calc. Thay thế các phỏng đoán cũ.
  • plans/formula-tracking.md — Bảng theo dõi công thức công nhật (chính / cũ SAI / bằng chứng gỡ / trạng thái). 🟢 2026-07-01: phần lớn ẩn số đã GỠ bằng file (25.000=cơm không phải NS; đơn giá dùng cả ×giờ lẫn ×sản lượng cho 2 khoản khác). Còn owner xác nhận đúng-ý (#5). Đọc kèm spec ở trên.
  • plans/period-close-implementation.md — Hiện thực chốt sổ + snapshot bất biến (bảng riêng denormalize + transaction/khóa khi chốt + enforce app-guard + tổng quát dtable). 3 sơ đồ mermaid (close sequence / read open-vs-closed / eval-loop check). Chốt từ Grok research, thực thi ADR 0004+0009. Đọc khi implement chốt sổ.
  • plans/mvp-mariadb-dynamic-tables-demo.md — Demo MariaDB thực tế: script SQL chạy được giải thích cách My quản lý "mớ bảng" (chỉ 6 bảng cố định). Có ví dụ đầy đủ schema (slug+label), records, search_index, relation, computed + snapshot cho payroll. Quan trọng: Có section giải thích "dtable" lấy cảm hứng từ SeaTable nhưng dtable-server proprietary → không thể ngồi xài không trực tiếp. Khuyến khích rename bảng thành hybrid_*. Đọc khi muốn test hoặc hiểu DB layer.