MOUT Builder v2 — Ghi chú thiết kế (vòng 2)

Date: 2026-06-18 | Status: DISCUSSION + PREVIEW (chưa enact) | Tiếp nối mout-moit-table-engine-notes.md (vòng 1). Preview live: https://vps.incomexsaigoncorp.vn/ui-preview/mcp-writes/mout-builder-v2.html Source VPS: /opt/incomex/docs/mcp-writes/ui-preview/mout-builder-v2.html Quyết định vòng này: chỉ tập trung MOUT. MOIT sẽ nhân ra từ cùng engine sau khi MOUT chốt.

1. Huyên duyệt concept v1 + yêu cầu bổ sung

"Trái = điều kiện, phải = sản phẩm" → OK. MOUT khi chốt phải đúc ra 1 báo cáo độc lập dùng được ngay. Bổ sung 5 nội dung (đã dựng hết trong v2):

1. Cột trái nối toàn bộ kho DB (~2000 trường), chia cụm theo lĩnh vực/công ty/chuyên môn (như MOW) + tìm nhanh.
2. ≤5 điều kiện lọc bất kỳ trường nào: trống = mặc nhiên thỏa mãn; điền 1 → lọc 1; điền 5 → AND cả 5. Cũng có bộ lọc tìm trường nhanh.
3. Thời gian từ–đến nhưng linh hoạt: hàng tuần/tháng, mốc cụ thể trong tháng (vd 16→28 hàng tháng), thậm chí hàng ngày/giờ. Tự động (định kỳ) nhưng cũng tạo tay được cho nhanh.
4. SUM rõ ràng hơn: không chỉ tổng cột cuối — bật cột nào cộng cột đó, bật hàng nào cộng hàng đó. SUM phải đi theo khuôn khi đúc sản phẩm.
5. Mục tiêu: yêu cầu báo cáo nào cũng quét vài thao tác là xong → tạo URL riêng + tải file đọc được bằng Excel & Google Sheets.

2. Quyết định kiến trúc vòng 2 (Cowork chốt)

2.1 Builder = "khuôn" 4 mục, preview = "bản đúc"

Trái 4 mục: (1) Cột sản phẩm, (2) ≤5 điều kiện lọc, (3) Thời gian, (4) Tổng. Phải: bảng đúc live + nút Đúc báo cáo + tải Excel/CSV + JSON khuôn.

2.2 Field Catalog dùng chung (point 1+2)

• Một picker, ba đích: chọn trường làm (a) cột output, (b) điều kiện lọc, (c) trường ngày. Cùng kho field.
• Facet: Lĩnh vực × Công ty × Phòng ban/Chuyên môn + ô search (khớp label/path/entity) → thu hẹp ~2000 trường tức thì.
• Điều kiện DOT dựng được vẫn là: field ∈ field_registry, có type đã duyệt (nối vòng 1).
• Picker filter (lọc danh sách field) ≠ data filter (lọc dữ liệu). Hai tầng khác nhau, đừng lẫn.

2.3 Lọc (point 2) — blank=wildcard, AND

• 5 slot: {field, operator, value}. operator theo type (text: =,chứa,thuộc d.sách,khác · số/tiền: =,>,≥,<,≤,trong khoảng · ngày: =,>,<,trong khoảng).
• Trống → bỏ qua (true). Tổ hợp = AND. (OR để vòng sau nếu cần — giữ đơn giản theo ý Huyên.)
• "5" là ngưỡng mềm như "12 cột".

2.4 Thời gian (point 3) — TÁCH HAI THỨ

Quyết định cốt lõi: tách Kỳ báo cáo khỏi Lịch chạy (dù thường đi cùng).

• Kỳ (period): absolute (từ–đến cụ thể, tạo tay 1 lần) HOẶC relative tự giải lúc chạy: Hôm nay/Tuần này/Tháng này/Tháng trước/7-30 ngày qua/Quý/Năm/Khoảng ngày trong tháng (D1→D2, vd 16→28).
• Lịch (schedule): none(mở là chạy)/hourly/daily/weekly/monthly → map cron (0 6 * * *…). Nối với năng lực scheduled-task của hệ.
• Lợi: vừa "tháng trước chốt cứng", vừa "tháng này cập nhật mỗi ngày (month-to-date)".
• Preview giải ra ngày thật theo "hôm nay" để người tạo thấy ngay kỳ nghĩa là gì.

2.5 SUM (point 4) — mô hình rõ

• Σ cột (bật từng cột) → dòng tổng dưới cùng (query-side, nối vòng 1).
• Σ hàng (công tắc "Tổng hàng") → cột tổng phải, cộng ngang các cột Σ; grand total ở giao điểm.
• Cảnh báo thiết kế: Σ hàng chỉ có nghĩa khi các cột Σ cùng đơn vị (tháng/quý). Báo cáo phẳng dị chủng (Số lượng + Thành tiền) cộng ngang vô nghĩa → đây là đất của Pivot/Grid.
• Toàn bộ cấu hình tổng nằm trong khuôn (totals.column_sum[], row_sum, grand_total) → đúc ra là SUM đi theo, mỗi lần chạy tự tính lại.

2.6 Đúc → sản phẩm (point 5)

• Bấm Đúc → sinh report_id (slug bỏ dấu từ tiêu đề) + URL riêng /r/<id> render live.
• Tải file: CSV (UTF-8 BOM, Google Sheets + Excel đọc) + .xls (HTML table, Excel mở). Preview đã làm download thật.
• Khuôn = JSON: {report_id,title,mode,stt,columns[],filters[],time{period,schedule,cron},totals{},data{fn},output{url,export}}.

3. Preview v2 đã có (verified)

• Catalog 438 trường demo (đại diện ~2000), facet lĩnh vực/công ty/phòng ban + search, đếm động.
• 5 ô lọc blank=wildcard AND, toán tử theo type, lọc bảng preview tức thì.
• Thời gian cụ thể/định kỳ + lịch, giải kỳ ra ngày thật (verified: 16→28 = 16/06→28/06/2026; tháng trước = 01/05→31/05).
• Cột: thêm từ catalog, ẩn/hiện, đổi thứ tự ↑↓, xóa, Σ chỉ cột số.
• Σ cột + Σ hàng + grand; đúc ra URL + tải CSV/.xls thật; JSON khuôn live. slug verified (rpt_doanh_thu_theo_khach_hang).

4. Open items vòng sau

1. Đồng bộ với MOIT: sau khi MOUT chốt, nhân engine sang MOIT-Grid (ô sửa được, ghi direct/queue) + MOUT-Pivot (cột động).
2. field_registry thật: type + display + agg hợp lệ + operator hợp lệ; nối KIT F01–F10 của MOT.
3. DOT Function Registry: hàm số liệu nhận filters[] + period đã giải + trả {columns,rows,totals}; ai duyệt, governance D0-G.
4. Cột placeholder (chờ nối): khi thêm cột mới từ catalog, DOT phải tự sinh/nối hàm số liệu — quy tắc auto vs cần khai hàm.
5. OR / nhóm điều kiện nếu nghiệp vụ cần (hiện chỉ AND).
6. Permission filter backend + cột nhạy cảm (lương…) theo role.
7. Lịch chạy nối scheduled-task thật + nơi lưu bản đúc (cache/materialized view) + thông báo khi xong.
8. Export .xlsx thật (server-side) thay .xls HTML; giữ định dạng tiền/ngày.

Ghi chú vòng 2 — chờ Huyên phản hồi preview v2.